> 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/phase33-session05-polish-public-demo-ui-states/spec.md). # Session Specification **Session ID**: `phase33-session05-polish-public-demo-ui-states` **Phase**: 33 - Cloudflare Pages Real Product Fixtures **Status**: Not Started **Created**: 2026-06-25 *** ## 1. Session Overview This session polishes the hosted Cloudflare Pages demo surfaces after Sessions 01 through 04 captured, froze, and hardened real Trend Finder and Dream Review fixture data. The public demo already has static-only boundaries and committed snapshot assets; the remaining work is to make the UI read as an intentional frozen product demo instead of a local runtime that failed to start. The session focuses on public-demo copy, disabled runtime controls, empty states, route labels, browser-local state explanations, and targeted UI tests. It keeps Pages static-only: collectors, schedulers, account auth, local bridge reads, Dream runtime jobs, uploads, source setup writes, analytics, and admin mutations remain unavailable in the hosted demo. The result prepares Session 06 to run scan, budget, build, route-smoke, and Cloudflare deployment verification gates without first having to repair misleading product surfaces. *** ## 2. Objectives 1. Make Trend Finder public demo routes present frozen real product output with concise provenance, disabled runtime controls, and no live-hosted-work claims. 2. Make Dream Review on the home dashboard present populated public snapshot data when available and an intentional unavailable state when not available. 3. Keep local-only actions disabled or honestly browser-local in public demo mode, including run controls, source setup, scheduler actions, uploads, fixture mutation, Creator Lens drafts, Signal Workbench triage, visibility settings, watchlist pins, and AI Rogue progress. 4. Add focused unit and route-smoke assertions proving public demo routes do not call local bridge or mutation endpoints and use product-facing copy. *** ## 3. Prerequisites ### Required Sessions * [x] `phase33-session01-capture-local-demo-runs` - produced and reviewed the local Trend Finder and Dream Review output selected for the public demo. * [x] `phase33-session02-freeze-public-fixtures` - converted reviewed output into deterministic committed Pages fixtures and metadata. * [x] `phase33-session03-harden-trend-finder-projection` - preserved useful Trend Finder artifacts with schema-valid provenance and bounded references. * [x] `phase33-session04-harden-dream-projection` - added the allowlisted Dream Review projection and regenerated committed public demo fixtures. ### Required Tools Or Knowledge * Bun 1.3.14 and project scripts from `package.json`. * Existing public demo mode helpers in `src/lib/public-demo.ts`. * Existing public demo endpoint selection in `src/lib/use-live-data.ts`. * Existing Trend Finder view models, run controls, scheduler/source controls, visibility state, and route views under `src/extensions/trend-finder/`. * Existing Dream Review home components in `src/components/home/dream-hero.tsx` and `src/components/dream-run-button.tsx`. * Existing Pages route matrix in `scripts/lib/pages-demo-routes.ts`. ### Environment Requirements * Work from the repository root. * Use `VITE_AI_OS_PUBLIC_DEMO` as the public demo mode switch. * Do not require Cloudflare credentials, collector credentials, account auth, local bridge access, scheduler runtime, Dream runtime, uploads, analytics, or admin mutation access. *** ## 4. Scope ### In Scope (MVP) * Trend Finder users can evaluate frozen real snapshot output on Trends, Engine Replay, Hidden Gems, Sources, Signal Workbench, Watchlist, and Brief routes. * Trend Finder provenance labels use concise product language such as `Frozen snapshot`, `Frozen real Trend Finder snapshot`, `Reviewed public-source snapshot`, and `AI runtime disabled on hosted demo`. * Trend Finder run, collector, scheduler, source setup, asset bridge, upload, visibility, triage, pin, note, tag, and fixture mutation controls are either disabled or labeled as browser-local where appropriate. * Dream Review on the home dashboard uses frozen real snapshot copy when public demo data is present. * Dream Review empty public-demo state says the frozen Dream snapshot is unavailable instead of telling hosted users to run local scheduler commands. * Dream run controls stay disabled in public demo mode and do not fetch `/__token`, post `/__run_dream`, or refresh local data. * The route matrix includes product-surface checks for public demo labels that matter to Trend Finder, Dream Review, and navigation. * Focused unit and browser checks cover public demo copy, disabled-runtime behavior, no local bridge calls, and desktop/mobile route readability. ### Out Of Scope (Deferred) * Running local capture or fixture regeneration - Reason: Sessions 01 through 04 already produced the committed public fixtures. * Changing fixture projection policy - Reason: Sessions 03 and 04 own projection hardening; this session consumes the committed projection. * Running final Pages scan, bundle budget, build, deployment dry run, or Cloudflare deploy - Reason: Session 06 owns release gates and deployment. * Adding hosted mutation endpoints, Pages Functions, collectors, schedulers, analytics, source writes, uploads, account auth, or hosted Dream runtime - Reason: Phase 33 keeps the public demo static-only. * Reworking application navigation outside public demo state honesty - Reason: this session only adjusts navigation/sidebar behavior when public-demo labels or route reachability are misleading. *** ## 5. Technical Approach ### Architecture Keep public-demo copy centralized in `src/lib/public-demo.ts` and let route surfaces consume that shared copy where practical. The UI should communicate three separate states clearly: frozen committed snapshot data, disabled hosted runtime actions, and browser-local interactions that do not mutate committed fixtures. Trend Finder changes should stay inside existing route views and shared components rather than creating a second public-demo route tree. Dream Review changes should keep the existing home `DreamHero`, `DreamRunButton`, and `useDreamRun()` contract, with public-demo mode short-circuiting local runtime fetches and surfacing snapshot/unavailable copy. Tests should extend existing focused suites instead of adding broad new harnesses: public-demo helper tests, Dream run/hero tests, Trend Finder view tests, the Pages demo route registry test, and the existing desktop/mobile Pages demo Playwright route specs. ### Design Patterns * Shared public-demo copy: One source for frozen, disabled, read-only, and browser-local messages keeps route copy consistent. * Static route tree: Reuse the real AI OS and Trend Finder routes in public demo mode; do not create hosted-only route forks. * Disabled-first local actions: Local-only controls render as disabled or browser-local before any token, bridge, or mutation path can fire. * Product-facing empty states: Hosted demo copy explains the product state, not local command instructions or diagnostics. * Route matrix verification: Pages route metadata and e2e smoke prove the same public-demo route set across desktop and mobile. *** ## 6. Deliverables ### Files To Create No new files are expected; this session updates existing UI, copy, tests, and route-matrix artifacts. ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- | | `src/lib/public-demo.ts` | Extend shared frozen, disabled, read-only, unavailable, and browser-local copy for Trend Finder and Dream Review. | \~45 | | `src/components/home/dream-hero.tsx` | Add public-demo Dream snapshot and unavailable copy paths. | \~40 | | `src/components/dream-run-button.tsx` | Tighten disabled public-demo label, title, aria, and click behavior. | \~20 | | `src/lib/use-dream-run.ts` | Preserve no-fetch public-demo short-circuit and duplicate-trigger semantics. | \~20 | | `src/extensions/trend-finder/views/trends-view.tsx` | Polish frozen snapshot notice, provenance, run control, and empty states. | \~50 | | `src/extensions/trend-finder/views/engine-replay-view.tsx` | Polish replay snapshot, runtime-disabled, scheduler/live-progress copy. | \~35 | | `src/extensions/trend-finder/views/sources-view.tsx` | Polish source setup and scheduler read-only public-demo copy. | \~35 | | `src/extensions/trend-finder/views/hidden-gems-view.tsx` | Polish hidden-gem empty states and browser-local watch filters. | \~30 | | `src/extensions/trend-finder/views/signal-workbench-view.tsx` | Polish browser-local triage and public snapshot state copy. | \~30 | | `src/extensions/trend-finder/views/watchlist-view.tsx` | Polish generated rows versus browser-local pins, notes, and tags. | \~30 | | `src/extensions/trend-finder/views/brief-view.tsx` | Polish frozen brief, export, clipboard, and unavailable copy. | \~35 | | `src/components/app-sidebar.tsx` | Adjust public-demo navigation/sidebar labels only if they imply live local runtime. | \~20 | | `scripts/lib/pages-demo-routes.ts` | Add or tighten product-surface checks for public-demo labels and route reachability. | \~30 | | `src/lib/__tests__/public-demo.test.ts` | Cover shared public-demo copy variants. | \~35 | | `src/components/__tests__/dream-run-button.test.tsx` | Cover disabled Dream public-demo button semantics. | \~20 | | `src/components/home/__tests__/dream-hero.test.tsx` | Cover populated and unavailable public-demo Dream states. | \~35 | | `src/lib/__tests__/use-dream-run.test.tsx` | Cover no token, no run, and no refresh behavior in public demo mode. | \~25 | | `src/lib/__tests__/trend-finder-dashboard.test.tsx` | Cover Trend Finder public-demo route copy and no bridge calls. | \~45 | | `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx` | Cover browser-local public-demo triage copy. | \~25 | | `src/extensions/trend-finder/views/__tests__/brief-view.test.tsx` | Cover frozen brief/export copy. | \~25 | | `scripts/lib/__tests__/pages-demo-routes.test.ts` | Cover updated route matrix expectations. | \~25 | | `tests/e2e/pages-demo-routes.spec.ts` | Use route matrix checks to assert desktop product surfaces and no `/__*` requests. | \~15 | | `tests/e2e/pages-demo-mobile.spec.ts` | Use route matrix checks to assert mobile product surfaces and no overflow. | \~15 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Public users can tell Trend Finder and Dream Review data is frozen, public-safe, and useful for product evaluation. * [ ] Dream Review looks intentionally populated when snapshot data exists. * [ ] If Dream Review public-demo data is empty, the UI says the frozen Dream snapshot is unavailable and does not mention local scheduler commands. * [ ] No hosted control implies that a collector, Dream job, scheduler, upload, source setup write, graph mutation, asset bridge write, or fixture mutation will run. * [ ] Browser-local controls explicitly say they affect only the current browser and do not update committed fixtures. * [ ] Public demo routes do not request `/__*` local bridge or mutation endpoints. * [ ] Trend Finder Trends, Engine Replay, Hidden Gems, Sources, Signal Workbench, Watchlist, Brief, the home dashboard, and sidebar navigation remain reachable in public demo mode. ### Testing Requirements * [ ] Unit tests cover shared public-demo copy and Dream public-demo controls. * [ ] Unit tests cover Trend Finder public-demo labels, empty states, and no-bridge runtime behavior. * [ ] Pages route registry tests cover the updated public-demo surface checks. * [ ] Desktop and mobile Pages demo route smoke remains ready for Session 06. ### Non-Functional Requirements * [ ] Public-demo copy stays concise and product-facing. * [ ] Runtime diagnostics remain confined to tests, logs, or dev-only surfaces. * [ ] Existing static-only Pages boundary is preserved. * [ ] No secrets, private paths, raw prompts, provider bodies, token-like strings, analytics, or personal data are added. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] UI text fits inside compact route panels and buttons on desktop and mobile. *** ## 8. Implementation Notes ### Working Assumptions * This is a single-repo application session, not a package-scoped monorepo session. Evidence: analyzer output reported `monorepo: null`, no packages, and every Phase 33 candidate has `package: null`; planning can proceed with repo-root-relative paths. * Public demo mode continues to be controlled by `VITE_AI_OS_PUBLIC_DEMO`. Evidence: the Session 05 stub lists it as a prerequisite and `src/lib/public-demo.ts` already parses that variable; planning can proceed by extending existing helpers instead of adding a second flag. * Dream Review public-demo UI must handle both populated and unavailable snapshot states. Evidence: Session 04 added allowlisted Dream projection and the Session 05 stub explicitly says empty Dream data should be described as a frozen snapshot unavailable state; planning can include both branches without changing projection policy. ### Conflict Resolutions * The Session 05 stub repeats Trend Finder and Dream provenance/empty-state bullets. Chosen interpretation: make one consolidated UI pass across shared copy, route notices, disabled controls, and empty states rather than treating duplicate bullets as separate fixture-projection work. * Session 06 owns scan, build, budget, route-smoke, and deploy gates, while the UX PRD says UI sessions need browser-visible validation. Chosen interpretation: Session 05 adds focused assertions and keeps route-smoke specs ready, but final build/deploy verification remains Session 06. ### Key Considerations * Preserve the static public-demo boundary. No UI polish may add hosted collectors, local bridge calls, Pages Functions, analytics, or writes. * Keep Trend Finder product language separate from AI OS host/operator cockpit language. * Use concise labels that do not bury the ranked trend surface or Dream Review product moment. * Keep browser-local behavior honest for Creator Lens drafts, Signal Workbench triage, visibility settings, Watchlist pins, and AI Rogue progress. ### Potential Challenges * Copy can become over-explanatory and crowd dense dashboard panels: Mitigation: use short badges plus one clear sentence per route state. * Existing tests may assert old local scheduler copy: Mitigation: update tests only where public-demo branches change and keep non-public behavior intact. * Route smoke can pass while the UI still looks like a debug surface: Mitigation: add product-surface assertions for labels users actually see. ### Relevant Considerations * \[P31/P32] **Pages demo stays static-only**: Public-demo UI work must not add `/__*` bridge calls, hosted writes, collectors, analytics, Functions, or advanced Workers. * \[P31/P32] **Public-demo release gates stay bundled**: Session 05 prepares route surfaces; Session 06 must still run build, scan, budget, no-bridge, and smoke checks together. * \[P31] **Route smoke is a privacy gate**: Keep desktop/mobile route matrix assertions strong enough to catch accidental bridge leaks. * \[P31] **Metadata-backed provenance beats diagnostics**: Snapshot metadata and concise labels should communicate provenance without live collection claims. * \[P31] **Do not let public demo become live runtime**: Pages builds must not run snapshot capture, local bridge reads, collectors, or public writes. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Public-demo controls accidentally trigger local bridge or mutation endpoints. * Empty states tell hosted users to run local commands or imply broken runtime. * Browser-local settings appear to update committed fixtures or hosted state. *** ## 9. Testing Strategy ### Unit Tests * `src/lib/__tests__/public-demo.test.ts` for shared copy and flag behavior. * `src/lib/__tests__/use-dream-run.test.tsx` for no token, no Dream run, and no refresh behavior in public demo mode. * `src/components/__tests__/dream-run-button.test.tsx` and `src/components/home/__tests__/dream-hero.test.tsx` for Dream public-demo control and empty/populated states. * `src/lib/__tests__/trend-finder-dashboard.test.tsx`, `src/lib/__tests__/trend-finder-engine-replay.test.tsx`, `src/extensions/trend-finder/components/__tests__/signal-workbench-view.test.tsx`, and `src/extensions/trend-finder/views/__tests__/brief-view.test.tsx` for public-demo Trend Finder route labels. * `scripts/lib/__tests__/pages-demo-routes.test.ts` for route matrix checks. ### Integration Tests * Use the existing Pages demo desktop and mobile Playwright specs to confirm public route surfaces render and no `/__*` requests are made. * Keep final full build, budget, scan, deploy dry run, and hosted smoke for Session 06. ### Runtime Verification * Build public-demo route assertions around `/`, Trend Finder Trends, Engine Replay, Hidden Gems, Sources, Signal Workbench, Watchlist, and Brief. * Confirm the home dashboard Dream Review state is intentional in both populated and unavailable public-demo snapshots. * Confirm sidebar navigation exposes the public-demo route set without implying live hosted runtime work. ### Edge Cases * Public demo flag values accepted by `parsePublicDemoFlag()`. * Populated Dream snapshot, empty Dream snapshot, and malformed/missing Dream branch. * Offline browser state while reading committed public snapshot data. * Disabled controls clicked repeatedly. * Browser-local triage, pins, notes, tags, visibility settings, and AI Rogue progress revisited after route navigation. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase33-session01-capture-local-demo-runs`, `phase33-session02-freeze-public-fixtures`, `phase33-session03-harden-trend-finder-projection`, `phase33-session04-harden-dream-projection` * Depended by: `phase33-session06-scan-build-and-deploy` *** ## Next Steps Run the `implement` workflow step to begin 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/phase33-session05-polish-public-demo-ui-states/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.