> 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/public-demo/docs_public-demo/validation.md). # Validation Validate the public demo as a static browser artifact. Do not assume a root-path local serve is enough. ## Static File Checks From the repository root, run the deterministic asset parity check before browser validation: ```bash npm run media:gates:check npm run media:demo:check npm run battlefield:check ``` `npm run media:gates:check` verifies cross-surface media release readiness, including docs references, browser evidence tokens, reduced motion coverage, failed media fallback coverage, privacy redaction, lazy-loading policy, and offline reload evidence. `npm run media:demo:check` verifies public-demo media inventory, app catalog coverage, docs references, manifest entries, service-worker cache policy, lazy music exclusions, MP3 durations, byte budgets, and runtime workspace import exclusions. `npm run battlefield:check` verifies the six app/demo battlefield runtime assets, app/demo hashes, documented byte budgets, public demo service-worker precache entries, and same-origin shell asset existence. Repository-relative media paths checked by `npm run media:demo:check`: ``` public-demo/icon-192.png public-demo/icon-512.png public-demo/icon-maskable-512.png public-demo/assets/battlefield/background.webp public-demo/assets/battlefield/heroes/orc.webp public-demo/assets/battlefield/heroes/human.webp public-demo/assets/battlefield/heroes/elf.webp public-demo/assets/battlefield/heroes/undead.webp public-demo/assets/battlefield/heroes/lobster.webp public-demo/assets/showcase/heroes-banner.jpg public-demo/assets/portraits/orc.jpg public-demo/assets/portraits/human.jpg public-demo/assets/portraits/elf.jpg public-demo/assets/portraits/undead.jpg public-demo/assets/portraits/lobster.jpg public-demo/assets/speech/elf-elunebewithyou-01.mp3 public-demo/assets/speech/elf-elunebewithyou-02.mp3 public-demo/assets/speech/elf-forkalimdor-01.mp3 public-demo/assets/speech/elf-forkalimdor-02.mp3 public-demo/assets/speech/human-for_the_king-01.mp3 public-demo/assets/speech/human-for_the_king-02.mp3 public-demo/assets/speech/human-yes_mlord-01.mp3 public-demo/assets/speech/human-yes_mlord-02.mp3 public-demo/assets/speech/orc-whachyawanmetokill-01.mp3 public-demo/assets/speech/orc-whachyawanmetokill-02.mp3 public-demo/assets/speech/orc-zugzug-01.mp3 public-demo/assets/speech/orc-zugzug-02.mp3 public-demo/assets/speech/undead-iamsworn-01.mp3 public-demo/assets/speech/undead-iamsworn-02.mp3 public-demo/assets/speech/undead-ihunger-01.mp3 public-demo/assets/speech/undead-ihunger-02.mp3 public-demo/assets/music/01_mythic_battle_theme_take_1.mp3 public-demo/assets/music/02_mythic_battle_theme_take_2.mp3 public-demo/assets/music/03_noble_heroic_oath_take_1.mp3 public-demo/assets/music/04_noble_heroic_oath_take_2.mp3 public-demo/assets/music/05_dark_tribal_war_march_take_1.mp3 public-demo/assets/music/06_dark_tribal_war_march_take_2.mp3 public-demo/assets/music/07_elven_moonlit_overture_take.mp3 public-demo/assets/music/08_elven_guardian_hymn_take.mp3 public-demo/assets/music/09_elven_blades_dance_take.mp3 public-demo/assets/music/10_undead_necropolis_theme_take.mp3 public-demo/assets/music/11_undead_lament_of_the_hollow_crown_take.mp3 public-demo/assets/music/12_undead_graveborn_war_march_take.mp3 ``` Confirm these files exist before deployment: * `index.html` * `sw.js` * `manifest.webmanifest` * `icon-192.png` * `icon-512.png` * `icon-maskable-512.png` * `assets/battlefield/background.webp` * `assets/battlefield/heroes/orc.webp` * `assets/battlefield/heroes/human.webp` * `assets/battlefield/heroes/elf.webp` * `assets/battlefield/heroes/undead.webp` * `assets/battlefield/heroes/lobster.webp` * `assets/showcase/heroes-banner.jpg` * `assets/portraits/orc.jpg` * `assets/portraits/human.jpg` * `assets/portraits/elf.jpg` * `assets/portraits/undead.jpg` * `assets/portraits/lobster.jpg` * `assets/speech/elf-elunebewithyou-01.mp3` * `assets/speech/elf-elunebewithyou-02.mp3` * `assets/speech/elf-forkalimdor-01.mp3` * `assets/speech/elf-forkalimdor-02.mp3` * `assets/speech/human-for_the_king-01.mp3` * `assets/speech/human-for_the_king-02.mp3` * `assets/speech/human-yes_mlord-01.mp3` * `assets/speech/human-yes_mlord-02.mp3` * `assets/speech/orc-whachyawanmetokill-01.mp3` * `assets/speech/orc-whachyawanmetokill-02.mp3` * `assets/speech/orc-zugzug-01.mp3` * `assets/speech/orc-zugzug-02.mp3` * `assets/speech/undead-iamsworn-01.mp3` * `assets/speech/undead-iamsworn-02.mp3` * `assets/speech/undead-ihunger-01.mp3` * `assets/speech/undead-ihunger-02.mp3` * `assets/music/01_mythic_battle_theme_take_1.mp3` * `assets/music/02_mythic_battle_theme_take_2.mp3` * `assets/music/03_noble_heroic_oath_take_1.mp3` * `assets/music/04_noble_heroic_oath_take_2.mp3` * `assets/music/05_dark_tribal_war_march_take_1.mp3` * `assets/music/06_dark_tribal_war_march_take_2.mp3` * `assets/music/07_elven_moonlit_overture_take.mp3` * `assets/music/08_elven_guardian_hymn_take.mp3` * `assets/music/09_elven_blades_dance_take.mp3` * `assets/music/10_undead_necropolis_theme_take.mp3` * `assets/music/11_undead_lament_of_the_hollow_crown_take.mp3` * `assets/music/12_undead_graveborn_war_march_take.mp3` ## Browser Smoke Checks Run these checks on desktop: 1. Load `https://demo.faction-os.com/` or the path-prefixed local validation URL. 2. Confirm the splash renders with artwork. 3. Enter the demo. 4. Confirm the 2D battlefield board has nonzero dimensions. 5. Confirm heroes render on the battlefield with state badges, accessible names, `aria-pressed`, and selected labels. 6. Confirm the battlefield background image loads and the board exposes `data-background-state`, `data-connection-state`, and `data-hero-count`. 7. Confirm failed media routes show visible fallback terrain or faction initials and do not leak sensitive diagnostics. 8. Confirm reduced motion keeps hero state badges, selected labels, and board meaning visible. 9. Confirm empty terrain clears the selected hero and token clicks do not trigger empty-board clearing. 10. Confirm the top-right music icon shows the stop state after entering the demo, then stops and resumes the same track position when toggled. 11. Click the orc, human, elf, and delayed undead reinforcement heroes on the battlefield and in the roster; confirm one matching faction voice line plays for each click. 12. Confirm the mission log has search and state filters. 13. Open and close the trophy room. 14. Open and close the mission heatmap. 15. Open and close faction standings. 16. Open and close the command palette. 17. Open and close keyboard shortcuts. 18. Confirm visible copy states the demo is synthetic and has no local server, LLM endpoints, plan workpad, persistent server state, hosted replay, or War Room federation. 19. Confirm no page errors, console errors, failed local requests, or failed local asset requests are reported by the browser guards. Run these checks on mobile or mobile emulation: 1. Load `https://demo.faction-os.com/` or the path-prefixed local validation URL. 2. Enter the demo by tapping the splash button. 3. Confirm the 2D battlefield board has nonzero dimensions. 4. Confirm heroes render with nonzero token dimensions and readable state badges. 5. Confirm the single-column layout orders battlefield before mission log. 6. Confirm the mission log and roster remain scrollable. 7. Confirm reduced motion keeps media meaning visible. 8. Confirm no failed local asset requests are reported by the browser guards. ## Phase 08 Session 06 Mobile And Accessibility Evidence Session 06 adds local browser and component evidence for public-demo mobile and accessibility behavior. The public-demo evidence checks: * splash and cockpit horizontal overflow * desktop/mobile battlefield dimensions and hero keyboard activation * mission log search focus, roster visibility, and mobile section ordering * music control visible state and blocked voice-line visible equivalents * synthetic/no-server/no-LLM/no-plan-workpad/no-War-Room limitation copy * reduced-motion battlefield meaning * service-worker offline shell after one online visit * accessible names, text fit, and privacy-safe visible text where feasible Run: ```bash npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts ``` This is local browser evidence using Playwright desktop and Pixel 7 emulation. It is not formal WCAG certification, physical-device mobile certification, third-party audit evidence, production-hosted validation, hosted replay validation, or proof that local server, War Room, hooks, LLM endpoints, or plan workpad behavior exists in the static artifact. ## Service Worker Checks After one successful online load: 1. Confirm `navigator.serviceWorker.ready` resolves. 2. Confirm the registration scope is the public demo path. 3. Confirm the active service worker is activated and the cache version in `sw.js` matches the expected release value. The Session 06 value is `factionos-demo-v9`. 4. Switch the browser context offline. 5. Reload the page. 6. Confirm the splash shell appears from cache. 7. Switch the browser context back online before the next test. ## Phase 08 Session 07 Media And Cache Gate Session 07 does not change public-demo precache content. The current cache version remains `factionos-demo-v9`, and background music remains lazy-loaded outside `SHELL_ASSETS`. Release-facing public-demo media posture: * Battlefield runtime WebP files remain the only approved release-ready media group after `npm run battlefield:check` and `npm run media:gates:check`. * Speech clips, portraits, showcase art, install icons, and background music remain conditional demo-local media with source, rights, attribution, metadata, fallback, accessibility, privacy, and budget blockers. * Generated drafts, raw provider staging, and quarantined `EXAMPLES/` media must not be imported, transformed, precached, lazy-loaded, or promoted by the public demo. * If any future edit changes `SHELL_ASSETS`, the service-worker cache version must be reviewed or bumped and `npm run media:demo:check`, `npm run battlefield:check`, and `git diff --check` must be rerun. ## Production URL Smoke Phase 08 production-hosted validation uses the root hosted smoke command: ```bash npm run release:hosted-smoke -- --target public-demo ``` The command fetches the configured production public demo URL and same-origin `sw.js` with bounded timeouts. It validates shell markers, service-worker availability, current cache-version evidence, absence of local endpoint leak markers, and absence of raw repository asset leak markers. JSON output is safe for evidence capture because it contains target ids, safe hostnames, statuses, booleans, timing buckets, docs paths, and issue codes only. `npm run release:hosted-smoke -- --no-network --target public-demo` records an unavailable no-claim summary and must not be described as deployed Pages validation. Browser Playwright evidence, local public-demo media gates, and service-worker offline checks remain prerequisites for release confidence, but they are separate from production-hosted URL smoke evidence. ## Phase 08 Session 08 Public-Demo Release-Candidate Evidence Session 08 records local public-demo release evidence in `.spec_system/archive/phases/phase_08/release_candidate_validation_record.md`. `CI=1 FACTIONOS_AUTH_TOKEN= VITE_FACTIONOS_AUTH_TOKEN= FACTIONOS_E2E_SERVER_PORT=2770 FACTIONOS_E2E_WEB_PORT=6195 FACTIONOS_E2E_DEMO_PORT=9103 npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts` passed with 14 tests passed and 2 skipped. `npm run media:demo:check`, `npm run media:gates:check`, and `npm run battlefield:check` also passed during Session 08 media revalidation. This does not clear deployed Pages validation. The live hosted public-demo smoke reported `SENSITIVE_OUTPUT`, while no-network smoke records only unavailable/no-claim evidence. Keep production URL smoke as blocked/no-claim until the deployed artifact is updated or the smoke scanner is revised with tests and the live command passes. ## Visual Checks Inspect screenshots for: * missing splash art * missing portraits * zero-width battlefield * overlapping header controls * clipped buttons * unreadable modal content * mobile content trapped off-screen ## Automation Notes Playwright or agent-browser checks should cover the Cloudflare Pages production URL when available. Local compatibility checks should also use a path-prefixed server such as: ``` http://127.0.0.1:8101/factionos/ ``` Screenshot checks are the primary visual review path for the 2D battlefield. Treat page errors and failed requests as blockers. Phase 02 Session 07 automated evidence covers public demo desktop/mobile projects, splash screenshots, cockpit screenshots, battlefield board screenshots, desktop overlay screenshots, service-worker readiness, offline shell reload, limitation copy, and browser guard assertions. Manual review also confirmed the small-viewport header no longer overlaps after the mobile badge fix. ## Required Command Checks Run: ```bash npm run media:gates:check npm run battlefield:check npm run media:demo:check npx biome check public-demo tests/e2e/public-demo.e2e.ts npm run release:hosted-smoke -- --no-network --target public-demo npm run test:e2e -- --project=public-demo-desktop --project=public-demo-mobile tests/e2e/public-demo.e2e.ts git diff --check -- public-demo tests/e2e/public-demo.e2e.ts docs/media-assets.md scripts/README_scripts.md ``` If the docs folder is ignored by Biome, `git diff --check` is still required. --- # 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/public-demo/docs_public-demo/validation.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.