> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session03-data-driven-radar-aliases-and-watching-state/spec.md). # Session Specification **Session ID**: `phase27-session03-data-driven-radar-aliases-and-watching-state` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-12 *** ## 1. Session Overview This session completes the Tier 1 Alpha Radar adoption path by turning the Signal Radar from a decorative source-name visualization into a topic opportunity map. Radar positions should encode momentum on the x-axis and novelty or inverse saturation on the y-axis, with fallback bands for topics that do not have enough derived signal data. Clicking a radar point selects the same topic in the Trends view so the visual becomes part of the triage workflow rather than a passive animation. The session also exposes already-generated topic aliases, extends the existing browser-local Signal Workbench triage storage with a `watching` state, and adds a cross-source outlier preset over existing source-local lift fields. The generated Watchlist remains read-only, thumbnails remain out of scope, and no collector/source/API work is introduced. The result is a sharper operator loop: aliases help users recognize canonical topics, watching lets users pin topics locally across reloads and runs, the radar answers "what should I inspect first", and the outlier preset surfaces the strongest source-local lift rows across all supported sources without weakening Trend Finder's browser-safe payload boundary. *** ## 2. Objectives 1. Plot Trend Finder topics on a data-driven radar using validated payload fields with explicit fallback bands for missing axis data. 2. Render topic aliases on card/detail surfaces and include aliases in Signal Workbench search. 3. Add a browser-local `watching` triage state with accessible controls and filter chips on Trends and Hidden Gems. 4. Add a deterministic cross-source outlier preset over existing source-local lift data, with explicit unavailable and low-sample handling. *** ## 3. Prerequisites ### Required Sessions * [x] `phase27-session01-brief-movement-groups-and-calibration-metrics` - establishes Phase 27 additive view-model and fixture patterns. * [x] `phase27-session02-deterministic-derived-signals-and-risk-flags` - provides saturation, hidden-gem score, risk flags, builder signal, and source-local Workbench fields consumed by this session. ### Required Tools/Knowledge * Bun 1.3.14 for package scripts and Vitest. * React 19, TanStack Start, Tailwind CSS 4, and existing dense Trend Finder UI patterns. * Existing Signal Radar, Signal Workbench, localStorage triage, Trends, Hidden Gems, schema, fixture, and view-model helpers. * Source-local lift semantics from `scripts/extensions/trend-finder/source-local-signals.ts`. ### Environment Requirements * Repository rooted at `/home/aiwithapex/projects/aios`. * Phase 27 PRD stubs present under `.spec_system/PRD/phase_27/`. * No live source run is required; fixtures and unit/component tests cover radar, aliases, watching, malformed storage, and outlier ordering. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operator can read the Signal Radar as an opportunity map: momentum on x, novelty or inverse saturation on y, bubble size by evidence count, and color by movement status until Session 06 adds lifecycle colors. * Trend Finder operator can click a plotted radar point to select that topic in the Trends view, with keyboard-accessible controls and reduced-motion safe animation. * Trend Finder operator can see aliases on trend cards/detail surfaces and search by aliases in Signal Workbench. * Trend Finder operator can mark a topic as `watching` using existing browser-local triage storage, without mutating generated Watchlist rows, generated data, exports, or caches. * Trends and Hidden Gems provide filter chips for all topics vs watched topics and keep empty states explicit when no watched topics match. * Signal Workbench provides a cross-source outlier preset that filters and sorts rows by available source-local lift/actionability with deterministic tie-breakers. * Tests cover projection math, alias search, localStorage migration/parsing, watching filters, outlier preset ordering, and non-mutation of generated data. ### Out of Scope (Deferred) * Lifecycle-stage radar coloring - Reason: planned for Session 06 after the deterministic lifecycle classifier lands. * Daily sparkline or trajectory data - Reason: planned for Sessions 04, 05, and 07. * Per-outlier creator ideas - Reason: planned for Session 11 after the outlier surface exists. * Thumbnails or any new media exposure - Reason: compliance-gated non-goal in the Phase 27 PRD. * New source adapters, collector calls, AI calls, or score math changes - Reason: this session is presentation and browser-local state over existing payload fields. * Mutating the generated Watchlist - Reason: the generated Watchlist remains read-only by design; watching is browser-local triage state only. *** ## 5. Technical Approach ### Architecture Keep the session browser/UI focused and consume validated payload fields through existing schema and view-model boundaries: * `src/extensions/trend-finder/view-model.ts` owns radar point projection, axis labels, fallback copy, alias formatting, and deterministic point ordering so components do not duplicate math. * `src/extensions/trend-finder/components/signal-radar.tsx` consumes projected topic points, preserves the existing HUD aesthetic, exposes point buttons, and distinguishes fallback points from evidence-backed data points. * `src/extensions/trend-finder/views/trends-view.tsx` passes the full topic set, selected topic, selection handler, and local watching filter state into the radar/list surfaces. * `src/extensions/trend-finder/signal-workbench-storage.ts` adds `watching` to the existing version 1 triage state enum, preserving backward-compatible parsing, caps, dedupe, and malformed-storage recovery. * `src/extensions/trend-finder/signal-workbench-model.ts` includes aliases in search text and adds outlier preset projection/sort helpers over existing `sourceLocal` fields. Radar y-axis should prefer inverse saturation when saturation is available and fall back to novelty when saturation is unavailable. Missing momentum or saturation/novelty inputs should place topics in a labeled fallback band, never in invented high-opportunity positions. Bubble size derives from bounded evidence count. Color derives from movement status until lifecycle data lands. ### Design Patterns * Project before rendering: Components consume sanitized view-model rows and labels instead of deriving raw display decisions inline. * Browser-local state boundary: `watching` persists only under `ai-os.trend-finder.signal-workbench.v1` and never writes generated data. * Explicit unavailable states: Missing axis or source-local data stays visible as fallback/unavailable, not hidden or invented. * Stable deterministic ordering: Radar points, watched filters, and outlier presets use fixed tie-breakers by score, lift, rank, name, and ID. * Additive UI behavior: Existing `acted-on`, `ignored`, and `revisit` triage rows keep parsing and rendering. * Behavioral quality by design: Interactive controls include labels, focus states, disabled-while-saving behavior, re-entry reloads, empty states, and reduced-motion handling. ### Technology Stack * TypeScript 6.0.3 * React 19.2.0 * Zod 4.4.3 * Vitest 4.1.6 * Bun 1.3.14 *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/__tests__/signal-radar-projection.test.ts` | Unit tests for radar point projection, fallback bands, sizing, movement tone, and deterministic ordering. | \~140 | ### Files to Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `src/extensions/trend-finder/view-model.ts` | Add radar projection, axis/fallback labels, alias formatting, watching summary labels, and deterministic outlier helpers if kept in view-model. | \~220 | | `src/extensions/trend-finder/components/signal-radar.tsx` | Replace source-name node positions with topic radar points, point buttons, fallback legend, alias display, and reduced-motion safe behavior. | \~260 | | `src/extensions/trend-finder/views/trends-view.tsx` | Wire radar selection, watched filter chips, watching toggle state, empty states, and topic list counts. | \~160 | | `src/extensions/trend-finder/components/trend-card.tsx` | Render topic aliases as bounded chips on card/detail surfaces. | \~70 | | `src/extensions/trend-finder/signal-workbench-storage.ts` | Extend triage state with `watching`, preserving parse, persist, dedupe, caps, reset, and malformed-storage recovery. | \~90 | | `src/extensions/trend-finder/hooks/use-signal-workbench-triage.ts` | Preserve re-entry reload behavior and expose `watching` through existing state actions. | \~30 | | `src/extensions/trend-finder/components/signal-triage-controls.tsx` | Add watching control with duplicate-trigger prevention while saving and accessible labels. | \~90 | | `src/extensions/trend-finder/signal-workbench-model.ts` | Include aliases in search, add watching facets/order, add outlier preset projection/filter/sort helpers, and keep generated data immutable. | \~220 | | `src/extensions/trend-finder/components/signal-workbench-controls.tsx` | Add outlier preset control and helper copy with reset behavior and no layout overflow. | \~100 | | `src/extensions/trend-finder/components/signal-workbench-table.tsx` | Surface watching state and outlier lift context in rows without breaking stable column sizing. | \~80 | | `src/extensions/trend-finder/views/signal-workbench-view.tsx` | Wire outlier preset state into filters/sort with state reset or revalidation on re-entry. | \~90 | | `src/extensions/trend-finder/views/hidden-gems-view.tsx` | Add watched filter chips, local watching state, toggles, explicit empty states, and pagination reset on filter changes. | \~160 | | `src/extensions/trend-finder/fixtures.ts` | Ensure aliases, watched candidates, missing-axis topics, and source-local outlier rows are available for focused tests. | \~90 | | `src/extensions/trend-finder/__tests__/signal-workbench-storage.test.ts` | Cover watching parse/persist/dedupe, malformed rows, and legacy states. | \~90 | | `src/extensions/trend-finder/__tests__/signal-workbench-model.test.ts` | Cover alias search, watching filter/facet/sort behavior, outlier preset ordering, unavailable rows, and non-mutation. | \~160 | | `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx` | Cover outlier preset and watching control behavior in the Workbench surface. | \~120 | | `src/extensions/trend-finder/components/__tests__/trend-motion.test.tsx` | Extend browser-visible motion/accessibility checks for radar reduced-motion behavior if needed. | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Radar positions derive only from validated topic fields; missing values render in an explicit fallback band. * [ ] Radar point click and keyboard activation select the corresponding Trends topic. * [ ] Visual fallback nodes are distinguishable from data-backed topic nodes. * [ ] Topic aliases render as bounded chips and Workbench search matches alias text. * [ ] `watching` survives reloads, dedupes by topic ID, drops malformed rows, and does not write generated data, generated Watchlist rows, exports, or caches. * [ ] Trends and Hidden Gems watched filters show explicit empty states when no watched topics match. * [ ] Outlier preset includes only rows with available source-local baselines and deterministic source-local lift ordering. * [ ] Low-sample, placement-excluded, unsupported, and unavailable source-local states remain explicit and are not promoted as outliers. ### Testing Requirements * [ ] Unit tests cover radar projection math, fallback bands, sizing, movement tone, and deterministic ordering. * [ ] Storage tests cover `watching`, legacy triage rows, malformed storage, dedupe, caps, reset, and write failure paths. * [ ] Workbench model tests cover alias search, outlier preset ordering, watching facets/filters, and generated-data non-mutation. * [ ] Component tests cover outlier preset controls, watching controls, and visible empty states. * [ ] Focused Trend Finder tests pass before full validation is attempted. ### Non-Functional Requirements * [ ] No new source calls, AI calls, third-party transfers, browser-visible raw source payloads, private paths, prompts, provider responses, thumbnails, or local notes in generated output are introduced. * [ ] Radar and list controls are keyboard accessible, labeled, and safe under reduced-motion preferences. * [ ] New UI text remains compact and does not cause table, card, or mobile overflow. * [ ] Source-local outlier rows use bounded deterministic ordering and do not expose unsupported/unavailable rows as actionable. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test` passes or failures are documented before validation. * [ ] `bun run typecheck` and `bun run typecheck:scripts` pass or failures are documented before validation. *** ## 8. Implementation Notes ### Key Considerations * The current Signal Radar computes node coordinates from source names. This session must move coordinate math into a deterministic topic projection so position has product meaning. * The generated Watchlist remains read-only. Watching is local triage state, not a new generated payload branch. * Topic aliases already exist in `TrendTopicSchema`; this session exposes them rather than changing identity resolution. * The source-local lift math already exists and is stronger than Alpha Radar's YouTube-only outlier divisor. This session should surface it without changing collection or scoring. ### Potential Challenges * Radar layout regression: Preserve the dense HUD style while making axes, fallback bands, and selected points legible on desktop and mobile. * State re-entry drift: Reload localStorage on run changes, visibility/focus, and storage events so watched filters stay accurate across tabs. * Outlier overclaiming: Exclude unavailable/low-sample rows from the preset and label placement-excluded rows explicitly. * Table overflow: Keep preset and watching labels compact inside the existing fixed Workbench table layout. ### Relevant Considerations * \[P24] **Browser-safe export and triage boundaries**: Watching remains browser-local and excluded from exports, generated data, caches, and raw evidence output. * \[P24] **Deterministic ordering helps dense triage**: Radar points, watched filters, and outlier preset rows use stable tie-breakers. * \[P24] **Additive defaults keep legacy payloads alive**: Alias display and outlier logic consume existing optional fields without requiring payload migrations. * \[P05] **Script-only runtime boundary**: No new collector/runtime calls are needed; browser code consumes validated payload fields only. * \[P02] **Extension payloads and demo labels stay bounded**: This session adds local state and presentation, not unbounded payload fields. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Radar points could imply false precision when saturation or momentum is missing unless fallback bands are explicit. * Local watching could corrupt or leak generated data if it bypasses the existing triage storage boundary. * Outlier preset could over-promote unsupported, low-sample, or placement-excluded rows unless unavailable states are visible. * Interactive radar and filter controls could become mouse-only or motion-heavy without keyboard and reduced-motion support. *** ## 9. Testing Strategy ### Unit Tests * Radar projection helper maps momentum, inverse saturation/novelty fallback, evidence count, movement color, missing data, and deterministic ordering. * Signal Workbench storage parses `watching`, legacy states, malformed rows, duplicate topic IDs, invalid notes, and caps. * Signal Workbench model includes aliases in search and sorts outlier preset rows by source-local lift with stable tie-breakers. ### Integration Tests * Workbench view test verifies outlier preset updates filters/sort and reset returns to the default state. * Triage controls test verifies watching disables while saving and emits accessible status text. * Trends and Hidden Gems view tests verify watched filters and empty states if existing test harness support is available. ### Manual Testing * Load Trend Finder Trends with fixture data, click radar points, confirm the selected list item and detail panel update together. * Mark a topic as watching, reload, and verify Trends, Hidden Gems, and Workbench all show the watched state. * Apply the outlier preset and verify rows are ordered by available source-local lift and unavailable rows remain excluded or explicitly labeled. ### Edge Cases * Topics with missing saturation, zero evidence, missing momentum, no aliases, no source-local baseline, malformed localStorage, quota write failure, reduced-motion preference, and no watched topics. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase27-session01-brief-movement-groups-and-calibration-metrics`, `phase27-session02-deterministic-derived-signals-and-risk-flags` * **Depended by**: `phase27-session04-daily-time-series-persistence-and-sparklines`, `phase27-session06-lifecycle-stage-taxonomy`, `phase27-session09-competitor-lens-and-creator-angle-pack`, `phase27-session11-theme-rollups-and-outlier-ideas` *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase27-session03-data-driven-radar-aliases-and-watching-state/spec.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.