claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/frontend-3d/rules/frontend-aesthetics-3d.md

@@ -0,0 +1,81 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/presentation/**/*.tsx"
+  - "**/presentation/**/*.jsx"
+  - "**/landing/**/*.tsx"
+  - "**/landing/**/*.jsx"
+tokens: 685
+---
+
+# Frontend Aesthetics — 3D & Presentation
+
+Aesthetics rules for 3D-enhanced presentation/landing pages. If the core `frontend-aesthetics` rule is installed, this extends it with animation and 3D-specific patterns; every rule below also stands on its own.
+
+## 1. Anti-Center Bias
+
+When a section contains more than 4 visual elements (cards, CTAs, images, 3D objects), do not center everything — pick one of:
+- Split screen: content left, 3D right (or vice versa)
+- Asymmetric layout with intentional negative space
+- 3D element offset from center for visual interest
+
+## 2. Cards Only When Earned
+
+Use a card only when elevation communicates hierarchy — never as the default container. If every section is a card, nothing has emphasis.
+
+## 3. Viewport Units
+
+```tsx
+// WRONG — iOS Safari address bar causes jumping
+h-screen
+
+// RIGHT — dynamic viewport height
+min-h-[100dvh]
+```
+
+## 4. Grid Over Flex Math
+
+```tsx
+// WRONG — fragile percentage calculations
+<div className="flex">
+  <div className="w-[calc(50%-12px)]">
+
+// RIGHT — explicit grid
+<div className="grid grid-cols-2 gap-6">
+```
+
+## 5. Staggered Reveals
+
+List/grid items MUST use staggered entrance — batch pop-in (all items appearing simultaneously) looks cheap.
+
+```tsx
+// 0.05-0.1s delay between items (GSAP)
+stagger: { each: 0.08, from: 'start' }
+```
+
+## 6. Spring Physics for Interactions
+
+For interactive presentation elements (hover cards, draggable 3D, mouse-tracking) on Framer Motion stacks (`framer-motion` / `motion`):
+
+```tsx
+// WRONG — robotic
+transition={{ duration: 0.3, ease: 'linear' }}
+
+// RIGHT — natural feel
+transition={{ type: 'spring', stiffness: 300, damping: 20 }}
+```
+
+GSAP has no `type: 'spring'` — never paste these props into a GSAP tween. On GSAP-only stacks use an ease instead (`ease: 'back.out(1.7)'` for interactive pops; for scroll/3D ease choices see the Ease Standards table in `gsap-conventions.md`). Simple open/close state transitions in plain 2D UI follow the frontend-ui `motion-and-animation.md` rule when installed: duration-based ease-out, not springs.
+
+## 7. 3D Scene Atmosphere
+
+- Dark backgrounds: ambient < 0.3, dramatic key light
+- Light backgrounds: ambient 0.7–0.8, soft even lighting
+- Add `<Float>` for idle animation (static 3D looks dead) — EXCEPT when `window.matchMedia('(prefers-reduced-motion: reduce)')` matches: render the scene without idle motion
+- `ContactShadows` for grounding — floating objects feel disconnected
+
+## 8. Scroll-Driven 3D
+
+- The 3D model MUST respond to scroll — rotation, scale, material changes
+- Use phase-based animation (entry → showcase → transition → exit); each phase has a clear visual purpose — no random motion
+- Timeline and scrub mechanics follow `gsap-conventions.md`

package/packages/frontend-3d/rules/gsap-conventions.md

@@ -0,0 +1,129 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/presentation/**"
+  - "**/src/**/*.tsx"
+  - "**/src/**/*.jsx"
+tokens: 827
+---
+
+# GSAP ScrollTrigger Conventions
+
+Mandatory rules for GSAP scroll-driven animation code. Violations cause visual bugs.
+
+**Scope:** this rule governs scroll-scrubbed presentation timelines and 3D scene motion. Interactive 2D UI element transitions (buttons, dropdowns, modals, hovers) follow `motion-and-animation.md` (frontend-ui package) instead — including its ease rules.
+
+## 1. Timeline Extension — normalized scrub timelines ONLY
+
+Precondition — apply this rule only when BOTH hold:
+
+- the timeline is driven by ScrollTrigger `scrub`, AND
+- its positions are normalized to the 0–1 range (the Phase Object pattern, rule 6).
+
+Then, immediately after creating the timeline, add:
+
+```tsx
+tl.set({}, {}, 1.0); // no-op keyframe at position 1.0 — forces timeline to span the full 0–1 range
+```
+
+**Why:** without it, animations compress into the first ~10% of the scroll range.
+
+Duration-based (non-scrub) timelines: do NOT add this line — position `1.0` is meaningless there and inserts a stray keyframe.
+
+## 2. Scrub Must Be a Number
+
+```tsx
+// WRONG
+scrub: true
+
+// RIGHT
+scrub: 1       // standard smoothness
+scrub: 0.5     // snappier
+scrub: 0.3     // very responsive
+```
+
+**Why:** `scrub: true` (boolean) causes jerky, non-smooth scrolling behavior.
+
+## 3. invalidateOnRefresh
+
+Every ScrollTrigger config MUST include:
+
+```tsx
+scrollTrigger: {
+  invalidateOnRefresh: true,
+  // ... other config
+}
+```
+
+**Why:** without it, calculated positions break on window resize.
+
+## 4. Context Cleanup
+
+All animations MUST be inside `gsap.context()` with cleanup:
+
+```tsx
+useEffect(() => {
+  const ctx = gsap.context(() => {
+    // all animations here
+  }, containerRef);
+
+  return () => ctx.revert();
+}, []);
+```
+
+**Why:** without context, animations leak memory and break on React re-renders.
+
+## 5. Centralized GSAP Import
+
+Import GSAP from the project's setup module, never directly:
+
+```tsx
+// WRONG
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+
+// RIGHT
+import { gsap, ScrollTrigger } from '@/lib/gsap-setup';
+```
+
+If no setup module exists yet, create one first (adjust the path to the project's alias):
+
+```tsx
+// lib/gsap-setup.ts
+import gsap from 'gsap';
+import { ScrollTrigger } from 'gsap/ScrollTrigger';
+
+gsap.registerPlugin(ScrollTrigger);
+
+export { gsap, ScrollTrigger };
+```
+
+**Why:** ensures plugins are registered exactly once, consistently.
+
+## 6. Phase Object for Timeline Positions
+
+Use named constants, not magic numbers:
+
+```tsx
+const P = {
+  entryStart: 0,
+  entryEnd: 0.25,
+  showcaseStart: 0.25,
+  showcaseEnd: 0.7,
+  exitStart: 0.7,
+  exitEnd: 1.0,
+};
+
+tl.fromTo(element, { opacity: 0 }, { opacity: 1, duration: P.entryEnd - P.entryStart }, P.entryStart);
+```
+
+## 7. Ease Standards — scroll/3D contexts only
+
+This table applies to scroll-scrubbed timelines and 3D scene motion. For 2D UI element transitions, use the ease rules in `motion-and-animation.md` (frontend-ui package): ease-out there, never ease-in.
+
+| Use Case | Ease | Why |
+|----------|------|-----|
+| Entrances | `power3.out` | Fast start, gentle stop |
+| Crossfades | `power2.inOut` | Smooth both directions |
+| Subtle motion | `sine.in` / `sine.out` | Barely perceptible |
+| Viewport exits | `power2.in` | Gentle start, fast finish — allowed for scroll/3D exits only |

package/packages/frontend-3d/rules/threejs-conventions.md

@@ -0,0 +1,116 @@
+---
+alwaysApply: false
+applyWhenPaths:
+  - "**/components/3d/**"
+  - "**/three/**"
+  - "**/scene/**"
+  - "**/r3f/**"
+tokens: 870
+---
+
+# Three.js / R3F Conventions
+
+Mandatory rules for React Three Fiber and Three.js code. For debugging wrong-looking colors (washed out, oversaturated, too dark), load the `threejs-color-management` skill — the settings below match its pipeline.
+
+## 1. UI Screen Textures
+
+Textures representing UI (screenshots, app screens) on 3D models:
+
+```tsx
+<meshBasicMaterial
+  map={screenTexture}
+  toneMapped={false}
+/>
+// + screenTexture.colorSpace = THREE.SRGBColorSpace
+```
+
+**Rules:**
+- Use `meshBasicMaterial` — screens emit light, they don't reflect it
+- NEVER `MeshStandardMaterial` for display screens
+- Set `toneMapped={false}` — prevents ACES tone mapping from distorting UI colors
+- Set `texture.colorSpace = THREE.SRGBColorSpace` for any photo/UI texture; data textures (normal, roughness) stay `THREE.LinearSRGBColorSpace`
+- Never `sRGBEncoding` / `texture.encoding` — deprecated since r152; use `colorSpace`
+- Set Canvas `gl={{ toneMapping: THREE.NoToneMapping }}` when a UI/screen texture occupies the majority of the frame or is the hero object; otherwise keep the R3F default (`THREE.ACESFilmicToneMapping`) for realistic scenes. Always write the named constant, never bare `0`.
+
+## 2. UV Settings on Texture Replacement
+
+When replacing a material's texture map, MUST copy ALL UV settings:
+
+```tsx
+newTexture.flipY = oldTexture.flipY;
+newTexture.wrapS = oldTexture.wrapS;
+newTexture.wrapT = oldTexture.wrapT;
+newTexture.offset.copy(oldTexture.offset);
+newTexture.repeat.copy(oldTexture.repeat);
+newTexture.rotation = oldTexture.rotation;
+newTexture.center.copy(oldTexture.center);
+```
+
+**Why:** Forgetting any of these causes texture misalignment, stretching, or mirroring.
+
+Also set `newTexture.colorSpace` per Section 1 — the seven lines above do not copy it.
+
+## 3. GLB Preloading
+
+Always preload at module level (outside the component):
+
+```tsx
+useGLTF.preload('/models/phone.glb');
+```
+
+**Why:** Without preload, model loads on mount causing visible pop-in.
+
+## 4. useFrame Performance
+
+```tsx
+// WRONG — allocates on every frame (60fps = 60 allocations/sec)
+useFrame(() => {
+  const pos = new THREE.Vector3(1, 2, 3);
+});
+
+// RIGHT — pre-allocate in ref
+const tempVec = useRef(new THREE.Vector3());
+useFrame(() => {
+  tempVec.current.set(1, 2, 3);
+});
+```
+
+## 5. Zustand in useFrame
+
+```tsx
+// WRONG — hook subscription triggers re-renders
+const progress = useStore((s) => s.progress);
+useFrame(() => { /* use progress */ });
+
+// RIGHT — direct read, no re-renders
+useFrame(() => {
+  const { progress } = useStore.getState();
+});
+```
+
+## 6. DPR Settings
+
+```tsx
+<Canvas dpr={[1, 2]}>
+```
+
+Higher values degrade mobile performance with minimal visual benefit.
+
+## 7. Disposal
+
+Pick the branch by how the asset is used:
+
+| Asset | Rule |
+|-------|------|
+| Shared/preloaded GLTF (`useGLTF`, rendered in more than one place or preloaded via `useGLTF.preload`) | Wrap in `<group dispose={null}>` — the loader cache owns the asset; auto-disposal on unmount would break every other consumer |
+| One-off geometry/material/texture declared in JSX, used by a single component | No `dispose={null}` — R3F disposes it automatically on unmount |
+| Objects created imperatively (`new THREE.CanvasTexture(...)`, render targets) | Call `.dispose()` yourself in the `useEffect` cleanup |
+
+```tsx
+// Shared/preloaded model — protect the cached asset:
+<group dispose={null}>
+  <Model />
+</group>
+```
+
+Do NOT put `dispose={null}` on one-off scenes — that leaks GPU memory on unmount.

package/packages/frontend-3d/skills/gltf-debugging/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: gltf-debugging
+description: Runtime GLB/GLTF inspection — traverse nodes, identify screen meshes, inspect UV coordinates, material property dumping, fixing exported materials at runtime. Use when textures don't map correctly to 3D models.
+tokens: 1419
+---
+
+# GLTF/GLB Debugging
+
+## Purpose
+
+Runtime inspection recipes for when textures don't map correctly onto a loaded GLB/GLTF model: traverse meshes, check UV coordinates, dump material properties, replace textures without breaking UV mapping.
+
+## Use when / Do not use
+
+**Use when:** a texture renders wrong on a GLB/GLTF (stretched, black, mirrored, on the wrong mesh), or you need to find which mesh is the "screen"/target surface in a model.
+**Do not use for:** general color-space pipeline setup (see `threejs-color-management`) or scroll/animation issues (see `r3f-scroll-driven-3d`).
+
+## Hard Rules
+
+1. Run Steps 1→4 in order. Inspect before fixing — never guess at a fix without traversal + UV + material data.
+2. NEVER modify a mesh's material in place. Clone first (`mesh.material = mat.clone()`) — exported materials are often shared across meshes.
+3. When replacing a texture, copy ALL 7 UV settings from the old map: `flipY`, `wrapS`, `wrapT`, `offset`, `repeat`, `rotation`, `center`. Missing even one causes flipped/offset textures.
+4. After any texture or material change, set both `texture.needsUpdate = true` AND `material.needsUpdate = true`.
+5. `colorSpace = THREE.SRGBColorSpace` + `toneMapped = false` applies to color/UI/photo maps (`.map`) ONLY. Data textures (`normalMap`, `roughnessMap`, `metalnessMap`, `aoMap`) use `THREE.LinearSRGBColorSpace` and keep `toneMapped` as exported.
+
+## Workflow
+
+Optional pre-check (offline, before touching runtime code) — list scenes, meshes, materials, and textures of the file:
+
+```bash
+npx @gltf-transform/cli inspect model.glb
+```
+
+### Step 1 — Traverse All Meshes
+
+See what's in the model; find the target mesh by name.
+
+```tsx
+useEffect(() => {
+  scene.traverse((child) => {
+    if ((child as THREE.Mesh).isMesh) {
+      const mesh = child as THREE.Mesh;
+      console.log(`Mesh: ${mesh.name}`, {
+        geometry: mesh.geometry.attributes,
+        material: (mesh.material as THREE.Material).type,
+        visible: mesh.visible,
+      });
+    }
+  });
+}, [scene]);
+```
+
+### Step 2 — Inspect UV Coordinates
+
+UV coordinates map 2D textures onto 3D geometry. Range 0–1 = good.
+
+```tsx
+const geo = mesh.geometry;
+const uvAttr = geo.attributes.uv;
+
+if (!uvAttr) {
+  console.error(`${mesh.name}: NO UV coordinates!`);
+  // Fix: re-export from Blender with UV map
+} else {
+  // Check UV range
+  let minU = Infinity, maxU = -Infinity;
+  let minV = Infinity, maxV = -Infinity;
+  for (let i = 0; i < uvAttr.count; i++) {
+    const u = uvAttr.getX(i), v = uvAttr.getY(i);
+    minU = Math.min(minU, u); maxU = Math.max(maxU, u);
+    minV = Math.min(minV, v); maxV = Math.max(maxV, v);
+  }
+  console.log(`${mesh.name} UV range: U[${minU},${maxU}] V[${minV},${maxV}]`);
+  // [0,1] = single texture fill. [0,0.5] = uses half the texture (atlas)
+}
+```
+
+### Step 3 — Dump Material Properties
+
+```tsx
+const mat = mesh.material as THREE.MeshStandardMaterial;
+console.log(`${mesh.name} material:`, {
+  type: mat.type,
+  map: mat.map ? 'yes' : 'no',
+  emissiveMap: mat.emissiveMap ? 'yes' : 'no',
+  normalMap: mat.normalMap ? 'yes' : 'no',
+  roughness: mat.roughness,
+  metalness: mat.metalness,
+  color: mat.color?.getHexString(),
+  toneMapped: mat.toneMapped,
+});
+```
+
+### Step 4 — Replace Texture Safely
+
+Apply Hard Rules 2–5: clone the material, copy all 7 UV settings, flag updates.
+
+```tsx
+function replaceTexture(mesh: THREE.Mesh, newTexture: THREE.Texture) {
+  const mat = mesh.material as THREE.MeshBasicMaterial;
+  const oldMap = mat.map;
+
+  // Clone material to not affect other meshes sharing it
+  mesh.material = mat.clone();
+  const newMat = mesh.material as THREE.MeshBasicMaterial;
+
+  // Copy ALL UV settings from original texture
+  if (oldMap) {
+    newTexture.flipY = oldMap.flipY;
+    newTexture.wrapS = oldMap.wrapS;
+    newTexture.wrapT = oldMap.wrapT;
+    newTexture.offset.copy(oldMap.offset);
+    newTexture.repeat.copy(oldMap.repeat);
+    newTexture.rotation = oldMap.rotation;
+    newTexture.center.copy(oldMap.center);
+  }
+
+  // Color/UI/photo texture tail. For data textures (normalMap, roughnessMap,
+  // metalnessMap, aoMap): use THREE.LinearSRGBColorSpace and keep toneMapped.
+  newTexture.colorSpace = THREE.SRGBColorSpace;
+  newTexture.needsUpdate = true;
+
+  newMat.map = newTexture;
+  newMat.toneMapped = false;
+  newMat.needsUpdate = true;
+}
+```
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Texture stretched/squished | UV coordinates don't match texture aspect ratio | Check UV range (Step 2). If model uses a UV atlas, you may need custom UV mapping |
+| Texture appears on wrong mesh | Multiple meshes share a material | Clone material before modifying: `mesh.material = mat.clone()` |
+| Texture flipped/mirrored | `flipY` mismatch between old and new texture | Copy `flipY` from original texture, or try toggling it |
+| Black/invisible texture | `needsUpdate` not called, or wrong `colorSpace` | Set `texture.needsUpdate = true` and `material.needsUpdate = true`; check Hard Rule 5 |
+| Sketchfab model with baked textures | Texture atlas — UVs map to specific regions of a combined image | Use the original atlas texture, or re-UV the screen mesh in Blender |
+| Glass mesh hiding screen content | Front glass mesh occludes screen texture | Set glass mesh `visible={false}`, or `material.transparent = true` with low opacity |
+
+## Recap — non-negotiables
+
+- Inspect in order (traverse → UV → material dump) before applying any fix.
+- Clone shared materials; never mutate in place.
+- Copy all 7 UV settings when swapping a texture; then `needsUpdate = true` on both texture and material.
+- `SRGBColorSpace`/`toneMapped = false` for color maps only — data maps stay linear.

package/packages/frontend-3d/skills/html-to-3d-texture/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: html-to-3d-texture
+description: Capture HTML/React components as PNG or canvas textures for 3D model screens — Playwright, html2canvas, live CanvasTexture, resolution guide, rounded-corner masking.
+tokens: 1514
+---
+
+# HTML to 3D Texture Pipeline
+
+## Purpose
+
+Display web UI on a 3D surface: render a React component, capture it as a PNG or canvas, apply it as a Three.js texture on the model's screen mesh.
+
+```
+React Component → Capture (Playwright/html2canvas) → PNG/Canvas → Three.js Texture → 3D Mesh
+```
+
+## Use when / Do not use
+
+- **Use when**: a 3D model (phone, laptop, tablet) must show real web UI on its screen.
+- **Do not use when**: the UI must stay clickable/scrollable on the 3D surface — a texture is a flat image. Use `@react-three/drei` `<Html>` instead.
+
+## Hard Rules
+
+- Set `texture.colorSpace = THREE.SRGBColorSpace` on every texture built from a capture — otherwise colors wash out.
+- Capture at 2x (`deviceScaleFactor: 2` / `scale: 2`) — 1x textures look blurry on retina screens.
+- html2canvas re-parses the entire DOM subtree on every call — this cost applies to Method 2 AND Method 3. In any repeated-capture loop, cap refresh at 1–2 fps for production; higher rates (e.g. 10 fps) are local-dev demos only.
+
+## Workflow
+
+1. Pick the capture method from the decision table below.
+2. Capture at 2x using that method's code.
+3. Post-process if the screen needs rounded corners (sharp recipe below).
+4. Apply as texture with `SRGBColorSpace` set (PNG → `THREE.TextureLoader`; canvas → `THREE.CanvasTexture`).
+
+## Decision table — which method
+
+| Content on the 3D screen | Method |
+|--------------------------|--------|
+| Static — never changes at runtime | **Method 1** — Playwright PNG (build-time) |
+| Changes on discrete events (user action, data loaded) | **Method 2** — one-shot html2canvas per event |
+| Changes continuously (timers, animations, live data) | **Method 3** — throttled html2canvas loop |
+| Must remain interactive (clicks, scroll, inputs) | Not a texture — drei `<Html>` |
+
+Default when unsure: **Method 1** — best quality, zero runtime cost.
+
+## Method 1: Playwright Capture (build-time, best quality)
+
+Best for: production screenshots, pixel-perfect captures.
+
+```javascript
+// scripts/capture-screen.mjs
+import { chromium } from 'playwright';
+
+const PORT = process.argv[2] || 3000;
+const WIDTH = 440;   // Native screen width
+const HEIGHT = 956;  // Native screen height
+const SCALE = 2;     // Retina (output: 880x1912)
+
+async function capture() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage({
+    viewport: { width: WIDTH, height: HEIGHT },
+    deviceScaleFactor: SCALE,
+  });
+
+  await page.goto(`http://localhost:${PORT}/capture`);
+  await page.waitForLoadState('networkidle');
+
+  // Find target element
+  const el = await page.locator('[data-screen-id="main"]');
+  await el.screenshot({
+    path: 'public/textures/screen.png',
+    type: 'png',
+  });
+
+  await browser.close();
+  console.log(`Captured: ${WIDTH * SCALE}x${HEIGHT * SCALE}px`);
+}
+
+capture();
+```
+
+## Method 2: One-shot html2canvas (event-driven runtime capture)
+
+Best for: content that changes on discrete events. Call once per change event (button click, data arrival) — do NOT wrap this in an interval; that is Method 3.
+
+```tsx
+import html2canvas from 'html2canvas';
+import * as THREE from 'three';
+
+async function captureToTexture(element: HTMLElement): Promise<THREE.CanvasTexture> {
+  const canvas = await html2canvas(element, {
+    scale: 2,
+    useCORS: true,
+    backgroundColor: null, // transparent
+  });
+
+  const texture = new THREE.CanvasTexture(canvas);
+  texture.colorSpace = THREE.SRGBColorSpace;
+  texture.needsUpdate = true;
+
+  return texture;
+}
+```
+
+## Method 3: Throttled html2canvas loop (continuous updates)
+
+Best for: UI that changes continuously while displayed on the 3D surface. Same capture as Method 2, driven by a timer — so the html2canvas cost from Hard Rules repeats every tick. Keep `FPS` at 1–2 in production.
+
+```tsx
+const FPS = 2; // production-safe (1-2 fps). 10 fps = local-dev demo only — CPU-heavy.
+
+function useHTMLTexture(ref: React.RefObject<HTMLDivElement>) {
+  const textureRef = useRef<THREE.CanvasTexture | null>(null);
+
+  useEffect(() => {
+    const interval = setInterval(async () => {
+      if (!ref.current) return;
+      const canvas = await html2canvas(ref.current, { scale: 2 });
+      if (textureRef.current) {
+        textureRef.current.image = canvas;
+        textureRef.current.needsUpdate = true;
+      } else {
+        textureRef.current = new THREE.CanvasTexture(canvas);
+        textureRef.current.colorSpace = THREE.SRGBColorSpace;
+      }
+    }, 1000 / FPS);
+
+    return () => clearInterval(interval);
+  }, [ref]);
+
+  return textureRef;
+}
+```
+
+## Resolution Guide
+
+| Device | Native (pts) | @2x (px) | Use for |
+|--------|-------------|----------|---------|
+| iPhone 15 Pro | 393x852 | 786x1704 | Phone model screen |
+| iPhone 16 Pro Max | 440x956 | 880x1912 | Large phone model |
+| iPad Pro 11" | 834x1194 | 1668x2388 | Tablet model |
+| MacBook Pro 14" | 1512x982 | 3024x1964 | Laptop model |
+
+## Applying Rounded Corners
+
+PNG with transparent rounded corners for phone screens:
+
+```javascript
+// Using sharp (Node.js)
+import sharp from 'sharp';
+
+const RADIUS = 124; // 62pt * 2x scale
+const { width, height } = await sharp('screen.png').metadata();
+
+const mask = Buffer.from(
+  `<svg width="${width}" height="${height}">
+    <rect x="0" y="0" width="${width}" height="${height}" 
+          rx="${RADIUS}" ry="${RADIUS}" fill="white"/>
+  </svg>`
+);
+
+await sharp('screen.png')
+  .ensureAlpha()
+  .composite([{ input: mask, blend: 'dest-in' }])
+  .png()
+  .toFile('screen-rounded.png');
+```
+
+## Tips
+
+- Always capture at 2x for retina quality
+- Use `data-screen-id` attribute to find elements reliably
+- Remove debug borders/outlines before capture
+- Test with `sips -g pixelWidth -g pixelHeight` (macOS) to verify dimensions
+- Set `backgroundColor: null` for transparent backgrounds when needed
+
+## Recap — non-negotiables
+
+- `SRGBColorSpace` on every capture-derived texture.
+- Capture at 2x, always.
+- Repeated html2canvas capture: 1–2 fps in production; 10 fps only as a labeled local-dev demo value.
+- Unsure which method: Method 1 (Playwright PNG).