> 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/phase02-session05-battlefield-asset-and-public-demo-parity/spec.md).

# Session Specification

**Session ID**: `phase02-session05-battlefield-asset-and-public-demo-parity` **Phase**: 02 - Product Surface and 2D Battlefield Completion **Status**: Completed **Created**: 2026-05-29 **Package**: Cross-cutting (`apps/web`, `public-demo`, docs, scripts) **Package Stack**: React 18.3.1, Vite 6.4.2, TypeScript 5.9.3, Tailwind CSS 3.4.6, standalone public demo HTML/JS/CSS, Playwright 1.60.0, Node.js 20

***

## 1. Session Overview

This session keeps the approved app battlefield asset set and the standalone public demo in sync after the app-side battlefield interaction polish from Session 04. It validates that the six generated battlefield runtime assets exist in both surfaces, stay within the documented size budget, are cached correctly by the public demo service worker, and remain documented through stable provenance records.

The work is cross-cutting because the app owns runtime assets under `apps/web/public/battlefield/`, while the demo owns copied runtime assets, inline behavior, and service worker caching under `public-demo/`. The session should preserve the boundary that `public-demo/` is a no-build static artifact with synthetic data only and no imports from workspace packages.

The expected outcome is a checked parity contract: app and demo asset paths match, public demo battlefield behavior visibly mirrors the current app contract where the demo owns the behavior, offline reload still works after an online visit, and docs make provenance, cache, standalone, and excluded historical-media boundaries explicit.

***

## 2. Objectives

1. Validate app and public demo battlefield assets for existence, byte-size budget, copied parity, browser load behavior, service worker precache coverage, and provenance alignment.
2. Align public demo battlefield interaction, state labels, fallback behavior, and limitation copy with the current app contract while keeping the demo standalone.
3. Add deterministic checks for missing assets, app/demo drift, workspace import violations, and service worker cache-list drift.
4. Update stable battlefield, media, and public demo documentation so asset provenance, public demo constraints, and validation commands remain current.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase02-session01-product-surface-requirements-reconciliation` - Provides Phase 02 PRD, UX PRD, and product surface gap matrix.
* [x] `phase02-session02-cockpit-shell-and-navigation-cohesion` - Provides shell, command, and honest War Room boundary treatment used by demo copy.
* [x] `phase02-session03-hero-and-mission-workflow-completion` - Provides completed hero, mission, permission, plan, and overlay workflow context.
* [x] `phase02-session04-battlefield-state-and-interaction-polish` - Provides the app-side battlefield state, interaction, fallback, reduced-motion, and accessibility contract to mirror where relevant.

### Required Tools/Knowledge

* Node.js 20, npm workspace commands, and local dependencies installed from the workspace lockfile.
* Current asset record in `docs/media-assets.md` and current battlefield contract in `docs/battlefield.md`.
* Public demo standalone artifact rules in `public-demo/README_public-demo.md`, `public-demo/docs_public-demo/`, and `docs/public-demo-code-sharing.md`.
* Playwright e2e setup for `app-desktop`, `app-mobile`, `public-demo-desktop`, and `public-demo-mobile`.
* Current public demo service worker cache contract in `public-demo/sw.js`.

### Environment Requirements

* Repository root commands can run with Node.js 20 or newer.
* Browser validation can run through the existing Playwright webServer setup.
* No hosted services, local server data, LLM provider transfer, or Worker federation should be required for the public demo checks.

***

## 4. Scope

### In Scope (MVP)

* Maintainer can verify approved battlefield assets - Check app and public demo runtime paths, copied parity, byte sizes, documented budget, browser load behavior, and media provenance.
* Public demo user can understand the demo surface - Keep visible battlefield state, selection, fallback, roster, heatmap, standings, command, achievement, audio, and replay concepts aligned only where the standalone demo owns them.
* Public demo user can operate the battlefield safely - Preserve native hero controls, accessible names, selected state, empty-board clearing, state labels, asset fallbacks, and synthetic-data limitation copy.
* Maintainer can catch drift before release - Add deterministic checks for missing assets, app/demo copy mismatch, service worker precache drift, and accidental workspace imports into `public-demo/`.
* Reviewer can validate offline behavior - Keep service worker cache lists and cache version correct when shell assets change, and verify offline reload after one online visit.
* Stable docs stay current - Update battlefield, media asset, public demo, and sharing docs when behavior, paths, validation commands, or caveats change.

### Out of Scope (Deferred)

* Full media catalog, broad audio/visual pipeline, sprite atlas, or generated media catalog work - Reason: Phase 04 owns the larger media pipeline.
* Generating new battlefield art unless existing approved assets fail validation - Reason: Current generated set is approved; regeneration would need separate review and promotion.
* Importing `apps/web`, `@factionos/protocol`, or other workspace packages into `public-demo/` - Reason: The public demo is a static no-build artifact.
* Real local sessions, hooks, LLM endpoints, permission flow, plan workpad, persistent server state, or War Room federation in the public demo - Reason: These are excluded from the static demo or deferred to later phases.
* Deleting `EXAMPLES/`, historical build output, or legacy reports - Reason: Phase 08 owns final decommission gates.

***

## 5. Technical Approach

### Architecture

Keep the app battlefield asset paths owned by `apps/web/public/battlefield/` and the app runtime contract owned by `apps/web/src/components/battlefield/Battlefield.tsx`. Do not introduce new app dependencies or a shared package solely for the public demo.

Add a small root-level Node check that treats the asset list as explicit project data. The check should verify app and demo paths, byte sizes, app/demo copied parity, service worker precache references, public demo workspace import exclusions, and optional docs references. It should fail with clear messages instead of requiring browser inspection to find simple drift.

Keep public demo behavior inline in `public-demo/index.html`. Mirror only the current app-visible battlefield contract that the demo already owns: generated 2D background, hero standees, clamped positions, native hero buttons, selected state, visible state labels, asset fallbacks, and synthetic data boundaries. Preserve relative paths and service worker scope so the artifact works at `/` and under `/factionos/`.

### Design Patterns

* Explicit asset manifest: The parity check owns the list of expected app, demo, and reference paths.
* Standalone demo boundary: Demo code stays plain browser JavaScript and CDN React with no workspace imports.
* Native DOM controls: Demo hero tokens and empty-board interactions remain buttons with accessible names and selected state.
* Data attributes plus browser checks: Asset, state, fallback, and service worker behavior stay observable by Playwright tests.
* Local-first limitation copy: Demo copy must not imply real hooks, local server access, provider transfer, plan workpad, War Room federation, hosted replay, or persistent state.
* Conditional cache updates: Bump `CACHE_VERSION` only when precache entries change, and verify offline reload after one online visit.

### Technology Stack

* React 18.3.1 and CDN browser runtime in `public-demo/index.html`
* Vite 6.4.2 and React 18.3.1 for app-side browser validation
* TypeScript 5.9.3 for Playwright tests
* Node.js 20 filesystem helpers for asset checks
* Playwright 1.60.0 for desktop, mobile, and offline reload checks
* Biome 2.4.16 for formatting and lint checks

***

## 6. Deliverables

### Files to Create

| File                                                                                                    | Purpose                                                                                              | Est. Lines |
| ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase02-session05-battlefield-asset-and-public-demo-parity/implementation-notes.md` | Implementation evidence, asset measurements, validation commands, browser notes, and remaining risks | \~100      |
| `scripts/check-battlefield-assets.mjs`                                                                  | Deterministic asset parity, service worker precache, byte-budget, and public-demo boundary check     | \~180      |

### Files to Modify

| File                                          | Changes                                                                                                           | Est. Lines |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------- |
| `package.json`                                | Add a root command for the battlefield asset parity check                                                         | \~5        |
| `scripts/README_scripts.md`                   | Document the new asset parity check and expected usage                                                            | \~15       |
| `tests/e2e/support/browserGuards.ts`          | Strengthen asset request failure reporting for browser parity checks if needed                                    | \~40       |
| `public-demo/index.html`                      | Align battlefield state labels, fallback behavior, selection clearing, limitation copy, and standalone boundaries | \~180      |
| `public-demo/sw.js`                           | Verify or update shell asset precache list and cache version when entries change                                  | \~25       |
| `tests/e2e/public-demo.e2e.ts`                | Cover demo asset loading, state labels, selection, fallbacks, offline reload, and limitation copy                 | \~120      |
| `tests/e2e/app.e2e.ts`                        | Confirm app battlefield asset loading and visible state expectations used for parity                              | \~60       |
| `public-demo/README_public-demo.md`           | Document current demo battlefield, synthetic data, audio, offline, and limitation behavior                        | \~45       |
| `public-demo/docs_public-demo/validation.md`  | Add asset parity, service worker, desktop/mobile, and offline validation steps                                    | \~50       |
| `public-demo/docs_public-demo/maintenance.md` | Record when and how to run parity checks after app battlefield changes                                            | \~40       |
| `docs/public-demo-code-sharing.md`            | Clarify indirect sharing and no-import parity maintenance rules                                                   | \~30       |
| `docs/battlefield.md`                         | Update app/demo parity, validation, cache, and asset-copy guidance                                                | \~45       |
| `docs/media-assets.md`                        | Confirm or update asset measurements, promotion caveats, and validation command references                        | \~45       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] All six app battlefield runtime assets exist at `apps/web/public/battlefield/` and match the public demo copies by content or hash.
* [ ] Public demo service worker precache references the current battlefield assets, and `CACHE_VERSION` is bumped when the precache list changes.
* [ ] Public demo opens into a usable synthetic battlefield with native hero buttons, accessible names, selected state, visible state labels, and empty-board deselection.
* [ ] Public demo background and hero image failures have visible fallback treatment and do not leave a blank board or invisible token.
* [ ] Demo copy clearly states synthetic data and does not imply real hooks, LLM endpoints, plan workpad, local server connection, persistent server state, hosted replay, or War Room federation.
* [ ] The public demo remains no-build and does not import workspace packages.

### Testing Requirements

* [ ] Deterministic asset parity check passes from the repository root.
* [ ] Public demo Playwright checks cover desktop, mobile, offline reload, asset loading, selection, state labels, and limitation copy.
* [ ] App Playwright or focused browser checks confirm current app battlefield asset loading and state expectations used by the parity comparison.
* [ ] Focused Biome checks, `git diff --check`, ASCII validation, and LF validation pass for touched text files.

### Non-Functional Requirements

* [ ] Runtime battlefield set stays under the documented 3 MB initial asset budget per surface.
* [ ] Public demo remains static-host compatible at both `/` and a path prefix such as `/factionos/`.
* [ ] Public demo first-load media remains local to `public-demo/` except approved CDN framework and font dependencies.
* [ ] No quarantined `EXAMPLES/` media is imported, copied, transformed, or promoted.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] No new runtime dependency is introduced unless explicitly justified in implementation notes.

***

## 8. Implementation Notes

### Key Considerations

* The approved generated asset set is already measured at 668,358 bytes per surface in `docs/media-assets.md`; implementation should confirm the number rather than regenerate art.
* `public-demo/index.html` currently mirrors battlefield assets and helper behavior manually. Any parity change should keep the file standalone and plain browser JavaScript.
* `public-demo/sw.js` says to bump `CACHE_VERSION` whenever the precache list changes; content-only edits to already listed paths do not require list changes but still require offline reload validation.
* `docs/battlefield.md` makes Session 05 responsible for public-demo behavior parity, service worker cache updates, and app/demo asset-copy validation.
* The dirty worktree contains existing Phase 01 and Phase 02 artifacts. Keep edits scoped and do not revert unrelated changes.

### Potential Challenges

* Large inline demo file: Mitigate by changing focused battlefield helpers, copy blocks, and CSS instead of restructuring the whole artifact.
* Service worker cache persistence: Mitigate by using path-prefixed Playwright validation and fresh browser contexts for offline checks.
* Asset drift detection: Mitigate by comparing explicit app/demo paths and failing with concrete path and byte details.
* Documentation drift: Mitigate by routing stable docs through `docs/battlefield.md`, `docs/media-assets.md`, `docs/public-demo-code-sharing.md`, and demo docs.
* Demo copy overclaiming: Mitigate by checking for claims about real hooks, LLM endpoints, plan workpad, War Room federation, hosted replay, or persistent server state.

### Relevant Considerations

* \[P00] **Asset provenance gate**: This session directly verifies that battlefield and demo media remain generated or owned, documented, optimized, measured, and smoke-tested.
* \[P00-apps/web] **Responsive and accessibility debt**: Public demo desktop/mobile checks should verify nonzero board dimensions, reachable controls, state labels, and no obvious overlap.
* \[P01] **Stable docs are the current contract**: Update stable docs when parity behavior, cache behavior, or validation commands change.
* \[P01] **Local-first boundary is architectural**: The public demo must remain understandable without hosted services, local server connectivity, provider transfer, or remote federation.
* \[P01-apps/warroom+apps/web] **War Room is not wired into the web runtime yet**: Demo copy must not imply web-to-Worker federation or live rooms.
* \[P01] **Historical intake decommission remains gated**: Do not delete or promote `EXAMPLES/`; keep historical media evidence-only.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Public demo is a revisitable context where stale selected hero state, failed images, or service worker cache state can leave the board misleading after reload.
* Static demo controls can lose accessible names, focus behavior, selected state, or visible labels while mirroring app-side polish.
* Service worker and asset checks can hide stale or missing shell assets until users go offline.
* Demo copy can accidentally imply real local data, provider transfer, plan approval, or War Room federation even though the artifact is synthetic and standalone.

***

## 9. Testing Strategy

### Unit Tests

* Add a Node parity check for app/demo battlefield asset existence, byte sizes, copied parity, service worker precache references, no workspace imports, and documented budget.
* If the parity script exposes pure helpers, keep them simple and covered through script exit behavior rather than adding a new framework.

### Integration Tests

* Extend public demo Playwright checks for battlefield asset image presence, visible state labels, selected state, empty-board clear behavior, fallback paths where practical, and limitation copy.
* Extend app Playwright checks enough to confirm current battlefield image loading and state expectations still line up with demo parity assumptions.
* Keep browser guards strict for page errors, console errors, and failed local asset requests.

### Manual Testing

* Serve the public demo at `/factionos/`, enter the demo, inspect desktop and mobile battlefield layouts, select and clear heroes, and verify state labels remain readable.
* Verify the demo can reload offline after one online visit when service worker or shell asset behavior changes.
* Spot-check docs links from `public-demo/README_public-demo.md` and `docs/public-demo-code-sharing.md`.

### Edge Cases

* Missing app asset.
* Missing public demo copied asset.
* App/demo copied assets with different bytes or hashes.
* Public demo service worker omits a precached battlefield asset.
* Service worker cache version not bumped after a precache-list change.
* Path-prefixed static hosting under `/factionos/`.
* Browser offline reload after a fresh online visit.
* Public demo background or hero image failure.
* Public demo selected hero removed or dismissed by synthetic loop.
* Accidental import of workspace packages into `public-demo/`.

***

## 10. Dependencies

### External Libraries

* No new external libraries planned.

### Other Sessions

* **Depends on**: `phase02-session01-product-surface-requirements-reconciliation`, `phase02-session02-cockpit-shell-and-navigation-cohesion`, `phase02-session03-hero-and-mission-workflow-completion`, `phase02-session04-battlefield-state-and-interaction-polish`
* **Depended by**: `phase02-session06-settings-replay-notifications-and-scan-ux`, `phase02-session07-product-surface-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/phase02-session05-battlefield-asset-and-public-demo-parity/spec.md?ask=<question>&goal=<endgoal>
```

`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.