howone 0.1.38 → 0.1.39

package/templates/vite/.howone/skills/web-shader-extractor/references/surface-discovery.md

@@ -0,0 +1,113 @@
+# Surface Discovery
+
+Surface discovery has two jobs: inventory candidates, then prove causality between the requested visual and one or more rendering surfaces. Inventory alone never decides the target.
+
+## Surfaces To Enumerate
+
+- visible and hidden `canvas`
+- canvases inside same-origin iframes; for cross-origin iframes, record frame bounds, screenshots, network/frame metadata, or tool-accessible observations without bypassing origin restrictions
+- `OffscreenCanvas` transferred to workers
+- WebGPU canvas contexts
+- DOM masks, clip paths, sticky containers, SVG filters, videos, and images composited with canvas
+- shared renderer canvases that persist across routes
+
+## Candidate Record
+
+Record each candidate as:
+
+```json
+{
+  "id": "surface-1",
+  "selector": "canvas#hero",
+  "frame": "main",
+  "bounds": { "x": 0, "y": 0, "width": 1440, "height": 900 },
+  "cssSize": { "width": 1440, "height": 900 },
+  "backingSize": { "width": 2880, "height": 1800 },
+  "dpr": 2,
+  "visibility": "visible",
+  "zIndex": "auto",
+  "context": "webgl2|webgl|webgpu|2d|bitmaprenderer|unknown",
+  "owner": "main-thread|iframe|worker|unknown",
+  "routePersistence": "single-route|persistent|unknown",
+  "notes": []
+}
+```
+
+## Context Probes
+
+Use non-destructive runtime evaluation first:
+
+- inspect size, bounding rect, computed style, opacity, transform, pointer-events, z-index
+- check known dataset hints such as `data-engine`, `data-renderer`, embed IDs
+- detect existing contexts without creating unrelated new contexts when possible
+- observe worker script URLs, `transferControlToOffscreen`, and WebGPU adapter/device calls if available
+
+If context creation must be probed, label that as probe-induced evidence so it is not confused with the page's real context.
+
+## Target Model
+
+The target may be a surface group:
+
+```text
+canvas#background
++ canvas#particles
++ DOM mask
++ scroll progress
+```
+
+Use `targetSet` in Scout Card and Manifest. Do not force the result into a single `targetCanvas`.
+
+## Ranking And Attribution
+
+Rank candidates for attribution by:
+
+- overlap with the requested visual area
+- frame-to-frame pixel change
+- z-order and clipping relationship
+- pointer/scroll/resize coupling
+- route persistence
+- owner traceability
+
+Attribution scoring dimensions:
+
+- `visualCoverage`: how much the surface overlaps the target visual region
+- `temporalActivity`: how much the surface changes across sampled frames
+- `interactionCoupling`: pointer, scroll, resize, or route changes affect the target
+- `sectionCoupling`: relationship to page sections, sticky positioning, masks, and clips
+- `routePersistence`: whether the surface persists across route changes
+- `ablationImpact`: what target pixels/behaviors disappear when the surface is hidden or frozen
+- `ownershipEvidence`: how well context and renderer owner can be traced
+
+## Attribution Actions
+
+Use the lowest-cost action that resolves the current unknown:
+
+1. style, bounds, and visibility observation
+2. multi-frame diff on a target crop
+3. temporary `visibility:hidden`, opacity, transform, or clip ablation
+4. freeze `requestAnimationFrame` or replace a candidate surface output
+5. pointer sweep
+6. small scroll
+7. resize
+8. route switch
+9. owner stack or preload probe
+
+All modifications are brief, reversible, and observational. Do not persist source-site changes.
+
+## Evidence Examples
+
+Strong attribution examples:
+
+- target crop loses the distortion only when `surface-2` is hidden
+- scroll progress changes uniforms on `surface-1` and the visual phase changes accordingly
+- DOM mask plus canvas output together create the visible target; either alone is incomplete
+- `OffscreenCanvas` worker owns the only context whose frame changes match the target crop
+
+Weak attribution examples:
+
+- candidate is the largest canvas
+- candidate animates continuously
+- candidate has a framework-looking dataset attribute
+- bundle contains shader strings but no target binding exists
+
+Area alone is weak evidence. A small overlay, mask, or DOM layer may be essential to the target effect.

package/templates/vite/.howone/skills/web-shader-extractor/references/target-lock.md

@@ -0,0 +1,205 @@
+# Target Lock
+
+`TARGET_LOCKED` is an evidence gate.
+After it passes, source tracing and capture can focus on one target surface group.
+Use `attributed` when visual causality is proven but owner or source is still unresolved.
+
+## Required Fields
+
+`TARGET_ATTRIBUTED` means:
+
+- the target surface or surface group is visually attributed
+- ablation, frame comparison, interaction response, or equivalent evidence proves causality
+- context, owner, framework, or source may still be incomplete
+- only owner probes, backend probes, or narrow source probes tied to `nextProbe` are allowed
+
+`TARGET_LOCKED` requires:
+
+- target is a surface or surface group
+- visual attribution evidence exists
+- context type is known
+- owner thread/frame/worker is known or reliably located
+- framework, platform, runtime, or source clues are bound to the target
+- effect boundary is classified
+- exactly one primary trace route is selected
+- alternatives and exclusion reasons are recorded
+
+Do not set `lockStatus` to `locked` until these fields are present in `scout-card.json` with evidence paths.
+Conversation text is not enough.
+If owner/source is still unresolved but the visual target is proven, set `lockStatus` to `attributed`.
+Make the next action an owner or backend probe.
+
+## Scout Card v3
+
+Write a small card before the full Manifest:
+
+```json
+{
+  "schemaVersion": 3,
+  "source": {
+    "url": "https://example.com/",
+    "route": "/",
+    "viewport": { "width": 1440, "height": 900, "dpr": 2 }
+  },
+  "candidates": [
+    {
+      "id": "surface-1",
+      "selector": "canvas#hero",
+      "frame": "main",
+      "context": "webgl2",
+      "owner": "unknown",
+      "visualCoverage": "high",
+      "temporalActivity": "high",
+      "ablationImpact": "major",
+      "evidence": ["evidence/scout/surface-1.json"]
+    }
+  ],
+  "lockStatus": "provisional",
+  "targetSet": [],
+  "alternatives": [],
+  "effectBoundary": "surface-only|surface-plus-dom|page-coupled|route-coupled",
+  "frameworkHypotheses": [],
+  "platformHypotheses": [],
+  "interactions": [],
+  "scopeRisk": "low|medium|high",
+  "blockingUnknowns": [],
+  "nextProbe": {
+    "type": "surface-ablation|runtime-owner|platform-api|frame-capture|preload|source-map|bundle-slice",
+    "target": "surface-1",
+    "resolves": ["owner", "framework"]
+  }
+}
+```
+
+## Target-Bound Evidence
+
+Weak evidence can form hypotheses only:
+
+- `window.THREE` exists
+- a bundle contains `three`, `babylon`, `pixi`, `regl`, or shader keywords
+- the domain resembles a known platform
+- a global variable contains a renderer
+- another canvas on the page uses a framework
+
+Promote a hypothesis only when at least one strong target binding exists:
+
+- `renderer.domElement === targetCanvas`
+- engine rendering canvas equals the target canvas
+- target context creation stack comes from the framework/platform
+- target draw calls, programs, or state are associated with framework objects
+- public platform definition instance ID matches the target embed/canvas
+- source map or module path initializes the target surface
+
+## Route Selection
+
+Pick the next route from the strongest current target-bound clue:
+
+```text
+strong platform feature
+-> platform structured definition or public API
+
+target renderer object accessible
+-> runtime object and framework version
+
+generic WebGL
+-> frame capture or shader/runtime capture
+
+WebGPU / TSL
+-> platform source, TSL definition, WebGPU capture
+
+owner or timeline unclear
+-> preload hooks
+
+source/config still missing
+-> source map or targeted bundle slice
+```
+
+## Adapter Interface
+
+Each platform/framework adapter should answer:
+
+```text
+detect(context)             target-bound evidence
+preferredEvidence(context)  highest-authority entry with lowest collection cost
+capture(context)            facts needed for replay
+replay(context)             recommended baseline route
+validationHints(context)    known failure cases and QA focus
+fallback(context)           next route if primary fails
+```
+
+Initial adapters: Unicorn Studio, shaders.com / TSL, generic WebGL, generic WebGPU, Canvas2D, and Three.js target binding.
+
+## Three.js Target Binding
+
+Use this only after a target surface exists. Three.js on the page is not enough.
+
+Accept Three.js as the target framework when one is true:
+
+- `renderer.domElement === targetCanvas`
+- target canvas `data-engine` or dataset is corroborated by runtime renderer object
+- target context creation stack includes Three.js renderer initialization
+- target draw calls/programs correspond to Three.js material/program records
+- source map/module that creates the target surface imports Three.js renderer/material code
+
+Capture runtime facts:
+
+- `THREE.REVISION`
+- renderer output color space/tone mapping
+- renderer size and pixel ratio
+- scene/camera relationship for the target pass
+- material type, shader chunks, `onBeforeCompile` hooks
+- render targets and composer passes
+- clock/time update rule
+
+Three.js r170+ may use TSL and WebGPU.
+Do not expect GLSL strings from `shaderSource()`.
+Route to `references/three-shader-reconstruction.md` or `references/capture-backends.md` when node graphs or WebGPU backend are target-bound.
+
+## Scope Gate
+
+Default scope is `effect`.
+
+Scope values:
+
+- `effect`: independent visual effect
+- `page`: current page DOM/CSS/interaction plus renderer cooperation
+- `site`: main public visual routes, unique visual templates, shared renderer, and transitions; not backend, accounts, private data, or bulk same-template content pages
+
+Ask a scope question only when all are true:
+
+- the user did not specify scope
+- WebGL/WebGPU is the overall experience skeleton
+- it is coupled with DOM, scroll, navigation, or route
+- extracting one surface would lose the main target experience
+
+A fullscreen background canvas alone is not a reason to ask.
+
+Question template:
+
+```text
+I have locked the main rendering system.
+The site's WebGL/WebGPU also participates in layout, scroll, interaction feedback, or route transitions.
+Extracting one effect would omit part of the main experience.
+
+Choose the reproduction scope:
+A. Core effect (default, fastest) - first build it as an independently runnable local effect.
+B. Current page - also reproduce the DOM/CSS, scroll, interaction, and renderer cooperation.
+C. Main site visual experience - inspect public visual routes and templates.
+Reproduce the shared renderer, key visual pages, and route transitions.
+Do not reproduce backend, accounts, private data, or bulk same-template content pages.
+
+Reply with A, B, or C. If you reply "continue" or provide no scope, proceed with A.
+```
+
+Ask separately only for login, CAPTCHA, private pages, paid resources, or permission/license uncertainty.
+Combine blockers into one note.
+
+## Gate Rules
+
+- Before attribution completes, `lockStatus` can only be `unlocked` or `provisional`.
+- `attributed` allows owner/backend/source probes bound to `nextProbe`; it does not allow deep source or bundle work.
+- `locked` requires a non-empty `gateDecision.requiredEvidence` checklist in `scout-card.json`; every item must be an evidence item with `status`, `evidenceId`, `path`, `truth`, and `notes`.
+- `frameworkHypotheses` and `platformHypotheses` are candidates, not conclusions.
+- `nextProbe` has one main action.
+- Raw DOM, screenshots, network logs, and frame captures go into files and are referenced by path.
+- After lock, fill `targetSet`, excluded alternatives, lock evidence, and primary route.

package/templates/vite/.howone/skills/web-shader-extractor/references/three-shader-reconstruction.md

@@ -0,0 +1,155 @@
+# Three.js Shader Reconstruction
+
+Use this reference when target-bound evidence shows Three.js shader customization.
+Applies to `material.onBeforeCompile`, Three.js TSL, WebGPU node graphs, or material systems that must preserve recorded source behavior.
+
+## onBeforeCompile Failure Cases
+
+### Built-In Function Signatures Vary By Version
+
+Three.js shader chunk signatures change across versions:
+
+```glsl
+// r166 and earlier
+vec4 getIBLVolumeRefraction(n, v, roughness, diffuseColor, specularColor, specularF90,
+  pos, modelMatrix, viewMatrix, projectionMatrix, ior, thickness,
+  attenuationColor, attenuationDistance)
+
+// r167+ adds dispersion
+vec4 getIBLVolumeRefraction(n, v, roughness, diffuseColor, specularColor, specularF90,
+  pos, modelMatrix, viewMatrix, projectionMatrix, dispersion, ior, thickness,
+  attenuationColor, attenuationDistance)
+```
+
+Always check the target version's actual signature:
+
+```bash
+curl -s "https://cdn.jsdelivr.net/npm/three@0.167.0/src/renderers/shaders/ShaderChunk/transmission_pars_fragment.glsl.js" \
+  | tr '\n' ' ' | grep -oE 'vec4 getIBLVolumeRefraction\([^)]+\)'
+```
+
+### GLSL Does Not Allow Nested Function Definitions
+
+```glsl
+// Wrong.
+void main() {
+  float myRand(vec2 co) { return fract(sin(...)); }
+}
+
+// Correct.
+float myRand(vec2 co) { return fract(sin(...)); }
+void main() {
+  float r = myRand(uv);
+}
+```
+
+### Preserve Conditional Compilation Guards
+
+Some variables exist only under specific macros:
+
+- `vWorldPosition` requires `USE_TRANSMISSION`
+- `vTransmissionMapUv` requires `USE_TRANSMISSIONMAP`
+- `roughnessFactor` is available after `lights_physical_fragment`
+
+If replacing `#include <transmission_fragment>`, keep the source guard pattern.
+
+### Avoid Name Collisions
+
+Injected global functions and variables can collide with Three.js internals:
+
+- avoid generic names such as `hash`, `random`, and `noise`
+- prefix custom helper names when needed
+- prefix uniforms consistently, for example `uDistortion` and `uNoiseTime`
+
+## Preferred Injection Pattern
+
+Modify normals before the existing chunk when the target evidence supports it:
+
+```javascript
+material.onBeforeCompile = (shader) => {
+  shader.uniforms.uDistortion = { value: 0 };
+  shader.uniforms.uNoiseTime = { value: 0 };
+
+  shader.fragmentShader = `
+    uniform float uDistortion;
+    uniform float uNoiseTime;
+    ${noiseGLSL}
+  ` + shader.fragmentShader;
+
+  shader.fragmentShader = shader.fragmentShader.replace(
+    '#include <transmission_fragment>',
+    `
+    #ifdef USE_TRANSMISSION
+    {
+      if (uDistortion > 0.0) {
+        normal = normalize(normal + uDistortion * vec3(
+          snoiseFractal(vWorldPosition * 0.08 + vec3(uNoiseTime)),
+          snoiseFractal(vWorldPosition.zxy * 0.08 - vec3(uNoiseTime)),
+          snoiseFractal(vWorldPosition.yxz * 0.08)
+        ));
+      }
+    }
+    #endif
+    #include <transmission_fragment>
+    `
+  );
+};
+```
+
+When target evidence shows grain from low sample counts and chromatic aberration, a full `#include <transmission_fragment>` replacement may be required.
+Keep the `#ifdef USE_TRANSMISSION` wrapper.
+Preserve transmission and thickness map blocks.
+Use the correct `getIBLVolumeRefraction` signature.
+Pass evidence-derived dispersion/IOR values.
+
+## Effect Source Mapping
+
+| Effect | Source | Implementation |
+|---|---|---|
+| Glass refraction | `MeshPhysicalMaterial` `transmission` | Three.js built-in |
+| Chromatic aberration | different IOR values for R/G/B | replace `transmission_fragment` |
+| Film grain | low sample count plus per-pixel random direction | replace `transmission_fragment` |
+| Organic distortion | simplex noise perturbing normal/refraction direction | `onBeforeCompile` injection |
+| Color offset | `dispersion` property in r167+ | `MeshPhysicalMaterial` built-in |
+
+## TSL Identification
+
+Three.js r170+ TSL composes shader node graphs through JavaScript function chains and compiles them at runtime.
+
+Identification signals:
+
+1. Bundles contain many `uniform` or `shader` terms but very little `precision` or `gl_FragColor`.
+2. The target canvas `data-engine` or runtime evidence indicates Three.js r170+.
+3. The target-bound source contains chained calls such as `.mul()`, `.add()`, `.toVar()`, or `.assign()`.
+
+## TSL To GLSL Mapping
+
+| TSL | GLSL |
+|---|---|
+| `screenUV` | `gl_FragCoord.xy / resolution` |
+| `viewportSize` | `uniform vec2 resolution` |
+| `float()` / `vec2()` / `vec3()` / `vec4()` | same GLSL constructors, though TSL uses JavaScript functions |
+| `.mul()` / `.add()` / `.sub()` / `.div()` | `*` / `+` / `-` / `/` |
+| `sin()` / `cos()` / `mix()` / `smoothstep()` | same names |
+| `clamp()` / `abs()` / `fract()` / `floor()` | same names |
+| `pow()` / `exp()` / `sqrt()` / `dot()` / `length()` | same names |
+| `Fn()` | shader function wrapper; inline it into GLSL |
+| `uniform()` | `uniform <type> name` |
+| `convertToTexture()` | RTT or FBO pass |
+| `.sample(uv)` | `texture(sampler, uv)` |
+| `.toVar()` / `.assign()` | mutable variable declaration/assignment |
+| `.oneMinus()` | `1.0 - x` |
+
+## TSL Reconstruction Steps
+
+1. Locate `fragmentNode` near the target component name or target-bound module.
+2. Build the mapping from minified imports to TSL function names using bundle import statements.
+   ```javascript
+   import { A as screenUV, W as sin, ... } from "three-module"
+   ```
+3. Translate chained calls into GLSL expressions.
+   ```javascript
+   // TSL: screenUV.x.sub(center.x).mul(aspect)
+   // GLSL: (uv.x - center.x) * aspect
+   ```
+4. Convert `convertToTexture(childNode)` into an independent FBO pass and sample it with `texture()` in the consuming shader.

package/templates/vite/.howone/skills/web-shader-extractor/references/tool-capability-matrix.md

@@ -0,0 +1,57 @@
+# Tool Capability Matrix
+
+The skill depends on capabilities, not specific tool names. Probe available tools first, then choose the smallest sufficient profile.
+
+## Capability Names
+
+```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
+```
+
+## Profiles
+
+### Profile A: Light Scout
+
+Use for navigation, runtime eval, canvas inventory, screenshots, pointer/scroll/resize, and network overview.
+A browser CLI, browser MCP, or host browser automation can satisfy this profile.
+
+If Playwright is already installed, `scripts/fetch-rendered-dom.mjs` can serve as an optional inventory helper for DOM/canvas/network observations.
+It does not perform Surface Attribution, Target Lock, Replay Ready, or QA gates.
+Treat its output as inventory and hypothesis evidence only.
+
+### Profile B: Chrome Deep Diagnostics
+
+Use for pre-navigation init scripts, source-mapped stacks, response bodies, performance traces, and existing Chrome sessions.
+CLI fits batch work. MCP fits continued interaction.
+
+### Profile C: GPU Capture
+
+Use WebGL frame capture or WebGPU recorders only after target and backend are known. GPU tools are optional adapters, not first-strike requirements.
+
+### Profile D: Static Fallback
+
+Use HTML, public API, source maps, dynamic chunk graph, and narrow bundle slices. Do not default to full deobfuscation.
+
+`scripts/scan-bundle.sh` may be used on a target-bound slice to count shader/framework keywords.
+Treat every result as a hypothesis that still needs target-bound evidence.
+Do not infer GPGPU from generic `RenderTarget`, generic `DataTexture`, or post-processing hits.
+Require feedback-loop, ping-pong pair, data-texture simulation, or compute-like update evidence.
+
+## Rules
+
+- Do not require a single MCP before starting.
+- Do not silently install large dependencies.
+- If a tool is missing, downgrade to the closest capability and record the gap.
+- If connecting to an existing logged-in browser, warn that credentials/page data may be visible to the agent and avoid persisting sensitive material.
+- Store variable tool/version observations in run artifacts, not hard-coded skill instructions.