luckiest-co 1.0.13 → 1.0.15

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/replay-policy.md

@@ -0,0 +1,145 @@
+# Replay Policy
+
+Replay policy covers the `REPLAY_READY` gate, first local baseline, and stack choice.
+The goal is to match recorded source behavior with the fewest new assumptions.
+
+## Replay Ready Contract
+
+Record before entering `RAW_REPLAY`:
+
+- replay route: `SOURCE_REPLAY`, `PIPELINE_REPLAY`, or `BEHAVIOR_REBUILD`
+- fidelity tier and known limits
+- blocking, important, deferred, and external unknowns
+- fallback for any unresolved blocking unknown
+- truth labels for implementation-critical leaf and wiring facts
+
+Do not mark `REPLAY_READY` because the capture appears plausible.
+`SOURCE` leaf facts do not imply `SOURCE` wiring.
+If pass order, input coupling, time units, or output composite are still inferred, label those facts `PARTIAL` or `GUESS`.
+Keep inferred gate facts blocking or record an explicit fidelity downgrade.
+
+Proceed to `RAW_REPLAY` only when `blockingUnknowns` is empty, or every blocker has an explicit fallback with a recorded fidelity downgrade.
+Move important unknowns into QA focus.
+
+Do not enter `RAW_REPLAY` until `replay-manifest.json.gateDecision.replayReady` is true.
+Its required evidence checklist must contain structured evidence items.
+If the baseline depends on a fallback, record the fallback and downgrade in the manifest before implementation starts.
+
+If a local baseline uses fitted values to run, those facts are not source replay.
+Keep the values labeled `GUESS`.
+Place them in `known-gaps.md`.
+Route QA toward the missing source/runtime evidence.
+
+## Replay Routes
+
+Choose and record one replay route in `replay-manifest.json`:
+
+- `SOURCE_REPLAY`: public structured definitions, original source, source maps, readable framework modules, platform exports, or configs. Prefer this when available.
+- `PIPELINE_REPLAY`: shader/WGSL, runtime objects, GPU frame capture, draw/pass/resource/state, input, and timing trace. Use when source is incomplete but runtime facts are sufficient.
+- `BEHAVIOR_REBUILD`: partial source plus observed behavior. This is the last fallback and must be labeled approximate.
+
+Do not describe a behavior rebuild as source extraction. Projectization does not change the baseline fidelity tier.
+
+## Stack Selection
+
+Use native WebGL/WebGL2 when the target is:
+
+- fullscreen shader
+- small number of passes
+- no complex scene graph
+- no PBR/material lifecycle
+- no GPGPU lifecycle tied to a framework
+- conversion facts are complete
+
+Use the source stack when:
+
+- the framework/platform version is known or closely bounded
+- source, source map, platform definition, or runtime objects are complete
+- behavior depends on material systems, node graphs, post-processing, scene graph, resource lifecycle, or renderer quirks
+- retaining the source stack reaches an evidence-matched baseline with fewer assumptions
+
+Project-lite is a post-verification optimization. It is not a substitute for the verified baseline.
+
+## Raw Replay Priorities
+
+Raw replay creates the first local baseline with the least rewriting:
+
+1. Preserve recorded source behavior and data shape.
+2. Keep original constants, shader code, pass order, timing, resources, and color model.
+3. Make it run locally with a minimal launch path.
+4. Document known gaps rather than masking them with tuning.
+
+Use the source stack when it adds fewer assumptions. Use native WebGL/WebGL2 only when conversion does not add uncertainty.
+
+## Baseline Directory
+
+Output artifacts should be layered:
+
+```text
+output/
+|-- capture-baseline/
+|-- editable-project/
+|-- project-lite/
+|-- scout-card.json
+|-- replay-manifest.json
+|-- qa-report.md
+|-- extraction-report.md
+|-- known-gaps.md
+`-- .web-shader-extractor/run-state.json
+```
+
+```text
+output/capture-baseline/
+|-- index.html
+|-- src/
+|-- assets/
+|-- README-run.md
+`-- evidence-links.md
+```
+
+## No Compensation Tuning
+
+Do not change brightness, speed, offsets, noise scale, fresnel multipliers, SDF epsilons, or color values without evidence.
+If the result differs, classify the root cause: color, timing, coordinates, FBO graph, resource, state, input, or environment.
+
+Once baseline verification starts, do not overwrite it for projectization.
+Fix baseline in place only for baseline errors.
+Create `editable-project/` separately for refactors.
+
+Use the bundled templates as starting 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`, and `templates/extraction-report.md`.
+Fill every placeholder with target-bound evidence or record the gap.
+
+## Projectization
+
+Projectization starts only after `BASELINE_VERIFIED`.
+
+Default output:
+
+```text
+output/editable-project/
+|-- package.json or importmap-based index.html
+|-- src/
+|-- assets/
+|-- README.md
+`-- qa/
+```
+
+Projectization may modularize source, add parameter interfaces, improve naming, or introduce a build pipeline.
+It must not silently change the replay route or fidelity tier.
+
+Run Baseline -> Editable validation after projectization:
+
+- same viewport, DPR, browser/backend
+- same fixed time/frame
+- same pointer/scroll/resize state
+- same crop and background/composite
+
+Any P0/P1/P2 regression returns to `PROJECTIZE`, not to target scouting unless the regression reveals the baseline was wrong.
+
+Create `project-lite/` only when simplification is supported by evidence and independently verified.
+If it fails, remove or mark it experimental.
+Do not downgrade the verified editable project.
+
+Do not create `editable-project/` as the primary deliverable until `qa-report.md` records Source -> Baseline as passed or passed with documented gaps.
+Do not mark `DONE_PROJECTIZED` until Baseline -> Editable regression is recorded in `qa-report.md`.

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/shaders-com.md

@@ -0,0 +1,212 @@
+# shaders.com / TSL Adapter
+
+Use this adapter only after the target surface group has been attributed to a shaders.com renderer or a shaders.com public definition.
+Treat versions, keys, mappings, and backend choice as runtime facts to verify on the current target.
+
+Stability: volatile. Treat endpoint names, variable names, keys, component IDs, short-code mappings, and backend choices as hints until verified on the current target.
+
+shaders.com is a shader design tool. Observed builds use Nuxt.js, Three.js TSL, and Supabase. Verify the exact Three.js version and WebGPU/WebGL backend from target runtime or current bundle evidence.
+
+## Adapter Interface
+
+- `detect(context)`: target canvas has shaders.com renderer evidence, target route/API returns the matching preset/collection definition, or runtime owner binds the renderer to target.
+- `preferredEvidence(context)`: public collection/preset definition, current runtime config, and target-bound Three.js/TSL module route.
+- `capture(context)`: component tree, decoded definition, TSL node source, assets/SDFs, renderer backend, time/input rules, color/output model.
+- `replay(context)`: `SOURCE_REPLAY` when definition and TSL source are sufficient; `PIPELINE_REPLAY` when runtime/capture facts are sufficient but source is incomplete.
+- `validationHints(context)`: SDF Y flip, linear color pipeline, TSL timer rules, Glass parameter fidelity, WebGPU vs WebGL backend.
+- `fallback(context)`: target-bound source-map or module slice, frame capture, then behavior rebuild with explicit downgrade.
+
+## Recognition Signals
+
+- URL pattern: `shaders.com/collection/{slug}/{presetId}` or `shaders.com/preset/{id}`
+- Canvas hints such as `data-renderer="shaders"` plus `data-engine`; verify the version dynamically
+- Nuxt.js paths such as `_nuxt/`
+- Clerk authentication on the site
+- Supabase storage URLs such as `data.shaders.com/storage/v1/`
+
+## Architecture Differences
+
+Compared with Unicorn Studio:
+
+- It commonly uses Three.js TSL node graphs rather than raw GLSL source.
+- It has multiple component types, each potentially backed by a TSL `fragmentNode`; verify the current count and names from the current bundle.
+- Definition data may be XOR + base64 encoded.
+- Components can be nested; for example a Glass component may contain child effects.
+
+## Data Acquisition
+
+### API Endpoints
+
+```bash
+# Collection variant with encoded definition; public when accessible without auth.
+curl -s "https://shaders.com/api/collections/{slug}/{variantId}"
+
+# Preview API with encoded definition and possible watermark injection.
+curl -s "https://shaders.com/api/preview/preset/{presetId}"
+
+# Nuxt payload, usually metadata only rather than shader definition.
+curl -s "https://shaders.com/collection/{slug}/{id}/_payload.json"
+```
+
+### Definition Decoding
+
+Definitions may use XOR + base64 encoding with route-specific keys.
+
+1. Website API (`/api/collections/`):
+   - Extract the obfuscation key from the current Nuxt runtime config. Do not reuse fixed keys from old samples.
+   - Component/property names may use short codes such as `C52` for `Plasma` or `p06` for `angle`.
+   - Decode with `JSON.parse(XOR(base64decode(encoded), keyBytes))`.
+   - Restore readable names with the current code-to-name mapping table.
+
+2. Preview API (`/api/preview/`):
+   - Verify the key and response shape from the current public frontend code.
+   - It may use readable property names directly.
+   - It may inject a watermark `ImageTexture` component.
+
+### Code Mapping Table
+
+Extract component and property short-code mappings from the current JS bundle. Do not assume component counts, sorting, or numeric IDs are stable across releases.
+
+## Known Failure Cases
+
+### Y-Axis Flip
+
+Observed shaders.com samples show a Y flip for SDF textures and UVs.
+
+SDF binaries (`.bin`) often use image coordinates where Y=0 is at the top, while WebGL texture coordinates use Y=0 at the bottom. Loading them directly can flip shapes vertically.
+
+```glsl
+// Wrong: direct sampling.
+float sdf = texture(tSDF, shapeUV).r;
+
+// Correct for known flipped SDFs: flip Y.
+vec2 sdfUV = vec2(shapeUV.x, 1.0 - shapeUV.y);
+float sdf = texture(tSDF, sdfUV).r;
+
+// The Y component of the gradient may also need sign inversion.
+float dSdy = -(texture(tSDF, sdfUV - vec2(0, eps)).r - sdf) / eps;
+```
+
+Component definitions may also use DOM coordinates where Y=0 is at the top. For Glass-style shaders, verify whether `center.y` must be flipped as `center.y = 1.0 - center.y`.
+
+### SDF Binary Format
+
+Known samples use:
+
+- 512 x 512 Float32 single-channel data
+- 1,048,576 bytes: `512 * 512 * 4`
+- signed distance values, negative inside and positive outside
+- raw values without `* 2.0 - 1.0` remapping
+- `OES_texture_float_linear` for linear filtering when needed
+
+WebGL2 loading pattern:
+
+```js
+gl.texImage2D(gl.TEXTURE_2D, 0, gl.R32F, 512, 512, 0, gl.RED, gl.FLOAT, data);
+```
+
+## Component Table
+
+| Category | Components | Complexity |
+|---|---|---|
+| Texture | Plasma, Godrays, SimplexNoise, LinearGradient, RadialGradient | medium |
+| Shape | Glass, Blob, Circle, Ring, Star, RoundedRect, Polygon | high |
+| Distortion | WaveDistortion, ChromaticAberration, Liquify, Twirl, Bulge | low to medium |
+| Stylization | FilmGrain, Halftone, Ascii, Dither, Glow, Bloom | low to medium |
+| Post-processing | Blur, ProgressiveBlur, BrightnessContrast, HueShift | low |
+
+## Render Pipeline
+
+Typical target-bound evidence may reveal:
+
+```text
+Three.js TSL renderer; verify version dynamically
+|- prefers WebGPU, falls back to WebGL
+|- orthographic camera plus one fullscreen quad
+|- component tree composited bottom to top
+|- components with children capture child content through RTT
+|- blend mode implemented with custom blend functions
+`- Glass path: SDF evaluation -> gradient normal -> refraction -> chromatic aberration -> blur -> tint -> highlight -> Fresnel -> composite
+```
+
+## Replay Strategy
+
+1. TSL cannot be copied as raw GLSL; translate it or replay it through the source stack.
+2. Extract the target-bound TSL `fragmentNode` from the current JS bundle when source replay requires it.
+3. Convert the component tree into a multi-pass FBO graph.
+4. Validate SDF Y orientation against the target.
+5. Glass components have many parameters; keep source multipliers exact.
+
+## Color Space
+
+Known shaders.com / Three.js TSL samples commonly use a linear workflow, but the current target must still be verified from renderer, runtime, or source evidence.
+
+- Hex colors such as `#2c2c42` are commonly sRGB values.
+- TSL `color()` commonly converts sRGB to linear.
+- Whether intermediate FBOs store linear values must be verified from the target render graph.
+- The final output encoding stage must be verified from target renderer configuration.
+
+Example for a common path:
+
+```glsl
+// Common path: sRGB hex -> linear at definition time.
+vec3 colorA = pow(vec3(0.173, 0.173, 0.259), vec3(2.2));  // #2c2c42
+
+// Intermediate passes and final output encoding must follow target evidence.
+fragColor = vec4(pow(color.rgb, vec3(1.0 / 2.2)), color.a);
+```
+
+Error case: applying a fixed gamma correction in intermediate or final passes without verifying the target renderer's color configuration.
+
+## Parameter Fidelity
+
+Do not tune parameters manually. Match the formulas and multipliers from the TSL translation:
+
+```text
+Original TSL multiplier       GLSL must use
+aberration * 0.06             not 0.12
+fresnelSoftness * 0.06        not 0.12
+fresnel = 0.17                not 0.4
+SDF gradient eps = 0.01       not 0.005
+```
+
+If the visual result does not match, inspect:
+
+1. color space, especially sRGB/linear confusion
+2. noise implementation differences such as Perlin vs `mx_noise_float`
+3. time base
+4. FBO/component-tree order
+
+Do not change multipliers to mask a mismatch. That may fit one preset while breaking other parameter combinations.
+
+## TSL Time Convention
+
+`timerLocal(speed)` increments by `speed` units per second. Replay as `uTime = seconds * speed`, then apply any component-specific multiplier inside the shader.
+
+| Component | speed parameter | shader multiplier | effective rate per second |
+|---|---:|---:|---:|
+| Plasma | 2 | 0.125 | 0.25 |
+| Godrays | 0.7 | 0.2 | 0.14 |
+| WaveDistortion | 0.8 | 0.5 | 0.4 |
+| FilmGrain | none | none | static |
+
+## TSL To GLSL Identifier Mapping
+
+These mappings are examples from one observed bundle and may change. Extract them dynamically from the current build.
+
+| Local name | TSL function | GLSL |
+|---|---|---|
+| `C` / `z` | `vec4()` | `vec4` |
+| `x` / `D` | `vec2()` | `vec2` |
+| `q` / `N` | `vec3()` | `vec3` |
+| `P` / `J` | `resolution` | `u_resolution` |
+| `A` / `$` | `uv` | `vUv` |
+| `se` / `Oe` | `sin()` | `sin` |
+| `W` / `I` | `cos()` | `cos` |
+| `ne` | `mix()` | `mix` |
+| `D` | `smoothstep()` | `smoothstep` |
+| `fe` | `clamp()` | `clamp` |
+| `ar` | `mx_noise_float()` | `perlinNoise3D()` candidate |
+| `dr` / `Gt` | `timerLocal()` | `u_time * speed` |
+| `Me` / `wt` | `rtt()` | FBO pass |
+| `Ce` | `renderOutput()` | `fragColor` |

package/skills/luckiest-website-cloner-shaders/vendor/web-shader-extractor/references/source-analysis.md

@@ -0,0 +1,112 @@
+# Source Analysis
+
+Source analysis is a targeted fallback after target lock, or before lock only when it resolves a precise `nextProbe`. Keep output as evidence, not rewritten implementation.
+
+## Bundle Slices
+
+Allowed before `TARGET_LOCKED` only when the current `scout-card.json` is `attributed` or has a precise `nextProbe`:
+
+- source map lookup for a target context creation stack
+- public platform definition referenced by target embed ID
+- dynamic chunk graph around a target script URL
+- small grep for target IDs, canvas selectors, or known shader/program names
+
+Do not download and deobfuscate every bundle before `TARGET_LOCKED`.
+
+If a local slice already exists, `scripts/scan-bundle.sh` can summarize keyword hypotheses. Use it only to choose the next target-bound probe; do not promote its counts to implementation facts.
+
+When delegating bundle analysis, provide:
+
+```text
+Target: surface-1 / targetSet [...]
+Known owner evidence: ...
+Unknown to resolve: ...
+Files/slices: ...
+Search anchors: target ID, stack function, shader keyword, platform component
+Required output: exact source facts with file offsets and confidence
+Forbidden: global framework conclusions not bound to target
+```
+
+Look for:
+
+- shader/WGSL/TSL source or node definitions
+- renderer/canvas creation path
+- render graph and FBO setup
+- resource URLs and loaders
+- timing/input update rules
+- config decoding and component tree reconstruction
+
+## Config Extraction
+
+Configuration values must be source-derived and target-bound. Do not guess colors, dimensions, speeds, or feature flags to compensate for visual mismatch.
+
+Evidence priority:
+
+1. Public structured API or platform definition whose instance ID matches the target surface/embed.
+2. Payload data referenced by the target route or target component.
+3. Inline JSON or `window` globals tied to the target instance.
+4. Source map or readable module creating the target surface.
+5. Narrow bundle slice selected from target-bound evidence.
+
+Common searches:
+
+```bash
+rg -o 'api/(presets|shaders|collections|embeds)[^"'\'' )]+' evidence/source
+rg '_payload\.json|public:\{' evidence/source evidence/dom
+rg '__NEXT_DATA__|self\.__next_f|runtimeConfig' evidence/dom evidence/source
+rg 'window\.__[A-Z0-9_]+__\s*=' evidence/dom evidence/source
+```
+
+For every implementation-critical value, record:
+
+- evidence location
+- target IDs it applies to
+- value type and units
+- whether ranges are 0-1, 0-255, CSS pixels, backing pixels, seconds, frames, or normalized coordinates
+- any decode step used
+
+If a config value cannot be proven and the baseline depends on it, keep it in `blockingUnknowns` or mark an explicit replay-route downgrade.
+
+## Encoded Definitions
+
+Use this when a target-bound public API or payload contains encoded scene/effect definitions.
+
+Decode only definitions from public content or content the user is authorized to access.
+Do not persist private cookies, Authorization headers, tokens, or account data.
+Do not bypass paywalls, CAPTCHA, or access controls.
+
+Recognition signals:
+
+- `_encoded: true`
+- `definition` is Base64 or compressed text instead of JSON
+- source contains `atob`, `btoa`, `TextEncoder`, `TextDecoder`, XOR, inflate, or mapping tables
+- runtime config exposes a public obfuscation/decode key
+
+```bash
+rg '(atob|btoa|obfuscation|_encoded|TextDecoder|TextEncoder|inflate)' evidence/source
+rg '(codeToComponent|codeToProp|components.*sort|properties.*sort)' evidence/source
+```
+
+When decoding, record:
+
+- input definition path
+- key source path and whether it is public
+- decode algorithm source
+- decoded schema hash
+- target IDs using the decoded definition
+
+Base64 + XOR pattern:
+
+```python
+import base64, json
+
+def decode(encoded, key):
+    raw = base64.b64decode(encoded)
+    key_bytes = key.encode("utf-8")
+    decrypted = bytes([raw[i] ^ key_bytes[i % len(key_bytes)] for i in range(len(raw))])
+    return json.loads(decrypted.decode("utf-8"))
+```
+
+Treat hard-coded keys in examples as stale. Extract keys dynamically from the current public source and bind them to the target route.
+
+After decoding, validate the definition by checking that component tree, resources, and render route match target runtime evidence.

package/skills/luckiest-website-cloner-shaders/vendor/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.