@vgai/engine 0.2.0 → 0.3.0

package/dist/setup/setup-renderer.js

@@ -0,0 +1,363 @@
+import { N8AOPostPass } from 'n8ao';
+import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectComposer, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
+import { MotionBlurEffect, SSGIEffect, SSREffect, VelocityDepthNormalPass } from 'realism-effects';
+import * as THREE from 'three';
+import { resolveRenderSettings } from '../render/render-settings';
+import { DEFAULTS } from '../scene/defaults';
+/**
+ * Apply the live renderer-level render settings (shadows, resolution scale) from
+ * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
+ * and are handled at construction, not here. Pass the scene `rendering` scope
+ * (e.g. `env.rendering`); absent values fall back to the registry defaults so
+ * behavior is unchanged when a scene omits `rendering`.
+ *
+ * `basePixelRatio` is the call-site's native pixel-ratio policy (the runtime caps
+ * at 2; the editor uses the raw devicePixelRatio); `resolutionScale` multiplies it.
+ */
+export function applyRendererSettings(renderer, rendering, basePixelRatio = Math.min(window.devicePixelRatio, 2)) {
+    const settings = resolveRenderSettings(rendering);
+    renderer.shadowMap.enabled = Boolean(settings['shadows']);
+    const scale = Number(settings['resolutionScale']) || 1;
+    renderer.setPixelRatio(basePixelRatio * scale);
+}
+/**
+ * Create ONLY the WebGL renderer. The HOST owns the renderer (see
+ * `HostContext.renderer`); the game/adapter owns the scene/camera/composer it
+ * renders into. Split out of `setupRenderer` for the adapter inversion.
+ *
+ * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
+ * reload-only `antialias` option at construction and the live shadow/resolution
+ * settings (via {@link applyRendererSettings}). Absent → registry defaults.
+ *
+ * `opts` is additive (T6.1 slice 1, COMPOSITION-DESIGN.md D5 §1/§4): omitted
+ * entirely, construction is byte-identical to before (no `alpha`/
+ * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
+ * passes it. The worlds path passes `alpha:true` for every stacked canvas
+ * above the bottom one (so its clear-alpha-0 shows the layer below through
+ * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
+ * recorded capture-tier cost, paid once here rather than re-derived later).
+ */
+export function createHostRenderer(canvas, width = window.innerWidth, height = window.innerHeight, rendering, opts) {
+    // A newly-shown editor tab can report 0x0 for one layout frame. WebGL render
+    // targets cannot have zero-sized attachments, so boot at the smallest valid
+    // backing size and let the normal resize path apply the real dimensions.
+    const safeWidth = Math.max(1, width);
+    const safeHeight = Math.max(1, height);
+    const settings = resolveRenderSettings(rendering);
+    const renderer = new THREE.WebGLRenderer({
+        canvas,
+        antialias: Boolean(settings['antialias']),
+        powerPreference: 'high-performance',
+        ...(opts?.alpha ? { alpha: true } : {}),
+        ...(opts?.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
+    });
+    renderer.setSize(safeWidth, safeHeight);
+    applyRendererSettings(renderer, rendering);
+    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    renderer.toneMapping = toneMappingModes[DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = DEFAULTS.toneMapping.exposure;
+    return renderer;
+}
+/**
+ * Create the scene, camera, and postprocessing composer that a first-party game
+ * renders into, given a host-provided renderer. The GPU-only `composer` is
+ * created here; a headless host (no GPU) skips this entirely.
+ */
+export function createSceneView(renderer, width = window.innerWidth, height = window.innerHeight) {
+    const safeWidth = Math.max(1, width);
+    const safeHeight = Math.max(1, height);
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x1a1a2e);
+    const camera = new THREE.PerspectiveCamera(DEFAULTS.camera.fov, safeWidth / safeHeight, DEFAULTS.camera.near, DEFAULTS.camera.far);
+    camera.position.set(0, 5, 10);
+    camera.lookAt(0, 0, 0);
+    const composer = new EffectComposer(renderer);
+    composer.addPass(new RenderPass(scene, camera));
+    composer.addPass(new EffectPass(camera, new BloomEffect({ luminanceThreshold: DEFAULTS.postProcessing.bloom.luminanceThreshold })));
+    return { scene, camera, composer };
+}
+/**
+ * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
+ *
+ * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
+ * combination of {@link createHostRenderer} + {@link createSceneView}.)
+ */
+export function setupRenderer(canvas, width = window.innerWidth, height = window.innerHeight) {
+    const renderer = createHostRenderer(canvas, width, height);
+    const { scene, camera, composer } = createSceneView(renderer, width, height);
+    return { renderer, scene, camera, composer };
+}
+const toneMappingModes = {
+    none: THREE.NoToneMapping,
+    linear: THREE.LinearToneMapping,
+    reinhard: THREE.ReinhardToneMapping,
+    cineon: THREE.CineonToneMapping,
+    aces: THREE.ACESFilmicToneMapping,
+    agx: THREE.AgXToneMapping,
+};
+const smaaPresets = {
+    low: SMAAPreset.LOW,
+    medium: SMAAPreset.MEDIUM,
+    high: SMAAPreset.HIGH,
+    ultra: SMAAPreset.ULTRA,
+};
+/**
+ * Rebuild composer passes from scene environment settings.
+ * Scenes without toneMapping default to ACES (the runtime default).
+ * Code can further modify the composer after this call.
+ *
+ * Pass objectMap to enable entity-referencing effects (godRays, outline).
+ * Pass entities to resolve tag-based references (outline).
+ */
+export function applyScenePostProcessing(composer, renderer, scene, camera, env, objectMap, entityTags) {
+    // Dispose the existing passes before discarding them — removeAllPasses() just
+    // drops the references, so their GPU render targets would otherwise leak on
+    // every env edit / scene switch.
+    for (const pass of composer.passes) {
+        pass.dispose?.();
+    }
+    composer.removeAllPasses();
+    composer.addPass(new RenderPass(scene, camera));
+    // ── Tone mapping ──────────────────────────────────────────────────────
+    const tm = env?.toneMapping;
+    renderer.toneMapping =
+        toneMappingModes[tm?.mode ?? DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = tm?.exposure ?? DEFAULTS.toneMapping.exposure;
+    // ── Master switch ─────────────────────────────────────────────────────
+    // When post-processing is disabled at the scene/engine level, render the
+    // plain scene (the RenderPass added above) and skip every effect pass. The
+    // per-effect `enabled` flags below still apply when the master switch is on.
+    if (!resolveRenderSettings(env?.rendering)['postProcessing'])
+        return;
+    const pp = env?.postProcessing;
+    const d = DEFAULTS.postProcessing;
+    // ── Prerequisite passes ───────────────────────────────────────────────
+    // NormalPass — needed by SSAO
+    let normalPass;
+    if (pp?.ssao?.enabled) {
+        normalPass = new NormalPass(scene, camera);
+        composer.addPass(normalPass);
+    }
+    // VelocityDepthNormalPass — needed by SSR, SSGI, MotionBlur
+    let velocityPass;
+    if (pp?.ssr?.enabled || pp?.ssgi?.enabled || pp?.motionBlur?.enabled) {
+        velocityPass = new VelocityDepthNormalPass(scene, camera);
+        composer.addPass(velocityPass);
+    }
+    // N8AOPostPass — separate Pass, not an Effect
+    if (pp?.n8ao?.enabled) {
+        const n8aoPass = new N8AOPostPass(scene, camera);
+        const cfg = n8aoPass.configuration;
+        cfg.aoSamples = pp.n8ao.aoSamples ?? d.n8ao.aoSamples;
+        cfg.aoRadius = pp.n8ao.aoRadius ?? d.n8ao.aoRadius;
+        cfg.intensity = pp.n8ao.intensity ?? d.n8ao.intensity;
+        cfg.denoiseSamples = pp.n8ao.denoiseSamples ?? d.n8ao.denoiseSamples;
+        cfg.denoiseRadius = pp.n8ao.denoiseRadius ?? d.n8ao.denoiseRadius;
+        cfg.distanceFalloff = pp.n8ao.distanceFalloff ?? d.n8ao.distanceFalloff;
+        if (pp.n8ao.screenSpaceRadius !== undefined)
+            cfg.screenSpaceRadius = pp.n8ao.screenSpaceRadius;
+        if (pp.n8ao.halfRes !== undefined)
+            cfg.halfRes = pp.n8ao.halfRes;
+        if (pp.n8ao.color)
+            cfg.color = new THREE.Color(pp.n8ao.color);
+        composer.addPass(n8aoPass);
+    }
+    // ── Collect Effect instances ──────────────────────────────────────────
+    const effects = [];
+    // Anti-aliasing
+    if (pp?.smaa?.enabled) {
+        const preset = smaaPresets[pp.smaa.preset ?? d.smaa.preset] ?? SMAAPreset.HIGH;
+        effects.push(new SMAAEffect({ preset }));
+    }
+    // Ambient occlusion
+    if (pp?.ssao?.enabled && normalPass) {
+        effects.push(new SSAOEffect(camera, normalPass.texture, {
+            radius: pp.ssao.radius ?? d.ssao.radius,
+            intensity: pp.ssao.intensity ?? d.ssao.intensity,
+            bias: pp.ssao.bias ?? d.ssao.bias,
+            samples: pp.ssao.samples ?? d.ssao.samples,
+            rings: pp.ssao.rings ?? d.ssao.rings,
+            fade: pp.ssao.fade ?? d.ssao.fade,
+            ...(pp.ssao.color ? { color: new THREE.Color(pp.ssao.color) } : {}),
+        }));
+    }
+    // SSR (realism-effects)
+    if (pp?.ssr?.enabled && velocityPass) {
+        effects.push(new SSREffect(scene, camera, velocityPass, {
+            intensity: pp.ssr.intensity ?? d.ssr.intensity,
+            exponent: pp.ssr.exponent ?? d.ssr.exponent,
+            distance: pp.ssr.distance ?? d.ssr.distance,
+            thickness: pp.ssr.thickness ?? d.ssr.thickness,
+            maxRoughness: pp.ssr.maxRoughness ?? d.ssr.maxRoughness,
+        }));
+    }
+    // SSGI (realism-effects)
+    if (pp?.ssgi?.enabled && velocityPass) {
+        effects.push(new SSGIEffect(scene, camera, velocityPass, {
+            intensity: pp.ssgi.intensity ?? d.ssgi.intensity,
+            distance: pp.ssgi.distance ?? d.ssgi.distance,
+            thickness: pp.ssgi.thickness ?? d.ssgi.thickness,
+            maxRoughness: pp.ssgi.maxRoughness ?? d.ssgi.maxRoughness,
+        }));
+    }
+    // Motion blur (realism-effects)
+    if (pp?.motionBlur?.enabled && velocityPass) {
+        effects.push(new MotionBlurEffect(velocityPass, {
+            intensity: pp.motionBlur.intensity ?? d.motionBlur.intensity,
+            jitter: pp.motionBlur.jitter ?? d.motionBlur.jitter,
+            samples: pp.motionBlur.samples ?? d.motionBlur.samples,
+        }));
+    }
+    // Bloom
+    if (pp?.bloom?.enabled) {
+        effects.push(new BloomEffect({
+            intensity: pp.bloom.intensity ?? d.bloom.intensity,
+            luminanceThreshold: pp.bloom.luminanceThreshold ?? d.bloom.luminanceThreshold,
+            luminanceSmoothing: pp.bloom.luminanceSmoothing ?? d.bloom.luminanceSmoothing,
+        }));
+    }
+    // Depth of field
+    if (pp?.depthOfField?.enabled) {
+        effects.push(new DepthOfFieldEffect(camera, {
+            worldFocusDistance: pp.depthOfField.worldFocusDistance ?? d.depthOfField.worldFocusDistance,
+            worldFocusRange: pp.depthOfField.worldFocusRange ?? d.depthOfField.worldFocusRange,
+            bokehScale: pp.depthOfField.bokehScale ?? d.depthOfField.bokehScale,
+            focalLength: pp.depthOfField.focalLength ?? d.depthOfField.focalLength,
+        }));
+    }
+    // Tilt shift
+    if (pp?.tiltShift?.enabled) {
+        effects.push(new TiltShiftEffect({
+            offset: pp.tiltShift.offset ?? d.tiltShift.offset,
+            rotation: pp.tiltShift.rotation ?? d.tiltShift.rotation,
+            focusArea: pp.tiltShift.focusArea ?? d.tiltShift.focusArea,
+            feather: pp.tiltShift.feather ?? d.tiltShift.feather,
+        }));
+    }
+    // God rays (needs entity reference)
+    if (pp?.godRays?.enabled && pp.godRays.sourceEntity && objectMap) {
+        const lightObj = objectMap.get(pp.godRays.sourceEntity);
+        if (lightObj instanceof THREE.Mesh || lightObj instanceof THREE.Points) {
+            effects.push(new GodRaysEffect(camera, lightObj, {
+                density: pp.godRays.density ?? d.godRays.density,
+                decay: pp.godRays.decay ?? d.godRays.decay,
+                weight: pp.godRays.weight ?? d.godRays.weight,
+                exposure: pp.godRays.exposure ?? d.godRays.exposure,
+                samples: pp.godRays.samples ?? d.godRays.samples,
+            }));
+        }
+    }
+    // Outline (needs entity tag references)
+    if (pp?.outline?.enabled && objectMap) {
+        const outlineEffect = new OutlineEffect(scene, camera, {
+            edgeStrength: pp.outline.edgeStrength ?? d.outline.edgeStrength,
+            pulseSpeed: pp.outline.pulseSpeed ?? d.outline.pulseSpeed,
+            visibleEdgeColor: pp.outline.visibleEdgeColor
+                ? new THREE.Color(pp.outline.visibleEdgeColor).getHex()
+                : new THREE.Color(d.outline.visibleEdgeColor).getHex(),
+            hiddenEdgeColor: pp.outline.hiddenEdgeColor
+                ? new THREE.Color(pp.outline.hiddenEdgeColor).getHex()
+                : new THREE.Color(d.outline.hiddenEdgeColor).getHex(),
+            xRay: pp.outline.xRay ?? false,
+        });
+        // Add entities matching tags to selection
+        const tags = pp.outline.tags ?? [];
+        if (tags.length > 0 && entityTags) {
+            for (const [entityId, eTags] of entityTags) {
+                if (tags.some((t) => eTags.includes(t))) {
+                    const obj = objectMap.get(entityId);
+                    if (obj)
+                        outlineEffect.selection.add(obj);
+                }
+            }
+        }
+        effects.push(outlineEffect);
+    }
+    // Chromatic aberration
+    if (pp?.chromaticAberration?.enabled) {
+        effects.push(new ChromaticAberrationEffect({
+            offset: new THREE.Vector2(pp.chromaticAberration.offsetX ?? d.chromaticAberration.offsetX, pp.chromaticAberration.offsetY ?? d.chromaticAberration.offsetY),
+            radialModulation: pp.chromaticAberration.radialModulation ?? false,
+            modulationOffset: pp.chromaticAberration.modulationOffset ?? d.chromaticAberration.modulationOffset,
+        }));
+    }
+    // Lens distortion
+    if (pp?.lensDistortion?.enabled) {
+        effects.push(new LensDistortionEffect({
+            distortion: new THREE.Vector2(pp.lensDistortion.distortionX ?? d.lensDistortion.distortionX, pp.lensDistortion.distortionY ?? d.lensDistortion.distortionY),
+            principalPoint: new THREE.Vector2(0, 0),
+            focalLength: new THREE.Vector2(pp.lensDistortion.focalLengthX ?? d.lensDistortion.focalLengthX, pp.lensDistortion.focalLengthY ?? d.lensDistortion.focalLengthY),
+            skew: pp.lensDistortion.skew ?? d.lensDistortion.skew,
+        }));
+    }
+    // Shock wave
+    if (pp?.shockWave?.enabled) {
+        effects.push(new ShockWaveEffect(camera, new THREE.Vector3(pp.shockWave.positionX ?? 0, pp.shockWave.positionY ?? 0, pp.shockWave.positionZ ?? 0), {
+            speed: pp.shockWave.speed ?? d.shockWave.speed,
+            maxRadius: pp.shockWave.maxRadius ?? d.shockWave.maxRadius,
+            waveSize: pp.shockWave.waveSize ?? d.shockWave.waveSize,
+            amplitude: pp.shockWave.amplitude ?? d.shockWave.amplitude,
+        }));
+    }
+    // Color adjustments
+    if (pp?.brightnessContrast?.enabled) {
+        effects.push(new BrightnessContrastEffect({
+            brightness: pp.brightnessContrast.brightness ?? d.brightnessContrast.brightness,
+            contrast: pp.brightnessContrast.contrast ?? d.brightnessContrast.contrast,
+        }));
+    }
+    if (pp?.hueSaturation?.enabled) {
+        effects.push(new HueSaturationEffect({
+            hue: pp.hueSaturation.hue ?? d.hueSaturation.hue,
+            saturation: pp.hueSaturation.saturation ?? d.hueSaturation.saturation,
+        }));
+    }
+    if (pp?.sepia?.enabled) {
+        effects.push(new SepiaEffect({ intensity: pp.sepia.intensity ?? d.sepia.intensity }));
+    }
+    if (pp?.colorDepth?.enabled) {
+        effects.push(new ColorDepthEffect({ bits: pp.colorDepth.bits ?? d.colorDepth.bits }));
+    }
+    // Film / retro
+    if (pp?.noise?.enabled) {
+        effects.push(new NoiseEffect({ premultiply: pp.noise.premultiply ?? d.noise.premultiply }));
+    }
+    if (pp?.scanline?.enabled) {
+        effects.push(new ScanlineEffect({ density: pp.scanline.density ?? d.scanline.density }));
+    }
+    if (pp?.dotScreen?.enabled) {
+        effects.push(new DotScreenEffect({
+            angle: pp.dotScreen.angle ?? d.dotScreen.angle,
+            scale: pp.dotScreen.scale ?? d.dotScreen.scale,
+        }));
+    }
+    if (pp?.grid?.enabled) {
+        effects.push(new GridEffect({
+            scale: pp.grid.scale ?? d.grid.scale,
+            lineWidth: pp.grid.lineWidth ?? d.grid.lineWidth,
+        }));
+    }
+    if (pp?.pixelation?.enabled) {
+        effects.push(new PixelationEffect(pp.pixelation.granularity ?? d.pixelation.granularity));
+    }
+    if (pp?.glitch?.enabled) {
+        effects.push(new GlitchEffect({
+            delay: new THREE.Vector2(pp.glitch.delayX ?? d.glitch.delayX, pp.glitch.delayY ?? d.glitch.delayY),
+            duration: new THREE.Vector2(pp.glitch.durationX ?? d.glitch.durationX, pp.glitch.durationY ?? d.glitch.durationY),
+            strength: new THREE.Vector2(pp.glitch.strengthX ?? d.glitch.strengthX, pp.glitch.strengthY ?? d.glitch.strengthY),
+            columns: pp.glitch.columns ?? d.glitch.columns,
+            ratio: pp.glitch.ratio ?? d.glitch.ratio,
+        }));
+    }
+    // Vignette (last color effect)
+    if (pp?.vignette?.enabled) {
+        effects.push(new VignetteEffect({
+            darkness: pp.vignette.darkness ?? d.vignette.darkness,
+            offset: pp.vignette.offset ?? d.vignette.offset,
+        }));
+    }
+    // ── Merge all effects into a single EffectPass ────────────────────────
+    if (effects.length > 0) {
+        composer.addPass(new EffectPass(camera, ...effects));
+    }
+}

package/dist/tools/define-tool.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Project tools — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3 contract).
+ *
+ * A project tool is ONE file, `src/tools/<name>.tool.tsx`, discovered by
+ * folder scan (same physics as data assets, §3.1: zero registration, delete
+ * the file → gone). The file exports exactly two things:
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'tuning',          // stable slug — becomes the tab's test id
+ *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
+ *   placement: 'dock',     // project-global dashboard tab (§3.2)
+ * });
+ * export default function Tuning() { … }   // plain React
+ * ```
+ *
+ * or, selection-scoped (W3 — §3.2's second placement):
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'spin',
+ *   title: 'Spin',
+ *   placement: 'inspector',                  // selection-scoped section
+ *   match: (node) => node?.kind === 'mesh',  // same contract as the
+ * });                                        // inspector-section registry
+ * export default function Spin({ node }: InspectorToolProps) { … }
+ * ```
+ *
+ * The editor renders dock tools as visually distinct tabs after a separator
+ * at the end of the bottom dock's tab row (§3.5); inspector tools render as
+ * a ⚙-marked section in the Inspector rail whenever `match` accepts the
+ * current selection. Both render inside an error boundary — a crashing tool
+ * never takes the editor down. Tools are EDITOR-ONLY: no game build bundles
+ * `src/tools/` (§4 — nothing in game code imports it), so dev/cheat surfaces
+ * can never leak into a tester serve.
+ *
+ * This module is deliberately react-free metadata (the engine core outside
+ * `src/react/` must not import react — `test/react-core-import-ban.test.ts`);
+ * the react-facing tool hooks live in `@engine/react/use-data`, and the
+ * editor-styled widget kit tools build panels from is `@editor/widgets`.
+ */
+import type { AuthoringAdapter, EditorNode } from '../adapter';
+/** The two placements (§3.2). Deliberately nothing else — no floating
+ *  windows, no in-game overlay host (§3.2 "deliberately NOT built"). */
+export type ToolPlacement = 'dock' | 'inspector';
+/** Fields every tool declares — see {@link defineTool} for the contract. */
+interface ToolConfigBase {
+    /**
+     * Stable slug for this tool: letters/digits/`-`/`_` only. It becomes the
+     * mount's `data-testid` (`bottom-tab-tool-<id>` for dock tools,
+     * `inspector-tool-<id>` for inspector tools), so keep it short and never
+     * rename it casually — automation and saved layouts key off it.
+     */
+    id: string;
+    /** Human label: the dock tab text, or the inspector section's header,
+     *  rendered after the ⚙ project-tool marker (§3.5). */
+    title: string;
+}
+/** A project-global dashboard tab in the bottom dock (§3.2, W4). */
+export interface DockToolConfig extends ToolConfigBase {
+    placement: 'dock';
+}
+/** A selection-scoped Inspector section (§3.2, W3). */
+export interface InspectorToolConfig extends ToolConfigBase {
+    placement: 'inspector';
+    /**
+     * When this section appears — the SAME contract as the editor's
+     * `inspector-section-registry`: called with the currently selected node
+     * (`null` in the no-selection/environment state) and the active authoring
+     * adapter; return `true` to render. Keep it cheap and pure — it runs on
+     * every inspector render. A `match` that throws is treated as `false`
+     * (with one console teaching error), never crashing the inspector.
+     */
+    match: (node: EditorNode | null, adapter: AuthoringAdapter) => boolean;
+}
+/** Metadata for a project tool — a discriminated union on `placement`. */
+export type ToolConfig = DockToolConfig | InspectorToolConfig;
+/**
+ * Props the editor passes to an INSPECTOR tool's default-exported component
+ * (dock tools receive no props). Everything richer (live game store, field
+ * addresses) arrives through the §3.3 hooks, not through more props.
+ */
+export interface InspectorToolProps {
+    /** The selected node your `match` accepted (`null` in the no-selection
+     *  state, if your `match` chose to accept it). */
+    node: EditorNode | null;
+    /** The selected node's stable id (`null` in the no-selection state). */
+    nodeId: string | null;
+}
+/**
+ * Validate and freeze a project tool's metadata (docs/DATA-TOOLS-DESIGN.md
+ * §3.1). Call it once at module scope of a `src/tools/<name>.tool.tsx` file
+ * and export the result as `tool`, next to a default-exported React
+ * component — the editor's folder scan picks the file up automatically.
+ *
+ * Fails loud (§6.5 "errors teach") on anything malformed rather than letting
+ * a half-shaped tool render confusingly: bad `id`/`title`, an unknown
+ * placement, an inspector tool without a callable `match`.
+ *
+ * The returned config is frozen: tool metadata is a definition, not state
+ * (the same immutability rule data assets follow, §2.1).
+ */
+export declare function defineTool(config: ToolConfig): Readonly<ToolConfig>;
+export {};
+//# sourceMappingURL=define-tool.d.ts.map

package/dist/tools/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../src/tools/define-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE/D;wEACwE;AACxE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC;AAEjD,4EAA4E;AAC5E,UAAU,cAAc;IACtB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;2DACuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAe,SAAQ,cAAc;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,SAAS,EAAE,WAAW,CAAC;IACvB;;;;;;;OAOG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;CACxE;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,mBAAmB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;sDACkD;IAClD,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAUD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC,UAAU,CAAC,CAiCnE"}

package/dist/tools/define-tool.js

@@ -0,0 +1,82 @@
+/**
+ * Project tools — W4/W3 of `docs/DATA-TOOLS-DESIGN.md` (§3 contract).
+ *
+ * A project tool is ONE file, `src/tools/<name>.tool.tsx`, discovered by
+ * folder scan (same physics as data assets, §3.1: zero registration, delete
+ * the file → gone). The file exports exactly two things:
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'tuning',          // stable slug — becomes the tab's test id
+ *   title: 'Tuning',       // the tab label (rendered after a ⚙ marker)
+ *   placement: 'dock',     // project-global dashboard tab (§3.2)
+ * });
+ * export default function Tuning() { … }   // plain React
+ * ```
+ *
+ * or, selection-scoped (W3 — §3.2's second placement):
+ *
+ * ```tsx
+ * export const tool = defineTool({
+ *   id: 'spin',
+ *   title: 'Spin',
+ *   placement: 'inspector',                  // selection-scoped section
+ *   match: (node) => node?.kind === 'mesh',  // same contract as the
+ * });                                        // inspector-section registry
+ * export default function Spin({ node }: InspectorToolProps) { … }
+ * ```
+ *
+ * The editor renders dock tools as visually distinct tabs after a separator
+ * at the end of the bottom dock's tab row (§3.5); inspector tools render as
+ * a ⚙-marked section in the Inspector rail whenever `match` accepts the
+ * current selection. Both render inside an error boundary — a crashing tool
+ * never takes the editor down. Tools are EDITOR-ONLY: no game build bundles
+ * `src/tools/` (§4 — nothing in game code imports it), so dev/cheat surfaces
+ * can never leak into a tester serve.
+ *
+ * This module is deliberately react-free metadata (the engine core outside
+ * `src/react/` must not import react — `test/react-core-import-ban.test.ts`);
+ * the react-facing tool hooks live in `@engine/react/use-data`, and the
+ * editor-styled widget kit tools build panels from is `@editor/widgets`.
+ */
+const TEMPLATE_EXAMPLE = 'the template worked example: src/tools/example.tool.tsx';
+/** Teaching-error helper (§6.5): every rejection names the fix and cites the
+ *  template example by path. */
+function toolError(problem, fix) {
+    return new Error(`defineTool: ${problem} — ${fix} (see ${TEMPLATE_EXAMPLE}).`);
+}
+/**
+ * Validate and freeze a project tool's metadata (docs/DATA-TOOLS-DESIGN.md
+ * §3.1). Call it once at module scope of a `src/tools/<name>.tool.tsx` file
+ * and export the result as `tool`, next to a default-exported React
+ * component — the editor's folder scan picks the file up automatically.
+ *
+ * Fails loud (§6.5 "errors teach") on anything malformed rather than letting
+ * a half-shaped tool render confusingly: bad `id`/`title`, an unknown
+ * placement, an inspector tool without a callable `match`.
+ *
+ * The returned config is frozen: tool metadata is a definition, not state
+ * (the same immutability rule data assets follow, §2.1).
+ */
+export function defineTool(config) {
+    if (config === null || typeof config !== 'object') {
+        throw toolError('expected a config object', "call it as defineTool({ id, title, placement: 'dock' })");
+    }
+    const { id, title, placement } = config;
+    if (placement !== 'dock' && placement !== 'inspector') {
+        throw toolError(`unknown placement ${JSON.stringify(placement)}`, "the placements are 'dock' (project-global bottom tab) and 'inspector' (selection-scoped section, §3.2)");
+    }
+    if (typeof id !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(id)) {
+        throw toolError(`invalid id ${JSON.stringify(id)}`, 'pass a non-empty slug of letters, digits, "-" or "_" — it becomes the tool\'s data-testid (bottom-tab-tool-<id> / inspector-tool-<id>)');
+    }
+    if (typeof title !== 'string' || title.trim() === '') {
+        throw toolError(`invalid title ${JSON.stringify(title)}`, 'pass a short human-readable label');
+    }
+    if (placement === 'inspector') {
+        if (typeof config.match !== 'function') {
+            throw toolError(`placement 'inspector' requires a match function (got ${JSON.stringify(config.match)})`, "pass match: (node) => boolean — e.g. match: (node) => node?.kind === 'mesh' — deciding which selections show this section");
+        }
+        return Object.freeze({ id, title, placement, match: config.match });
+    }
+    return Object.freeze({ id, title, placement });
+}

package/dist/world2d/authoring-2d.d.ts

@@ -0,0 +1,76 @@
+import type { Container } from 'pixi.js';
+/**
+ * AuthoringAdapter-2D — the world2d analog of the editor AuthoringAdapter /
+ * IngestAuthoringAdapter, implemented DIRECTLY over a live PixiJS display tree
+ * (no fabricated Scene2D / SceneEntity — the anti-shim rule). Used by the editor to
+ * inspect + edit world2d entities (first-party OR an ingested unmodified game),
+ * with stable structural-path ids so edits re-bind after the tree rebuilds.
+ */
+export interface EditorNode2D {
+    id: string;
+    label: string;
+    kind: 'sprite' | 'animatedsprite' | 'text' | 'container' | string;
+    parentId: string | null;
+    childIds: string[];
+}
+export interface Transform2DValue {
+    position: [number, number];
+    rotation: number;
+    scale: [number, number];
+}
+export interface Property2D {
+    path: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'vec2' | 'color';
+    value: unknown;
+}
+/** A persisted edit overlay keyed by structural-path id (the 2D analog of IngestOverlay). */
+export interface Override2D {
+    position?: [number, number];
+    rotation?: number;
+    scale?: [number, number];
+    tint?: number;
+    visible?: boolean;
+}
+export type Overlay2D = Record<string, Override2D>;
+export declare class AuthoringAdapter2D {
+    private readonly root;
+    private readonly byId;
+    private overlay;
+    private dirty;
+    constructor(root: Container, opts?: {
+        overlay?: Overlay2D;
+    });
+    /** Walk the live tree assigning deterministic structural-path ids, reapply overlay. */
+    refresh(): {
+        count: number;
+        sprites: number;
+    };
+    roots(): EditorNode2D[];
+    node(id: string): EditorNode2D | null;
+    displayObject(id: string): Container | null;
+    private toNode;
+    getTransform(id: string): Transform2DValue | null;
+    setTransform(id: string, t: Partial<Transform2DValue>): void;
+    properties(id: string): Property2D[];
+    set(id: string, path: string, value: unknown): void;
+    private applyOverride;
+    /**
+     * Re-apply a saved/external overlay onto the (already-walked) live tree, merging
+     * it into the in-memory overlay so a later `serializeOverlay()`/save preserves it
+     * and a later `refresh()` re-applies it again. Ids absent from the current tree
+     * are skipped (orphaned, not an error) — the 2D analog of
+     * `IngestAuthoringAdapter.applyOverlay` (T3.2 slice 3). Used both for the initial
+     * reload (constructor `opts.overlay`) and for `PersistenceProvider.applyExternal`
+     * (re-apply a changed overlay file without a full remount).
+     */
+    applyOverlay(overlay: Overlay2D): {
+        applied: number;
+        orphaned: number;
+    };
+    isDirty(): boolean;
+    serializeOverlay(): Overlay2D;
+    /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
+    markClean(): void;
+}
+//# sourceMappingURL=authoring-2d.d.ts.map

package/dist/world2d/authoring-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/authoring-2d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAClE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,6FAA6F;AAC7F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AACD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAUnD,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,KAAK,CAAS;gBAGH,IAAI,EAAE,SAAS,EAChC,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,SAAS,CAAA;KAAO;IAMpC,uFAAuF;IACvF,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAsB7C,KAAK,IAAI,YAAY,EAAE;IAIvB,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAKrC,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI3C,OAAO,CAAC,MAAM;IAYd,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAUjD,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;IAe5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,EAAE;IAkBpC,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAUnD,OAAO,CAAC,aAAa;IAUrB;;;;;;;;OAQG;IACH,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IAevE,OAAO,IAAI,OAAO;IAGlB,gBAAgB,IAAI,SAAS;IAG7B,qFAAqF;IACrF,SAAS,IAAI,IAAI;CAGlB"}