@pascal-app/core 0.8.0 → 0.9.2

package/dist/registry/registry.d.ts

@@ -0,0 +1,136 @@
+import type { AnyNodeDefinition, BakePolicy, NodeRegistry, Plugin } from './types';
+export declare const nodeRegistry: NodeRegistry & {
+    _register: (def: AnyNodeDefinition) => void;
+    _reset: () => void;
+};
+export declare function registerNode(def: AnyNodeDefinition): void;
+/** The plugin that registered a node kind, when it came through {@link loadPlugin}. */
+export declare function getNodePluginId(kind: string): string | undefined;
+/**
+ * Whether a registered kind should participate in a project. Kinds registered
+ * directly by the host and the built-in plugin are always enabled. An omitted
+ * install list means a legacy scene whose plugin state predates persistence, so
+ * loaded plugins remain visible for backward compatibility.
+ */
+export declare function isNodeKindEnabled(kind: string, installedPlugins?: readonly string[]): boolean;
+/**
+ * Returns the set of registered kinds whose definition declares the
+ * `selectable` capability. Callers that maintain hardcoded "selectable kinds"
+ * lists (SelectionManager, FloatingActionMenu) should concat this with their
+ * legacy entries instead of editing the hardcoded list per migration.
+ *
+ * Phase 6 deletes the hardcoded lists entirely and uses this function as the
+ * single source of truth. For now it's additive over the legacy lists so the
+ * existing kinds keep working unchanged.
+ */
+export declare function getSelectableKinds(): string[];
+/**
+ * Returns true when the kind is declared selectable in the registry. Use
+ * in expression chains like `if (node.type === 'wall' || isRegistrySelectable(node.type))`.
+ */
+export declare function isRegistrySelectable(kind: string): boolean;
+/**
+ * Kinds whose `def.floorplanScope` matches the requested scope. Used by
+ * `FloorplanRegistryLayer` to discover building-scoped kinds (e.g.
+ * elevator) without hardcoding kind names in the editor layer. `'level'`
+ * is the default, so `kindsWithFloorplanScope('level')` includes kinds
+ * that didn't set the field at all.
+ */
+export declare function kindsWithFloorplanScope(scope: 'level' | 'building'): string[];
+/**
+ * A kind's {@link BakePolicy} from the registry, defaulting to `'static'` for
+ * kinds that don't declare one (or aren't registered). The bake and the baked
+ * `/viewer` consult this instead of hardcoding kind names — see
+ * plans/editor-plugin-trees-example.md → Part D.
+ */
+export declare function bakePolicyOf(kind: string): BakePolicy;
+/** Registered kinds whose {@link BakePolicy} matches `policy`. `'static'` is the
+ *  default, so `kindsWithBakePolicy('static')` includes kinds that didn't set it. */
+export declare function kindsWithBakePolicy(policy: BakePolicy): string[];
+/**
+ * Returns true when the kind is movable from a 2D floor-plan handle —
+ * either via `capabilities.movable`, an explicit
+ * `def.floorplanMoveTarget`, or an `affordanceTools.move` 3D mover that
+ * the floating action menu can engage. Replaces the kind-name ternary
+ * chain in `floating-action-menu.tsx`.
+ */
+export declare function isRegistryMovable(kind: string): boolean;
+/**
+ * Whether the kind has a move tool that MOUNTS in the 3D viewport — the
+ * generic `capabilities.movable` mover or a bespoke `affordanceTools.move`.
+ * Narrower than {@link isRegistryMovable}, which also accepts floorplan-only
+ * movers (e.g. zone) that have no 3D tool. Gates 3D direct move: Ctrl/Meta-drag
+ * and the move-cross grip. Kept beside `isRegistryMovable` so the 2D and 3D
+ * movability predicates can't drift apart.
+ */
+export declare function hasRegistry3DMoveTool(kind: string): boolean;
+/**
+ * Whether the kind can be saved as a reusable preset. Default: an
+ * explicit `capabilities.presettable` boolean wins; otherwise the kind
+ * is presettable iff it declares `def.parametrics`. Read by host apps
+ * (community shell) to gate "save as preset" UI on a selection.
+ */
+export declare function isPresettable(def: AnyNodeDefinition): boolean;
+export declare function isPresettableKind(kind: string): boolean;
+/**
+ * Resolve a kind's facing-triangle config, or `null` when it has none.
+ * `{ reversed }` says whether the triangle points along the node's local -Z
+ * (its front) instead of +Z. One reader (the editor-side `<FacingPoseIndicator>`
+ * publishers) so placement and move stay consistent.
+ */
+export declare function resolveFacingIndicator(kind: string): {
+    reversed: boolean;
+} | null;
+/**
+ * Names of schema fields on `def` that are host references (`wallId`,
+ * `wallT`, etc.). Read by host apps at preset-save time to strip these
+ * from the stored payload — see `def.capabilities.hostRefFields` docs.
+ * Returns an empty array for kinds that don't declare any.
+ */
+export declare function getHostRefFields(def: AnyNodeDefinition): ReadonlyArray<string>;
+/**
+ * Whether instances of this kind are created by drawing with a build tool
+ * (tool id === node `type`) rather than dropping a finished instance. Read
+ * by host apps to route preset placement of such kinds through
+ * `setToolDefaults(type, params)` + `setTool(type)` — see
+ * `def.capabilities.drawTool` docs.
+ */
+export declare function isDrawnViaTool(def: AnyNodeDefinition): boolean;
+export declare function isDrawnViaToolKind(kind: string): boolean;
+export declare function loadPlugin(plugin: Plugin): Promise<void>;
+/**
+ * App-level plugin discovery hook. The bootstrap loads `builtinPlugin`
+ * unconditionally and then awaits this to pick up any extra plugins
+ * (third-party node packs, AI-authored bundles, user-installed kinds).
+ * Defaults to returning `[]` — apps that want external plugins call
+ * {@link setPluginDiscovery} before the bootstrap module runs.
+ *
+ * Kept async so a future loader can fetch over the network without
+ * changing the contract. See `wiki/architecture/plugin-authoring.md` for
+ * the plugin author surface this enables.
+ */
+export type PluginDiscovery = () => Promise<Plugin[]>;
+/**
+ * Replace the plugin discovery implementation. Call once at app startup
+ * before {@link discoverPlugins} is invoked (bootstrap order matters).
+ *
+ * The contract is intentionally minimal — just "return a list of
+ * plugins to load." The loader can be a static `import.meta.glob`, a
+ * `fetch` against a registry endpoint, a worker IPC, etc. Each returned
+ * plugin still goes through {@link loadPlugin} so the same API-version
+ * gate + duplicate-kind protection applies.
+ */
+export declare function setPluginDiscovery(fn: PluginDiscovery): void;
+/**
+ * Extend the current plugin discovery instead of replacing it. Useful for app-
+ * bundled example or first-party plugins that should load alongside any host-
+ * provided discovery source, not clobber it.
+ */
+export declare function extendPluginDiscovery(fn: PluginDiscovery): void;
+/**
+ * Run the active plugin discovery and return the discovered plugins.
+ * Bootstrap code is expected to call this after `loadPlugin(builtinPlugin)`
+ * and then `await loadPlugin(...)` each result in order.
+ */
+export declare function discoverPlugins(): Promise<Plugin[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAkFlF,eAAO,MAAM,YAAY,EAAE,YAAY,GAAG;IACxC,SAAS,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAA;IAC3C,MAAM,EAAE,MAAM,IAAI,CAAA;CACM,CAAA;AAE1B,wBAAgB,YAAY,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAEzD;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI7F;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAQ7C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,EAAE,CAO7E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAErD;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,EAAE,CAMhE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAK7D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAIjF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAE9D;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU9D;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;AAMrD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,CAO5D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,eAAe,GAAG,IAAI,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnD"}

package/dist/registry/registry.js

@@ -0,0 +1,282 @@
+const HOST_API_VERSION = 1;
+const BUILTIN_PLUGIN_ID = 'pascal:core';
+const pluginIdsByKind = new Map();
+// True in dev / test builds, false in production. Tries Vite's
+// `import.meta.env.DEV` first (the editor app's bundler) and falls back
+// to `process.env.NODE_ENV !== 'production'` for Node test runners.
+function isDevMode() {
+    try {
+        const meta = import.meta;
+        if (typeof meta?.env?.DEV === 'boolean')
+            return meta.env.DEV;
+    }
+    catch {
+        // import.meta unavailable in some CJS contexts — fall through.
+    }
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV) {
+        return process.env.NODE_ENV !== 'production';
+    }
+    // No environment signal — be safe and treat as production.
+    return false;
+}
+class NodeRegistryImpl {
+    defs = new Map();
+    has(kind) {
+        return this.defs.has(kind);
+    }
+    get(kind) {
+        return this.defs.get(kind);
+    }
+    entries() {
+        return this.defs.entries();
+    }
+    schemas() {
+        return Array.from(this.defs.values(), (d) => d.schema);
+    }
+    get size() {
+        return this.defs.size;
+    }
+    // Internal — exposed via registerNode below.
+    _register(def) {
+        if (typeof def.kind !== 'string' || def.kind.length === 0) {
+            throw new Error('[registry] NodeDefinition.kind must be a non-empty string');
+        }
+        if (typeof def.schemaVersion !== 'number' || def.schemaVersion < 1) {
+            throw new Error(`[registry] NodeDefinition.schemaVersion must be a positive integer (kind: "${def.kind}")`);
+        }
+        // Duplicate-kind handling depends on environment:
+        //   - **Production**: throw. The plugin-authoring contract
+        //     (`wiki/architecture/plugin-authoring.md`) guarantees that two
+        //     plugins shipping `kind: 'couch'` is a startup-time error, not
+        //     a silent overwrite — collisions need to be visible.
+        //   - **Dev (HMR)**: replace with a warning. Saving `def.ts` would
+        //     otherwise either crash on re-execute or skip it entirely,
+        //     leaving stale descriptors pinned in memory.
+        if (this.defs.has(def.kind)) {
+            if (isDevMode()) {
+                console.warn(`[registry] re-registering node kind "${def.kind}" (HMR)`);
+            }
+            else {
+                throw new Error(`[registry] duplicate node kind: "${def.kind}" already registered`);
+            }
+        }
+        this.defs.set(def.kind, def);
+    }
+    // Test-only — clears the registry. Not exported from the package barrel.
+    _reset() {
+        this.defs.clear();
+        pluginIdsByKind.clear();
+    }
+}
+export const nodeRegistry = new NodeRegistryImpl();
+export function registerNode(def) {
+    nodeRegistry._register(def);
+}
+/** The plugin that registered a node kind, when it came through {@link loadPlugin}. */
+export function getNodePluginId(kind) {
+    return pluginIdsByKind.get(kind);
+}
+/**
+ * Whether a registered kind should participate in a project. Kinds registered
+ * directly by the host and the built-in plugin are always enabled. An omitted
+ * install list means a legacy scene whose plugin state predates persistence, so
+ * loaded plugins remain visible for backward compatibility.
+ */
+export function isNodeKindEnabled(kind, installedPlugins) {
+    const pluginId = getNodePluginId(kind);
+    if (!pluginId || pluginId === BUILTIN_PLUGIN_ID || installedPlugins === undefined)
+        return true;
+    return installedPlugins.includes(pluginId);
+}
+/**
+ * Returns the set of registered kinds whose definition declares the
+ * `selectable` capability. Callers that maintain hardcoded "selectable kinds"
+ * lists (SelectionManager, FloatingActionMenu) should concat this with their
+ * legacy entries instead of editing the hardcoded list per migration.
+ *
+ * Phase 6 deletes the hardcoded lists entirely and uses this function as the
+ * single source of truth. For now it's additive over the legacy lists so the
+ * existing kinds keep working unchanged.
+ */
+export function getSelectableKinds() {
+    const result = [];
+    for (const [kind, def] of nodeRegistry.entries()) {
+        if (def.capabilities.selectable !== undefined) {
+            result.push(kind);
+        }
+    }
+    return result;
+}
+/**
+ * Returns true when the kind is declared selectable in the registry. Use
+ * in expression chains like `if (node.type === 'wall' || isRegistrySelectable(node.type))`.
+ */
+export function isRegistrySelectable(kind) {
+    return nodeRegistry.get(kind)?.capabilities.selectable !== undefined;
+}
+/**
+ * Kinds whose `def.floorplanScope` matches the requested scope. Used by
+ * `FloorplanRegistryLayer` to discover building-scoped kinds (e.g.
+ * elevator) without hardcoding kind names in the editor layer. `'level'`
+ * is the default, so `kindsWithFloorplanScope('level')` includes kinds
+ * that didn't set the field at all.
+ */
+export function kindsWithFloorplanScope(scope) {
+    const result = [];
+    for (const [kind, def] of nodeRegistry.entries()) {
+        const declared = def.floorplanScope ?? 'level';
+        if (declared === scope)
+            result.push(kind);
+    }
+    return result;
+}
+/**
+ * A kind's {@link BakePolicy} from the registry, defaulting to `'static'` for
+ * kinds that don't declare one (or aren't registered). The bake and the baked
+ * `/viewer` consult this instead of hardcoding kind names — see
+ * plans/editor-plugin-trees-example.md → Part D.
+ */
+export function bakePolicyOf(kind) {
+    return nodeRegistry.get(kind)?.bake ?? 'static';
+}
+/** Registered kinds whose {@link BakePolicy} matches `policy`. `'static'` is the
+ *  default, so `kindsWithBakePolicy('static')` includes kinds that didn't set it. */
+export function kindsWithBakePolicy(policy) {
+    const result = [];
+    for (const [kind, def] of nodeRegistry.entries()) {
+        if ((def.bake ?? 'static') === policy)
+            result.push(kind);
+    }
+    return result;
+}
+/**
+ * Returns true when the kind is movable from a 2D floor-plan handle —
+ * either via `capabilities.movable`, an explicit
+ * `def.floorplanMoveTarget`, or an `affordanceTools.move` 3D mover that
+ * the floating action menu can engage. Replaces the kind-name ternary
+ * chain in `floating-action-menu.tsx`.
+ */
+export function isRegistryMovable(kind) {
+    const def = nodeRegistry.get(kind);
+    if (!def)
+        return false;
+    if (def.capabilities.movable !== undefined)
+        return true;
+    if (def.floorplanMoveTarget !== undefined)
+        return true;
+    if (def.affordanceTools?.move !== undefined)
+        return true;
+    return false;
+}
+/**
+ * Whether the kind has a move tool that MOUNTS in the 3D viewport — the
+ * generic `capabilities.movable` mover or a bespoke `affordanceTools.move`.
+ * Narrower than {@link isRegistryMovable}, which also accepts floorplan-only
+ * movers (e.g. zone) that have no 3D tool. Gates 3D direct move: Ctrl/Meta-drag
+ * and the move-cross grip. Kept beside `isRegistryMovable` so the 2D and 3D
+ * movability predicates can't drift apart.
+ */
+export function hasRegistry3DMoveTool(kind) {
+    const def = nodeRegistry.get(kind);
+    if (!def)
+        return false;
+    return def.capabilities.movable !== undefined || def.affordanceTools?.move !== undefined;
+}
+/**
+ * Whether the kind can be saved as a reusable preset. Default: an
+ * explicit `capabilities.presettable` boolean wins; otherwise the kind
+ * is presettable iff it declares `def.parametrics`. Read by host apps
+ * (community shell) to gate "save as preset" UI on a selection.
+ */
+export function isPresettable(def) {
+    if (typeof def.capabilities.presettable === 'boolean') {
+        return def.capabilities.presettable;
+    }
+    return def.parametrics !== undefined;
+}
+export function isPresettableKind(kind) {
+    const def = nodeRegistry.get(kind);
+    return def ? isPresettable(def) : false;
+}
+/**
+ * Resolve a kind's facing-triangle config, or `null` when it has none.
+ * `{ reversed }` says whether the triangle points along the node's local -Z
+ * (its front) instead of +Z. One reader (the editor-side `<FacingPoseIndicator>`
+ * publishers) so placement and move stay consistent.
+ */
+export function resolveFacingIndicator(kind) {
+    const facing = nodeRegistry.get(kind)?.facingIndicator;
+    if (!facing)
+        return null;
+    return { reversed: facing === true ? false : (facing.reversed ?? false) };
+}
+/**
+ * Names of schema fields on `def` that are host references (`wallId`,
+ * `wallT`, etc.). Read by host apps at preset-save time to strip these
+ * from the stored payload — see `def.capabilities.hostRefFields` docs.
+ * Returns an empty array for kinds that don't declare any.
+ */
+export function getHostRefFields(def) {
+    return def.capabilities.hostRefFields ?? [];
+}
+/**
+ * Whether instances of this kind are created by drawing with a build tool
+ * (tool id === node `type`) rather than dropping a finished instance. Read
+ * by host apps to route preset placement of such kinds through
+ * `setToolDefaults(type, params)` + `setTool(type)` — see
+ * `def.capabilities.drawTool` docs.
+ */
+export function isDrawnViaTool(def) {
+    return def.capabilities.drawTool === true;
+}
+export function isDrawnViaToolKind(kind) {
+    const def = nodeRegistry.get(kind);
+    return def ? isDrawnViaTool(def) : false;
+}
+export async function loadPlugin(plugin) {
+    if (plugin.apiVersion !== HOST_API_VERSION) {
+        throw new Error(`[registry] plugin "${plugin.id}" requires apiVersion ${plugin.apiVersion}; host supports ${HOST_API_VERSION}`);
+    }
+    for (const def of plugin.nodes ?? []) {
+        registerNode(def);
+        pluginIdsByKind.set(def.kind, plugin.id);
+    }
+}
+const defaultPluginDiscovery = async () => [];
+let pluginDiscovery = defaultPluginDiscovery;
+/**
+ * Replace the plugin discovery implementation. Call once at app startup
+ * before {@link discoverPlugins} is invoked (bootstrap order matters).
+ *
+ * The contract is intentionally minimal — just "return a list of
+ * plugins to load." The loader can be a static `import.meta.glob`, a
+ * `fetch` against a registry endpoint, a worker IPC, etc. Each returned
+ * plugin still goes through {@link loadPlugin} so the same API-version
+ * gate + duplicate-kind protection applies.
+ */
+export function setPluginDiscovery(fn) {
+    if (isDevMode() && pluginDiscovery !== defaultPluginDiscovery) {
+        console.warn('[registry] setPluginDiscovery replaced an existing discovery chain — plugins registered earlier (e.g. via extendPluginDiscovery) are dropped. Use extendPluginDiscovery to compose instead.');
+    }
+    pluginDiscovery = fn;
+}
+/**
+ * Extend the current plugin discovery instead of replacing it. Useful for app-
+ * bundled example or first-party plugins that should load alongside any host-
+ * provided discovery source, not clobber it.
+ */
+export function extendPluginDiscovery(fn) {
+    const previous = pluginDiscovery;
+    pluginDiscovery = async () => {
+        const [base, extra] = await Promise.all([previous(), fn()]);
+        return [...base, ...extra];
+    };
+}
+/**
+ * Run the active plugin discovery and return the discovered plugins.
+ * Bootstrap code is expected to call this after `loadPlugin(builtinPlugin)`
+ * and then `await loadPlugin(...)` each result in order.
+ */
+export function discoverPlugins() {
+    return pluginDiscovery();
+}

package/dist/registry/registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry.test.d.ts.map

package/dist/registry/registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.test.d.ts","sourceRoot":"","sources":["../../src/registry/registry.test.ts"],"names":[],"mappings":""}

package/dist/registry/registry.test.js

@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { z } from 'zod';
+import { getHostRefFields, getNodePluginId, isDrawnViaTool, isDrawnViaToolKind, isNodeKindEnabled, isPresettable, isPresettableKind, loadPlugin, nodeRegistry, registerNode, } from './registry';
+// Re-registering a kind warns + replaces in dev (HMR) but throws in
+// production — see `registry._register`. `bun test` runs with
+// NODE_ENV=test (dev path), so the throw-path tests pin NODE_ENV to
+// 'production' for the duration of the call.
+async function inProduction(fn) {
+    const prev = process.env.NODE_ENV;
+    process.env.NODE_ENV = 'production';
+    try {
+        return await fn();
+    }
+    finally {
+        process.env.NODE_ENV = prev;
+    }
+}
+function makeDefinition(kind, overrides = {}) {
+    return {
+        kind,
+        schemaVersion: 1,
+        schema: z.object({ type: z.literal(kind) }),
+        category: 'utility',
+        defaults: () => ({}),
+        capabilities: {},
+        renderer: { kind: 'parametric', module: async () => ({ default: () => null }) },
+        ...overrides,
+    };
+}
+describe('nodeRegistry', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('starts empty', () => {
+        expect(nodeRegistry.size).toBe(0);
+        expect(nodeRegistry.has('anything')).toBe(false);
+        expect(nodeRegistry.get('anything')).toBeUndefined();
+    });
+    test('registerNode adds a definition', () => {
+        const def = makeDefinition('column');
+        registerNode(def);
+        expect(nodeRegistry.size).toBe(1);
+        expect(nodeRegistry.has('column')).toBe(true);
+        expect(nodeRegistry.get('column')).toBe(def);
+    });
+    test('registerNode throws on duplicate kind in production', async () => {
+        await inProduction(() => {
+            registerNode(makeDefinition('column'));
+            expect(() => registerNode(makeDefinition('column'))).toThrow(/duplicate node kind/);
+        });
+    });
+    test('registerNode replaces on duplicate kind in dev (HMR)', () => {
+        const first = makeDefinition('column');
+        const second = makeDefinition('column');
+        registerNode(first);
+        registerNode(second);
+        expect(nodeRegistry.size).toBe(1);
+        expect(nodeRegistry.get('column')).toBe(second);
+    });
+    test('registerNode rejects empty kind', () => {
+        expect(() => registerNode(makeDefinition(''))).toThrow(/non-empty string/);
+    });
+    test('registerNode rejects invalid schemaVersion', () => {
+        expect(() => registerNode(makeDefinition('bad', { schemaVersion: 0 }))).toThrow(/schemaVersion/);
+        expect(() => registerNode(makeDefinition('bad', { schemaVersion: -1 }))).toThrow(/schemaVersion/);
+    });
+    test('entries() iterates registered definitions', () => {
+        registerNode(makeDefinition('a'));
+        registerNode(makeDefinition('b'));
+        const kinds = Array.from(nodeRegistry.entries(), ([k]) => k);
+        expect(kinds).toEqual(['a', 'b']);
+    });
+    test('schemas() returns all registered schemas', () => {
+        const a = makeDefinition('a');
+        const b = makeDefinition('b');
+        registerNode(a);
+        registerNode(b);
+        expect(nodeRegistry.schemas()).toEqual([a.schema, b.schema]);
+    });
+});
+describe('isPresettable', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('explicit true wins', () => {
+        const def = makeDefinition('explicit-true', { capabilities: { presettable: true } });
+        expect(isPresettable(def)).toBe(true);
+    });
+    test('explicit false wins even with parametrics', () => {
+        const def = makeDefinition('explicit-false', {
+            capabilities: { presettable: false },
+            parametrics: { groups: [] },
+        });
+        expect(isPresettable(def)).toBe(false);
+    });
+    test('defaults to true when parametrics exists', () => {
+        const def = makeDefinition('param', { parametrics: { groups: [] } });
+        expect(isPresettable(def)).toBe(true);
+    });
+    test('defaults to false without parametrics', () => {
+        const def = makeDefinition('no-param');
+        expect(isPresettable(def)).toBe(false);
+    });
+    test('isPresettableKind looks up the registry', () => {
+        registerNode(makeDefinition('shelfy', { parametrics: { groups: [] } }));
+        expect(isPresettableKind('shelfy')).toBe(true);
+        expect(isPresettableKind('unknown')).toBe(false);
+    });
+});
+describe('getHostRefFields', () => {
+    test('returns the declared hostRefFields verbatim', () => {
+        const def = makeDefinition('door', { capabilities: { hostRefFields: ['wallId'] } });
+        expect(getHostRefFields(def)).toEqual(['wallId']);
+    });
+    test('defaults to an empty array when none declared', () => {
+        const def = makeDefinition('shelf');
+        expect(getHostRefFields(def)).toEqual([]);
+    });
+});
+describe('isDrawnViaTool', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('true when capability set', () => {
+        const def = makeDefinition('fence', { capabilities: { drawTool: true } });
+        expect(isDrawnViaTool(def)).toBe(true);
+    });
+    test('false when unset or not exactly true', () => {
+        expect(isDrawnViaTool(makeDefinition('column'))).toBe(false);
+        expect(isDrawnViaTool(makeDefinition('off', { capabilities: { drawTool: false } }))).toBe(false);
+    });
+    test('isDrawnViaToolKind looks up the registry', () => {
+        registerNode(makeDefinition('fence', { capabilities: { drawTool: true } }));
+        expect(isDrawnViaToolKind('fence')).toBe(true);
+        expect(isDrawnViaToolKind('unknown')).toBe(false);
+    });
+});
+describe('loadPlugin', () => {
+    beforeEach(() => {
+        nodeRegistry._reset();
+    });
+    test('registers all nodes from a plugin', async () => {
+        const plugin = {
+            id: 'test:plugin',
+            apiVersion: 1,
+            nodes: [makeDefinition('a'), makeDefinition('b')],
+        };
+        await loadPlugin(plugin);
+        expect(nodeRegistry.size).toBe(2);
+        expect(nodeRegistry.has('a')).toBe(true);
+        expect(nodeRegistry.has('b')).toBe(true);
+        expect(getNodePluginId('a')).toBe('test:plugin');
+        expect(getNodePluginId('b')).toBe('test:plugin');
+    });
+    test('enables plugin kinds only when the project has the plugin installed', async () => {
+        await loadPlugin({ id: 'test:plugin', apiVersion: 1, nodes: [makeDefinition('plugin:node')] });
+        expect(isNodeKindEnabled('plugin:node', [])).toBe(false);
+        expect(isNodeKindEnabled('plugin:node', ['test:plugin'])).toBe(true);
+        expect(isNodeKindEnabled('plugin:node')).toBe(true);
+        expect(isNodeKindEnabled('host:node', [])).toBe(true);
+    });
+    test('keeps built-in plugin kinds enabled independently of project installs', async () => {
+        await loadPlugin({ id: 'pascal:core', apiVersion: 1, nodes: [makeDefinition('wall')] });
+        expect(isNodeKindEnabled('wall', [])).toBe(true);
+    });
+    test('handles plugin with no nodes', async () => {
+        await loadPlugin({ id: 'empty', apiVersion: 1 });
+        expect(nodeRegistry.size).toBe(0);
+    });
+    test('handles plugin with empty nodes array', async () => {
+        await loadPlugin({ id: 'empty', apiVersion: 1, nodes: [] });
+        expect(nodeRegistry.size).toBe(0);
+    });
+    test('throws on apiVersion mismatch', async () => {
+        const plugin = {
+            id: 'old-plugin',
+            apiVersion: 99,
+            nodes: [],
+        };
+        await expect(loadPlugin(plugin)).rejects.toThrow(/apiVersion/);
+    });
+    test('propagates duplicate-kind error from a single plugin in production', async () => {
+        const plugin = {
+            id: 'broken',
+            apiVersion: 1,
+            nodes: [makeDefinition('dup'), makeDefinition('dup')],
+        };
+        await inProduction(() => expect(loadPlugin(plugin)).rejects.toThrow(/duplicate node kind/));
+    });
+    test('propagates duplicate-kind error across plugins in production', async () => {
+        await inProduction(async () => {
+            await loadPlugin({ id: 'a', apiVersion: 1, nodes: [makeDefinition('shared')] });
+            await expect(loadPlugin({ id: 'b', apiVersion: 1, nodes: [makeDefinition('shared')] })).rejects.toThrow(/duplicate node kind/);
+        });
+    });
+});

package/dist/registry/relations-resolver.d.ts

@@ -0,0 +1,42 @@
+import type { AnyNode, AnyNodeId } from '../schema/types';
+import type { SceneApi } from './types';
+/**
+ * Spatial neighbor query — given a node and a set of kinds, returns IDs of
+ * neighboring nodes of those kinds. The runtime provides this from
+ * `spatialGridManager`; tests can pass a stub.
+ */
+export type SpatialQuery = (node: AnyNode, kinds: readonly string[]) => Iterable<AnyNodeId>;
+/**
+ * Returns the IDs of nodes that share `node` as a parent. The runtime can
+ * pass an optimized index; the default fallback iterates the scene.
+ */
+export type ChildQuery = (node: AnyNode) => Iterable<AnyNodeId>;
+export type CascadeContext = {
+    scene: SceneApi;
+    /** Optional: bounded spatial neighbor lookup. Required for `affectsSpatial`. */
+    spatialQuery?: SpatialQuery;
+    /** Optional: children-by-parent lookup. Defaults to iterating the scene. */
+    childQuery?: ChildQuery;
+    /** Safety cap on cascade depth — guards against bad data and pathological
+     * registry configurations. Default 16 (deeper than the maxHostDepth of 6). */
+    maxDepth?: number;
+};
+/**
+ * Walks the relations graph from one dirty node and returns the full set of
+ * IDs (including the starting one) that should be marked dirty. Pure — does
+ * NOT call `scene.markDirty`; callers iterate the result.
+ *
+ * Phase 1 implements:
+ * - `hosts`: marks children whose `type` matches the kind list
+ * - `affectsSpatial`: marks neighbors found via `spatialQuery`
+ *
+ * Phase 3 will add `linkedBy: 'endpoint-match'` for wall corner propagation.
+ */
+export declare function cascadeDirty(startId: AnyNodeId, ctx: CascadeContext): Set<AnyNodeId>;
+/**
+ * Recursively collects every descendant of a node, plus the node itself.
+ * Used by `cascadeDelete: 'descendants'` and by tools that need to delete a
+ * subtree atomically. Independent of dirty-marking — pure traversal.
+ */
+export declare function collectDescendants(startId: AnyNodeId, ctx: Pick<CascadeContext, 'scene' | 'childQuery' | 'maxDepth'>): Set<AnyNodeId>;
+//# sourceMappingURL=relations-resolver.d.ts.map

package/dist/registry/relations-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations-resolver.d.ts","sourceRoot":"","sources":["../../src/registry/relations-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAEvC;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAA;AAE3F;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAA;AAE/D,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,QAAQ,CAAA;IACf,gFAAgF;IAChF,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB;kFAC8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB,CAAA;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,cAAc,GAAG,GAAG,CAAC,SAAS,CAAC,CAKpF;AA+CD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,EAClB,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,GAAG,YAAY,GAAG,UAAU,CAAC,GAC7D,GAAG,CAAC,SAAS,CAAC,CAKhB"}