> 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/phase14-session02-battlefield-preview-and-product-mockups/spec.md). # Session Specification **Session ID**: `phase14-session02-battlefield-preview-and-product-mockups` **Phase**: 14 - Homepage And Core Product Story **Status**: Complete **Created**: 2026-06-01 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session builds the homepage battlefield preview that turns the Phase 14 product story from a branded hero into a product-like operational surface. It adds a responsive map-style preview with synthetic missions, agent tokens, status rings, mission routes, file and tool traces, and event stream snippets without introducing live data, runtime calls, analytics, or visitor-specific state. The work is the natural next step after the completed hero cockpit because Session 01 established the first viewport, static data posture, CTAs, and marketing component directory. Session 02 extends that same homepage flow with visual proof of the battlefield and cockpit concepts before later sessions add the narrative decks, trust sections, and final conversion surfaces. The implementation stays inside `public-website` and follows the static Astro boundary from Phase 13. The preview must look like a real product surface while remaining explicit that all values are deterministic samples, not real local sessions, prompts, file paths, terminal output, hosted telemetry, or user data. *** ## 2. Objectives 1. Create a responsive `BattlefieldPreview.astro` component that presents a product-like mission map, agent tokens, status rings, routes, traces, and event stream. 2. Extend homepage data with typed, synthetic battlefield preview content that cannot be mistaken for real user, workstation, or hosted runtime data. 3. Integrate the preview into the homepage immediately after the hero without clipping, overlap, or first-viewport CTA regressions. 4. Preserve accessibility, non-color-only state communication, mobile fallback behavior, and reduced-motion-safe static state visibility. *** ## 3. Prerequisites ### Required Sessions * [x] `phase13-session01-astro-scaffold-and-workspace-wiring` - Provides the static Astro workspace and package scripts. * [x] `phase13-session02-design-tokens-and-layout-shell` - Provides global CSS tokens, shell primitives, sections, panels, and accessible focus defaults. * [x] `phase13-session03-seo-metadata-and-static-site-plumbing` - Provides the static route and metadata plumbing used by the homepage. * [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - Provides the package-local media rules and provenance guardrails, even though this session should not need new media promotion. * [x] `phase14-session01-hero-cockpit-and-primary-ctas` - Provides the homepage hero, static-data posture, CTAs, and marketing component directory. ### Required Tools/Knowledge * Astro component authoring with scoped CSS and package-relative imports. * Existing `public-website` primitives: `Section`, `Panel`, `Badge`, `MetricStrip`, `ButtonLink`, and homepage data patterns. * Static-site privacy boundaries from the PRD, UX PRD, considerations, and security posture. * Responsive visual composition with stable aspect ratios and reduced-motion media queries. ### Environment Requirements * Node.js 26.2.0 or newer. * npm 11.16.0 workspace install available. * No React, Tailwind, CMS adapter, server adapter, auth, hosted form handling, analytics, WebSocket connection, iframe, canvas, or WebGL added for this session. *** ## 4. Scope ### In Scope (MVP) * Website visitor can inspect a product-like battlefield preview - Build `BattlefieldPreview.astro` with mission map, agent lanes, status rings, routes, coordinate/grid treatment, traces, and event stream. * Website visitor can distinguish sample data from real telemetry - Use typed synthetic data and explicit static-preview labels, with no raw prompts, local paths, terminal output, credentials, or user-provided code. * Website visitor can read state without relying on color alone - Pair cyan, purple, green, and red accents with labels, badges, captions, and text summaries. * Desktop and tablet users get a stable product surface - Preserve a 16:9 map frame with bounded rails and no text or token clipping. * Mobile users get a usable fallback - Swap to a stacked workpad layout with reachable map, trace, and event panels and no horizontal overflow. * Reduced-motion users get equivalent information - Stop continuous animation while keeping state rings, labels, routes, and status treatment visible. * Homepage readers see the preview in context - Integrate the component immediately after `HeroCockpit` without disrupting existing hero CTAs or metadata. ### Out of Scope (Deferred) * Real app iframe embedding - Reason: The public website must stay static and separate from the app and synthetic demo. * Real local session data, WebSocket streams, or runtime calls - Reason: The website has no visitor-specific data collection or local runtime access. * Canvas, WebGL, drag/drop, or complex controls - Reason: Session scope is a static Astro product mockup. * Full homepage narrative decks, latest-content previews, and final CTA - Reason: Phase 14 Session 03 owns those sections. * Product overview, features, and how-it-works routes - Reason: Phase 14 Sessions 04 and 05 own those pages. *** ## 5. Technical Approach ### Architecture Extend `public-website/src/data/homepage.ts` with typed battlefield preview data: mission summary, agent tokens, route segments, status readouts, bounded file/tool trace rows, event stream rows, and static privacy labels. Keep the data deterministic and compact so the component can render without fetching, hydrating, storing, or personalizing anything. Create `public-website/src/components/marketing/BattlefieldPreview.astro` as a server-rendered Astro component. The component should compose existing layout and system primitives where useful, then use scoped CSS for the board, route lines, tokens, rails, responsive workpad layout, and reduced-motion rules. The homepage route imports the new component below `HeroCockpit` so the first viewport stays focused while the next section immediately supplies visual product proof. ### Design Patterns * Static typed data: Keeps the preview deterministic and prevents accidental runtime or hosted-data claims. * Semantic visualization: Uses DOM labels, lists, captions, and summaries so the preview is not an inaccessible image-only artifact. * Component-scoped visual system: Keeps tactical map styles local unless a reusable primitive is clearly needed. * Progressive responsive layout: Desktop uses a 16:9 battlefield frame; mobile swaps to stacked map, trace, and event panels. * Reduced-motion equivalence: Animation is decorative only; static labels and state treatment remain understandable. ### Technology Stack * Astro 6.4.2 static output. * TypeScript 5.9.3 for typed homepage data validation. * Scoped Astro CSS and existing global design tokens. * Existing npm workspace validation through typecheck and build scripts. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/components/marketing/BattlefieldPreview.astro` | Product-like homepage battlefield preview with map, agent tokens, traces, event stream, responsive layout, accessibility labels, and reduced-motion handling. | \~360 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/data/homepage.ts` | Add typed synthetic battlefield preview data, labels, mission traces, and event stream rows. | \~150 | | `public-website/src/pages/index.astro` | Import and render the battlefield preview immediately after the hero. | \~10 | | `public-website/src/styles/global.css` | Add only reusable helpers if component-scoped CSS is insufficient. | \~20 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Homepage renders a stable battlefield/cockpit preview immediately after the hero. * [ ] Preview includes a 2D mission map, agent tokens, active status rings, mission routes, file/tool trace hints, event snippets, mission state, and coordinate/grid treatment. * [ ] Preview content is explicitly synthetic and does not imply live user data, hosted telemetry, real prompts, raw file paths, terminal output, or runtime collection. * [ ] State is communicated with labels, badges, captions, and text summaries, not color alone. * [ ] Preview does not clip text, rings, tokens, routes, rails, or badges at desktop, tablet, mobile, or wide desktop widths. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] Manual browser smoke covers 360px, 768px, 1280px, wide desktop, keyboard/focus behavior where controls exist, and reduced-motion mode. ### Non-Functional Requirements * [ ] Static output remains free of analytics, hosted forms, CMS adapters, auth, server rendering, WebSocket calls, iframe embeds, canvas, and WebGL. * [ ] Continuous motion is disabled in reduced-motion mode while static state indicators remain visible. * [ ] No conditional showcase media is promoted by implication. * [ ] Homepage CTAs from Session 01 remain visible and focusable. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * Prefer extending `homepage.ts` instead of scattering copy inside the component; this keeps synthetic data auditable and typed. * Use bounded arrays for event and trace rows so the preview cannot grow into an unbounded feed. * Use labels such as "static sample", "synthetic mission", or equivalent near the preview to avoid live-data implications. * If token markers are interactive, use native controls with accessible names and visible focus; if they are not interactive, render them as semantic list items instead of fake controls. * Keep all paths package-relative from the repo root in tasks and imports. ### Potential Challenges * Dense map visuals can become decorative: Tie every visual element to a named mission state, agent, route, trace, or event. * Status colors can become inaccessible: Pair accents with text labels, badges, captions, and summaries. * 16:9 boards can clip on small screens: Use aspect-ratio on larger viewports and a stacked workpad fallback on mobile. * Motion can hide meaning: Ensure animation is optional and reduced-motion keeps the same state legible. * Product mockups can overclaim: Keep no-hosted, no-live-data, and local-first boundaries visible. ### Relevant Considerations * \[P13-public-website] **Public site page depth is still upcoming**: This session adds the homepage product visual proof while leaving narrative, trust, conversion, responsive/accessibility hardening, deployment, and launch evidence to later sessions. * \[P13-public-website] **Static Astro boundary is intentional**: The preview must stay static Astro with no server adapter, React, Tailwind, CMS, auth, hosted forms, analytics, WebSocket, iframe, or runtime personalization. * \[P13-public-website] **Registry-backed media is the website pattern**: Avoid new media unless it goes through the registry; this session can use CSS/DOM visualization instead of conditional showcase media. * \[P13-public-website] **Do not promote conditional media by implication**: Showcase assets remain conditional and should not be presented as release-ready product screenshots. * \[P03] **Real executors remain unimplemented by design**: Battlefield preview copy must not imply approved actions execute files, git, terminal, Docker, or remote work. * \[P06-S07-HOSTED-VALIDATION] **Production-hosted validation remains no-claim**: Homepage preview copy must not claim production-hosted validation. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * The preview appears to display live visitor, workstation, prompt, file path, terminal, or hosted telemetry data. * Dense map, rails, event rows, or labels overlap or clip at common responsive widths. * Motion, color-only status, or fake controls make the preview inaccessible or misleading. *** ## 9. Testing Strategy ### Unit Tests * No dedicated unit tests are required for static Astro rendering unless the implementation introduces exported TypeScript helpers with branching logic. ### Integration Tests * Run package typecheck to validate Astro imports, typed homepage data, and component prop usage. * Run package build to validate static output, route rendering, CSS bundling, and homepage integration. ### Manual Testing * Start or build-preview the public website and inspect the homepage at 360px, 768px, 1280px, and wide desktop widths. * Confirm hero CTAs remain reachable and the new preview starts below the hero without overlap. * Check reduced-motion mode and verify continuous route, scan, or pulse animation stops while labels and state rings remain visible. * If token markers are implemented as controls, tab through them and confirm accessible names and visible focus. ### Edge Cases * Long agent names, mission labels, trace text, and event rows wrap inside bounded regions without horizontal scrolling. * Mobile layout keeps the map, trace rail, event stream, and mission summary reachable without clipping. * Red/warning states include text labels and do not depend on color. * Preview copy never exposes realistic local paths, raw prompts, command bodies, credentials, terminal output, or user-provided code. *** ## 10. Dependencies ### External Libraries * Astro: 6.4.2 * `@astrojs/sitemap`: 3.7.3 * `@astrojs/rss`: 4.0.18 * `@astrojs/mdx`: 6.0.1 * sharp: 0.34.5 * TypeScript: 5.9.3 ### Other Sessions * **Depends on**: `phase13-session01-astro-scaffold-and-workspace-wiring`, `phase13-session02-design-tokens-and-layout-shell`, `phase13-session03-seo-metadata-and-static-site-plumbing`, `phase13-session05-asset-pipeline-and-brand-media-prep`, `phase14-session01-hero-cockpit-and-primary-ctas` * **Depended by**: `phase14-session03-homepage-narrative-sections`, `phase14-session04-product-overview-page`, `phase14-session05-features-and-how-it-works-pages` *** ## 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/phase14-session02-battlefield-preview-and-product-mockups/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.