oneie/one/things/plans/performace.md

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

---
title: Performace
dimension: things
category: plans
tags: ai
related_dimensions: events, knowledge, people
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
  This document is part of the things dimension in the plans category.
  Location: one/things/plans/performace.md
  Purpose: Documents lighthouse snapshot — 10 oct 2025
  Related dimensions: events, knowledge, people
  For AI agents: Read this to understand performace.
---

# Lighthouse Snapshot — 10 Oct 2025

Captured on Moto G Power (emulated), Slow 4G throttling, Lighthouse 12.8.2, Headless Chromium 137.0.7151.119 — single-page session, initial load.

## Baseline Metrics

- Performance 94
- Accessibility 94
- Best Practices 100
- SEO 100
- First Contentful Paint 1.8 s
- Largest Contentful Paint 2.5 s
- Total Blocking Time 60 ms
- Cumulative Layout Shift 0
- Speed Index 4.3 s

## Guiding Principles (Astro First)

- Serve HTML first: leverage Astro’s server-first rendering so the browser sees a static document immediately.
- Lean on Astro islands: hydrate only the components that truly need interactivity, and delay hydration with `client:idle`, `client:visible`, or `client:media`.
- Simplify over delete: keep functionality, but move logic to build time, server routes, or islands that hydrate later.
- Build once, cache forever: ensure assets are hashed, compressed, and delivered via HTTP/2.
- Measure every iteration using the same Lighthouse profile; confirm wins with real trace captures.

## Root Causes (From Audit)

- LCP held at 2.5 s by render-blocking CSS and a 1.58 s deep script cascade from Astro client bundles.
- Forced synchronous layout in `/_astro/client.C-k3xUc3.js:10:1392`, `/_astro/use-mobile.CrtMAo8K.js:6:337`, and the `cdn.usal.dev/latest` script (total 148 ms of reflow work).
- No preconnect or early hints, so every third-party handshake blocks on TCP+TLS.
- ~22 KiB of unused JavaScript in Astro bundles; three main-thread tasks longer than 50 ms.
- Accessibility score capped by unlabeled action buttons (hurts user experience and audit score).

## Performance Plan — Simple & Astro-Aligned

### 1. Above-the-Fold Simplicity

- Deliver a minimal, static hero layout built with semantic HTML and existing global CSS. Avoid inline CSS; rely on the base stylesheet generated by Astro and tailwind utilities already compiled.
- Use Astro’s layout components to pre-render navigation, headline, and primary CTA with zero hydration.
- Defer complex UI (notifications, dropdowns, charts) to islands placed below the fold. Provide static placeholders that load instantly, then hydrate progressively when scrolled into view.

### 2. Astro Islands & Hydration Strategy

- Audit every component that currently ships as part of the main bundle; convert interactive sections to islands using `client:visible` or `client:idle`. For buttons that trigger modals, wrap just the modal logic in an island instead of hydrating the whole sidebar.
- Bundle measurements and DOM mutations inside islands; keep islands small and focused so their JavaScript stays lean.
- Use `client:only="react"` (or other frameworks) sparingly. Prefer native Astro components with minimal runtime.

### 3. CSS & Styling Discipline

- Consolidate styling into the shared CSS build produced by Astro. Remove redundant imports and ensure the main stylesheet is tree-shaken through Tailwind’s content scanning.
- Adopt CSS layering or utility classes to prevent bloating the bundle. If additional styles are needed per island, scope them with CSS modules to avoid shipping large global additions.
- Lean on the design tokens available at build time so styles compile once; no runtime theming above the fold.

### 4. JavaScript Performance at Build Time

- Move configuration, data fetching, and formatting logic into Astro’s `load` functions or server-side helpers so the HTML arrives complete.
- Extract shared helper functions into `Astro.glob` or server collections so they do not duplicate across bundles.
- Use `@astrojs/image` to pre-generate responsive images, ensuring the hero image is optimized, lazy loaded, and served in modern formats without client-side overhead.
- Enable `astro-compress` (or Vite compression) to serve brotli/gzip out of the box.

### 5. Manage Third-Party Dependencies

- Replace the `cdn.usal.dev/latest` script with a locally hosted build or ship its minimal subset through an island that hydrates after user interaction.
- Preconnect only to origins we cannot remove (e.g., API or auth). Configure them in `src/components/Head.astro` to guarantee consistent hints.
- Use `rel="prefetch"` or `rel="preload"` for essential islands that must hydrate quickly after interaction.

### 6. Prevent Layout Thrash

- Review `client.C-k3xUc3.js` and `use-mobile.CrtMAo8K.js` to ensure layout reads and writes are separated. If these files belong to islands, gate DOM work until `requestAnimationFrame`.
- For menu toggles and responsive adjustments, prefer CSS `:has()` or Tailwind responsive utilities so layout changes happen without scripting.
- Establish a lint rule (ESLint custom rule) to flag direct layout reads inside synchronous component initialization.

### 7. Accessibility & Semantics

- Provide descriptive text for every button flagged by Lighthouse. Astro’s server render ensures labels are available without hydration.
- Use native form controls and semantic tags to reduce custom script logic; accessible components often hydrate faster due to simpler DOM.
- Run `@astrojs/seo` audit to enforce meta tags and accessible structure without extra code.

### 8. Progressive Enhancement Workflow

- First render: static HTML + CSS-only interactions (hover, focus, simple toggles).
- Second phase: hydrate priority islands when they appear on screen (e.g., user menu, notifications).
- Third phase: load non-critical islands after idle time (analytics, toasts).
- Provide skeleton or shimmer states coded in CSS so the user sees immediate feedback while islands hydrate.

## Execution Roadmap (Lean Sprints)

- Sprint 1: Inventory components, convert above-the-fold layout to pure Astro HTML, configure islands with `client:visible`, fix accessible labels (goal: LCP ≤ 2.3 s).
- Sprint 2: Optimize build pipeline (image component, compression, helper dedupe), refactor layout scripts, ensure no forced reflow > 16 ms (goal: TBT ≤ 40 ms).
- Sprint 3: Fine-tune hydration triggers, add network hints, verify third-party scripts defer correctly (goal: Performance 100, Accessibility 100).
- Continuous: Maintain budgets (JS < 80 KiB initial load, CSS < 30 KiB critical). Add Lighthouse CI with Moto G Power profile nightly.

## Verification & Guardrails

- Measure with Lighthouse and Chrome Performance traces on every PR touching layout, CSS, or scripts.
- Store comparison snapshots in `/one/things/perf-historical` (create if missing) to verify regression-free trend.
- Add automated `axe-core` run to catch regressions in accessible names.
- Keep dashboard: LCP, TBT, JS payload size, CSS payload size — fail build when limits are exceeded.

## Target Outcomes

- Performance 100 with LCP ≤ 2.1 s, TBT ≤ 40 ms, CLS 0 maintained.
- Accessibility 100 with labeled controls, relying on semantic HTML.
- Simplified front-end stack: reduced Astro runtime footprint, predominantly static delivery.
- Repeatable workflow grounded in deletion, simplification, and constant measurement.