Three.js WebGPU/TSL Choose Skills

Three.js WebGPU/TSL Choose Skills

This router targets the repository's [Gated] r185 architecture: WebGPURenderer from three/webgpu, TSL from three/tsl, NodeMaterial families, node RenderPipeline, and compute/storage only when the workload justifies them. The installed package plus runtime THREE.REVISION are the revision gate; verify lockfile coherence separately. Never infer API availability from the router's version label.

Fallback for unavailable WebGPU is quarantined. If, and only if, the user asks how to apply fallback when WebGPU is unavailable, route that teaching to $threejs-compatibility-fallbacks after finding the canonical owner. Otherwise retain the flagship route and report the unavailable WebGPU requirement as a blocker. Never dilute destination skills with alternate-renderer branches.

Quantitative Evidence Labels

Every quantitative claim, budget value, threshold, count, resolution, memory figure, timing, and example must carry one of these labels inline:

Serialize reported values as { value, unit, label, source }. An unlabelled numeric budget is unknown. Do not route or accept from it. A published skill table is not [Measured] for the composed scene unless its device, resolution, included work, and harness match.

Mandatory Preflight

Complete this before loading a destination skill:

1. Record the installed Three.js package/revision, inspect the matching migration guide, initialize WebGPURenderer, and record the actual backend. Record the required release/backend/features [Gated] and the installed/runtime facts [Measured]; verify their coherence.
2. Classify the workload and state its truth contract, interaction, temporal behavior, scale, topology, view pattern, deployment matrix, and permissible error. Missing product inputs are blockers, not invitations to guess.
3. Run the visual-causality and algorithm-selection gate. Choose from explicit candidates; do not assume compute, MRT, ray marching, temporal accumulation, or maximal geometry is faster or more faithful.
4. When physical domains interact, instantiate the shared physics domain and interaction contract: one PhysicsContext, typed providers and ErrorPropagationLedger records, an ordered multi-rate PhysicsGraph with exact PhysicsCoordinationAdvanceRecord executions, explicit one-way/two-way interactions and InteractionApplicationLedger records, atomic PhysicsCommitTransaction records, one immutable PhysicsPresentationCandidate, per-view camera/preparation publications, one sealed snapshot and PresentationRenderPlan per selected target/view, QualityTransition records for physical quality changes, and an active PhysicsCostLedger. A producer/consumer label alone is not an integration contract.
5. Build a resource/pass ownership graph before selecting effects: scene color, depth, normal, velocity, identifiers, history, tone map, output transform, and adaptive quality each need an owner or an explicit not used value.
6. Define [Gated] frame, memory, visual-error, and update-latency bounds from the product target. Define the measurement matrix before implementation.
7. Route the smallest skill intersection that owns the missing causal systems. Defer consumers until their input signal exists.

Workload Classification

Use this compact record. Domain is context; the other axes select algorithms.

workloadProfile:
  domain: scientific-visualization | product-configurator | architecture-aec | cinematic-art | digital-twin | data-scene | other
  intent: explain | inspect | configure | coordinate | present | monitor
  truthContract: metric | identity | physically-plausible | perceptual-style
  representation: imported-hierarchy | procedural-mesh | points-glyphs | lines-graph | surface-field | volume-field | hybrid
  interaction: fixed-view | orbit | free-navigation | direct-manipulation | multi-view
  temporal: static | deterministic-animation | simulation | sparse-events | streamed-deltas | live-irregular-updates
  scale: object | room | building | city-terrain | planetary | multiscale
  topology: imported-unique | procedural-unique | repeated | streamed-changing
  viewPattern: bounded | unconstrained | sectioned | overview-to-detail
  residency: host-authoritative | gpu-resident | hybrid
  uploadAndReadbackNeeds: []
  deployment: []
  authoredResolutionAndDpr: [] # numeric-evidence records
  errorBounds: []
  updateLatencyBound: { value: "", unit: ms, label: Gated, source: "product contract" }

Visual-Causality Ledger

causeLedger:
  sourceOfTruth: ""
  userQuestion: ""
  primaryObservable: ""
  truthOrStyleInvariant: ""
  unitsAndCoordinateFrame: ""
  missingDataAndUncertainty: ""
  physicalOrDataCause: ""
  earliestMissingLayer: topology | geometry | field | material | illumination | transport-volume | motion | camera-projection | image-transform
  missingSignal: ""
  candidateAlgorithms: []
  selectedAlgorithm: ""
  rejectedAlgorithms: []
  rejectionEvidence: []
  noPostBaseline: ""
  postProcessingRejectedBecause: ""
  primaryVisualContract: ""
  errorMetric: ""
  truthDebugView: ""

Select the earliest missing causal layer. A screen effect cannot repair wrong topology, an incorrect transfer function, missing shadows, a bad BRDF, or an unstable camera. Post-processing is eligible only when its source signal and no-post baseline are already proven.

Algorithm-Selection Gate

The route must name the losing alternatives and the evidence that rejected them. When target evidence does not distinguish candidates, retain an A/B prototype in the plan instead of asserting a winner.

Any screen-error argument for LOD, tessellation, impostors, field bands, or simulation extent follows the shared physical-pixel projected-error contract: unjittered projection, complete deformed support, nearest positive depth, per-view evaluation, hysteresis/dwell, and simultaneous transition memory.

Route Manifest

Every route decision produces this shape:

backendManifest:
  requiredReleaseBand: { value: "", unit: revision, label: Gated, source: "repository contract" }
  installedPackageVersion: { value: "", unit: semver, label: Measured, source: "installed package" }
  runtimeRevision: { value: "", unit: revision, label: Measured, source: "THREE.REVISION after import" }
  requiredBackend: { value: WebGPU, unit: backend, label: Gated, source: "flagship route contract" }
  actualBackend: { value: "", unit: backend, label: Measured, source: "initialized renderer" }
  deviceBrowserGpu: { value: "", unit: identity, label: Measured, source: "target run" }
  cssViewport: { value: "", unit: css-pixels, label: Measured, source: "target run" }
  rendererDpr: { value: "", unit: ratio, label: Measured, source: "initialized renderer" }
  physicalRenderExtent: { value: "", unit: physical-pixels, label: Derived, source: "CSS viewport and renderer DPR" }
  compatibilityMode: { value: "", unit: boolean, label: Measured, source: "initialized backend" }
  requestedSamples: { value: "", unit: samples-per-pixel, label: Authored, source: "render contract" }
  actualRendererSamples: { value: "", unit: samples-per-pixel, label: Measured, source: "initialized renderer" }
  maxColorAttachments: { value: "", unit: attachments, label: Measured, source: "initialized WebGPU device limits" }
  maxColorAttachmentBytesPerSample: { value: "", unit: bytes-per-sample, label: Measured, source: "initialized WebGPU device limits" }
  featureGates: []
  apiProof: []
workloadProfile: {}
causeLedger: {}
selectedSkills: []
omittedSkills: []
primaryOwner: ""
deferredSkills: []
owners:
  sourceOfTruth: ""
  representation: ""
  spatialFrame: ""
  timebase: ""
  semanticIds: ""
  selectionPicking: ""
  clipSection: ""
  presentation: ""
  validation: ""
requiredSignals:
  sceneColorRegistry: {}
  depthRegistry: {}
  normalRegistry: {}
  velocityRegistry: {}
  objectIdRegistry: {}
  historyRegistry: {}
domainSignals: {}
physicsContext: not used
physicsGraph: not used
physicsCoordinationAdvanceRecords: []
physicsCostLedger: not used
physicsSignals: {}
physicsErrorPropagationLedgers: {}
physicsInteractions: []
physicsInteractionApplicationLedgers: {}
physicsCommitTransactions: {}
physicsQualityTransitions: []
physicsPresentationTimeCohortsById: {}
physicsPresentationCandidate: not used
physicsCameraViewPublicationsByTarget: {}
physicsViewPreparationPublicationsByTarget: {}
physicsPresentationSnapshotsByTarget: {}
physicsPresentationRenderPlansByTarget: {}
frameExecutionRecord: not used
# Deprecated compatibility projection. It never carries allocated state.
physicsPresentationSnapshot: not used
outputOwnersByPresentationTarget: {}
# Compatibility projection for existing route tooling; "not used" never allocates.
sharedResourceOwners:
  gbuffer: ""
  depth: ""
  normal: ""
  velocity: ""
  history: ""
  weatherEnvelope: ""
  toneMap: ""
  outputTransform: ""
  adaptiveResolution: ""
performanceContract:
  requestedRefresh: { value: "", unit: Hz, label: Authored, source: "product brief" }
  actualDisplayRefresh: { value: "", unit: Hz, label: Measured, source: "target run" }
  frozenTargetRefresh: { value: "", unit: Hz, label: Gated, source: "accepted target envelope" }
  frameInterval: { value: "", unit: ms, label: Derived, source: "1000 ms / frozenTargetRefresh" }
  cpuP95Budget: { value: "", unit: ms, label: Gated, source: "derived CPU envelope" }
  gpuP95Budget: { value: "", unit: ms, label: Gated, source: "derived GPU envelope" }
  presentedP95Budget: { value: "", unit: ms, label: Gated, source: "presentation contract" }
  peakLiveMemoryBudget: { value: "", unit: bytes, label: Gated, source: "target memory contract" }
  cpuEnvelopeInputs: [] # numeric-evidence records
  gpuEnvelopeInputs: [] # numeric-evidence records
  interactionReserve: { value: "", unit: ms, label: Authored, source: "planning only; never acceptance" }
  errorBounds: []
  aggregationPolicy:
    basis: composed-full-frame-plus-paired-sample-marginals
    acceptance: measured-composed-frame
    forbidden: [standalone-total-addition, subsystem-percentile-addition, fixed-time-overhead]
  drawAccounting:
    source: renderer-info-plus-backend-trace
    batchedMeshModel: backend-multidraw-entries-measured
    forbiddenAssumption: single-gpu-draw-per-batchedmesh-material-family
  mrtDecision:
    status: not-used | candidate | accepted
    attachments: []
    consumerProof: []
    targetABEvidence: []
    tileGpuEvidence: []
  costRecords: []
  passKeys: []
  passLedger: []
  qualityLadder: []
  skillTierCrosswalk: {} # selected skill local tier -> Full/Budgeted/Minimum viable
  qualityController: {}
  routeStatus: provisional | measured-valid | invalid | unmeasurable
coverageStatus: complete | partial | blocked
acceptanceEvidence:
  requiredDebugViews: []
  requiredMetrics: []
  requiredCommands: []
  requiredArtifacts: []

selectedSkills is the smallest set that authors the requested causes. primaryOwner owns the earliest non-post missing layer. omittedSkills records tempting but unnecessary routes and their rejection reason. deferredSkills cannot be loaded until their source signal is proven. owners separates authoritative source/data, render representation, spatial/time/identity policy, presentation, and validation. requiredSignals describes actual allocation: an owner does not imply a depth, normal, velocity, ID, history, or MRT output. Every signal in a recipe has a producer and consumers or not used. When any selected domain consumes another domain's physical state, every declared physics... field plus frameExecutionRecord is mandatory and follows the shared ABI. Every PhysicsSampleResponseEnvelope.errorPropagationLedgerRef resolves to exactly one ErrorPropagationLedger in physicsErrorPropagationLedgers. Every InteractionBatchLedger.exactOnceApplicationLedgerVersion resolves to one InteractionApplicationLedger in physicsInteractionApplicationLedgers. Every PhysicsDependencyRef used by a stage execution, commit, candidate, PresentationRenderPlan, or frame execution resolves to the exact record and version in the route inventories; unresolved or stale references block publication. Every Candidate, frame-cohort admission, and render plan resolves its timeCohortId to one immutable PresentationTimeCohort in physicsPresentationTimeCohortsById; a target/view with different requested previous/current instants uses another cohort rather than mutating or sharing the wrong Candidate. domainSignals remains a routing index; every physical entry points to a PhysicsSignalDescriptor rather than redefining units, clocks, validity, or errors locally. Missing channels are absent and can block a consumer; they are never implicit zero. External solvers use the same boundary contract without ceding their internal representation or timestep. Represent every recurrent or adaptive coupled advance as exact PhysicsStageExecution records in one PhysicsCoordinationAdvanceRecord. Only the graph-wide PhysicsCatchUpPolicy may catch up, drop, or discontinue a physical interval; domain-local render-loop recurrence and catch-up are invalid. sharedResourceOwners is retained as a compatibility projection for existing route tooling. It mirrors actual requiredSignals, domainSignals, and outputOwnersByPresentationTarget; assigning a name there never authorizes allocation. history names the coordinator, while keyed histories remain separate by semantic signal, view, encoding, resolution, jitter, cadence, and reset policy. Signal and output registries are keyed by view/presentation target. Depth, velocity, histories, and output conversion from different cameras, layers, jitter, time samples, or canvases are not shareable merely because their field names match.

Preflight Checkpoints

import * as THREE from 'three/webgpu';

const renderer = new THREE.WebGPURenderer( {
  antialias: false
} );

await renderer.init();

const capabilities = {
  revision: THREE.REVISION,
  webgpu: renderer.backend.isWebGPUBackend === true,
  outputBufferType: renderer.getOutputBufferType(),
  actualSamples: renderer.samples,
  compatibilityMode: renderer.backend.compatibilityMode,
  deviceLimits: renderer.backend.device?.limits ?? null,
  rendererInfo: renderer.info
};

if ( capabilities.webgpu !== true ) {
  throw new Error(
    'Canonical flagship route requires WebGPU; route fallback teaching only when explicitly requested.'
  );
}

Legacy WebGL implementation: none in this router folder.

Installed-Revision Architecture Gates

[Gated] in this section means verify against the installed revision and target backend before coding.

• Renderer/materials: WebGPURenderer, TSL, and the appropriate node-material family. Do not mix a legacy post or material path into the flagship graph.
• Frame graph: use RenderPipeline, pass(), mrt(), renderOutput(), and PassNode.setResolutionScale() where proven. Plan producers, consumers, formats, resolutions, lifetimes, and history invalidation before effects. Configure MRT and request every consumed MRT/pass output before await scenePass.compileAsync( renderer ). renderPipeline.render() owns animation-loop presentation; deprecated renderAsync() is not a route. After changing outputNode or outputColorTransform, set renderPipeline.needsUpdate = true.
• Compute/storage: use renderer.compute() or renderer.computeAsync() with installed TSL storage APIs only when the algorithm-selection gate justifies dense GPU-resident generation/reduction, persistent state, or cross-pass reuse. Record dispatch extent [Derived]; validate synchronization and bounds [Gated]. After initialization, computeAsync() is not a GPU-completion fence. Workgroup/storage barriers do not provide global cross-workgroup ordering; use dispatch/pass boundaries and ping-pong state for global dependencies.
• Built-ins: start from GTAONode, BloomNode, TRAANode, TAAUNode, DepthOfFieldNode, and sky/fog nodes when they implement the required mechanism. Start shadows from ordinary light shadows; use CSMShadowNode or TileShadowNode only when their coverage/error contract and measured cost justify them. TileShadowNode tiles shadow coverage; it is not a tile-GPU performance primitive. Replace built-ins only with evidence. In the [Gated] installed revision, gate TAAU on disabled MSAA and the required lower-resolution beauty/depth/velocity inputs; gate TileShadowNode away from VSM.
• Scale: select batching/instancing/merging/chunking from topology, material, identity, update, and culling requirements. Avoid universal draw-count limits; CPU submit, GPU work, and memory behavior are [Measured] per target. [Gated] in installed r185, BatchedMesh does not prove a single GPU draw per material family: the WebGPU backend submits and updates renderer info per _multiDrawCount entry. Use it for compatible state/scene management, per-object culling, and replacement; measure backend draw entries instead of budgeting a family as one draw.
• Precision: choose coordinate origin, buffer precision, depth convention, and data encoding from the workload's scale/error contract. Scientific/AEC truth wins over an attractive but numerically unstable shortcut.
• Adaptive quality: [Gated] a single controller owns DPR and subsystem tiers. Each subsystem exposes monotonic quality states and its visual/error consequences. Record renderer DPR and every pass resolution scale separately because their physical extents compose. A scale/attachment transition updates texel uniforms, jitter, velocity, and history allocation/reset atomically.

Installed-Source API Proof

Record exact file/export proof in the manifest. A nearby release example is not proof for the installed package.

Quality Tiers

Every implementation defines canonical WebGPU tiers; no alternate renderer is a tier.

For scientific visualization, AEC, digital twins, and data scenes, quality adaptation must not silently alter values, transfer-function semantics, stable IDs, topology, dimensions, or uncertainty. If a lower tier changes such a quantity, expose the tier and its [Gated] error bound to the user.

The route manifest maps every selected skill's local tier vocabulary into Full, Budgeted, or Minimum viable in performanceContract.skillTierCrosswalk. A route transition names both the route tier and every affected local tier; matching names are not assumed to mean matching equations, costs, or errors.

Performance Contract And Aggregation

Budget Inputs

Do not use universal desktop/mobile pass, draw, triangle, or memory budgets. Build a target matrix from the product brief and representative hardware:

[Derived] frameIntervalMs = 1000 ms / targetRefreshHz
[Derived] cpuSceneEnvelopeMs = frameIntervalMs - measuredMainThreadReserveMs - authoredCpuSafetyReserveMs
[Derived] gpuSceneEnvelopeMs = frameIntervalMs - measuredCompositorGpuReserveMs - authoredGpuSafetyReserveMs

targetRefreshHz is [Gated]; reserves are [Measured] under the target host shell or explicitly provisional [Authored] starting points. Freeze separate [Gated] CPU/GPU tail-latency limits from the derived envelopes. CPU and GPU stages can overlap, so never add their durations unless a measured dependency serializes them. Memory, upload, update latency, presentation cadence, and deadline misses remain separate gates. End-to-end acceptance uses the composed frame, not independent skill tables.

Cost Scope

Every cost record declares exactly one scope:

costRecord:
  id: ""
  scope: full-frame | marginal-feature | unique-pass | memory | standalone-total | unknown
  deviceBrowserGpu: { value: "", unit: identity, label: Measured, source: "benchmark profile" }
  cssViewport: { value: "", unit: css-pixels, label: Measured, source: "benchmark profile" }
  rendererDpr: { value: "", unit: ratio, label: Measured, source: "benchmark profile" }
  renderExtent: { value: "", unit: physical-pixels, label: Derived, source: "CSS viewport and renderer DPR" }
  qualityState: ""
  sceneStateAndSeed: ""
  includes: []
  excludes: []
  passKeys: []
  cpuP50: { value: "", unit: ms, label: Measured, source: "benchmark trace" }
  cpuP95: { value: "", unit: ms, label: Measured, source: "benchmark trace" }
  gpuP50: { value: "", unit: ms, label: Measured, source: "GPU timestamp trace" }
  gpuP95: { value: "", unit: ms, label: Measured, source: "GPU timestamp trace" }
  presentedP50: { value: "", unit: ms, label: Measured, source: "presentation trace" }
  presentedP95: { value: "", unit: ms, label: Measured, source: "presentation trace" }
  bytes: { value: "", unit: bytes, label: Derived, source: "logical allocation ledger" }
  method: ""

Every populated percentile field is [Measured]. A range maximum from a standalone destination skill remains standalone-total; relabeling it marginal-feature is forbidden.

Correct Composed-Scene Estimate

Delete the old additive-maxima rule and fixed composition overhead. It double-counted scene passes/post work and mixed standalone totals with subsystem marginals. Base scene traversal, present, upsample, tone map, and shared buffers are measured or derived from the unique pass ledger; none receives an invented fixed time.

For planning only:

[Derived] T_plan,k = T_base,k + sum(deltaT_unique,compatible,k) + R_interaction,k
[Derived] Q_plan,p = quantile over k of T_plan,k

• T_base,k is a [Measured] composed-baseline frame sample with the shared scene/present architecture enabled.
• Each deltaT...k is [Measured] paired marginal work from the same target, resolution, seed/path, and quality context, and its pass keys are unique.
• R_interaction,k is an [Authored] starting-point allowance for unmeasured cache, queue, bandwidth, scheduling, and coupling effects. It is replaced by composed measurement, not tuned to make the route pass.

If compatible samplewise traces are unavailable, do not manufacture a numeric aggregate from skill rows; keep the route qualitative and provisional.

This estimate is not an acceptance proof: percentile sums are not the percentile of a sum, GPU work can overlap, and added attachments can change the cost of existing passes. A route is performance-valid only when the final composition satisfies [Measured] CPU and GPU p50/p95, memory, latency, and sustained-state gates on the target matrix.

For a feature (s) added to composed graph (G), pair contemporaneous frame samples:

[Derived] deltaT_s|G,k = T_k(G with s) - T_k(G without s)

Report [Measured] p50/p95 of the paired differences. Never subtract two independently sampled percentiles: quantiles are not additive and their tails may occur on different frames. If GPU timestamps are unsupported, mark GPU timing unmeasurable; CPU or presentation timing cannot be relabelled as GPU evidence.

Shared-Pass Deduplication

Build the union of pass keys, never concatenate skill-local pass lists:

passRecord:
  key: "stable semantic producer key"
  runtimeRole: exclusive | shared | validation-only | compile-time-only
  accountingOwner: ""
  viewScope:
    scene: ""
    camera: ""
    view: ""
    layers: ""
    jitter: ""
    timeSample: { value: "", unit: seconds, label: Authored, source: "reproducible input path" }
  producer: ""
  consumers: []
  kind: cpu-update | upload | render | compute | copy | resolve | present
  clockId: not used
  cadence: not used
  substepMultiplicity: not used
  executionsPerPresentedFrame: not used
  inputs: []
  outputs: []
  resolution: { value: "", unit: physical-pixels, label: Derived, source: "canvas, DPR, pass scale" }
  formats: []
  sampleCount: { value: "", unit: samples-per-pixel, label: Measured, source: "configured pass after backend normalization" }
  loadStoreResolve: []
  lifetime: ""
  hotBytesPerExecution: not used
  sourceReactionOrConservationGroups: []
  timing:
    p50: { value: "", unit: ms, label: Measured, source: "GPU timestamp trace" }
    p95: { value: "", unit: ms, label: Measured, source: "GPU timestamp trace" }

Skills are ownership/algorithm documents, not timing buckets. Mark validation and compilation work explicitly; it contributes to validation/startup evidence, not steady-frame cost. Shared work has one accounting owner and any number of consumers.

If AO, temporal reconstruction, outlines, and grading consume the same scene depth/normal/velocity, their owners reference the same producer. Tone mapping, output conversion, history update, and upsample are likewise unique semantic producers. A consumer that needs another encoding or resolution must declare a conversion pass and its bytes; name reuse is not deduplication. Physics stages additionally declare state epochs, barriers, subcycling, hot traffic, and conservation side effects. Do not infer solver order from the render-pass list.

MRT And Tile-GPU Bandwidth Gate

MRT saves work only when its consumers justify the attachments. For each attachment j, compute logical uncompressed payloads from labelled inputs:

[Derived] logicalSamplePayload_j = width_j * height_j * backendSampleCount_j * bytesPerTexel_j * liveSlots_j
[Derived] logicalResolvedPayload_j = width_j * height_j * bytesPerTexel_j * resolvedStoresPerFrame_j

Every operand is a { value, unit, label, source } record; the products are [Derived] records citing those operands.

These are representation estimates, not physical allocation or external-memory traffic floors. Record requested samples, actual renderer/pass samples, backend-normalized samples, MSAA storage, resolve targets, depth/stencil, history copies, texture reads, load/store actions, and concurrent lifetimes separately. Row alignment applies to explicit copies/readback, not generic render target traffic. Compression, tile residency/spills, implementation allocation, and external traffic are [Gated] or [Measured] properties.

On a tile-based GPU, an attachment consumed after its render pass may require off-chip store/resolve traffic; a wide G-buffer can therefore lose against a minimal forward path even when it removes a geometry pass. Keep attachment count/formats minimal, avoid unconsumed outputs, and A/B the minimal-forward and shared-MRT compositions on representative mobile hardware. Select from [Measured] full-frame p50/p95, attachment traffic/counters when available, transient memory, and thermal behavior—not desktop intuition.

Do not infer auxiliary MRT formats from getOutputBufferType(): prove each attachment's type, format, packing, and consumer encoding before compile. Query the initialized device's color-attachment count and per-sample byte limits. For mobile AO, A/B depth reconstruction against a stored normal attachment. Bloom does not justify emissive MRT unless selective emission is required.

Measurement Protocol

• Fix browser/device/GPU, power/thermal state, canvas CSS size, physical render size, DPR, camera path, seed/data stream, quality state, visibility, and compilation state.
• Warm and stabilize shaders/resources before sampling. For mobile and integrated devices, continue through a sustained run until thermal and clock behavior are represented; a cold burst is not acceptance evidence.
• Capture [Measured] full-frame CPU p50/p95, presentation p50/p95, and GPU p50/p95 whenever GPU performance is a gate. If required GPU timing is unavailable, performance status is unmeasurable, not passing. Also capture dropped/deferred-frame behavior and pass/dispatch timings, uploads, explicit allocation ledgers, render-target logical payloads, and live storage. Treat renderer.info as engine counters/logical estimates with known exclusions, not measured VRAM or external traffic. Record hardware counters, residency, power, clocks, and thermal state only when exposed; otherwise mark them unavailable and rely on sustained timing/cadence/quality drift.
• Measure feature marginals with paired on/off runs over the same deterministic path. Report the sampling method and run-to-run dispersion; do not subtract unrelated percentile tables.
• Separate CPU-bound, vertex/primitive-bound, fragment/fill-bound, compute-bound, memory/bandwidth-bound, upload-bound, and synchronization-bound cases before changing quality.

Hysteretic Quality Adaptation

Every adaptive route records the controller, never just adaptive DPR:

qualityController:
  observedSignals: [cpuP50, cpuP95, gpuP50, gpuP95, presentedP50, presentedP95, droppedFrames, memoryPressure, thermalState]
  samplingWindow: { value: "", unit: frames-or-time, label: Authored, source: "controller policy" }
  downgradePredicate: { value: "p95 exceeds its Gated budget for persistent windows", unit: predicate, label: Gated, source: "performance contract" }
  upgradePredicate: { value: "p50 and p95 remain below lower recovery gates for longer persistence", unit: predicate, label: Gated, source: "performance contract" }
  headroom: { value: "", unit: budget-fraction-or-ms, label: Authored, source: "controller policy" }
  downgradePersistence: { value: "", unit: windows, label: Authored, source: "controller policy" }
  upgradePersistence: { value: "", unit: windows, label: Authored, source: "controller policy" }
  cooldown: { value: "", unit: windows, label: Authored, source: "controller policy" }
  bottleneckClassifier: ""
  qualityLadder: []
  protectedInvariants: []

[Gated] controller invariants: upgrade persistence is stricter than downgrade persistence; upgrade has positive headroom; a cooldown follows a transition; the controller applies one independently valid transition transaction, observes the settled result, then reclassifies pressure. A transaction may atomically change coupled state such as scene scale, TAAU, velocity, and history, or remove an attachment while enabling its reconstruction path. Quantize scale/tier transitions; frequent DPR or pass-scale changes can trigger target reallocation. Each transition declares history reset/resample, settling, lifecycle, and dispose ownership. These inequalities create hysteresis without inventing device-independent thresholds. Every physical quality change—including cadence, discretization, state, filter, identity, residency, or coupling—must use a QualityTransition that declares state projection/reset, provider-version publication, conservation correction or residual, simultaneous residency, and consumer invalidation. A render governor may request the transition but cannot mutate physical state directly. Changing solver class to meet a budget is a new truth contract, not a tier.

Choose the downgrade axis from the measured bottleneck:

Skill Inventory Gate

Enumerate the live threejs-* skills before composing a route and intersect it with this repository roster:

• threejs-ambient-contact-shading
• threejs-black-holes-and-space-effects
• threejs-bloom
• threejs-camera-controls-and-rigs
• threejs-choose-skills
• threejs-compatibility-fallbacks
• threejs-debugging
• threejs-dynamic-surface-effects
• threejs-exposure-color-grading
• threejs-image-pipeline
• threejs-particles-trails-and-effects
• threejs-procedural-buildings-and-cities
• threejs-procedural-creatures
• threejs-procedural-fields
• threejs-procedural-geometry
• threejs-procedural-materials
• threejs-procedural-motion-systems
• threejs-procedural-planets
• threejs-procedural-vegetation
• threejs-rain-snow-and-wet-surfaces
• threejs-scalable-real-time-shadows
• threejs-sky-atmosphere-and-haze
• threejs-spectral-ocean
• threejs-visual-validation
• threejs-volumetric-clouds
• threejs-water-optics

Route only to the intersection. Record divergence in the manifest. If a causal owner is absent, block that part or reduce scope; never invent a renamed owner.

Route By Causal System

See references/router-recipes.md for general-purpose domain routes.

For a local archipelago, the default primary owner is procedural fields, not planets or water. One deterministic field bundle must provide land support, elevation, bathymetry, coast distance/frame, slope/exposure, material regions, and placement validity. Geometry, materials, vegetation, structures, and water consume that bundle; none may regenerate a private coastline. Spectral ocean is optional and owns only the deep/open-water incident sea. The detailed route and fixed-view evidence contract live in the stylized archipelago / coastal scene recipe.

Color, Data, And Output Rules

• Mark color imagery with its actual color space; keep normals, roughness, identifiers, masks, simulation state, uncertainty, and scientific scalar data in linear/data encodings.
• Keep HDR working buffers in the justified format until the unique tone-map step. Format precision and bytes are [Gated]/[Derived], not aesthetic defaults.
• Final conversion is a [Gated] exclusive choice: either provide a scene-linear outputNode with renderPipeline.outputColorTransform = true, or use an explicit renderOutput() node with outputColorTransform = false. After changing the node or flag, set renderPipeline.needsUpdate = true. Materials/effects must not double-convert.
• Quantitative transfer functions declare input domain, normalization/clamping, missing/out-of-range values, interpolation, and display conversion. Do not expose scientific values to eye adaptation unless the contract explicitly permits it.
• Generate mipmaps for data/storage outputs only when the sampling semantics and update cost require them.

Execution Order

1. Run backend/API gates and classify the workload.
2. Fix truth/style contract, views, deployment matrix, frame/memory/error bounds, and reproducible input path.
3. Run the cause/algorithm gate and assign the primary causal owner.
4. Establish coordinate/precision/camera policy when scale, projection, or navigation affects representation.
5. For interacting physical domains, freeze PhysicsContext, signal/error inventories, exact PhysicsGraph executions and graph-wide catch-up, source/reaction/application-ledger ownership, commit dependencies, presentation interpolation/render plans, and QualityTransition admission.
6. Implement subject/data representation, fields, material identity, and motion; prove no-post diagnostics.
7. Build the unique pass/resource graph and A/B minimal-forward versus shared-MRT or spatial versus temporal alternatives where relevant.
8. Add lighting, shadows, atmosphere, and volumes only when their source geometry and data are correct.
9. Add image effects only when their source signals and rejection conditions are proven.
10. Measure the composed scene, implement hysteretic quality adaptation, run sustained target-device validation, and capture deterministic evidence.

Space And Owner Handoff

Every handoff labels:

For physical handoffs these labels are serialized, not prose. Use PhysicsSignalDescriptor, InteractionRecord, PhysicsPresentationCandidate, and per-target/view PhysicsPresentationSnapshot from the physics contract, including footprint/filtering, validity, typed error, latency, origin epoch, state version, and residency.

Route-Away Ledger

Routing Constraints

• The router owns generic installed-revision preflight; $threejs-debugging owns failure isolation and upstream fix/version proof; destination skills own domain algorithms.
• Do not route “make it beautiful” directly to post. Find the missing cause.
• Prefer a causal, inspectable visual rule over unrelated noise/effect layers.
• Preserve supplied-reference mechanisms and authoritative data, not merely a broad visual category.
• Keep source/world/view/screen spaces separate unless the composition defines a conversion and owner.
• Do not call a workload “game-like” to justify weaker accuracy or stronger hardware assumptions. Route from its actual truth, interaction, view, and deployment contracts.
• When no skill owns a cause, state the gap and use official/domain sources; do not invent a pseudo-owner.

Acceptance Gate

A routed implementation is incomplete without:

• required revision/backend/API constraints [Gated], installed/runtime facts [Measured], coherence proof, and target-device matrix;
• workload profile, truth/error contract, cause ledger, rejected algorithms, and primary owner;
• deterministic seed, fixed camera path, or reproducible live-data trace;
• explicit Full/Budgeted/Minimum viable tiers with protected invariants and visible consequences;
• unique resource/pass ledger with formats, resolution, lifetimes, consumers, and shared-pass deduplication;
• for every interacting physical route, a serialized PhysicsContext, typed signal/provider and error-ledger inventory, ordered multi-rate PhysicsGraph with exact coordination advances and graph-wide catch-up, interaction, application and conservation ledgers, atomic commit transactions/dependencies, external-solver adapter evidence where applicable, physics-material/proxy identities, the immutable presentation publication chain and PresentationRenderPlan, conservative QualityTransition records, and an active PhysicsCostLedger covering coordination intervals, native owner steps, worst permitted catch-up, stage executions/hot bytes, critical queue path, traffic/readbacks, multiview/ frames-in-flight multiplication, migration overlap, and sustained thermal state;
• no-post baseline plus field, geometry, material, identity, depth, velocity, history, and output diagnostics actually used by the route;
• color/data encoding, HDR format, tone-map owner, output-transform owner, and proof of no double conversion;
• [Derived] render-target/storage byte accounting and target-specific MRT A/B evidence when multiple attachments are proposed;
• [Measured] composed CPU p50/p95 and presentation p50/p95; GPU p50/p95 for every GPU-performance verdict or unmeasurable status; uploads and pass/dispatch evidence; [Derived] logical memory ledgers; renderer.info limitations; sustained timing/quality drift; and exposed thermal/hardware signals or an explicit unavailable reason;
• hysteretic controller trace showing pressure classification, downgrade, cooldown, recovery headroom, and absence of oscillation;
• fixed-view/trajectory captures and regression artifacts for every accepted target tier;
• coupled replay, subcycle/step convergence, reaction/conservation, provider error propagation, origin-rebase, presentation-motion, and quality-migration evidence for every active physics edge;
• { value, unit, label, source } evidence on every quantitative claim.