> 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-session07-media-accessibility-privacy-and-performance-gates/spec.md). # Session Specification **Session ID**: `phase04-session07-media-accessibility-privacy-and-performance-gates` **Phase**: 04 - Media Catalog and Audio/Visual Pipeline **Status**: Complete **Created**: 2026-05-29 **Package**: cross-cutting **Package Stack**: Node 20 ES modules, TypeScript catalog fixtures, React 18, Vite, static public demo, Playwright, Vitest, Biome *** ## 1. Session Overview This session adds release-grade gates for Phase 04 media accessibility, privacy, metadata, lazy-loading, fallback behavior, and performance budgets. It turns the current catalog, promotion tooling, audio runtime, and public demo media checks into a final blocker-oriented gate before Phase 04 closeout. The work is cross-cutting because media release readiness spans repository scripts, app catalog records, web and public-demo browser behavior, release docs, privacy docs, and the media gap matrix. The session should reuse the existing explicit-config pattern from `media:visual:check` and `media:demo:check`, then add one root media gate that verifies all media records remain accessible, privacy-safe, cache-aware, fallback-backed, and budgeted before release claims can move forward. This session does not promote new media or certify full WCAG compliance. It preserves the Phase 04 boundary: battlefield runtime media is approved, many tracked media groups remain conditional, generated drafts remain non-runtime, and `EXAMPLES/` media remains quarantined evidence only. *** ## 2. Objectives 1. Add a deterministic media release gate that validates accessibility, privacy, metadata, lazy-loading, fallback, budget, and blocker coverage. 2. Ensure media catalog records, visual promotion config, public-demo config, and docs agree on which media is approved, conditional, planned, rejected, prototype-only, or deferred. 3. Expand browser validation coverage for media failure paths, reduced motion, audio visible equivalents, offline/cache behavior, and desktop/mobile overlap risk. 4. Update release, media, public-demo, and privacy docs so current blockers and validation commands are explicit before Session 08 closeout. *** ## 3. Prerequisites ### Required Sessions * [x] `phase04-session02-typed-media-catalog-contracts` - provides media catalog contracts, app-facing fixtures, validation helpers, and release-ready grouping. * [x] `phase04-session03-draft-asset-generation-and-source-capture` - provides non-runtime generated draft records, redacted briefs, provider provenance, and release blockers. * [x] `phase04-session04-visual-promotion-tooling-and-budgets` - provides visual promotion config, byte budgets, metadata checks, path checks, and app/demo parity gates. * [x] `phase04-session05-browser-audio-runtime-and-controls` - provides opt-in full app audio controls, visible equivalents, cleanup-safe synthetic cues, and blocked file-backed audio policy. * [x] `phase04-session06-public-demo-media-parity-and-offline-loading` - provides public-demo media inventory, catalog coverage, service-worker cache policy, lazy music decisions, and offline validation evidence. ### Required Tools/Knowledge * Node 20 and npm workspace scripts. * Existing `npm run media:check`, `media:visual:check`, `media:demo:check`, `media:drafts:check`, and `battlefield:check` gates. * Media catalog contract fields in `packages/protocol/src/mediaCatalog.ts`. * App-facing catalog fixtures and helpers in `apps/web/src/data/mediaCatalog.ts` and `apps/web/src/lib/mediaCatalog.ts`. * Playwright desktop/mobile projects for the app and public demo. * Privacy, release, and public-demo documentation requirements. ### Environment Requirements * Run commands from the repository root. * No provider credentials are required. * No hosted service, analytics, War Room federation, public replay hosting, or remote media storage is required. * Browser validation may use local dev/static servers only. * `EXAMPLES/` remains quarantined and must not be copied, transformed, imported, cached, or used as generation input. *** ## 4. Scope ### In Scope (MVP) * Maintainers can run one root media release gate - validate accessibility, privacy, metadata, fallback, lazy-loading, budget, and blocker coverage across catalog, visual, public-demo, draft, and docs inputs. * Maintainers can block release claims for unsafe media - fail on unknown provenance, missing attribution, pending metadata without blockers, missing fallback, inaccessible audio-only meaning, oversized files, unsupported formats, unsafe paths, or missing docs references. * Demo and app users can understand media-driven UI without audio, motion, or successful media loads - expand browser checks for visible equivalents, reduced motion, failed media, and mobile layout. * Maintainers can verify sensitive data stays out of media surfaces - check docs, catalog records, checker output, browser errors, and validation notes for raw prompts, tokens, provider prompts, command bodies, broad local paths, and `EXAMPLES/` excerpts. * Maintainers can keep public-demo cache and lazy-loading policy release-safe - confirm service-worker entries, cache version, optional music lazy-loading, offline reload, and no workspace imports remain aligned. ### Out of Scope (Deferred) * Full WCAG certification - *Reason: this session adds release gates and smoke evidence, not a formal external accessibility audit.* * Promoting generated draft media into runtime - *Reason: promotion requires separate source, rights, attribution, metadata, accessibility, privacy, and budget approval.* * Hosted media transfer, analytics, public asset hosting, public replay hosting, or account media libraries - *Reason: later phases own hosted consent, authorization, retention, and erasure design.* * Phase 08 trusted erasure implementation - *Reason: this session can document the release blocker, but unified erasure is a later phase.* * Replacing existing conditional public-demo speech, music, portraits, brand, or showcase media - *Reason: Session 07 gates current state; new assets need their own approval path.* *** ## 5. Technical Approach ### Architecture Add a repository-level media release gate under `scripts/` using the same explicit manifest approach as the current visual and public-demo gates. The gate should import or read stable media inputs, validate a small release-gate config, and compare catalog records, promotion config, public-demo inventory, draft records, docs, and browser evidence requirements with deterministic issue codes. The gate should treat approved media differently from conditional, planned, prototype-only, rejected, unknown, and deferred media. Approved records must have complete accessibility, privacy, metadata, fallback, optimization, byte budget, browser-support, product-use, and docs coverage. Non-approved records must retain explicit blockers and must not appear as release-ready in docs, runtime cache lists, public-demo behavior, or generated draft outputs. Browser validation should remain focused. Extend existing Playwright support to assert visible fallback states, reduced-motion-safe meaning, optional audio equivalents, failed local media handling, public-demo offline behavior, and no unexpected console/page/failed-request leaks on supported desktop and mobile surfaces. ### Design Patterns * Explicit gate config over broad discovery: keeps release rules reviewable and avoids accidental promotion. * Stable report codes: every failure should be actionable and deterministic. * Approved-versus-blocked split: approved records must be complete; blocked records must keep visible blockers. * Boundary redaction: checker output, docs, tests, and browser errors must not expose secrets, broad local paths, provider prompts, or raw historical excerpts. * Browser evidence as release input: desktop/mobile smoke checks prove that media failure, reduced-motion, audio-off, and offline paths remain usable. ### Technology Stack * Node 20 ES modules for repository gates. * TypeScript media catalog fixtures in `apps/web`. * React 18, Vite, Zustand, Web Audio API, and static public-demo assets. * Vitest for release-gate helper and catalog coverage. * Playwright for app and public-demo desktop/mobile smoke evidence. * Biome for formatting and linting. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/media-release-gates-config.mjs` | Declared release-gate rules for matrix rows, statuses, docs, accessibility, privacy, metadata, lazy-loading, budgets, and browser evidence. | \~220 | | `scripts/check-media-release-gates.mjs` | Root CLI that validates catalog records, existing media gate configs, docs, blocker state, redaction policy, and release readiness. | \~360 | | `tests/mediaReleaseGates.test.ts` | Vitest coverage for release-gate config, issue codes, approved versus blocked records, sensitive-value redaction, and docs/budget failures. | \~220 | ### Files to Modify | File | Changes | Est. Lines | | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Add a root `media:gates:check` script and preserve existing gate names. | \~4 | | `apps/web/src/data/mediaCatalog.ts` | Add or tighten S0407 gate notes for accessibility, privacy, metadata, fallback, lazy-loading, and release blockers. | \~120 | | `apps/web/src/lib/mediaCatalog.ts` | Add deterministic summaries for accessibility, privacy, fallback, metadata, and release-blocker coverage. | \~90 | | `apps/web/tests/mediaCatalog.test.ts` | Update catalog expectations for release readiness, blocked records, fallback coverage, and S0407 gate summaries. | \~90 | | `tests/e2e/support/browserGuards.ts` | Add helpers for media-failure, reduced-motion, console/page-error, failed-request, and privacy-safe error assertions. | \~80 | | `tests/e2e/app.e2e.ts` | Expand app desktop/mobile media checks for fallback states, optional audio visible equivalents, reduced motion, and no layout overlap. | \~120 | | `tests/e2e/public-demo.e2e.ts` | Expand public-demo checks for failed media, audio/music optional states, service-worker readiness, offline reload, and mobile behavior. | \~120 | | `scripts/README_scripts.md` | Document the media release gate, failure remediation, and required gate ordering. | \~70 | | `docs/media-assets.md` | Document Session 07 media gate policy, blockers, supported commands, and approved versus conditional state. | \~100 | | `docs/privacy-and-security.md` | Document media privacy gate coverage and sensitive-data exclusions. | \~70 | | `docs/release.md` | Add `media:gates:check` to release readiness and update public-demo cache/audio/media blockers. | \~80 | | `public-demo/README_public-demo.md` | Update demo media accessibility, fallback, lazy-loading, and offline validation notes. | \~60 | | `public-demo/docs_public-demo/validation.md` | Update public-demo media validation checklist and evidence requirements. | \~80 | | `.spec_system/specs/phase04-session07-media-accessibility-privacy-and-performance-gates/implementation-notes.md` | Record decisions, command output, browser evidence, and unresolved blockers during implementation. | \~120 | | `.spec_system/specs/phase04-session07-media-accessibility-privacy-and-performance-gates/security-compliance.md` | Record accessibility, privacy, metadata, release-blocker, and quarantine review. | \~90 | *** ## 7. Success Criteria ### Functional Requirements * [ ] A root `media:gates:check` command validates media release readiness with deterministic ordering and stable issue codes. * [ ] Approved catalog records must include complete accessibility, privacy, metadata, fallback, optimization, byte-size, browser-support, product-use, and docs evidence. * [ ] Conditional, planned, prototype-only, rejected, unknown, and deferred records keep explicit blockers and cannot appear as release-ready. * [ ] Public-demo cache policy, service-worker version, lazy music exclusions, offline reload, manifest paths, and standalone boundaries remain validated. * [ ] App and public-demo browser tests cover visible fallback states, optional audio meaning, reduced motion, desktop/mobile layout, and media failure paths. * [ ] Checker output, docs, validation notes, and browser errors do not expose raw prompts, provider prompts, tokens, command bodies, broad local paths, raw request bodies, or `EXAMPLES/` excerpts. ### Testing Requirements * [ ] Vitest coverage written and passing for release-gate helpers and catalog summaries. * [ ] Existing media gates still pass: `npm run media:check`, `npm run media:visual:check`, `npm run media:demo:check`, `npm run media:drafts:check`, and `npm run battlefield:check`. * [ ] Focused Playwright app and public-demo desktop/mobile projects pass for media failure and fallback scenarios. * [ ] Manual or recorded evidence confirms no page errors, console errors, failed local media requests, privacy leaks, or mobile overlap regressions. ### Non-Functional Requirements * [ ] Release-gate checks avoid broad filesystem scans and use explicit repository-relative paths. * [ ] Large optional music, future video, and other optional media remain lazy-loaded unless a documented budget exception is approved. * [ ] Metadata, source, rights, attribution, fallback, and browser-support blockers remain visible until closed. * [ ] The gate can run locally without provider credentials or hosted services. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Treat release gates as blockers, not promotion mechanisms. * Reuse current explicit media configs instead of scanning arbitrary media directories. * Keep conditional public-demo speech, music, portraits, showcase, and install media blocked until all required evidence exists. * Browser audio and music must remain optional and visibly equivalent. * Avoid sensitive absolute paths in checker details, docs, browser errors, and validation notes. ### Potential Challenges * State drift between catalog, docs, promotion config, and public-demo config: centralize expected row/status coverage in the new release-gate config. * False release readiness for conditional media: require blockers for every non-approved record and fail if docs imply approval. * Browser failure-path brittleness: prefer stable media-failure hooks and existing browser guard helpers over timing-sensitive assertions. * Metadata tool availability: distinguish unsupported local tools from release approval and keep pending metadata blockers visible. ### Relevant Considerations * \[P03] **Redaction is boundary-specific**: media catalog records, checker output, browser errors, replay/export adjacency, and docs need explicit minimization. * \[P00] **Asset provenance gate**: no media should ship from quarantined or unknown sources without source, rights, attribution, metadata, optimization, fallback, accessibility, privacy, and budget review. * \[P02-apps/web] **Responsive and accessibility debt**: browser validation must cover mobile, focus behavior, reduced motion, contrast, visible equivalents, and non-overlapping text. * \[P03] **Stable docs are the current contract**: release, media, privacy, and public-demo docs must describe current shipped behavior and blockers. * \[P03] **Phase complete is not release complete**: media closeout does not imply hosted collaboration, analytics, mobile certification, trusted erasure, or decommission readiness. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * A gate can pass while docs or catalog records imply conditional media is release-ready. * Media failure, muted audio, reduced motion, or offline reload can silently remove meaning from the app or public demo. * Checker output, validation notes, or browser errors can leak sensitive local paths, raw prompts, provider context, or historical excerpts. * Optional large media can accidentally become precached or eagerly loaded. *** ## 9. Testing Strategy ### Unit Tests * Validate release-gate config ordering, row coverage, status policy, docs references, and blocker requirements. * Validate checker issue codes for missing accessibility, privacy, metadata, fallback, budget, docs, lazy-loading, and sensitive-value cases. * Validate catalog helper summaries for release-ready, blocked, fallback, privacy, metadata, and accessibility coverage. ### Integration Tests * Run `npm run media:gates:check`. * Run `npm run media:check`. * Run `npm run media:visual:check`. * Run `npm run media:demo:check`. * Run `npm run media:drafts:check`. * Run `npm run battlefield:check`. ### Manual Testing * Run focused Playwright app desktop/mobile media scenarios and inspect screenshots for non-overlapping text, visible failure states, and reduced motion meaning. * Run focused public-demo desktop/mobile scenarios, verify audio/music remains optional, and confirm offline reload after one online visit. ### Edge Cases * Approved record with missing fallback, pending metadata, or missing docs. * Conditional record with no release blocker. * Large optional music track accidentally precached. * Public-demo service-worker cache list changes without version alignment. * Browser audio unavailable, blocked, muted, or failed. * Image load failure for battlefield, portrait, showcase, icon, or hero media. * Checker details containing absolute paths, tokens, provider prompts, raw command bodies, or `EXAMPLES/` excerpts. *** ## 10. Dependencies ### External Libraries * Playwright: browser validation for desktop, mobile, failed media, reduced motion, service-worker, and offline paths. * Vitest: script, catalog helper, and config tests. * Existing media tooling packages from Phase 04; no new runtime dependency is planned. ### Internal Dependencies * `packages/protocol/src/mediaCatalog.ts`: catalog record contract and release-ready validation vocabulary. * `apps/web/src/data/mediaCatalog.ts`: app-facing media catalog fixtures. * `apps/web/src/lib/mediaCatalog.ts`: app-facing catalog helper summaries. * `scripts/media-visual-promotion-config.mjs`: visual media gate inputs. * `scripts/public-demo-media-config.mjs`: public-demo media gate inputs. * `assets/generated/phase04/draft-generation-manifest.json`: draft generation blockers and non-runtime records. * `tests/e2e/support/browserGuards.ts`: browser guard helpers. ### Other Sessions * **Depends on**: `phase04-session02-typed-media-catalog-contracts`, `phase04-session03-draft-asset-generation-and-source-capture`, `phase04-session04-visual-promotion-tooling-and-budgets`, `phase04-session05-browser-audio-runtime-and-controls`, `phase04-session06-public-demo-media-parity-and-offline-loading` * **Depended by**: `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-session07-media-accessibility-privacy-and-performance-gates/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.