> 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/static-artifact.md). # Public Demo Static Artifact `public-demo/` is maintained as a standalone static artifact. It is meant to be served directly by the official Cloudflare Pages project without a build step, package install, Node server, Vite server, or workspace dependency resolution. The artifact is intentionally separate from the full application in `apps/web`. It demonstrates the product shape with synthetic client-side data, while the full app owns the real local server, WebSocket connection, persisted stores, CLI hook integration, War Room integration, and LLM-backed features. ## Artifact Boundary The deployable unit is the `public-demo/` directory itself. The official Cloudflare Pages project publishes this directory as the build output: * `index.html` - single-file React, Tailwind, demo state, helpers, event loop, and UI. * `sw.js` - service worker for shell precache and runtime CDN caching. * `manifest.webmanifest` - installable PWA metadata. * `icon-*.png` - app and install icons. * `assets/battlefield/*.webp` - generated 2D battlefield and hero standee art served from the demo artifact. * `assets/showcase/heroes-banner.jpg` - splash artwork served from the demo artifact. * `assets/portraits/*.jpg` - faction portraits served from the demo artifact. * `assets/speech/*.mp3` - click-triggered unit voice lines served from the demo artifact. * `assets/music/*.mp3` - background music served from the demo artifact. * `README_public-demo.md` and `docs_public-demo/` - demo-specific docs. Files outside `public-demo/` are not required at runtime after the artifact is uploaded. The demo can be copied to another static host as a directory and served as-is. ## Runtime Dependencies The first online visit loads these external browser dependencies: * React and ReactDOM from `https://esm.sh`. * Tailwind browser v4 runtime from `https://cdn.jsdelivr.net`. * Fonts from `https://fonts.googleapis.com` and `https://fonts.gstatic.com`. Demo art, icons, voice lines, and background music are local to the artifact, so first-load media rendering does not depend on `raw.githubusercontent.com` or other repository file URLs. After the first successful visit, the service worker can cache the shell and allowed CDN responses. That supports offline reloads after the browser has installed and activated the service worker. It does not make the first-ever visit offline-capable because the browser must fetch `index.html` before the service worker exists for that origin and path. ## Cloudflare Pages Shape The official deployment serves the artifact at a Cloudflare Pages site root. The current project is `factionos-public-demo`; production traffic uses: ``` https://demo.faction-os.com/ ``` The project Pages domain is `https://factionos-public-demo.pages.dev/`. Wrangler deploys also produce per-deployment preview URLs under `https://.factionos-public-demo.pages.dev/`. The project is currently not connected to a Git provider. Deploy by uploading the static directory with Wrangler: ```bash CLOUDFLARE_ACCOUNT_ID= npx wrangler pages deploy public-demo \ --project-name=factionos-public-demo \ --branch=main \ --commit-hash="$(git rev-parse HEAD)" \ --commit-message="$(git log -1 --pretty=%s)" ``` If Git integration is enabled later, use these Cloudflare Pages settings: | Setting | Value | | ---------------------- | ----------------------- | | Production branch | `main` | | Root directory | repository root / blank | | Build command | `exit 0` | | Build output directory | `public-demo` | If the Cloudflare Pages root directory is changed to `public-demo`, the build output directory must change to `.` so the site root still contains `index.html`. ## Path Prefix Compatibility All same-origin demo paths use relative URLs such as `./sw.js`, `./manifest.webmanifest`, and `./assets/...`. The service worker registers with `scope: "./"`, so the artifact still works under a fallback repository path prefix like `/factionos/`. ## What The Demo Does Not Do The demo does not import or execute code from these main project areas: * `apps/web` * `apps/server` * `apps/hooks` * `apps/cli` * `apps/warroom` * `apps/adapters` * `packages/protocol` It also does not connect to a local WebSocket, read local files, run Claude Code hooks, call LLM APIs, persist server state, or join a War Room. ## Synthetic Data Contract `useDemoLoop()` drives the demo with generated browser-local data. The generated objects intentionally resemble the full app's domain concepts: * heroes * missions * tool uses * notices * scrolls * achievements * faction standings * mission heatmap buckets * command palette entries This is a behavioral and documentation contract, not a direct import contract. If the protocol or main app behavior changes, the standalone demo must be reviewed and updated deliberately. ## Mirrored Helper Logic Some helper behavior is manually ported into `index.html` so the demo feels like the full UI: * `buildHeatmapBuckets` * `computeStandings` * `metricValue` * `formatStandingsValue` * `metricLabel` * `sessionStats` * `rankCommands` These helpers are copied or simplified mirrors of app concepts. They are kept inline because the demo has no bundler and must remain directly deployable as a static artifact. Changes to matching helpers in `apps/web/src/lib` should prompt a demo review. ## Service Worker Rules When changing `sw.js`: * Bump `CACHE_VERSION` whenever the precache list changes. * Keep same-origin shell assets in `SHELL_ASSETS`. * Keep the `LAZY_MEDIA_ASSETS` music list out of `SHELL_ASSETS`; the current lazy paths are `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`, and `public-demo/assets/music/12_undead_graveborn_war_march_take.mp3`. * Keep runtime CDN caching limited to known read-only asset origins. * Keep large optional media, such as background music, out of `SHELL_ASSETS` unless first-load precaching is explicitly worth the larger install. * Avoid caching private APIs, local server endpoints, or user-specific data. * Keep `scope: "./"` registration in `index.html` so path-prefixed fallback hosts continue to work. ## Maintenance Checklist Before treating the artifact as ready for public deployment: 1. Serve the artifact at `/` and under a path prefix such as `/factionos/`. 2. Verify `index.html`, `manifest.webmanifest`, `sw.js`, icons, and local assets return HTTP 200. 3. Run a desktop browser smoke test for splash entry, 2D battlefield board, mission search, trophy room, heatmap, standings, command palette, and shortcuts. 4. Run a mobile browser smoke test for splash entry and nonzero battlefield board dimensions. 5. Verify no page errors, console errors, or failed asset requests. 6. Verify service worker scope is the artifact path and offline reload works after one successful online visit. 7. Run `npm run media:demo:check`. 8. Run formatting and lint checks that include `public-demo/`. ## When To Prefer The Full App Use `apps/web` plus the local server when validating real product behavior: * real hook events * WebSocket hydration and replay * localStorage settings * server-backed LLM routes * War Room federation * CLI installer behavior * adapter behavior * protocol compatibility Use `public-demo/` when validating static hosting, first impression, public demo flow, and zero-install shareability. --- # 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/static-artifact.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.