> 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/phase16-session02-performance-and-image-optimization/spec.md). # Session Specification **Session ID**: `phase16-session02-performance-and-image-optimization` **Phase**: 16 - Quality, Deployment, And Launch Handoff **Status**: Not Started **Created**: 2026-06-02 **Package**: public-website **Package Stack**: Astro/TypeScript *** ## 1. Session Overview This session continues Phase 16 by optimizing the static FactionOS public website's images, CSS, browser scripts, font strategy, and build output size after the responsive and accessibility hardening pass. Phase 16 Session 01 is complete, so the next risk is launch performance: the website must keep its Cyber-Tactical visual direction while avoiding avoidable payload, expensive decorative effects, oversized image delivery, unnecessary client JavaScript, and undocumented font requests. The current public website already uses Astro static output, a typed media registry, and `OptimizedMedia.astro` for registry-backed image rendering. This session should turn those foundations into launch-performance evidence by reviewing every package-local website asset, keeping `public/` limited to intentional pass-through files, tuning image loading and responsive widths, checking font behavior, trimming unnecessary CSS/script cost, and recording static output size notes. Initial local evidence shows `public-website/dist` is about 8.7 MB, `public-website/dist/_astro` is about 7.0 MB, and the largest current image source/output is the `heroes-banner` asset at about 2.9 MB. Implementation stays within `public-website` and the session evidence files. It must not add analytics, performance beacons, hosted forms, CMS behavior, auth, server rendering, runtime personalization, third-party embeds, or a new image pipeline beyond current launch needs. Any optimization that would weaken the website's product-specific visuals should be recorded as deferred instead of replacing the site with generic or low-context imagery. *** ## 2. Objectives 1. Inventory source assets, pass-through public files, generated static output, font references, CSS effects, and client scripts to establish launch performance baselines. 2. Tune registry-backed image usage, loading priority, widths, formats, alt text, reduced-motion fallbacks, and distortion safeguards where Astro image optimization applies. 3. Reduce or document unnecessary JavaScript, costly decorative CSS, and font loading risk without changing the tactical product direction. 4. Verify typecheck, build, link/static-boundary checks, ASCII/LF encoding, and final payload notes after the optimization pass. *** ## 3. Prerequisites ### Required Sessions * [x] `phase16-session01-responsive-and-accessibility-hardening` - complete responsive, keyboard, focus, semantic, and reduced-motion hardening for the first-release static website. * [x] `phase13-session05-asset-pipeline-and-brand-media-prep` - package-local brand/showcase media registry and optimized image component exist. * [x] `phase15-session06-cross-linking-and-copy-consistency-pass` - route, CTA, legal marker, and deterministic built-site checker contract is current. ### Required Tools/Knowledge * Astro 6 static output and `astro:assets` image optimization. * Existing media registry in `public-website/src/lib/media.ts`. * Existing `OptimizedMedia.astro` behavior for alt text, responsive widths, loading priority, provenance captions, and reduced-motion fallback images. * Package-local website scripts: `npm --workspace @factionos/public-website run typecheck`, `npm --workspace @factionos/public-website run build`, and `npm --workspace @factionos/public-website run check:links`. * Static website privacy boundaries from `.spec_system/CONSIDERATIONS.md` and `.spec_system/SECURITY-COMPLIANCE.md`. ### Environment Requirements * Node.js 26.2.0 or newer. * npm workspace commands available from the repository root. * Existing public website dependencies installed, including Astro, Sharp, MDX, RSS, sitemap, TypeScript, and Vite. * Local shell commands available for asset and output-size inspection, such as `find`, `du`, and `rg`. *** ## 4. Scope ### In Scope (MVP) * Visitors receive optimized static image output where Astro can process product, brand, showcase, press, and Open Graph assets. * Visitors receive useful image alt text, consistent aspect ratios, no distortion, explicit loading behavior, and reduced-motion fallbacks for animated or motion-like showcase media. * Operators have notes showing which `public/` files intentionally bypass Astro processing and why. * Operators have a production-ready font strategy or a recorded launch blocker for any third-party font request. * Operators have static output-size notes identifying large built assets, route HTML weight, and fixed or deferred payload issues. * Visitors are not given unnecessary JavaScript for behavior that can remain static or CSS-only. * Visitors with reduced-motion preferences do not receive continuous animation or high-cost effects without a static equivalent. * The website remains static Astro output with no analytics, trackers, hosted forms, runtime network calls, storage writes, beacons, auth, CMS adapter, or server rendering. ### Out of Scope (Deferred) * Rebuilding the website visual direction - *Reason: this session optimizes the existing launch site, not the brand or layout concept.* * Adding analytics, RUM, performance beacons, or third-party monitoring - *Reason: the first release has no analytics by default and no client-side data collection.* * Full automated image pipeline - *Reason: current launch needs can use the existing registry and Astro image processing.* * Generated social image pipeline - *Reason: manual Open Graph fallback is sufficient for first launch.* * Automated CI/build-gate expansion - *Reason: Phase 16 Session 03 owns automated checks and build gates.* * Cloudflare Pages deployment setup - *Reason: Phase 16 Session 04 owns the deployment path.* *** ## 5. Technical Approach ### Architecture Start with a deterministic inventory of `public-website/src/assets`, `public-website/public`, current `public-website/dist`, font references, CSS effects, and browser scripts. Use that inventory to prioritize fixes that keep the static Astro architecture intact: registry-backed local image imports, Astro image generation, responsive widths and sizes, explicit loading priority, no third-party font fetch by default, and only the small browser scripts needed for accessibility and mobile navigation. Image changes should preserve `public-website/src/lib/media.ts` as the source of truth for media keys, provenance, dimensions, status, loading, and fallback metadata. `OptimizedMedia.astro` should remain the rendering choke point for content images so alt text, dimensions, generated widths, quality, and reduced-motion fallback behavior stay centralized. If a source asset is too large for launch, prefer using Astro-generated responsive variants or a documented first-release deferral over replacing the visual with generic stock or background-only media. CSS and script changes should target measurable cost and launch risk. Keep decorative gradients, shadows, and motion only where they provide product context, reduce expensive effects where they are repeated heavily, and ensure `prefers-reduced-motion` disables continuous animation. Keep the existing script checker boundary intact: no runtime `fetch`, WebSocket, EventSource, analytics SDK, browser storage write, beacon, or hosted form behavior should appear in built HTML. ### Design Patterns * Registry-backed media: Keep image metadata in `media.ts` and render through `OptimizedMedia.astro`. * Static-first interaction: Retain JavaScript only for accessibility or mobile navigation behavior that cannot be represented with static HTML/CSS. * Evidence-led optimization: Record baseline and final payload sizes before claiming improvement. * Privacy-preserving performance review: Use local build artifacts and static inspection, not analytics or visitor telemetry. * Reduced-motion parity: Disable continuous motion while preserving static labels, context, and fallbacks. ### Technology Stack * Astro 6.4.2 static output. * `astro:assets` and Sharp 0.34.5. * TypeScript 5.9.3. * Node.js 26.2.0 or newer. * npm workspaces. * Existing package-local typecheck, build, and link/static-boundary checker. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase16-session02-performance-and-image-optimization/implementation-notes.md` | Baseline/final asset inventory, static output-size notes, optimization decisions, deferred payload issues, and verification evidence | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `public-website/src/lib/media.ts` | Review media metadata, loading priority, fallback links, and status notes for launch performance | \~60 | | `public-website/src/components/media/OptimizedMedia.astro` | Tune generated widths, sizes, quality, decoding, fit, fallback handling, and distortion safeguards | \~90 | | `public-website/src/components/marketing/HeroCockpit.astro` | Verify and tune eager brand mark rendering, sizes, and costly decorative effects in the first viewport | \~70 | | `public-website/src/components/marketing/PressAssetGrid.astro` | Verify press/showcase preview image sizes, provenance captions, and conditional high-byte media behavior | \~70 | | `public-website/src/data/company.ts` | Verify press asset descriptors, high-byte media policy, download state, and launch blocker copy | \~50 | | `public-website/src/styles/global.css` | Review font stack, motion, gradients, shadows, blur, global decorative layers, and reduced-motion behavior | \~120 | | `public-website/src/components/navigation/MobileNavigation.astro` | Review client script necessity, event lifecycle, and static-boundary-safe behavior | \~60 | | `public-website/src/components/navigation/SkipLink.astro` | Review client script necessity and keep focus behavior lightweight and static-boundary-safe | \~40 | | `public-website/README_public-website.md` | Document font strategy, public asset policy, and performance notes needed for launch handoff | \~60 | | `public-website/package.json` | Use existing package scripts for typecheck, build, and link/static-boundary checks; add no production dependency unless explicitly justified | \~10 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Launch images use Astro-optimized paths where appropriate. * [ ] Images load without distortion and include useful alt text. * [ ] Animated or motion-like showcase media has reduced-motion fallback behavior. * [ ] `public-website/public` contains only intentional pass-through assets such as favicon, robots, manifest, and press policy files. * [ ] No unnecessary JavaScript remains for static presentation. * [ ] Browser scripts do not introduce runtime network APIs, analytics, browser storage writes, beacons, hosted forms, or third-party embeds. * [ ] Font strategy is production-ready with no undocumented third-party font request, or a launch blocker is recorded. * [ ] Static output-size notes identify large route, CSS, and asset outputs and document fixed or deferred issues. ### Testing Requirements * [ ] `npm --workspace @factionos/public-website run typecheck` passes. * [ ] `npm --workspace @factionos/public-website run build` passes. * [ ] `npm --workspace @factionos/public-website run check:links` passes. * [ ] Source asset and built output-size checks are recorded before and after optimization. * [ ] Manual browser spot check confirms optimized images are not distorted and reduced-motion fallbacks remain understandable. ### Non-Functional Requirements * [ ] Public website remains static Astro output with no server adapter. * [ ] No analytics, trackers, hosted forms, cookies, runtime data collection, auth, CMS adapter, third-party embed, or performance beacon is introduced. * [ ] Visual direction remains specific to FactionOS and does not degrade into generic dark background imagery. * [ ] Existing no-claim boundaries for hosted identity, trusted erasure, production-hosted validation, and broad media readiness remain intact. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] No new production dependency is added unless the implementation notes justify it and validation passes. *** ## 8. Implementation Notes ### Key Considerations * The current `heroes-banner` source and generated JPEG output are each about 2.9 MB, making them the first high-byte media item to review. * The current build output is about 8.7 MB, with about 7.0 MB under `public-website/dist/_astro`. * Existing `OptimizedMedia.astro` already enforces non-empty alt text and uses Astro `Image`; improve it only where launch evidence shows a practical performance gain. * The site currently references font family names in CSS but does not show an external font import; verify this remains true in built output. * JSON-LD scripts are expected and should not be treated as client interaction. ### Potential Challenges * High-byte showcase media: Use responsive Astro variants and documented conditional status; defer broad media promotion if launch risk remains. * Visual regression from CSS trimming: Reduce repeated expensive effects carefully and preserve product context. * Script removal risk: Keep mobile navigation and skip-link accessibility behavior unless an equivalent static pattern exists. * Build output churn: Record size evidence and avoid committing generated output changes unless the repo's current public-website release practice requires it. ### Relevant Considerations * \[P16-public-website] **Launch hardening is still ahead**: This session closes the performance and payload slice before automated gates and deployment. * \[P13-public-website] **Static Astro boundary is intentional**: Keep no server adapter, React, Tailwind, CMS, auth, hosted forms, or analytics by default. * \[P13-public-website] **Registry-backed media is the website pattern**: Use `public-website/src/lib/media.ts` and `OptimizedMedia.astro` for optimized images, alt text, dimensions, source hashes, status, and fallback behavior. * \[P04] **Asset provenance gate remains active**: Brand/showcase media must not be promoted beyond its documented status without evidence. * \[P13-public-website] **Website media claims are scoped**: Brand identity assets are launch-ready for website identity use; showcase assets remain conditional until broad media promotion evidence closes blockers. * \[P13-public-website] **Public website external links are explicit**: Analytics, hosted forms, third-party fonts, CMS adapters, auth, or runtime personalization require separate privacy and security review. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Oversized or distorted images ship because source assets bypass Astro optimization or use mismatched sizes. * Static privacy boundary regresses through a performance script, font request, storage write, beacon, analytics SDK, or hosted form behavior. * Reduced-motion users still receive continuous animation or lose visual context when motion is disabled. *** ## 9. Testing Strategy ### Unit Tests * No new unit tests are expected unless implementation adds a new helper. If a helper is added, cover media selection, output-size parsing, or static boundary behavior with focused tests. ### Integration Tests * Run `npm --workspace @factionos/public-website run typecheck`. * Run `npm --workspace @factionos/public-website run build`. * Run `npm --workspace @factionos/public-website run check:links`. ### Manual Testing * Compare baseline and final source asset and built output sizes. * Inspect built HTML for image output, static script behavior, and absence of runtime network/storage/analytics APIs. * Spot check homepage and press page images in a local preview for distortion, alt text, loading behavior, and reduced-motion fallback. ### Edge Cases * High-byte `heroes-banner` remains conditional and must not imply broad media readiness. * `public/` assets intentionally bypass Astro optimization and need explicit policy notes. * JSON-LD scripts are allowed while interactive scripts remain static-boundary constrained. * Font names may resolve to local/system fonts; any network font request must be documented or blocked before launch. *** ## 10. Dependencies ### External Libraries * No new external libraries planned. * Existing `astro`, `astro:assets`, and `sharp` provide image optimization. ### Other Sessions * **Depends on**: `phase16-session01-responsive-and-accessibility-hardening` * **Depended by**: `phase16-session03-automated-checks-and-build-gates`, `phase16-session04-cloudflare-pages-deployment-path`, and `phase16-session05-launch-review-and-documentation-handoff` *** ## 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/phase16-session02-performance-and-image-optimization/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.