> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase04-session06-public-demo-media-parity-and-offline-loading/spec.md). # Session Specification **Session ID**: `phase04-session06-public-demo-media-parity-and-offline-loading` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Not Started **Created**: 2026-05-29 **Package**: cross-cutting **Package Stack**: Static public demo, service worker, Node 20 scripts, TypeScript catalog fixtures, Playwright, Vitest *** ## 1. Session Overview This session keeps the standalone public demo aligned with the Phase 04 media catalog and promotion decisions. It covers the copied battlefield media, portraits, showcase art, install icons, speech clips, music playlist, manifest, and service-worker cache rules that make `public-demo/` work without a build step or local server. The work is cross-cutting because the public demo must remain a standalone artifact while still reflecting app-owned and cataloged media truth. The session adds or tightens repository media checks, app-facing catalog records or documented standalone exceptions, public-demo cache rules, public-demo docs, and browser validation evidence for desktop, mobile, failed media, and offline reload after one online visit. This session does not expand the demo beyond the approved Phase 04 media scope. It preserves synthetic data, local artifact media, no workspace imports, gesture-compatible audio and music behavior, and clear boundaries from local server hooks, LLM endpoints, plan workpad behavior, real replay data, and War Room federation. *** ## 2. Objectives 1. Add deterministic public-demo media parity checks for images, icons, speech, music, manifest entries, cache policy, and workspace-import boundaries. 2. Complete catalog coverage or explicit standalone exceptions for current public-demo media, especially speech clips, background music, showcase art, and install icons. 3. Keep service-worker cache entries, cache versioning, lazy-loading decisions, and relative media paths aligned with Phase 04 catalog and docs. 4. Validate public-demo desktop, mobile, failed-media, console/page-error, and offline reload behavior with Playwright evidence. *** ## 3. Prerequisites ### Required Sessions * [x] `phase04-session02-typed-media-catalog-contracts` - provides shared media catalog contracts, app-facing fixtures, validation helpers, and current public-demo mirror records. * [x] `phase04-session04-visual-promotion-tooling-and-budgets` - provides visual promotion checks, app/demo mirror parity, service-worker cache checks, and media budget policy. * [x] `phase04-session05-browser-audio-runtime-and-controls` - confirms full app file-backed audio remains blocked and synthetic audio behavior has clear visible equivalents. ### Required Tools/Knowledge * Node 20 and npm workspace scripts. * Current `public-demo/` static artifact boundary and no-build deployment model. * Existing `npm run battlefield:check`, `npm run media:visual:check`, and `npm run media:drafts:check` gates. * Playwright public-demo desktop and mobile projects. * Service worker cache versioning, relative path handling, and offline reload behavior. ### Environment Requirements * Run commands from the repository root. * No provider credentials are required. * Network is required only for first-load browser validation of CDN dependencies; offline reload validation must happen after one successful online visit. * No `EXAMPLES/` file may be copied, transformed, imported, cached, or shipped through `public-demo/`. *** ## 4. Scope ### In Scope (MVP) * Maintainers can audit public-demo media inventory against catalog records or documented standalone exceptions - add a deterministic root check for demo assets, cache policy, and path boundaries. * Maintainers can verify public-demo media remains standalone - reject workspace imports, package imports, local-server paths, remote repository media URLs, broad absolute paths, and `EXAMPLES/` references in runtime demo files. * Demo users can load battlefield art, portraits, showcase art, speech clips, icons, and the music playlist through relative local artifact paths - update public-demo constants, manifest, and docs when drift is found. * Demo users can use speech and music through gesture-compatible controls with visible fallback behavior - preserve local synthetic demo copy, blocked or failed playback states, and nonessential audio meaning. * Demo users can reload the demo shell offline after one online visit - keep service-worker precache entries explicit, cache version changes deliberate, and large optional music tracks lazy-loaded unless a documented exception is approved. * Maintainers can validate public-demo desktop, mobile, failed-media, console error, page error, service-worker, and offline paths with Playwright. ### Out of Scope (Deferred) * Connecting the public demo to the local server, hooks, LLM endpoints, plan workpad, real replay data, or War Room federation - *Reason: the public demo remains a synthetic standalone artifact.* * Importing workspace packages into `public-demo/` - *Reason: standalone deployment must work without package install or workspace resolution.* * Expanding demo media beyond Session 01 approved or conditional scope - *Reason: Session 06 aligns current media; Session 07 owns release blockers.* * Promoting generated draft speech, music, SFX, HUD, achievement art, or optional video into runtime - *Reason: source, rights, metadata, accessibility, privacy, performance, and release gates remain incomplete.* * Full WCAG certification, hosted validation, analytics, public media hosting, or trusted erasure - *Reason: later phases own those surfaces.* *** ## 5. Technical Approach ### Architecture Add a public-demo media parity checker under `scripts/` with an explicit config for current demo media groups. The config should list battlefield mirrors, portraits, showcase art, install icons, speech clips, music tracks, manifest references, service-worker cache entries, and lazy-load exceptions. The checker should compare declared inventory with files, `public-demo/index.html`, `public-demo/sw.js`, `public-demo/manifest.webmanifest`, docs, and app-facing catalog records or documented standalone exceptions. Do not scan arbitrary media directories as a release source. The checker should use allowlisted repository-relative paths, reject `EXAMPLES/`, reject remote or absolute paths, preserve the public-demo no-workspace-import boundary, and emit stable report codes with redacted details. Large optional music should remain lazy-loaded unless the docs explicitly justify precaching it and the service worker cache version changes. Update the public-demo runtime files only where the audit finds drift or missing visible states. Existing browser behavior already covers splash entry, battlefield rendering, fallback art, speech clicks, music toggle/resume, and offline shell reload; this session tightens coverage around media inventory, failed local media requests, cache policy, and docs. ### Design Patterns * Explicit manifest over broad discovery: keeps demo media intentional and cache policy reviewable. * Catalog or exception first: every demo media group must map to a catalog record or a documented standalone exception with blockers. * Standalone artifact boundary: public-demo runtime files stay free of workspace imports and local server dependencies. * Service worker as contract: cache version, shell assets, runtime CDN origins, lazy music policy, and offline fallback are validated together. * Visible equivalent for audio: speech and music are optional cues, not the only way to understand demo state. ### Technology Stack * Static HTML, CSS, JavaScript, manifest, service worker, and local assets under `public-demo/`. * Node 20 ES modules for repository checks. * TypeScript app catalog fixtures using `@factionos/protocol` contracts. * Vitest for script and catalog helper coverage. * Playwright for desktop, mobile, service-worker, failed-media, and offline public-demo evidence. * Biome for format and lint checks. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/public-demo-media-config.mjs` | Declared public-demo media inventory, cache policy, lazy-load exceptions, docs references, and safe path prefixes. | \~180 | | `scripts/check-public-demo-media.mjs` | Root CLI for demo media file checks, catalog or exception mapping, service-worker policy, manifest checks, and boundary validation. | \~320 | | `tests/publicDemoMedia.test.ts` | Focused tests for demo media config, path rejection, cache policy, manifest checks, lazy music exceptions, and workspace import guards. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Add a root `media:demo:check` script and wire command naming consistently with other media gates. | \~4 | | `apps/web/src/data/mediaCatalog.ts` | Add or update public-demo current media records or explicit blocked/conditional context for speech, music, showcase, and install media. | \~120 | | `apps/web/tests/mediaCatalog.test.ts` | Update catalog expectations for current public-demo media and blocked generated replacements. | \~60 | | `public-demo/index.html` | Update relative media constants, visible fallback copy, or gesture-compatible audio/music handling if audit finds drift. | \~80 | | `public-demo/sw.js` | Align shell cache entries, cache version, runtime CDN policy, and lazy media exclusions with the demo media config. | \~40 | | `public-demo/manifest.webmanifest` | Verify or update icon references, scope, start URL, and PWA metadata if manifest drift is found. | \~20 | | `tests/e2e/public-demo.e2e.ts` | Expand browser coverage for media failures, speech/music behavior, service-worker readiness, and offline reload. | \~120 | | `scripts/README_scripts.md` | Document the public-demo media check, failure remediation, and cache-version rules. | \~60 | | `docs/media-assets.md` | Document Session 06 demo media parity, lazy music policy, catalog or exception coverage, and offline validation. | \~80 | | `public-demo/README_public-demo.md` | Update demo media behavior, current cache version, limitations, and validation commands. | \~70 | | `public-demo/docs_public-demo/static-artifact.md` | Update artifact boundary and service-worker/cache policy details. | \~60 | | `public-demo/docs_public-demo/validation.md` | Update media validation checklist, command set, and offline evidence requirements. | \~80 | | `.spec_system/specs/phase04-session06-public-demo-media-parity-and-offline-loading/implementation-notes.md` | Record decisions, command output, browser evidence, and remaining blockers during implementation. | \~100 | | `.spec_system/specs/phase04-session06-public-demo-media-parity-and-offline-loading/security-compliance.md` | Record privacy, cache, media provenance, and standalone-boundary review. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] A root command validates public-demo media inventory, cache policy, manifest paths, docs references, and standalone boundaries. * [ ] Current demo media groups map to app-facing catalog records or documented standalone exceptions with release blockers where appropriate. * [ ] `public-demo/sw.js` cache entries, cache version, and lazy-load exceptions match the declared demo media policy. * [ ] Public-demo runtime files keep relative paths and contain no workspace imports, local-server calls, remote repository media URLs, absolute local paths, or `EXAMPLES/` references. * [ ] Speech and music remain gesture-compatible, local to the demo, synthetic, visibly optional, and separated from full app file-backed audio policy. * [ ] Offline reload works after one online visit when shell or precache entries change. ### Testing Requirements * [ ] Vitest coverage written and passing for public-demo media check helpers. * [ ] Existing media gates still pass: `npm run battlefield:check`, `npm run media:visual:check`, and `npm run media:drafts:check`. * [ ] Public-demo Playwright desktop and mobile projects pass, including failed-media and offline shell paths. * [ ] Manual or recorded browser evidence confirms no page errors, console errors, failed local media requests, or mobile overlap regressions. ### Non-Functional Requirements * [ ] Checker output uses deterministic ordering and stable report codes. * [ ] Checks and docs do not expose provider secrets, raw prompts, account IDs, broad absolute paths, raw command bodies, local transcripts, tokens, or `EXAMPLES/` excerpts. * [ ] Large optional music remains lazy-loaded unless a documented cache budget exception is deliberately approved. * [ ] Public-demo first-load and offline behavior remain usable on supported desktop and mobile browser surfaces. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Treat `public-demo/` as a deployable static artifact, not an app package. * Use repository-relative paths in checks, docs, and catalog records. * Keep public-demo media synthetic and local; do not imply real local session data, hosted state, or War Room federation. * Bump service-worker cache version only when the shell or precache list changes. * Preserve existing music lazy-loading unless the implementation explicitly records why precaching is safe and necessary. ### Potential Challenges * Catalog coverage gaps: Add conditional public-demo records or documented standalone exceptions instead of treating uncataloged media as approved. * Service-worker stale cache drift: Validate cache version and shell asset list together so changed precache entries cannot ship with an old version. * Audio/music browser policy: Preserve user-gesture start, visible blocked state, and test mocks that avoid brittle autoplay assumptions. * Static artifact path prefixes: Keep `./` URLs and service-worker scope compatible with `/factionos/` local validation. ### Relevant Considerations * \[P03] **Redaction is boundary-specific**: demo checks, docs, and validation notes must avoid raw local paths, provider prompts, tokens, command bodies, and sensitive payloads. * \[P00] **Asset provenance gate**: public-demo media cannot become release-ready without source, rights, attribution, optimization, metadata, size, fallback, accessibility, privacy, and product-use evidence. * \[P02] **Explicit asset parity checks catch app/demo drift sooner**: reuse this pattern for public-demo media beyond battlefield assets. * \[P02-apps/web] **Responsive and accessibility debt**: browser validation must cover desktop and mobile layout, focusable controls, readable labels, and visible alternatives to audio. * \[P03] **Stable docs are the current contract**: public-demo README and docs must describe shipped media behavior and limitations accurately. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Service-worker cache changes can silently produce stale offline reloads. * Public-demo media can drift from catalog or docs while still appearing to work locally. * Optional speech and music can fail silently or imply state that is not visible without sound. * Static demo code can accidentally cross the workspace or local-server boundary. *** ## 9. Testing Strategy ### Unit Tests * Validate demo media config ordering, unique IDs, safe paths, cache policy, and lazy music exceptions. * Validate checker report codes for missing files, stale cache entries, missing manifest icons, remote paths, absolute paths, `EXAMPLES/` paths, and workspace imports. * Validate catalog fixtures for current public-demo media and blocked draft replacements. ### Integration Tests * Run `npm run media:demo:check`. * Run `npm run battlefield:check`. * Run `npm run media:visual:check`. * Run `npm run media:drafts:check`. * Run public-demo Playwright desktop and mobile projects. ### Manual Testing * Serve `public-demo/` under `/factionos/`, enter the demo, inspect screenshots, verify music toggle/resume behavior, verify speech clicks, and confirm no failed local media requests. * After one online visit, reload offline and confirm the splash shell appears. ### Edge Cases * Missing or failed battlefield background, hero standee, portrait, showcase image, speech clip, or music track. * Changed precache list without cache version bump. * Music tracks present in the playlist but incorrectly precached or missing from docs. * Manifest icon paths drift from actual files. * Public-demo runtime code imports workspace packages or references local server endpoints. *** ## 10. Dependencies ### External Libraries * Playwright: browser validation for desktop, mobile, service-worker, and offline paths. * Vitest: script and catalog helper tests. * Existing media tooling packages from Phase 04 promotion work; no new runtime dependency is planned. ### Internal Dependencies * `packages/protocol/src/mediaCatalog.ts`: media catalog contracts and validation vocabulary. * `apps/web/src/data/mediaCatalog.ts`: app-facing media catalog fixtures that can document public-demo media records. * `scripts/media-visual-promotion-config.mjs`: current visual media config and service-worker cache baseline. * `tests/e2e/support/browserGuards.ts`: browser guard helpers for console, page, failed-request, and offline checks. * `public-demo/`: standalone static demo artifact. ### Other Sessions * **Depends on**: `phase04-session02-typed-media-catalog-contracts`, `phase04-session04-visual-promotion-tooling-and-budgets`, `phase04-session05-browser-audio-runtime-and-controls` * **Depended by**: `phase04-session07-media-accessibility-privacy-and-performance-gates`, `phase04-session08-media-validation-and-documentation-closeout` *** ## 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase04-session06-public-demo-media-parity-and-offline-loading/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.