git:20260713.f0e8d5c to git:20260716.2ce13bc
156 added, 1 removed. Audit C to A.
- ../../threejs-black-holes-and-space-effects/SKILL.md
+ ---
+ name: threejs-black-holes-and-space-effects
+ description: Build curved-ray space effects in Three.js WebGPU/TSL. Use for artistic ray bending, Ellis wormholes, Schwarzschild black-hole lensing, accretion disks, physical thin-disk transport, or requests that need the Kerr/rotating-black-hole support boundary.
+ ---
+
+ # Curved-Ray Space Effects
+
+ Treat every result as one of three claims: an artistic deformation, an Ellis
+ null-geodesic solution, or a Schwarzschild null-geodesic solution. Numerical
+ integration alone does not turn an artistic field into a metric solution.
+
+ ## 1. Select the claim
+
+ | Requested observable | Select | Conditional reference | Completion criterion |
+ | --- | --- | --- | --- |
+ | Stylized bending, bounded glow, or a decorative disk | Artistic bounded ray | Read [artistic-rays-and-disks.md](references/artistic-rays-and-disks.md). | The implementation and its documentation say `artistic`, and fixed-view refinement bounds the visible change. |
+ | Traversal or turning through an ultrastatic spherical throat | Ellis wormhole | Read the Ellis section of [metric-rays.md](references/metric-rays.md). | The throat scale, exterior mapping, invariant, and `B < 1`, `B = 1`, `B > 1` termination classes are explicit. |
+ | Nonrotating black-hole lensing or a physical thin-disk image | Schwarzschild | Read the Schwarzschild and physical-transfer sections of [metric-rays.md](references/metric-rays.md). | The mass scale, horizon, photon sphere, critical impact, invariant, continuous events, and observer/emitter frames are explicit. |
+ | Rotating black hole | Unsupported here | Integrate an independently validated Kerr solver as an external lens-map producer. | The solver supplies its metric/sign conventions, constants of motion, tetrads, event semantics, and independent convergence evidence; otherwise return an unsupported-model result. |
+
+ **Complete when:** exactly one claim owns the ray path, and every visual claim
+ is no stronger than that branch's evidence.
+
+ ## 2. Declare the numerical domain
+
+ Define before authoring the march:
+
+ - the effect-to-world transform and a finite local integration bound;
+ - the camera event, ray origin, normalized direction, and exterior side;
+ - one length basis for positions, steps, horizons/cores, and medium
+ coefficients;
+ - the state vector, its integration parameter, its owner, and its valid time;
+ - the environment orientation and the orthonormal frame used for escaped-ray
+ lookup;
+ - horizon, core, disk, shell, proxy-exit, invalid-state, opacity, and step-cap
+ events that apply to the selected branch.
+
+ For metric rays, nondimensionalize with the Ellis throat radius `a` or the
+ Schwarzschild mass length `M = G M_SI / c^2`, while retaining the conversion
+ back to metres. Render delta never becomes a ray step. Preserve either spherical
+ metric through a similarity transform: translation, rotation, and uniform
+ scale. A nonuniform transform requires an explicitly derived transformed
+ metric and frame plus renewed invariant, event, and convergence validation;
+ otherwise reject it at setup.
+
+ Nonstationary metrics require an external solver that integrates or recovers
+ coordinate time and samples or interpolates metric and emitter state, with
+ validity and error, at every mapped integration evaluation. A frozen metric is
+ a quasi-static approximation only when its declared evolution-error gate
+ passes; otherwise report the model unsupported.
+
+ **Complete when:** every state component and event surface has a declared
+ basis, owner, and finite validity domain, and world-to-solver-to-render round
+ trips preserve the chosen scale and exterior. Each spherical metric uses a
+ similarity transform or supplies validated transformed-metric evidence, and
+ every nonstationary claim uses mapped coordinate-time sampling, is explicitly
+ labeled quasi-static with a passing evolution-error gate, or is unsupported.
+
+ ## 3. Build one bounded march
+
+ Use `WebGPURenderer` with TSL node functions. Initialize the renderer and
+ confirm the WebGPU backend before selecting compute, storage, or MRT resources.
+ The canonical march is:
+
+ 1. Transform the camera ray into effect space and intersect the finite bound.
+ A miss returns before numerical work.
+ 2. Initialize position, tangent or canonical momentum, radiance,
+ transmittance, event state, accepted-step count, and termination ID.
+ 3. Propose one candidate segment. An error-controlled rejection changes only
+ the next attempted step size.
+ 4. Locate every applicable event continuously on the segment. Root-refine the
+ earliest event; preserve ordered disk crossings when several contribute.
+ 5. Accumulate the accepted segment's transfer, then commit exactly one state
+ advance and increment the accepted-step count once.
+ 6. Terminate as `escaped`, `horizon`, `core`, `opaque`, `invalid`,
+ `unresolved-critical`, `minimum-step`, or `step-cap`.
+
+ The attempt cap bounds divergent work independently of the accepted-step cap.
+ A curvature or distance heuristic may propose a step; refinement against a
+ tighter solution decides whether it is accurate.
+
+ **Complete when:** a trace proves one committed advance per accepted step,
+ rejected attempts leave physical and event state unchanged, every ray receives
+ an explicit termination ID, and event residuals meet their declared bounds.
+
+ ## 4. Resolve transfer and the escaped direction
+
+ Sample an exterior environment only for `escaped` rays. Reconstruct its lookup
+ direction from the integrated outgoing tangent in the declared orthonormal
+ frame; orbital position angle alone is not a direction. Bound or integrate any
+ far-field tail truncated by the proxy.
+
+ Keep transfer aligned with the claim:
+
+ - An artistic disk declares a scene-length basis and a linear-HDR source
+ basis. Integrate extinction/emission front-to-back and label the result
+ artistic.
+ - A physical disk uses ordered geodesic crossings, a named emitter
+ four-velocity and observer tetrad, and invariant frequency transfer. Its
+ geometry and orbital model must match the selected Schwarzschild claim.
+
+ Accumulate into linear HDR. One pipeline stage owns tone mapping and output
+ conversion; diagnostics that replace the output mark the pipeline graph dirty.
+
+ **Complete when:** misses and non-escaped terminations cannot sample an
+ exterior, the escaped tangent is finite and normalized, disk crossings retain
+ their order, and transfer units reduce to radiance.
+
+ ## 5. Select direct work or reuse
+
+ Use a direct bounded march for changing lenses, sparse probes, or artistic
+ fields whose per-pixel work meets the target. Use a critical-split transfer
+ map for a static spherical Ellis or Schwarzschild lens when coherent reuse
+ beats direct integration. Use a local high-accuracy map near separatrices when
+ GPU `float32` direct rays miss the angular gate.
+
+ When a lens map, compute cache, or temporal reconstruction is selected, read
+ [lens-cache-and-history.md](references/lens-cache-and-history.md) before
+ allocating it. Keep the opaque scene and required depth at their required
+ resolution; scale only the effect pass whose error was measured.
+
+ **Complete when:** each cache or history resource has a reuse reason, a stable
+ identity, an invalidation rule, a completion/lifetime rule, and measured
+ benefit over the direct path.
+
+ ## 6. Verify the selected claim
+
+ Use a deterministic, seeded environment with high-frequency directional
+ features so angular, critical-curve, and history errors remain visible. It is a
+ validation input generated by the project, not a bundled visual preset.
+
+ For every branch:
+
+ - capture termination, accepted/rejected attempts, event count/location,
+ remaining transmittance, final direction, and invalid-state diagnostics;
+ - compare `h`, `h/2`, and `h/4` or an equivalent tolerance sequence at fixed
+ rays and cameras;
+ - compare final angular error against the environment footprint and compare
+ event residuals against the relevant geometric thickness;
+ - verify moved, uniformly scaled, camera-inside, miss, and far-from-origin
+ bounds, plus nonuniform-scale rejection or the explicitly transformed metric;
+ - verify the required Three.js revision, backend, final-output owner, resize,
+ reset, and disposal behavior.
+
+ Artistic rays pass when refinement preserves fixed-view silhouette,
+ termination class, ordered disk events, and radiance within declared bounds.
+ Ellis and Schwarzschild rays additionally require an independent CPU `float64`
+ reference, invariant drift, critical-regime classification, exterior/escape
+ agreement, and convergence of the final tetrad direction. A capped,
+ minimum-step, invalid, or unresolved-critical ray is diagnostic output rather
+ than physical evidence.
+
+ **Complete when:** every requested observable has a passing branch-specific
+ gate, every failure class is visible in diagnostics, and the final claim lists
+ the numerical and domain limits that remain.
+