howone 0.1.38 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howone",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "private": false,
   "description": "HowOne command line tools for creating app templates.",
   "type": "module",

package/templates/vite/.howone/skills/web-shader-extractor/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: web-shader-extractor
+description: >
+  Use when a user gives or references a webpage URL and wants to extract,
+  reproduce, port, or locally replay a WebGL, WebGPU, Canvas, shader-like,
+  animated background, interactive 3D, or web visual effect. Locks the target
+  rendering surface group, records shader/resource/render graph/timing/input
+  evidence, builds an evidence-matched local baseline, then projectizes it.
+  Do not use for ordinary DOM/CSS page cloning.
+---
+
+# Web Shader Extractor
+
+Index for WebGL / WebGPU / Canvas rendering investigation and local replay.
+Start from the target visual. Lock the surface group. Trace source or runtime facts. Build a runnable baseline. Then projectize.
+
+## Router Contract
+
+This file is the index. Do not treat it as the full operating manual. Before task action, read:
+
+- `references/operating-contract.md`
+- `references/recon-kernel.md`
+
+Then load only the focused references needed by the current state.
+Keep large evidence, captures, and generated outputs out of the conversation.
+Store them in the user's output directory.
+
+## Use This For
+
+- Extracting a webpage WebGL, WebGPU, Canvas2D, OffscreenCanvas, shader, or animated canvas effect.
+- Replaying an animated background, product shader, interactive WebGL scene, or Canvas visual locally.
+- Building an evidence-matched baseline first, then an editable project.
+- Investigating target-bound shader/render graph/timing/resource/input facts.
+
+Do not use this for ordinary DOM/CSS cloning, static screenshots, generic website copying, unrelated JavaScript deobfuscation, or product UI redesign.
+Use it only when the task has a shader/canvas target.
+
+## Core Rules
+
+- Target-bound before framework-bound: a global Three.js, platform, or shader signature is only a hypothesis until tied to the target surface group.
+- Evidence before implementation: source, runtime objects, frame captures, source maps, and public structured definitions outrank visual fitting.
+- Baseline before projectization: never overwrite a verified baseline for cleanup, simplification, or native conversion.
+- Honest labels: implementation-critical facts are `SOURCE`, `PARTIAL`, or `GUESS`; unlabeled values are treated as `GUESS`.
+- No compensation tuning: do not adjust brightness, time, color, offsets, or noise to mask missing pipeline evidence.
+- Gate artifacts are transition guards: if the required artifact is missing, incomplete, or has placeholders in gate-critical fields, the state has not advanced.
+- Ask only for product scope changes or external access/permission blockers.
+- Use plain records: state the fact, evidence path, current unknown, and next action. Avoid metaphor, broad claims, and unsupported conclusions.
+
+## State Router
+
+Use the Recon Kernel state flow:
+
+```text
+INTAKE -> CAPABILITY_SNAPSHOT -> QUICK_SCOUT -> SURFACE_ATTRIBUTION
+-> TARGET_LOCK_GATE
+   - provisional/failed -> REFINE_SCOUT
+   - attributed -> targeted owner/backend/source probe -> TARGET_LOCK_GATE
+   - locked -> SCOPE_CHECK
+-> TRACE_ROUTE_SELECT -> SOURCE_TRACE -> CAPTURE_MINIMUM_TRUTH
+-> REPLAY_READY_GATE
+   - not ready -> SOURCE_TRACE / CAPTURE_MINIMUM_TRUTH
+   - ready -> RAW_REPLAY
+-> BASELINE_RUN -> BASELINE_VERIFY
+-> BASELINE_VERIFIED -> PROJECTIZE -> PROJECT_VERIFY -> PACKAGE
+```
+
+`TARGET_LOCKED` must precede deep source/bundle work.
+Before lock, only narrow source probes tied to `nextProbe` are allowed.
+`REPLAY_READY` must precede implementation.
+`BASELINE_VERIFIED` must precede projectization.
+
+## Reference Router
+
+Load only what the current state needs:
+
+| Need | Read |
+|---|---|
+| Global contract, fact labels, completion states | `references/operating-contract.md` |
+| Kernel, initial protocol, state flow, autonomy, budgets | `references/recon-kernel.md` |
+| Surface discovery and visual attribution | `references/surface-discovery.md` |
+| Lock criteria, target-bound evidence, scope, Three.js binding | `references/target-lock.md` |
+| Evidence labels, ledgers, unknown classes, sensitive data | `references/evidence-policy.md` |
+| Tool capability selection | `references/tool-capability-matrix.md` |
+| WebGL, WebGPU, and Canvas2D capture facts | `references/capture-backends.md` |
+| Source maps, bundle slices, config, encoded definitions | `references/source-analysis.md` |
+| Replay readiness, routes, baseline, stack choice, projectization | `references/replay-policy.md` |
+| QA, failure routing, severity, mismatch signatures | `references/qa-failure-policy.md` |
+| Three.js shader injection or TSL reconstruction | `references/three-shader-reconstruction.md` |
+| Unicorn Studio target | `references/unicorn-studio.md` |
+| shaders.com / TSL target | `references/shaders-com.md` |
+
+## Tool And Artifact Policy
+
+Tools are replaceable capabilities, not prerequisites. First record the available capability profile:
+
+```text
+navigate, runtime-eval, preload-script, network-metadata, network-body,
+source-map, canvas-screenshot, interaction, frame-capture-webgl,
+frame-capture-webgpu, local-run, multi-frame-compare
+```
+
+Use `scripts/fetch-rendered-dom.mjs` only as an optional inventory helper when Playwright is already available.
+Use `scripts/scan-bundle.sh` only on target-bound bundle slices or a precise `nextProbe`.
+Script output is hypothesis evidence. It never satisfies Surface Attribution, Target Lock, Replay Ready, or QA gates by itself.
+
+Use bundled templates as schemas, not free-form notes:
+
+- `templates/scout-card.json`
+- `templates/replay-manifest.json`
+- `templates/run-state.json`
+- `templates/qa-report.md`
+- `templates/known-gaps.md`
+- `templates/extraction-report.md`
+
+## Platform Adapters
+
+Load platform references only after target-bound evidence points there:
+
+- Unicorn Studio: `references/unicorn-studio.md`
+- shaders.com / TSL: `references/shaders-com.md`
+- Three.js shader injection or TSL: `references/three-shader-reconstruction.md`
+
+If no adapter fits, follow generic WebGL, WebGPU, or Canvas2D capture in `references/capture-backends.md`.

package/templates/vite/.howone/skills/web-shader-extractor/references/capture-backends.md

@@ -0,0 +1,201 @@
+# Capture Backends
+
+Use after `TARGET_LOCKED`, or as a selected tactical probe while moving from `attributed` to `locked`. Capture only facts bound to the target surface group.
+
+## Common Rules
+
+- Prefer public source/config or runtime objects when they are target-bound.
+- Use preload hooks or frame capture when source does not expose the render graph.
+- Use bundle slices only when they resolve a named unknown.
+- Keep backend facts separate from replay implementation choices.
+- Record every hook result as evidence. Hook hits prove only that an API was used; they do not prove the target uses that API until tied to the target surface group, owner, frame, or call path.
+
+## WebGL / WebGL2
+
+Capture:
+
+- surface CSS size, backing size, DPR, and context attributes
+- vertex/fragment source or trusted source representation
+- attributes, buffers, indices, instancing, or fullscreen primitive
+- textures, samplers, formats, dimensions, and asset paths
+- pass order, FBOs, attachments, inputs, and outputs
+- viewport, scissor, clear, blend, depth, stencil, cull, alpha
+- time origin/unit/delta, random, uniform updates, pointer, scroll, resize
+- color space, tone mapping, premultiplied alpha, and DOM composite
+
+Common failure cases:
+
+- WebGL1 vs WebGL2 shader syntax
+- framebuffer orientation and texture coordinate flips
+- premultiplied alpha mismatch
+- renderer output color space vs shader internal color space
+- time measured in seconds, frames, or platform-specific increments
+- hidden parent DOM transforms changing canvas coordinates
+
+### WebGL Preload Hook Map
+
+Use this map when source or runtime objects do not expose enough facts. Hook only the minimum API set needed for the current unknown.
+
+Surface and owner:
+
+- `HTMLCanvasElement.prototype.getContext`
+- `OffscreenCanvas.prototype.getContext`
+- `HTMLCanvasElement.prototype.transferControlToOffscreen`
+
+Program and shader:
+
+- `createShader`
+- `shaderSource`
+- `compileShader`
+- `getShaderInfoLog`
+- `createProgram`
+- `attachShader`
+- `linkProgram`
+- `getProgramInfoLog`
+- `useProgram`
+
+Uniforms:
+
+- `getUniformLocation`
+- `uniform1f` / `uniform2f` / `uniform3f` / `uniform4f`
+- `uniform1i` / `uniform2i` / `uniform3i` / `uniform4i`
+- `uniformMatrix*`
+
+Geometry:
+
+- `createBuffer`
+- `bindBuffer`
+- `bufferData`
+- `bufferSubData`
+- `vertexAttribPointer`
+- `enableVertexAttribArray`
+- `bindVertexArray`
+
+Textures:
+
+- `createTexture`
+- `bindTexture`
+- `texImage2D`
+- `texSubImage2D`
+- `texParameteri`
+- `activeTexture`
+- `pixelStorei`
+
+Framebuffers:
+
+- `createFramebuffer`
+- `bindFramebuffer`
+- `framebufferTexture2D`
+- `createRenderbuffer`
+- `bindRenderbuffer`
+- `framebufferRenderbuffer`
+
+State:
+
+- `viewport`
+- `scissor`
+- `clearColor`
+- `clear`
+- `enable` / `disable`
+- `blendFunc` / `blendFuncSeparate`
+- `blendEquation`
+- `depthFunc`
+- `cullFace`
+- `colorMask`
+- `depthMask`
+
+Draw:
+
+- `drawArrays`
+- `drawElements`
+- `drawArraysInstanced`
+- `drawElementsInstanced`
+
+## WebGPU
+
+WebGPU targets do not pass through `gl.shaderSource()`. Treat them as a separate backend.
+
+Capture:
+
+- canvas configuration and preferred format
+- shader modules or trusted node/source definitions
+- render and compute pipeline descriptors
+- bind group layouts and bind groups
+- buffers, textures, samplers, and update cadence
+- render pass and compute pass order
+- command submission sequence
+- time, pointer, scroll, resize, random
+- output color, alpha, and canvas/DOM composite
+
+Prefer platform/source definitions, readable WGSL, or WebGPU capture tools.
+If the site uses Three.js TSL or another node system that targets WebGPU, capture the node definition and renderer route before translating to GLSL or WGSL.
+
+Do not declare WebGPU replay ready because a WebGL shader capture succeeded elsewhere on the page. Evidence must bind to the WebGPU target surface.
+
+### WebGPU Preload Hook Map
+
+- `navigator.gpu.requestAdapter`
+- `GPUAdapter.requestDevice`
+- `GPUCanvasContext.configure`
+- `GPUDevice.createShaderModule`
+- `GPUDevice.createRenderPipeline`
+- `GPUDevice.createComputePipeline`
+- `GPUDevice.createBindGroupLayout`
+- `GPUDevice.createBindGroup`
+- `GPUDevice.createBuffer`
+- `GPUDevice.createTexture`
+- `GPUCommandEncoder.beginRenderPass`
+- `GPUCommandEncoder.beginComputePass`
+- `GPURenderPassEncoder.setPipeline`
+- `GPURenderPassEncoder.setBindGroup`
+- `GPURenderPassEncoder.draw`
+- `GPURenderPassEncoder.drawIndexed`
+- `GPUQueue.writeBuffer`
+- `GPUQueue.writeTexture`
+- `GPUQueue.submit`
+
+## Canvas2D
+
+Canvas2D targets need command, asset, font, and timing facts rather than shader facts.
+
+Capture:
+
+- command stream or readable source
+- transforms and clipping
+- paths, text, image draws
+- gradients, patterns, filters
+- `globalCompositeOperation`
+- assets and fonts
+- timing, random, pointer, scroll, resize
+- canvas size, DPR, and DOM composite
+
+Use Vanilla JS for simple Canvas2D baselines. Keep static offscreen buffers when the source uses them. Match font loading and text metrics before tuning positions.
+
+Common failure cases:
+
+- font fallback changes glyph metrics
+- DPR scaling applied twice or not at all
+- filter/composite order differs from source
+- image smoothing settings change texture quality
+- random state is re-created every frame in the replay
+
+### Canvas2D Command Capture Map
+
+- `drawImage`
+- `fillRect` / `strokeRect` / `clearRect`
+- `beginPath` / `moveTo` / `lineTo` / `bezierCurveTo` / `arc` / `fill` / `stroke` / `clip`
+- `fillText` / `strokeText`
+- `setTransform` / `transform` / `translate` / `rotate` / `scale`
+- `save` / `restore`
+- `globalAlpha`
+- `globalCompositeOperation`
+- `filter`
+- `createLinearGradient` / `createRadialGradient` / `createPattern`
+- `imageSmoothingEnabled`
+
+## OffscreenCanvas And Worker Probes
+
+- Hook `transferControlToOffscreen` before page scripts run when worker ownership is suspected.
+- Record worker script URLs and message channels, but do not persist private message payloads unless they are public effect definitions needed for replay.
+- Bind OffscreenCanvas evidence back to the visible placeholder canvas or DOM layer before promoting owner or backend facts.
+- If worker source cannot be read, capture call timing, canvas dimensions, and message shapes as `PARTIAL` evidence and keep the missing source as a blocking or important unknown.

package/templates/vite/.howone/skills/web-shader-extractor/references/evidence-policy.md

@@ -0,0 +1,93 @@
+# Evidence Policy
+
+Choose evidence by authority and collection cost.
+
+## Truth Labels
+
+Every implementation-critical fact needs a nearby truth label. If a fact has no label, treat it as `GUESS`.
+
+| Label | Meaning | Valid evidence |
+|---|---|---|
+| `SOURCE` | Direct target-bound evidence from implementation or runtime. | Public source, source map, runtime object dump, captured shader/WGSL, GPU frame capture, network body with hash, or authoritative API output. |
+| `PARTIAL` | Target-bound handle whose value, wiring, or replay role is not proven. | Symbol name, bundle slice, framework object, shader without draw/resource state, owner hint, or resource URL without use evidence. |
+| `GUESS` | No direct evidence for the fact. | Visual fit, naming inference, copied defaults, hand-tuned constants, approximate behavior rebuild, or unverified assumption. |
+
+Do not describe `PARTIAL` or `GUESS` facts as extracted source. A behavior rebuild can be used, but it stays approximate until promoted by evidence.
+
+## Leaf Facts vs Wiring Facts
+
+False conclusions often come from proving a leaf fact and guessing the wiring fact. Audit them separately:
+
+- Leaf facts: shader source, WGSL, constants, config values, asset URLs, resource dimensions, sampler settings, context attributes.
+- Wiring facts: target ownership, draw/pass order, FBO dependencies, coordinate transforms, time unit, delta rule, random source, input coupling, resize behavior, color/alpha/DOM composite.
+
+`SOURCE` leaf facts do not promote unproven wiring.
+A source shader string does not prove active pass order.
+A config field named `velocity` does not prove units.
+A framework signature does not prove the target canvas uses that framework.
+
+## Promotion Rules
+
+Promote a fact only when evidence improves:
+
+- `GUESS -> PARTIAL`: a target-bound handle exists, but the value or wiring is still missing.
+- `PARTIAL -> SOURCE`: direct source/runtime/frame evidence proves the value and its use in the target path.
+- `SOURCE` for gate-critical wiring should have corroboration when practical. Examples: source plus runtime object, runtime plus frame capture, or source plus local replay smoke.
+
+When evidence conflicts with the model, do not tune parameters to mask the conflict.
+Route the mismatch back to attribution, source trace, or replay readiness.
+Record the unresolved unknown.
+
+## Unknown Classes
+
+- `blocking`: cannot build a baseline that matches required evidence without resolving it
+- `important`: baseline can run, but QA must focus on it
+- `deferred`: affects projectization or polish, not baseline
+- `external`: blocked by access, authorization, or legal permission
+
+## Choosing The Next Action
+
+Prefer the action that resolves the most blocking unknowns while keeping authority high and cost low.
+
+Invalid action: "download every bundle and inspect everything."
+
+Valid action: "target context creation stack points into `hero-renderer.*.js`; fetch only that source-mapped module to resolve owner and shader source."
+
+## Evidence Ledger
+
+Use ledger entries for facts that influence implementation:
+
+```json
+{
+  "id": "ev-0042",
+  "fact": "target surface is created by THREE.WebGLRenderer",
+  "value": true,
+  "truth": "SOURCE",
+  "targetIds": ["surface-1"],
+  "source": {
+    "type": "runtime|api|source-map|frame-capture|bundle|dom|screenshot|inference",
+    "location": "evidence/runtime/renderer.json#0",
+    "hash": "sha256:..."
+  },
+  "authority": "direct|corroborated|indirect|inferred",
+  "confidence": 0.96,
+  "verifiedBy": ["runtime-owner", "call-stack"]
+}
+```
+
+Implementation-critical values should not rely only on `inferred` evidence unless the replay route is explicitly `BEHAVIOR_REBUILD`.
+
+## Pre-Delivery Honesty Check
+
+Before reporting completion, verify:
+
+- Every implementation-critical value has `SOURCE`, `PARTIAL`, or `GUESS` evidence.
+- No fitted value is labeled `SOURCE`.
+- Wiring facts are proven separately from leaf facts.
+- `REPLAY_READY` has no blocking unknowns without a documented fallback and fidelity downgrade.
+- Known gaps describe the blocking unknown and the evidence needed to resolve it. Do not replace missing evidence with assumptions.
+
+## Sensitive Data
+
+Do not persist cookies, Authorization headers, access tokens, private API keys, or private account data.
+When a browser session is already logged in, record only the minimum non-sensitive facts needed for target attribution and replay.

package/templates/vite/.howone/skills/web-shader-extractor/references/operating-contract.md

@@ -0,0 +1,82 @@
+# Operating Contract
+
+This contract defines the behavior of the Web Shader Extractor skill before any focused workflow begins.
+
+## Objective
+
+Start from the visual effect the user points to.
+Lock the rendering surface, runtime, and source entry that produce it.
+Use the lowest-cost target-bound evidence path.
+Build a runnable and verifiable local baseline first.
+Perform cleanup, modularization, and editability work only after that baseline passes verification.
+
+This skill is not a general website cloner or a general JavaScript reverse-engineering workflow.
+The core completion state is a local, runnable, verified replay of the target visual.
+
+## Non-Negotiable Principles
+
+1. Start from the visual target, not from bundles, framework names, or project structure.
+2. Be canvas-first, not canvas-only: track iframes, OffscreenCanvas, workers, WebGPU, and DOM layers that participate in the effect.
+3. Attribute before locking: the largest, fullscreen, or continuously animated canvas is not automatically the target.
+4. Bind every conclusion to the target: a page-level Three.js, Babylon.js, or platform signature does not prove the target canvas uses it.
+5. Lock the target before deep analysis: do not deobfuscate full bundles before `TARGET_LOCKED`.
+6. Resolve one key unknown at a time: every action must state which unknown it resolves.
+7. Prefer evidence over inference: public definitions, source, source maps, runtime objects, and frame captures outrank minified guesses.
+8. Replay first: a runnable, verified local baseline is the core deliverable.
+9. Restore before refactoring: projectization, modularization, lite versions, and native WebGL conversions happen after the baseline.
+10. Choose the stack for evidence match: use native WebGL only when the scene is simple and conversion facts are complete.
+11. Do not compensate by tuning: never change brightness, speed, position, or noise values to mask timing, color, FBO, resource, coordinate, or state-model errors.
+12. Do not downgrade silently: if source replay falls back to pipeline replay or behavior rebuild, record it.
+13. A matching single frame is not dynamic correctness: verify time, input, scroll, and multi-pass behavior separately.
+14. Never overwrite the baseline: projectization and simplification happen in separate directories.
+15. Do not ask by default: ask only for product-level scope changes or external authorization blockers.
+16. Do not bypass access control: handle only public content or content the user is authorized to access and reproduce; do not save cookies, Authorization headers, tokens, or secrets.
+17. Label implementation-critical facts as `SOURCE`, `PARTIAL`, or `GUESS`; an unlabeled value is treated as `GUESS`.
+18. Separate leaf facts from wiring. Shader text, constants, asset URLs, and pass names can be source facts while render order, timing, input coupling, units, and ownership are still unproven.
+
+## False Conclusion Rules
+
+```text
+1. The largest or fullscreen canvas is not necessarily the target canvas.
+2. A framework existing on the page does not mean the target canvas uses it.
+3. A visible first frame does not prove the render graph, time, and inputs are correct.
+4. A similar screenshot does not prove the dynamic effect has been verified.
+5. A source constant does not prove the pipeline wiring that consumes it.
+6. A target-bound symbol name does not prove units, coordinate space, or timing semantics.
+7. A local fix that improves appearance is not evidence; it is a GUESS until traced or independently verified.
+```
+
+## Fact Labels
+
+Use truth labels close to facts that drive implementation:
+
+- `SOURCE`: direct target-bound evidence. Examples: public original source, source-mapped module, runtime object dump, captured shader/WGSL, frame capture, or network body with hash.
+- `PARTIAL`: a handle for the next probe. Examples: class/function/field name, target-bound bundle slice, framework object, or shader without state/pass/input facts.
+- `GUESS`: visual fitting, naming inference, copied defaults, hand-tuned constants, or any behavior rebuild value without direct evidence.
+
+Never upgrade a fact because output looks similar.
+If a value is fitted so the baseline resembles the source, keep it labeled `GUESS`.
+State which evidence would promote it.
+If direct source conflicts with runtime behavior, treat wiring, units, or target attribution as unresolved before tuning.
+
+Before declaring `TARGET_LOCKED`, `REPLAY_READY`, or `BASELINE_VERIFIED`, check both layers:
+
+- Leaf facts: shader/WGSL text, constants, config, asset paths, resource dimensions, context attributes.
+- Wiring facts: owner, pass order, FBO dependencies, coordinate transforms, time units, random rules, pointer/scroll/resize coupling, output composite.
+
+Read `references/evidence-policy.md` for the full labeling and audit rules.
+
+## External Blockers
+
+Ask separately only for login, CAPTCHA, private pages, paid resources, or permission/license uncertainty.
+Combine blockers into one note.
+
+If connecting to an existing logged-in browser, tell the user credentials or page data may be visible to the agent.
+Do not persist sensitive headers, cookies, tokens, or secrets.
+
+## Completion States
+
+- `DONE_BASELINE_VERIFIED`: baseline passed Source -> Baseline validation.
+- `DONE_PROJECTIZED`: editable project passed Baseline -> Editable regression.
+- `DONE_BASELINE_WITH_GAPS`: baseline runs, but differences or evidence gaps remain and are documented.
+- `BLOCKED_EXTERNAL`: legal access, authorization, or permission prevents progress.

package/templates/vite/.howone/skills/web-shader-extractor/references/qa-failure-policy.md

@@ -0,0 +1,100 @@
+# QA and Failure Policy
+
+Validation happens twice:
+
+1. Source -> Baseline: does the local baseline match the target evidence?
+2. Baseline -> Editable: did projectization avoid regression?
+
+## Fixed Conditions
+
+Keep these identical across comparisons:
+
+- viewport
+- DPR
+- browser/backend
+- fixed time or selected frame
+- pointer, scroll, resize, route state
+- random seed when controllable
+- background, alpha, and DOM composite
+- crop and time point
+
+## Validation Levels
+
+1. Build: dependencies and assets resolve
+2. GPU: shaders/pipelines compile and link
+3. Structural: pass, FBO, program, resource, and state match Manifest
+4. Visual: color, composition, alpha, edges
+5. Temporal: multi-frame rhythm, phase, randomness
+6. Interaction: pointer, scroll, resize, route
+7. Regression: editable project vs baseline
+
+## Minimum Source -> Baseline Protocol
+
+Minimum verification requires more than one static screenshot:
+
+1. Compare at the initial frame or a fixed time.
+2. Compare at a later frame.
+3. Compare after one relevant interaction if the target is interactive.
+4. For scroll-coupled effects, compare at top, middle, and target section.
+5. For route-coupled effects, compare at the route transition or persistent renderer state.
+6. Always record viewport, DPR, browser/backend, crop, time, pointer, scroll, and route state.
+
+Every comparison must save or reference:
+
+- source image or frame evidence
+- baseline image or frame evidence
+- diff image, numeric comparison, or written visual difference record
+
+If the environment cannot produce image diffs, write a structured visual difference record and keep that limitation in `known-gaps.md`. A single matching first frame is not enough for `BASELINE_VERIFIED`.
+
+## Truth Audit
+
+Run this audit before marking the final state:
+
+- Every implementation-critical fact in `replay-manifest.json` has direct evidence or a `PARTIAL` / `GUESS` label.
+- Leaf facts and wiring facts were checked separately. A verified shader or config value does not prove the active render graph, timing, coordinate space, or input route.
+- Any parameter changed to improve appearance is recorded as `GUESS` unless source/runtime/frame evidence proves it.
+- Any mismatch is routed to the upstream unknown that explains it. Do not cover mismatches with tuning.
+- Known gaps state the blocking unknown and the evidence needed to resolve it.
+
+The QA report is the gate artifact for `BASELINE_VERIFY` and `PROJECT_VERIFY`. Do not mark either gate passed while any required row is `pending`, any P0/P1/P2 issue is open, or the final status is absent.
+
+## Severity
+
+- `P0`: cannot run, cannot render, or route impossible
+- `P1`: wrong target, render graph, composition, or main interaction
+- `P2`: visible timing, color, alpha, responsive, or input drift
+- `P3`: polish or performance issue that does not block delivery
+
+Automatically loop only P0/P1/P2.
+
+## Failure Routing
+
+| Symptom | Category | Return |
+|---|---|---|
+| wrong canvas or missing shared surface | target | `SURFACE_ATTRIBUTION` |
+| missing shader/resource/input | evidence | `SOURCE_TRACE` |
+| wrong FBO, time, coordinates, color model | replay model | `CAPTURE_MINIMUM_TRUTH` |
+| dependency, path, or code error | implementation | `RAW_REPLAY` |
+| browser, GPU, CORS, or context issue | environment | `BASELINE_RUN` |
+| evidence complete but implementation visually wrong | fidelity implementation | `RAW_REPLAY` |
+
+Do not route all mismatches into parameter tuning.
+
+## Failure Signatures
+
+Use these signatures to classify mismatches before editing values.
+
+| Symptom | Likely Root Cause |
+|---|---|
+| overall too bright or color-shifted | color space, tone mapping, premultiplied alpha |
+| animation slowly drifts | seconds vs frames, delta, time origin |
+| vertical flip | UVs, render target orientation, SDF/image coordinate system |
+| black blocks or missing layers | FBO, clear, blend, depth, missing resources |
+| noise differs | RNG, precision, filtering, noise implementation |
+| edge softness differs | DPR, AA, derivatives, SDF smoothing |
+| scroll position drifts | DOM-canvas binding or scroll normalization |
+| route flicker | renderer lifecycle, resource cache, route persistence |
+| pointer response offset | canvas CSS transform, DPR, page scroll, coordinate normalization |
+
+Confirm the category with evidence before changing implementation constants.