Webgl

The platform declared React peers in five different shapes — >=18.0.0, >=18, ^18 || ^19, ^18.3.0 || ^19.0.0, ^19.0.0 — while its kernel (@wabbit/tome-core) and five app-layer packages already required >=19. Any package advertising React 18 was advertising a configuration that could not be installed alongside the kernel, so the split was never a supported matrix; it was drift.

One shape now, and it is the honest one.

These nine version independently of the linked blocks family (which gets its own coordinated bump), so they are listed here:

• @wabbit/tome-admin, @wabbit/tome-admin-pro — from ^18.3.0 || ^19.0.0
• @wabbit/tome-blocks-gallery — from ^18 || ^19; devDeps react/@types/react ^18.0.0 → ^19.0.0
• @wabbit/tome-blocks-org-pack — from >=18.0.0; same devDep correction
• @wabbit/tome-engine, @wabbit/tome-motion, @wabbit/tome-rpg, @wabbit/tome-webgl — from >=18
• @wabbit/tome-ui — from >=18.0.0

The ^18 devDependency pins on the two block-shaped packages were already fiction: the root pnpm.overrides pins @types/react to 19.2.14, so both have been building against React 19 types regardless. Correcting them changes the manifest, not the resolved tree.

Consumer impact: a React 18 consumer can no longer install these. That install was already impossible with the kernel in the graph.

build gains && node ../../scripts/fix-dist-extensions.mjs --strict as its last step, joining the 13 packages that already ran it. tsup builds bundle: false and emits relative specifiers exactly as the TypeScript source wrote them — extensionless — which bundlers resolve and raw Node does not (ESM ERR_MODULE_NOT_FOUND; CJS worse, require('./x') finds the ESM .js twin and Node 22+ require(esm) then dies on that file's own extensionless import). Every consumer outside a bundler hit this: the payload CLI under plain node, generate:types, generate:importmap, ops scripts, codegen tools.

No source changes, no API changes, and bundler consumers are unaffected — extensioned relative specifiers are universally resolvable.

Two supporting changes made the wiring possible, both in repo scripts rather than package source. fix-dist-extensions.mjs now skips bundler-asset specifiers (.css, .module.css, .scss, fonts, images, shaders) by explicit extension allowlist instead of reporting them as unresolvable — that single gap is why the 13 prior adopters were exactly the 13 packages that ship no CSS, since --strict exited 1 on any package with a relative stylesheet import.

Dotted MODULE names (./config.meta, ./x.variants, ./y.demo) are deliberately NOT treated as assets and still get .js/.cjs appended. assert-node-loadable.mjs gained the matching carve-outs so the new repo-wide CI gate reports real defects only: a resolution failure whose path lands under node_modules is a peer SKIP (next@15 has no exports map, so next/image fails as an absolute path), and a bundler-asset load failure is an environmental SKIP (CJS surfaces it as SyntaxError: Unexpected token '.' raised from inside the stylesheet).

Verified before/after on four packages built one at a time: print 8 FAIL → 0, readout 22 FAIL → 0, ai 3 FAIL → 0, gamification 2 FAIL → 0 (its failure was the other signature — a directory import missing /index). cop was already clean on a fresh build, so the audit's "27 of 46 fail" figure includes at least one package whose local dist was merely stale.

All 46 publishable manifests were missing the three fields a consumer sees before any code (2026-09-01 sale-readiness audit §6). Metadata only — no source, no build, no runtime change.

• homepage deep-links to that package README on GitHub (.../tree/main/packages/<dir>#readme). Without it a registry page links to the monorepo root and the reader has to guess which of 46 folders they want.
• bugs.url points at the repo issue tracker, so a paying customer has a place to report a defect that is not email.
• engines.node is >=22, matching the root engines and .nvmrc set the same day. This is a real floor, not decoration: CI on Node 20 could not expand the glob the block packs use for node --test, and a package installed on Node 20 fails at a runtime the installer cannot connect back to the version.

The forcing function ships with the change: scripts/assert-manifest-metadata.mjs (root pnpm assert:manifest-metadata, wired into platform-discipline.yml beside assert:license-metadata) fails when any publishable manifest lacks description, repository.directory matching its own folder, homepage, bugs, engines.node equal to the repo floor, license, files or sideEffects. It reported 138 violations before this change and 0 after.

• @wabbit/tome-blocks-core@0.16.0

Hardens the node-renderer path introduced for TSL and proves TSL↔GLSL parity. Additive and non-breaking — classic + GLSL stays the default; existing consumers are unaffected.

• WebGPU adapter init hardening — node-webgpu now races renderer.init() against a timeout and, on adapter-request hang/rejection, downgrades to a WebGL2 (forceWebGL:true) renderer with a one-time warn instead of hanging the canvas. node-webgl stays deterministic.
• postprocessing hard-gate — policy.postprocessing under a node renderer now throws an actionable error (@react-three/postprocessing is WebGL-bound and crashes on WebGPURenderer). The flag was previously inert, so no consumer breaks. Native node-renderer postprocessing via three's RenderPipeline is tracked for 0.7.x.
• renderer-init fallback — a new RendererInitBoundary renders a static poster if all renderer paths fail, instead of a blank/crashed canvas.
• docs — a README with the renderer decision tree (classic/node-webgl/node-webgpu), a TSL transition authoring guide, and a @react-three/drei compatibility matrix under node renderers (<Environment>/<Sky>/reflectors break; controls/useProgress/useGLTF/Html are safe).

node-webgpu remains "validate node-webgl in production first." TSL↔GLSL render parity for the built-in spiral was verified pixel-identical on the WebGL2/node-webgl path (render-parity harness in test/parity/).

Additive, non-breaking TSL lane alongside the GLSL/classic default. Existing consumers are unaffected until they opt in.

• `./transitions` — TransitionDefinition becomes a discriminated union: the GLSL fragmentShader arm is source-compatible with every existing definition, plus a new TSL nodeShader: (ctx: TransitionNodeContext) => Node arm. Adds the TransitionNodeContext / TransitionNodeBuilder contract.
• `./registry` — WebglCanvasPolicy gains autoUpgradeRendererForTsl; node-webgpu promoted from "reserved" to supported (validate node-webgl in production first).
• runtime — TransitionCompositor branches on the resolved definition: GLSL builds THREE.ShaderMaterial unchanged; TSL lazily imports three/webgpu and builds a NodeMaterial colorNode. WebglCanvasProvider enforces the renderer auto-upgrade contract — a TSL transition under renderer: 'classic' throws an actionable error by default, or coerces to node-webgl (with a one-time warn) when autoUpgradeRendererForTsl is set. Never a silent no-op or GLSL fallback.
• `./tsl` (new subpath) — React-free TSL Fn helper library (curlNoise/snoiseVec3, voronoi3D, scaffoldFloat, wrappedDiffuseTwoLight/blendVolumeNormal/fresnelRim/pulseEnvelope/pulseWavefront) plus builtInTransitionsTSL node-builders for the six curtains. Imports three/tsl only; never touches React.
• peer — three floor raised >=0.171 → >=0.180 (the floor that exports the required TSL/MaterialX surface).

three/webgpu + three/tsl are dynamic-import-only, so the classic GLSL path never pulls the WebGPU bundle.

WebglCanvasPolicy gains a renderer field. Default 'classic' preserves current behavior (R3F default THREE.WebGLRenderer).

New 'node-webgl' opts the shared background canvas into THREE.WebGPURenderer with forceWebGL: true — required for TSL / NodeMaterial consumers. Hardware path stays WebGL2, so browser support is unchanged.

A future 'node-webgpu' value is reserved for 0.5.x once adapter-request timing + WebGPU detection bootstrap are handled in the provider.

The WebGPU bundle (three/webgpu) is dynamically imported inside the gl factory, so consumers on 'classic' pay no bundle cost. Inline experiences (WebglInlineBlock) bring their own <Canvas> and pick their own renderer — this change only affects the shared background canvas.

Rationale: consumer-side TSL migrations (e.g. a consumer's node-aware rendering work) were blocked because THREE.WebGLRenderer has no node-aware path. Three's only node-aware renderer is WebGPURenderer, which transparently runs on either WebGPU or WebGL2 backends.

Shipping this opt-in unblocks consumer TSL work without forcing the change on consumers that aren't ready.

Pure FBO (0.2.0) cross-blends two static scene images. The hybrid model also lets each background scene choreograph its OWN entrance/exit _while_ it is being composited.

During a transition the TransitionCompositor now publishes the live eased progress plus each scene's role ('from' outgoing / 'to' incoming) through a React context; a scene reads it via useTransitionPhase() inside useFrame (a ref, never a render value — no per-frame React re-render) and animates its objects, while the transition shader blends the two animating images.

• New export useTransitionPhase() returning { role: 'from' | 'to' | null, progress: MutableRefObject<number> }. At rest: { role: null, progress.current === 1 }.
• New exported types TransitionPhase, TransitionRole.
• Backward-compatible: a scene that ignores the hook renders static (pure-FBO behavior, unchanged from 0.2.0). The BackgroundExperienceProps.transitionProgress prop stays the coarse signal; the hook is the live channel.

The choreography itself is consumer-owned (per-scene entrance/exit + which transitions per route are author decisions); the platform supplies the channel.

Also in this release:

• Per-scene camera in the FBO compositor — background experiences mount their own camera (e.g. drei <PerspectiveCamera makeDefault>); the compositor now renders each sub-scene to its target with ITS OWN camera (falls back to the main camera), so a scene's intended framing is preserved during a transition.
• Interactivity mode (mixed-by-route) — new interactive flag + setInteractive() on the canvas context, a useCanvasInteractive() hook, and the background canvas now toggles pointer-events accordingly. A consumer's route director can make the global canvas interactive on showcase routes (controls + pointer events) and a passive backdrop elsewhere. Default false (passive) — unchanged from prior behavior.

What changed (see spec amendment A1, 2026-05-25):

• `registerTransition` now writes to a module-level registry that the compositor resolves against (was a no-op void definition). Built-ins seed it; consumer registrations and per-controller transitions config merge over them.
• `createTransitionController` is real: trigger(toKey, name?) routes a scene change through the mounted provider's FBO compositor and resolves when the transition completes (or is skipped — first scene / reduced motion / no canvas mounted). list() returns built-in ∪ registered ∪ config.
• `TransitionCompositor` (new, internal to the runtime) renders the outgoing and incoming background scenes to two render targets via createPortal, then composites them with the active transition's fragment shader (uFrom/uTo/uProgress) on a clip-space full-screen quad. It mounts only during the transition window; steady state renders the single active scene directly, so the dual-render cost is bounded.
• `transitionProgress` is frame-driven: the smooth 0→1 value lives in a ref advanced in useFrame and written straight to the shader uniform (no per-frame React re-render). The BackgroundExperienceProps.transitionProgress prop contract is preserved but coarse (0 at start, 1 at completion).
• `singleLiveCanvas` is now enforced (was stored-never-read): the background canvas pauses (frameloop='never') when the document is hidden or no scene is active, and a new claimLiveCanvas/releaseLiveCanvas API on the provider lets an in-view inline canvas pause the background. WebglInlineBlock claims it automatically when mounted under a provider (graceful no-op without one).
• Reduced motion: when respectReducedMotion is on and the user prefers reduced motion, transitions are skipped (the new scene swaps in directly).
• New export: useOptionalWebglCanvasContext (non-throwing context read). New provider prop: transition?: { enabled?, default?, durationMs? }.

Admin-configurable transitions (per-page + per-route, editor-controlled):

• `createTransitionField(opts?)` (@wabbit/tome-webgl/block, React-free) — a Payload select field pre-populated with the built-in transition names (+ any extra custom names), with an Auto option. Registry-injection pattern like experienceKey. Drop it on a Page collection (per-page override) or inside a global route-map array.
• `resolveTransition({ pageTransition, routeMap, toPath, directional, fallback })` + `matchRouteTransition` (@wabbit/tome-webgl/transitions, pure) — resolve a transition with precedence per-page override → global route map → directional default → fallback ('auto'/null = unset; route map supports exact + prefix/* longest-wildcard match). The directional default is consumer-supplied (sibling order / route depth is consumer route data), keeping the layer generic.
• New React-free constants BUILT_IN_TRANSITION_NAMES / AUTO_TRANSITION (@wabbit/tome-webgl/transitions).

Non-breaking: the v0 inline-block + background contract is unchanged; setActiveBackground(key) keeps its signature (now optionally animates). The FBO composite's visual correctness is gated at the proving consumer (a consumer site + Playwright), per amendment A1 — WebGL cannot render in node, so the in-package gate covers the pure logic (registry, controller, easing, progress math).