@struq/skill 0.3.0 → 0.4.0

package/skills/struq/references/page-entrances.md

@@ -1,198 +0,0 @@
-# Per-Zone Page Entrances: the `template.tsx` layer
-
-One arm of the page-flow system: what the *revealed* page does. Siblings: [route-transitions.md](route-transitions.md) (the cover→swap→reveal wipe this entrance overlaps) and [loaders.md](loaders.md) (the first-load overlay).
-
-`template.tsx` re-mounts on every navigation within a route group ([setup.md](setup.md) §6), so it's where the revealed page gets a subtle entrance. It overlaps the reveal so content rises in the cover's wake rather than popping. Differentiate zones: richer for marketing, quick for app.
-
-```tsx
-// app/(marketing)/template.tsx: expressive
-"use client";
-import { useRef } from "react";
-import { useGSAP, gsap, ScrollTrigger } from "@/lib/gsap";
-
-export default function Template({ children }: { children: React.ReactNode }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useGSAP(() => {
-    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    gsap.from(ref.current, reduce
-      ? { opacity: 0, duration: 0.3, clearProps: "all" }
-      : { opacity: 0, y: 24, duration: 0.8, ease: "power3.out", clearProps: "all",
-          onComplete: () => ScrollTrigger.refresh() });
-  }, { scope: ref });
-  return <div ref={ref}>{children}</div>;
-}
-```
-
-```tsx
-// app/(app)/template.tsx: functional, fast
-"use client";
-import { useRef } from "react";
-import { useGSAP, gsap } from "@/lib/gsap";
-
-export default function Template({ children }: { children: React.ReactNode }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useGSAP(() => {
-    gsap.from(ref.current, { opacity: 0, duration: 0.25, ease: "power1.out", clearProps: "all" });
-  }, { scope: ref });
-  return <div ref={ref}>{children}</div>;
-}
-```
-
-**Two non-obvious, load-bearing details:**
-- **`clearProps: "all"`**: a leftover transform on this wrapper (even `translate(0,0)`) makes it a containing block for `position: fixed`, which silently breaks ScrollTrigger pinning for *every* section inside. Clearing props after the entrance removes the wrapper's footprint.
-- **`ScrollTrigger.refresh()` on complete**: trigger positions measured while the page was still offset (mid-entrance) are wrong. Refreshing after it settles re-measures against the final layout so pinned/scrubbed sections don't jump.
-
----
-
-## Hero entrances the presets name
-
-The template entrance above moves the whole page. The hero's own entrance is a separate, per-preset decision ([vibe-presets.md](vibe-presets.md)): Soft Modern's `weight-in` and Warm Editorial's `soft-scrub` live in [typography.md](typography.md) §5; the two below belong to Dark Cinematic and Luxury Minimal. Both follow the same rules as every recipe: a `"use client"` leaf, `useGSAP` with a scope ref, all animation inside the `no-preference` branch of `gsap.matchMedia()`, and the server markup already the final state for reduced motion.
-
-### `match-cut-hero`: image to type (Dark Cinematic)
-
-The hero opens on a full-bleed image, holds it for about a second, then cuts to the h1 sitting exactly where a shape in the image was (a horizon, an edge, a bright band). The cut is hard, or a 0.3s dissolve at most; the type itself does not rise. The shared shape is art direction: place the h1 on the image's horizon line at 1440 and at 390, and choose or crop the image so the shape lands there.
-
-```css
-/* globals.css: the type waits under the image only while motion is allowed */
-@media (prefers-reduced-motion: no-preference) {
-  [data-cut-hero]:not([data-cut]) [data-cut-type] { visibility: hidden; }
-}
-@media (prefers-reduced-motion: reduce) {
-  [data-cut-image] { display: none; } /* reduced motion opens on the type, no cut */
-}
-```
-
-```tsx
-"use client";
-import { useRef } from "react";
-import Image from "next/image";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-type NetInfo = { effectiveType?: string; saveData?: boolean };
-
-export function MatchCutHero({ src, title, cut = "hard" }: {
-  src: string; title: string; cut?: "hard" | "dissolve";
-}) {
-  const root = useRef<HTMLElement>(null);
-
-  useGSAP(() => {
-    const mm = gsap.matchMedia();
-    mm.add("(prefers-reduced-motion: no-preference)", () => {
-      const el = root.current!;
-      const img = el.querySelector<HTMLImageElement>("[data-cut-image] img");
-
-      // Shorter hold on slow or data-saving connections: the post-cut content is the LCP candidate.
-      const net = (navigator as Navigator & { connection?: NetInfo }).connection;
-      const slow = net?.saveData === true || /2g|3g/.test(net?.effectiveType ?? "");
-      const HOLD = slow ? 0.6 : 1;
-
-      const tl = gsap.timeline({ paused: true })
-        .call(() => { el.dataset.cut = "1"; }, [], 0) // the type is there at the cut
-        .to("[data-cut-image]", { autoAlpha: 0, duration: cut === "hard" ? 0 : 0.3, ease: "none" }, 0);
-
-      // The hold starts when the photo has PAINTED, never on mount: a hold over an empty frame
-      // is no match cut at all. Use delayedCall, not tl.delay(): play() ignores a delay set
-      // after the timeline was created.
-      let started = false;
-      let hold: gsap.core.Tween | undefined;
-      const start = (seconds: number) => {
-        if (started) return;
-        started = true;
-        hold = gsap.delayedCall(seconds, () => { tl.play(); });
-      };
-      const onLoad = () => start(HOLD);
-      img?.addEventListener("load", onLoad, { once: true });
-      if (img?.complete && img.naturalWidth > 0) onLoad();      // cached: already painted
-      const fallback = gsap.delayedCall(2.5, () => start(0));  // photo never came: open on the type
-
-      return () => {
-        tl.kill(); hold?.kill(); fallback.kill();
-        img?.removeEventListener("load", onLoad);
-        delete el.dataset.cut;
-      };
-    });
-  }, { scope: root });
-
-  return (
-    <section ref={root} data-cut-hero
-             className="relative grid min-h-svh items-end overflow-clip bg-surface-0 px-6 pb-[12svh]">
-      <h1 data-cut-type className="font-display text-display max-w-[16ch]">{title}</h1>
-      <div data-cut-image aria-hidden className="absolute inset-0">
-        {/* LCP hint: `preload` or `priority`, whichever the installed next/image declares (setup.md §0, Known API shifts) */}
-        <Image src={src} alt="" fill preload sizes="100vw" className="object-cover" />
-      </div>
-    </section>
-  );
-}
-```
-
-- **The hold is gated on the image.** `img.complete` (cached) or its `load` event starts a `gsap.delayedCall` for the hold, with a 2.5s fallback straight to the type. A timeline with `delay: 1` on mount fires the cut over an empty frame whenever the photo is remote or slow, and a delay set later with `tl.delay()` is ignored by `play()`. Verify it with a frame trace: the hold frame must be the photo ([pitfalls.md](pitfalls.md) §3.3).
-- **LCP is not free here.** The h1 is in the HTML from the start, hidden only by CSS while motion is allowed, and whatever is hidden until the cut (the h1, a product shot) becomes the LCP candidate the moment it appears. So lab LCP lands after hold plus cut, and fails the 2.5s floor ([performance.md](performance.md) §1) whenever the post-cut content paints a larger area than the photo did. Keep the post-cut hero smaller than the photo's painted area, and keep the shorter hold on slow connections (`HOLD` above). Measure it with the LCP probe in [performance.md](performance.md) §8; never assume it.
-- Add `<noscript><style>{"[data-cut-image]{display:none!important}[data-cut-type]{visibility:visible!important}"}</style></noscript>` to the root layout's `<head>`, so a JS failure opens on the type.
-- With a loader, start the hold as the loader exits ([loaders.md](loaders.md)), not on mount, or the cut happens behind the curtain.
-- **When not to:** when the image has no shape the type can land on (a cut with no shared shape is just a slideshow), and when the post-cut hero must be larger than the photo's painted area and LCP under 2.5s is a hard requirement: then open on the type and let the image follow.
-
-### `clip-line-hero`: the 1.6s single-line clip (Luxury Minimal)
-
-One line of display type, revealed by one slow `clip-path` wipe from left to right. No split, no stagger, no y-travel: the restraint is the move.
-
-```css
-/* globals.css: pre-paint guard, same shape as line-rise-hero */
-@media (prefers-reduced-motion: no-preference) {
-  [data-clip-line]:not([data-ready]) { clip-path: inset(0% 100% 0% 0%); }
-}
-```
-
-```tsx
-"use client";
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function ClipLineHero({ children }: { children: string }) {
-  const root = useRef<HTMLDivElement>(null);
-
-  useGSAP(() => {
-    const mm = gsap.matchMedia();
-    mm.add("(prefers-reduced-motion: no-preference)", () => {
-      const line = root.current!.querySelector<HTMLElement>("[data-clip-line]")!;
-      gsap.fromTo(line,
-        { clipPath: "inset(0% 100% 0% 0%)" },
-        { clipPath: "inset(0% 0% 0% 0%)", duration: 1.6, ease: "power4.inOut", delay: 0.2,
-          clearProps: "clipPath" }); // no clip left on the glyphs once it is open
-      line.dataset.ready = "1"; // the inline start clip now holds the line hidden
-    });
-  }, { scope: root });
-
-  return (
-    <div ref={root}>
-      <h1 data-clip-line className="font-display text-display -my-[0.1em] whitespace-nowrap py-[0.1em]">
-        {children}
-      </h1>
-    </div>
-  );
-}
-```
-
-- `fromTo` renders its start clip immediately, so `data-ready` can lift the CSS guard in the same tick without a flash. The 0.1em padding pulled back with a negative margin keeps descenders inside the clipped box at leading 0.92. An italic last glyph overhangs its box on the right: add `px-[0.08em] -mx-[0.08em]` too when the line ends in italic ([pitfalls.md](pitfalls.md) §1).
-- `power4.inOut` is the baseline's curtain ease: the wipe is a curtain drawn across one line. 1.6s is the top of the hero band, which Luxury Minimal's motion personality owns.
-- Add `<noscript><style>{"[data-clip-line]{clip-path:none!important}"}</style></noscript>` to the root layout's `<head>`.
-- One line only. If the copy needs two lines at 390px, shorten the copy ([page-architecture.md](page-architecture.md) §5); a two-line clip wipe reads as two reveals.
-
----
-
-## Timing reference
-
-| Phase | Duration | Ease | Transform |
-|---|---|---|---|
-| Marketing entrance | 0.8s | `power3.out` | `y 24→0` + fade |
-| App entrance | 0.25s | `power1.out` | fade |
-| Match cut (Dark Cinematic) | 1s hold from image load (0.6s on slow connections, 2.5s fallback), then 0s or 0.3s | `none` | image `autoAlpha` to 0, type static |
-| Single-line clip (Luxury Minimal) | 1.6s | `power4.inOut` | `clip-path` inset wipe |
-| **Reduced motion** | 0.3s | none | opacity only |
-
----
-
-## Anti-pattern (sweep before shipping)
-
-- **Forgetting `clearProps`/`refresh`** → broken pins on revealed pages. If a pinned section jumps only after navigating (not on hard reload), this is the cause ([pitfalls.md](pitfalls.md) §2).
-- **A timed entrance started on mount** while it depends on an image, a font or a loader → it plays behind the curtain or over an empty frame. Start it from the thing it waits for ([pitfalls.md](pitfalls.md) §3.3).

package/skills/struq/references/performance.md

@@ -1,235 +0,0 @@
-# Performance: cinematic and fast
-
-An award-tier site that stutters or takes four seconds to show its hero is not award-tier. The motion in this skill is cheap when it runs on one clock and animates transforms; what actually makes these sites slow is **assets**: a 40MB hero video, PNG photography, an unoptimized GLB, six font files. Fix assets first, then code.
-
-Run this in two places: on every build before verify, and first thing on a redesign of an existing project (existing projects are almost always carrying badly optimized media).
-
-## 1. Budgets
-
-| Asset | Budget | Notes |
-|---|---|---|
-| Hero image | 250KB at 1920w (AVIF or WebP) | the LCP element on most pages; preload it |
-| Content image | 150KB at 1440w | lazy below the first viewport |
-| Hero or ambient video loop | 2 to 4MB, 6 to 12s, no audio | always a poster; WebM first, MP4 fallback |
-| Any single video | 10MB max | longer content belongs on a video host |
-| GLB model | 1 to 3MB after compression | Draco or meshopt geometry, KTX2 or WebP textures |
-| Fonts | 2 families, 4 files max, about 150KB total | WOFF2, subset, variable where possible |
-| JavaScript on first load | about 250KB gzipped for the route, measured (§8) | three.js and R3F never in it; lazy island only |
-
-**Where the 250KB goes** (measured on a dry run with a recent Next.js and React, three.js correctly excluded: 244KB gzipped for `/`): the framework runtime (React, React DOM, the Next.js client and router) is roughly 150 to 190KB of it and is not yours to cut; GSAP core, ScrollTrigger, SplitText and DrawSVG are about 49KB; Lenis about 6KB; the rest is your components. Over budget, cut in this order: GSAP plugins registered but unused (MorphSVG and Flip are the usual passengers, [setup.md](setup.md) §1), Motion on a page where nothing uses it, Radix primitives imported into the root layout instead of the component that opens them, then heavy client components that could stay server components. The framework share moves with each major, so measure on the installed versions and write the number under VERIFY; never quote this table as the measurement.
-
-Targets on a mid-range phone profile: **LCP under 2.5s, CLS under 0.1, INP under 200ms**. Record them under VERIFY in STRUQ.md ([direction.md](direction.md)).
-
-## 2. Audit an existing project (redesign mode, step one)
-
-```bash
-# the 25 heaviest files under public/ and any asset folders
-find public assets -type f \( -iname "*.mp4" -o -iname "*.mov" -o -iname "*.webm" -o -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.webp" -o -iname "*.avif" -o -iname "*.gif" -o -iname "*.svg" -o -iname "*.glb" -o -iname "*.gltf" -o -iname "*.ttf" -o -iname "*.otf" -o -iname "*.woff" -o -iname "*.woff2" \) -printf "%s\t%p\n" 2>/dev/null | sort -rn | head -25 | awk -F'\t' '{printf "%8.1f KB  %s\n", $1/1024, $2}'
-
-# what a video actually is: codec, size, fps, duration, bitrate, audio
-ffprobe -v error -show_entries stream=codec_type,codec_name,width,height,r_frame_rate:format=duration,bit_rate,size -of compact input.mp4
-```
-
-(On macOS, `find -printf` is unavailable: use `du -k` over the same globs.)
-
-List every file over budget with its role (hero, ambient, content, poster), then fix them in this order: videos, images, models, fonts. Replace references in code to point at the optimized files; never optimize in place over the source.
-
-## 3. Video with ffmpeg
-
-Decorative and hero loops: strip audio, cap at 30fps, never upscale, trim to the loop.
-
-```bash
-# WebM (VP9), primary source. CRF 32 to 36 for ambient, 28 to 32 for a hero that people look at.
-ffmpeg -i input.mov -t 10 -an -vf "scale='min(1920,iw)':-2,fps=30" \
-  -c:v libvpx-vp9 -crf 32 -b:v 0 -pix_fmt yuv420p -row-mt 1 -deadline good -cpu-used 2 \
-  public/media/hero.webm
-
-# MP4 (H.264), fallback. faststart so playback starts before the download ends.
-ffmpeg -i input.mov -t 10 -an -vf "scale='min(1920,iw)':-2,fps=30" \
-  -c:v libx264 -preset slow -crf 24 -profile:v high -pix_fmt yuv420p -movflags +faststart \
-  public/media/hero.mp4
-
-# Mobile variant: same commands with min(1080,iw) and one CRF step higher.
-
-# Poster from a representative frame (pick the second, never a black first frame)
-ffmpeg -ss 2.5 -i input.mov -frames:v 1 -vf "scale='min(1920,iw)':-2" -c:v libwebp -quality 80 public/media/hero-poster.webp
-```
-
-```tsx
-<video autoPlay muted loop playsInline preload="metadata" poster="/media/hero-poster.webp">
-  <source src="/media/hero.webm" type="video/webm" />
-  <source src="/media/hero.mp4" type="video/mp4" />
-</video>
-```
-
-- Under `prefers-reduced-motion` or Save-Data, show the poster and do not autoplay.
-- Pause offscreen loops (IntersectionObserver); keep one decoding video per viewport.
-- A scroll-scrubbed video sequence is better as a WebP frame sequence on a canvas than as `currentTime` scrubbing, which stutters on most browsers: `ffmpeg -i input.mov -vf "fps=24,scale='min(1440,iw)':-2" -c:v libwebp -quality 75 frames/%04d.webp`, then cap the count (120 to 180 frames).
-
-## 4. Images
-
-Use `next/image` for everything it can serve: it negotiates AVIF and WebP and resizes per `sizes`. Set `images.formats = ["image/avif", "image/webp"]` in `next.config`. What it cannot fix is a 12MB source in the repo, so normalize sources first:
-
-```bash
-# one-off with sharp-cli: cap sources at 2400w and convert to high-quality WebP
-npx sharp-cli -i "assets/raw/*.{jpg,png}" -o public/images/ resize 2400 --withoutEnlargement -f webp -q 82
-```
-
-- The LCP hint on exactly one image, the LCP image of that page: `preload` or `priority`, whichever the installed `next/image` declares ([setup.md](setup.md) §0, Known API shifts). Never `fetchPriority="high"` without `loading="eager"`; on a lazy image the hint does nothing.
-- `sizes` on every large image, matching the layout (`(min-width: 1024px) 50vw, 100vw`).
-- Width and height, or `fill` inside a sized frame, on every image: that is CLS.
-- PNG only for real transparency that WebP cannot carry; GIF never (convert to a muted video loop).
-- The grade from [imagery.md](imagery.md) is applied before export, not with CSS filters at runtime.
-
-## 5. 3D models and textures
-
-```bash
-# one command: dedupe, weld, meshopt geometry, WebP textures capped at 2048,
-# with the scene graph kept intact
-npx @gltf-transform/cli optimize input.glb public/models/product.glb \
-  --compress meshopt --texture-compress webp --texture-size 2048 \
-  --flatten false --join false
-```
-
-- `--flatten false --join false` keep the node hierarchy and names. The defaults flatten the scene and merge meshes, which drops the node names that rigs, `useGLTF` lookups and per-part animation target. Drop the two flags only for a static, single-object model that nothing addresses by name.
-- drei's `useGLTF` takes meshopt as a boolean and ships its own decoder: `useGLTF(url, true, true)` (Draco on, meshopt on). The Draco decoder is fetched only for a Draco-compressed file; self-host it once with `useGLTF.setDecoderPath("/draco/")` at module level in the island. See [webgl-scenes.md](webgl-scenes.md) §1.
-- Textures are usually the weight, not geometry: 2048 max on desktop, 1024 for mobile variants.
-- Every model loads when its island mounts. `useGLTF.preload` buys nothing inside the lazy island (it runs only when the island chunk loads), and calling it from the section pulls three into the page bundle; the poster covers the wait.
-- Always ship the poster image that stands in before and instead of the canvas ([webgl-r3f.md](webgl-r3f.md)).
-
-## 6. Fonts
-
-- Two families, WOFF2 only, variable files where they exist. `next/font` self-hosts and subsets Google fonts automatically; for local files subset to the languages used.
-- Preload the display and the body face, nothing else.
-- `adjustFontFallback` (default in `next/font`) to keep CLS near zero when the face swaps.
-- The TTF kept for OG images lives outside `public/` so it is never shipped to browsers ([seo.md](seo.md)).
-
-## 7. Code
-
-- **Lazy WebGL.** three.js, R3F, Drei and postprocessing load only inside the island, via `next/dynamic` with `ssr: false`. They must never appear in the first-load bundle.
-- **One clock.** Lenis, ScrollTrigger and R3F all on `gsap.ticker` ([setup.md](setup.md)); a second requestAnimationFrame loop is a performance bug, not a style choice.
-- **Animate transforms and opacity only.** Never `top`, `left`, `width`, `height` or `filter: blur()` on scroll. `clip-path` and masks are fine for reveals.
-- **No React state per frame.** Scroll and pointer values go to refs, CSS variables or uniforms ([webgl-r3f.md](webgl-r3f.md) §3).
-- **`will-change` only while animating**, set and cleared by the timeline, never globally.
-- **Clean up.** Every `useGSAP` scope reverts on unmount; route changes must not leave ScrollTriggers, tickers or canvases alive ([route-transitions.md](route-transitions.md)).
-- **Register only the GSAP plugins in use.**
-
-## 8. Verify
-
-1. **Build for production and serve it** (`next build && next start -p <port>`, or `vite build && vite preview --port <port>`). Never measure or shoot the dev server. **Confirm the port belongs to the server you just started:** before starting, `lsof -i :<port>` (Windows: `netstat -ano | findstr :<port>`) shows nothing; after, it shows the PID of that production process. A dev server left running on the same port answers every request silently, and `next start` then fails with `EADDRINUSE` in a log nobody reads.
-2. **First-load JS.** Turbopack builds print no per-route "First Load JS" table, so measure it from the served HTML. The script also proves three.js is absent on touch and arrives lazily on desktop:
-
-   ```js
-   // scripts/firstload.mjs: node scripts/firstload.mjs http://localhost:<port>
-   import { gzipSync } from "node:zlib";
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   const html = await (await fetch(base + "/")).text();
-   const srcs = [...new Set([...html.matchAll(/<script[^>]+src="([^"]+)"/g)].map((m) => m[1]))];
-   const THREE = /WebGLRenderer|WebGL2RenderingContext|react-three-fiber/;
-   let raw = 0, gz = 0;
-   const hits = [];
-   for (const s of srcs) {
-     const buf = Buffer.from(await (await fetch(new URL(s, base))).arrayBuffer());
-     raw += buf.length; gz += gzipSync(buf).length;
-     if (THREE.test(buf.toString("utf8"))) hits.push(s);
-   }
-   console.log(`first-load: ${srcs.length} scripts, ${(raw / 1024).toFixed(1)} kB raw, ${(gz / 1024).toFixed(1)} kB gzip`);
-   console.log(`three.js in first load: ${hits.length ? hits.join(", ") : "none"}`);
-
-   const browser = await chromium.launch({ args: ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"] });
-   for (const [name, opts] of [
-     ["desktop", { viewport: { width: 1440, height: 900 } }],
-     ["phone", { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true }],
-   ]) {
-     const page = await browser.newPage(opts);
-     const js = [];
-     page.on("response", async (r) => {
-       if (!r.url().endsWith(".js")) return;
-       try { const b = await r.body(); js.push({ kb: b.length / 1024, three: THREE.test(b.toString("utf8")) }); } catch {}
-     });
-     await page.goto(base, { waitUntil: "networkidle" });
-     await page.waitForTimeout(1500);
-     const lazy = js.filter((j) => j.three);
-     console.log(`${name}: ${js.length} JS files; three.js chunks ${lazy.length} (${lazy.reduce((a, b) => a + b.kb, 0).toFixed(1)} kB raw)`);
-     await page.close();
-   }
-   await browser.close();
-   ```
-
-3. **LCP and CLS: an in-page probe** under 4x CPU and a throttled network (about 1.6 Mbps down, 150ms latency), mobile 390 and desktop 1440. It names the LCP element, which is the number that matters: with a hidden split hero or a match cut, the LCP element is whatever appears last, and on an unthrottled local server the figure is meaningless (a text hero measures 150ms locally).
-
-   ```js
-   // scripts/vitals.mjs: node scripts/vitals.mjs http://localhost:<port>
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   const browser = await chromium.launch();
-   for (const [label, opts] of [
-     ["mobile 390", { viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true }],
-     ["desktop 1440", { viewport: { width: 1440, height: 900 } }],
-   ]) {
-     const ctx = await browser.newContext(opts);
-     const page = await ctx.newPage();
-     const cdp = await ctx.newCDPSession(page);
-     await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
-     await cdp.send("Network.enable");
-     await cdp.send("Network.emulateNetworkConditions", {
-       offline: false, latency: 150, downloadThroughput: (1.6 * 1024 * 1024) / 8, uploadThroughput: (750 * 1024) / 8,
-     });
-     await page.addInitScript(() => {
-       const v = { lcp: 0, cls: 0, el: "" };
-       Object.assign(window, { __vitals: v });
-       new PerformanceObserver((list) => {
-         for (const e of list.getEntries()) {
-           v.lcp = e.startTime;
-           const el = e.element;
-           v.el = el ? `${el.tagName} ${(el.getAttribute("src") ?? el.textContent ?? "").slice(0, 60)}` : "";
-         }
-       }).observe({ type: "largest-contentful-paint", buffered: true });
-       new PerformanceObserver((list) => {
-         for (const e of list.getEntries()) if (!e.hadRecentInput) v.cls += e.value;
-       }).observe({ type: "layout-shift", buffered: true });
-     });
-     await page.goto(base, { waitUntil: "load" });
-     await page.waitForTimeout(5000);           // let timed entrances finish: their content is often the LCP
-     await page.mouse.wheel(0, 600);            // LCP stops recording at the first input
-     await page.waitForTimeout(500);
-     const v = await page.evaluate(() => window.__vitals);
-     console.log(`${label}: LCP ${(v.lcp / 1000).toFixed(2)}s (${v.el.trim()}), CLS ${v.cls.toFixed(3)}`);
-     await ctx.close();
-   }
-   await browser.close();
-   ```
-
-   Lighthouse (or PageSpeed Insights on the deploy) on the home page and one inner page is the second opinion. Lab tools report TBT, not INP: INP needs field data (PageSpeed's CrUX panel once the site has traffic) or a manual interaction trace in the performance panel (click the menu, a hover scene and a form control; read the longest interaction). Until then write "INP: field data pending" with the TBT number.
-4. **Frame trace for timed entrances.** A PNG at rest cannot show a hold that fires over an empty frame, a split hero that flashes unsplit, or a reveal stuck at opacity 0. Capture the first 3 seconds and look at the frames in order:
-
-   ```js
-   // scripts/trace.mjs: node scripts/trace.mjs http://localhost:<port>  (writes shots/trace-<w>-NN.png)
-   import { mkdirSync } from "node:fs";
-   import { chromium } from "playwright";
-
-   const base = process.argv[2];
-   mkdirSync("shots", { recursive: true });
-   const browser = await chromium.launch();
-   for (const [w, h, mobile] of [[1440, 900, false], [390, 844, true]]) {
-     const page = await browser.newPage({ viewport: { width: w, height: h }, isMobile: mobile, hasTouch: mobile });
-     const t0 = Date.now();
-     await page.goto(base, { waitUntil: "commit" });
-     for (let i = 0; i < 15; i++) {
-       await page.screenshot({ path: `shots/trace-${w}-${String(i).padStart(2, "0")}.png` }).catch(() => {});
-       console.log(`${w} frame ${i}: ${Date.now() - t0}ms`);
-       await page.waitForTimeout(200);
-     }
-     await page.close();
-   }
-   await browser.close();
-   ```
-
-   Each entrance must do what its recipe says: the hold frame of a match cut is the photo ([page-entrances.md](page-entrances.md)), the split hero never shows unsplit, nothing stays invisible ([pitfalls.md](pitfalls.md) §3).
-5. Scroll the full page with the browser's performance panel recording: no long tasks during scroll, frames steady through the pinned showpiece.
-6. Re-run the size listing from §2 on the output: nothing over budget without a written reason in STRUQ.md.
-
-The scripts use the `playwright` package (`npm i -D playwright`, then `npx playwright install chromium`); any harness browser tool that can throttle, observe and screenshot does the same job.