@vgai/engine 0.5.0 → 0.5.2

package/dist/setup/setup-renderer.js

@@ -1,363 +0,0 @@
-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 roots 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

@@ -1,130 +0,0 @@
-/**
- * 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: 'document', // project-global dashboard (§3.2; 'dock' = deprecated alias)
- * });
- * 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';
-/**
- * Tool placements. Since W0 of the editor workspace-shell program
- * (docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.2), placement describes MEANING,
- * not a physical container:
- *
- * - `'document'` — a substantial project-global surface (tuning dashboard,
- *   table, graph) that belongs in the center workspace;
- * - `'inspector'` — a selection-scoped section in the right Inspector rail;
- * - `'utility'` — a transient output/debug surface for the bottom drawer;
- * - `'dock'` — DEPRECATED physical compatibility alias. Existing dock tools
- *   remain in the bottom panel so projects do not lose the ability to tune
- *   them while watching the Game/Scene.
- *
- * Only an explicit `document` declaration replaces the center subject.
- * `utility` and legacy `dock` remain in the bottom drawer. Deliberately
- * still nothing else — no floating windows, no in-game overlay
- * host (docs/DATA-TOOLS-DESIGN.md §3.2 "deliberately NOT built").
- */
-export type ToolPlacement = 'document' | 'inspector' | 'utility' | 'dock';
-/** The project-global (non-selection-scoped) placements. */
-export type GlobalToolPlacement = 'document' | 'utility' | 'dock';
-/**
- * Compatibility means preserving behavior: legacy `'dock'` tools remain in
- * the bottom panel. New tools choose `'document'`, `'utility'`, or
- * `'inspector'` deliberately.
- */
-export declare function normalizeToolPlacement(placement: ToolPlacement): 'document' | 'inspector' | 'utility';
-/** 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 tool (§3.2 W4; `'dock'` preserves its historical bottom
- *  placement through the `'utility'` compatibility normalization). */
-export interface GlobalToolConfig extends ToolConfigBase {
-    placement: GlobalToolPlacement;
-}
-/** 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 = GlobalToolConfig | 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

@@ -1 +0,0 @@
-{"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;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAElE;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,aAAa,GACvB,UAAU,GAAG,WAAW,GAAG,SAAS,CAEtC;AAED,4EAA4E;AAC5E,UAAU,cAAc;IACtB;;;;;OAKG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;2DACuD;IACvD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;sEACsE;AACtE,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,SAAS,EAAE,mBAAmB,CAAC;CAChC;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,gBAAgB,GAAG,mBAAmB,CAAC;AAEhE;;;;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,CAyCnE"}

package/dist/tools/define-tool.js

@@ -1,96 +0,0 @@
-/**
- * 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: 'document', // project-global dashboard (§3.2; 'dock' = deprecated alias)
- * });
- * 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`.
- */
-/**
- * Compatibility means preserving behavior: legacy `'dock'` tools remain in
- * the bottom panel. New tools choose `'document'`, `'utility'`, or
- * `'inspector'` deliberately.
- */
-export function normalizeToolPlacement(placement) {
-    return placement === 'dock' ? 'utility' : placement;
-}
-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: 'document' })");
-    }
-    const { id, title, placement } = config;
-    if (placement !== 'document' &&
-        placement !== 'utility' &&
-        placement !== 'dock' &&
-        placement !== 'inspector') {
-        throw toolError(`unknown placement ${JSON.stringify(placement)}`, "the placements are 'document' (project-global center document), 'inspector' " +
-            "(selection-scoped section) and 'utility' (transient bottom-drawer output); " +
-            "'dock' remains accepted as a deprecated bottom-panel alias " +
-            '(docs/EDITOR-WORKSPACE-SHELL-TODO.md §7.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

@@ -1,80 +0,0 @@
-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 {
-    label?: string;
-    alpha?: number;
-    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;
-    /** Replace, rather than merge, overlay state after an exact history restore. */
-    replaceOverlay(overlay: Overlay2D): void;
-    /** Clear the dirty flag after a successful save (mirrors IngestAuthoringAdapter). */
-    markClean(): void;
-}
-//# sourceMappingURL=authoring-2d.d.ts.map