@waica/engine 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayrton Marini and Waica contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/aabb.d.ts

@@ -0,0 +1,2 @@
+/** Do two center+size AABBs overlap? Edges that merely touch don't count. */
+export declare function aabbOverlap(ax: number, ay: number, aw: number, ah: number, bx: number, by: number, bw: number, bh: number): boolean;

package/dist/aabb.js

@@ -0,0 +1,4 @@
+/** Do two center+size AABBs overlap? Edges that merely touch don't count. */
+export function aabbOverlap(ax, ay, aw, ah, bx, by, bw, bh) {
+    return Math.abs(ax - bx) * 2 < aw + bw && Math.abs(ay - by) * 2 < ah + bh;
+}

package/dist/animation/clip-player.d.ts

@@ -0,0 +1,20 @@
+export interface ClipDef {
+    /** Frame indices inside the spritesheet (row×cols + col). */
+    frames: number[];
+    fps: number;
+    /** Defaults to true; with false it sticks on the last frame. */
+    loop?: boolean;
+}
+/**
+ * Advances a clip through time. Pure logic (no three, no DOM) so it can
+ * be tested deterministically.
+ */
+export declare class ClipPlayer {
+    private frames;
+    private fps;
+    private loop;
+    private t;
+    set(clip: ClipDef): void;
+    /** Advances the clock and returns the sheet frame to show. */
+    advance(dt: number): number;
+}

package/dist/animation/clip-player.js

@@ -0,0 +1,24 @@
+/**
+ * Advances a clip through time. Pure logic (no three, no DOM) so it can
+ * be tested deterministically.
+ */
+export class ClipPlayer {
+    frames = [0];
+    fps = 1;
+    loop = true;
+    t = 0;
+    set(clip) {
+        this.frames = clip.frames.length > 0 ? clip.frames : [0];
+        this.fps = clip.fps;
+        this.loop = clip.loop ?? true;
+        this.t = 0;
+    }
+    /** Advances the clock and returns the sheet frame to show. */
+    advance(dt) {
+        this.t += dt;
+        const idx = Math.floor(this.t * this.fps);
+        const n = this.frames.length;
+        const clamped = this.loop ? idx % n : Math.min(idx, n - 1);
+        return this.frames[clamped] ?? 0;
+    }
+}

package/dist/animation/contract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Animation contract: the archetype declares which clips a character
+ * needs and how to degrade when one is missing. It's the centerpiece of
+ * the "the engine tells you which assets you need" thesis (DESIGN.md §2
+ * and §4): the game works from minute zero with whatever is there, and
+ * the editor (H2) will show the gaps as a checklist.
+ */
+export interface AnimationContract {
+    /** Clips the archetype expects to exist. */
+    required: string[];
+    /** Degradation chain: if a clip is missing, which one replaces it. */
+    fallbacks: Record<string, string>;
+}
+/**
+ * Resolves which clip to play: the requested one if it exists, otherwise
+ * it follows the fallback chain, and as a last resort the first available
+ * clip.
+ */
+export declare function resolveClip(contract: AnimationContract, available: Iterable<string>, wanted: string): string | undefined;
+/** Which contract clips are missing — what the editor will show as gaps. */
+export declare function missingClips(contract: AnimationContract, available: Iterable<string>): string[];

package/dist/animation/contract.js

@@ -0,0 +1,23 @@
+/**
+ * Resolves which clip to play: the requested one if it exists, otherwise
+ * it follows the fallback chain, and as a last resort the first available
+ * clip.
+ */
+export function resolveClip(contract, available, wanted) {
+    const set = new Set(available);
+    const seen = new Set();
+    let current = wanted;
+    while (current && !seen.has(current)) {
+        if (set.has(current))
+            return current;
+        seen.add(current);
+        current = contract.fallbacks[current];
+    }
+    const [first] = set;
+    return first;
+}
+/** Which contract clips are missing — what the editor will show as gaps. */
+export function missingClips(contract, available) {
+    const set = new Set(available);
+    return contract.required.filter((clip) => !set.has(clip));
+}

package/dist/animation/sheet.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Spritesheet slicing geometry shared by the runtime (UV math) and the
+ * editor (grid overlay + previews). A sheet is a cols×rows grid of cells;
+ * the optional params handle sheets whose frames don't fill the image:
+ * a margin before the first cell, gaps between cells, or an explicit
+ * cell size. All values are in source-image pixels and may be fractional
+ * (downscaled exports often land on half pixels).
+ */
+export interface SheetGridParams {
+    /** Top-left corner of the first cell. */
+    gridOffsetX?: number;
+    gridOffsetY?: number;
+    /** Gap between adjacent cells. */
+    spacingX?: number;
+    spacingY?: number;
+    /** Explicit cell size; unset/0 = split what the offset leaves evenly. */
+    cellWidth?: number;
+    cellHeight?: number;
+}
+/** One cell's pixel rect within the sheet image. */
+export interface SheetCell {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * One spritesheet: its image plus how it slices into frames — a uniform
+ * cols×rows grid, or explicit per-frame `cells` (auto-detected or hand-drawn)
+ * for packed sheets whose frames don't sit on a grid. When `cells` is present
+ * it wins over the grid.
+ */
+export interface SheetDef extends SheetGridParams {
+    texture: string;
+    cols: number;
+    rows: number;
+    cells?: SheetCell[];
+}
+/** How many frames a sheet yields: its cell count, else the grid, at least 1. */
+export declare function sheetFrameCount(sheet: {
+    cols: number;
+    rows: number;
+    cells?: SheetCell[];
+}): number;
+/**
+ * Maps a global frame index to its sheet and the frame within it. Sheets
+ * are numbered consecutively: sheet 0 owns frames 0..n0-1, sheet 1 the next
+ * n1, and so on. Out-of-range indices clamp to the nearest valid frame.
+ */
+export declare function locateFrame(sheets: readonly {
+    cols: number;
+    rows: number;
+    cells?: SheetCell[];
+}[], frame: number): {
+    sheet: number;
+    frame: number;
+};
+/**
+ * The pixel rect of `frame` (row-major index) in a sheet image. Explicit
+ * `cells` win when present (out-of-range indices clamp); otherwise the grid:
+ * with no params, the image divided evenly into cols×rows.
+ */
+export declare function sheetCell(imageWidth: number, imageHeight: number, cols: number, rows: number, frame: number, params?: SheetGridParams & {
+    cells?: SheetCell[];
+}): SheetCell;

package/dist/animation/sheet.js

@@ -0,0 +1,44 @@
+/** How many frames a sheet yields: its cell count, else the grid, at least 1. */
+export function sheetFrameCount(sheet) {
+    if (sheet.cells?.length)
+        return sheet.cells.length;
+    return Math.max(1, Math.floor(sheet.cols)) * Math.max(1, Math.floor(sheet.rows));
+}
+/**
+ * Maps a global frame index to its sheet and the frame within it. Sheets
+ * are numbered consecutively: sheet 0 owns frames 0..n0-1, sheet 1 the next
+ * n1, and so on. Out-of-range indices clamp to the nearest valid frame.
+ */
+export function locateFrame(sheets, frame) {
+    let rest = Math.max(0, Math.floor(frame));
+    for (let i = 0; i < sheets.length; i++) {
+        const count = sheetFrameCount(sheets[i]);
+        if (rest < count || i === sheets.length - 1)
+            return { sheet: i, frame: Math.min(rest, count - 1) };
+        rest -= count;
+    }
+    return { sheet: 0, frame: 0 };
+}
+const positive = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
+/**
+ * The pixel rect of `frame` (row-major index) in a sheet image. Explicit
+ * `cells` win when present (out-of-range indices clamp); otherwise the grid:
+ * with no params, the image divided evenly into cols×rows.
+ */
+export function sheetCell(imageWidth, imageHeight, cols, rows, frame, params = {}) {
+    if (params.cells?.length) {
+        const index = Math.min(Math.max(0, Math.floor(frame)), params.cells.length - 1);
+        return params.cells[index];
+    }
+    const c = Math.max(1, Math.floor(cols));
+    const r = Math.max(1, Math.floor(rows));
+    const ox = positive(params.gridOffsetX);
+    const oy = positive(params.gridOffsetY);
+    const sx = positive(params.spacingX);
+    const sy = positive(params.spacingY);
+    const width = positive(params.cellWidth) || Math.max(1, (imageWidth - ox - sx * (c - 1)) / c);
+    const height = positive(params.cellHeight) || Math.max(1, (imageHeight - oy - sy * (r - 1)) / r);
+    const col = frame % c;
+    const row = Math.floor(frame / c);
+    return { x: ox + col * (width + sx), y: oy + row * (height + sy), width, height };
+}

package/dist/archetype.d.ts

@@ -0,0 +1,37 @@
+import type { InputBindings } from './input.js';
+import type { PrefabJson, SceneEntityJson, SceneJson, SceneRegistry } from './scene.js';
+import type { ArchetypeBundle } from './state/hooks.js';
+/** One entity template exposed in an archetype's editor palette. */
+export interface EntityTemplate {
+    label: string;
+    icon: string;
+    category: PrefabJson['type'];
+    /** Builds the JSON for a new instance (no position; the editor sets it). */
+    make: () => SceneEntityJson;
+}
+/** One stock-art file shipped by an archetype package. */
+export interface ArchetypeArt {
+    /** File name under the archetype's assets/ and a demo project's src/art/. */
+    file: string;
+    /** Registry URI resolved by the archetype at runtime. */
+    uri: string;
+}
+/** The conventional contract exported by every archetype package. */
+export interface ArchetypeManifest {
+    id: string;
+    label: string;
+    scene: SceneJson;
+    blankScene: SceneJson;
+    registry: SceneRegistry;
+    palette: EntityTemplate[];
+    prefabs: Record<string, PrefabJson>;
+    art: ArchetypeArt[];
+    entityIcons: Readonly<Record<string, string>>;
+    bindings: Readonly<InputBindings>;
+    actionLabels: Readonly<Record<string, string>>;
+    bundle: ArchetypeBundle;
+}
+/** Browser manifest enriched with URLs produced by an asset-aware bundler. */
+export interface BrowserArchetypeManifest extends ArchetypeManifest {
+    artUrls: Readonly<Record<string, string>>;
+}

package/dist/archetype.js

@@ -0,0 +1 @@
+export {};

package/dist/camera.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The scene camera: a built-in, singular part of every scene — not a
+ * component you attach to an entity. The scene JSON carries its framing
+ * (position, zoom), an optional follow target and world limits; the Game
+ * drives the real THREE camera from it while simulating.
+ */
+/** World-space rectangle the camera view may never leave. */
+export interface CameraLimitsJson {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+export interface SceneCameraJson {
+    /** Where the camera starts (and stays, without a follow target). */
+    position?: [number, number];
+    /** Visible world height in units — the camera's zoom. */
+    zoom?: number;
+    /** Entity name to follow; absent or empty = fixed camera. */
+    follow?: string;
+    deadzoneWidth?: number;
+    deadzoneHeight?: number;
+    lookahead?: number;
+    smoothing?: number;
+    limits?: CameraLimitsJson;
+}
+export interface ResolvedSceneCamera {
+    position: [number, number];
+    zoom: number;
+    follow: string;
+    deadzoneWidth: number;
+    deadzoneHeight: number;
+    lookahead: number;
+    smoothing: number;
+    limits: CameraLimitsJson | null;
+}
+export declare const CAMERA_DEFAULTS: {
+    readonly position: [number, number];
+    readonly zoom: 12;
+    readonly follow: '';
+    readonly deadzoneWidth: 2;
+    readonly deadzoneHeight: 2.5;
+    readonly lookahead: 1.5;
+    readonly smoothing: 6;
+};
+/** Fills a scene's camera block with the engine defaults. */
+export declare function resolveSceneCamera(json?: SceneCameraJson): ResolvedSceneCamera;
+export interface CameraStepInput {
+    /** Current camera center. */
+    x: number;
+    y: number;
+    /** Half the visible world extents (from zoom and aspect). */
+    halfW: number;
+    halfH: number;
+    /** Followed entity's position, if the target exists. */
+    target: {
+        x: number;
+        y: number;
+    } | null;
+    /** Followed entity's horizontal velocity, for lookahead. */
+    vx: number;
+    dt: number;
+}
+/**
+ * One simulation step of the camera: deadzone-follow with lookahead and
+ * exponential smoothing, then limits. Pure — returns the next center.
+ */
+export declare function stepSceneCamera(cam: ResolvedSceneCamera, input: CameraStepInput): {
+    x: number;
+    y: number;
+};

package/dist/camera.js

@@ -0,0 +1,59 @@
+import * as THREE from 'three';
+export const CAMERA_DEFAULTS = {
+    position: [0, 0],
+    zoom: 12,
+    follow: '',
+    deadzoneWidth: 2,
+    deadzoneHeight: 2.5,
+    lookahead: 1.5,
+    smoothing: 6,
+};
+/** Fills a scene's camera block with the engine defaults. */
+export function resolveSceneCamera(json) {
+    return {
+        position: json?.position ?? CAMERA_DEFAULTS.position,
+        zoom: json?.zoom ?? CAMERA_DEFAULTS.zoom,
+        follow: json?.follow ?? CAMERA_DEFAULTS.follow,
+        deadzoneWidth: json?.deadzoneWidth ?? CAMERA_DEFAULTS.deadzoneWidth,
+        deadzoneHeight: json?.deadzoneHeight ?? CAMERA_DEFAULTS.deadzoneHeight,
+        lookahead: json?.lookahead ?? CAMERA_DEFAULTS.lookahead,
+        smoothing: json?.smoothing ?? CAMERA_DEFAULTS.smoothing,
+        limits: json?.limits ?? null,
+    };
+}
+/** Clamps a camera center so the view stays inside the limits on one axis. */
+function clampAxis(center, halfView, min, max) {
+    // Limits narrower than the view: center the view on them.
+    if (max - min <= halfView * 2)
+        return (min + max) / 2;
+    return Math.min(Math.max(center, min + halfView), max - halfView);
+}
+/**
+ * One simulation step of the camera: deadzone-follow with lookahead and
+ * exponential smoothing, then limits. Pure — returns the next center.
+ */
+export function stepSceneCamera(cam, input) {
+    let x = input.x;
+    let y = input.y;
+    if (input.target) {
+        let wantX = x;
+        let wantY = y;
+        const dx = input.target.x - x;
+        const dy = input.target.y - y;
+        const halfDzW = cam.deadzoneWidth / 2;
+        const halfDzH = cam.deadzoneHeight / 2;
+        if (Math.abs(dx) > halfDzW)
+            wantX = input.target.x - Math.sign(dx) * halfDzW;
+        if (Math.abs(dy) > halfDzH)
+            wantY = input.target.y - Math.sign(dy) * halfDzH;
+        if (Math.abs(input.vx) > 1)
+            wantX += Math.sign(input.vx) * cam.lookahead;
+        x = THREE.MathUtils.damp(x, wantX, cam.smoothing, input.dt);
+        y = THREE.MathUtils.damp(y, wantY, cam.smoothing, input.dt);
+    }
+    if (cam.limits) {
+        x = clampAxis(x, input.halfW, cam.limits.minX, cam.limits.maxX);
+        y = clampAxis(y, input.halfH, cam.limits.minY, cam.limits.maxY);
+    }
+    return { x, y };
+}

package/dist/collision-shape.d.ts

@@ -0,0 +1,26 @@
+export type CollisionShape = 'rectangle' | 'circle' | 'polygon';
+export type CollisionPoint = [number, number];
+export interface CollisionBody {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    shape?: CollisionShape;
+    /** Polygon vertices normalized against width/height, centered on the entity. */
+    points?: unknown;
+}
+export interface CollisionBounds {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export declare const COLLISION_SHAPES: readonly CollisionShape[];
+export declare const DEFAULT_COLLISION_POLYGON: ReadonlyArray<Readonly<CollisionPoint>>;
+/** Valid serialized points, or a fresh default triangle. */
+export declare function resolveCollisionPoints(value: unknown): CollisionPoint[];
+/** World-space outline used by collision tests and editor guides. */
+export declare function collisionVertices(body: CollisionBody): CollisionPoint[];
+export declare function collisionBounds(body: CollisionBody): CollisionBounds;
+/** Overlap between rectangle, ellipse/circle, and freeform simple polygons. */
+export declare function collisionOverlap(a: CollisionBody, b: CollisionBody): boolean;

package/dist/collision-shape.js

@@ -0,0 +1,136 @@
+export const COLLISION_SHAPES = [
+    'rectangle',
+    'circle',
+    'polygon',
+];
+export const DEFAULT_COLLISION_POLYGON = [
+    [-0.5, -0.5],
+    [0.5, -0.5],
+    [0, 0.5],
+];
+const CIRCLE_SEGMENTS = 32;
+const EPSILON = 1e-9;
+/** Valid serialized points, or a fresh default triangle. */
+export function resolveCollisionPoints(value) {
+    if (Array.isArray(value) && value.length >= 3) {
+        const points = [];
+        for (const point of value) {
+            if (!Array.isArray(point) ||
+                point.length < 2 ||
+                typeof point[0] !== 'number' ||
+                typeof point[1] !== 'number' ||
+                !Number.isFinite(point[0]) ||
+                !Number.isFinite(point[1])) {
+                return DEFAULT_COLLISION_POLYGON.map(([x, y]) => [x, y]);
+            }
+            points.push([point[0], point[1]]);
+        }
+        return points;
+    }
+    return DEFAULT_COLLISION_POLYGON.map(([x, y]) => [x, y]);
+}
+/** World-space outline used by collision tests and editor guides. */
+export function collisionVertices(body) {
+    const width = Math.abs(body.width);
+    const height = Math.abs(body.height);
+    const normalized = body.shape === 'circle'
+        ? Array.from({ length: CIRCLE_SEGMENTS }, (_, index) => {
+            const angle = (index / CIRCLE_SEGMENTS) * Math.PI * 2;
+            return [Math.cos(angle) * 0.5, Math.sin(angle) * 0.5];
+        })
+        : body.shape === 'polygon'
+            ? resolveCollisionPoints(body.points)
+            : [
+                [-0.5, -0.5],
+                [0.5, -0.5],
+                [0.5, 0.5],
+                [-0.5, 0.5],
+            ];
+    return normalized.map(([x, y]) => [body.x + x * width, body.y + y * height]);
+}
+export function collisionBounds(body) {
+    const vertices = collisionVertices(body);
+    let left = Infinity;
+    let right = -Infinity;
+    let top = -Infinity;
+    let bottom = Infinity;
+    for (const [x, y] of vertices) {
+        left = Math.min(left, x);
+        right = Math.max(right, x);
+        top = Math.max(top, y);
+        bottom = Math.min(bottom, y);
+    }
+    return { left, right, top, bottom };
+}
+/** Overlap between rectangle, ellipse/circle, and freeform simple polygons. */
+export function collisionOverlap(a, b) {
+    const boundsA = collisionBounds(a);
+    const boundsB = collisionBounds(b);
+    if (boundsA.right <= boundsB.left ||
+        boundsA.left >= boundsB.right ||
+        boundsA.top <= boundsB.bottom ||
+        boundsA.bottom >= boundsB.top) {
+        return false;
+    }
+    const verticesA = collisionVertices(a);
+    const verticesB = collisionVertices(b);
+    for (let ai = 0; ai < verticesA.length; ai++) {
+        const a1 = verticesA[ai];
+        const a2 = verticesA[(ai + 1) % verticesA.length];
+        for (let bi = 0; bi < verticesB.length; bi++) {
+            const b1 = verticesB[bi];
+            const b2 = verticesB[(bi + 1) % verticesB.length];
+            if (segmentsCross(a1, a2, b1, b2))
+                return true;
+        }
+    }
+    return hasInteriorPoint(verticesA, verticesB) || hasInteriorPoint(verticesB, verticesA);
+}
+function hasInteriorPoint(points, polygon) {
+    for (let index = 0; index < points.length; index++) {
+        const point = points[index];
+        if (pointInPolygon(point, polygon))
+            return true;
+        const next = points[(index + 1) % points.length];
+        if (pointInPolygon([(point[0] + next[0]) / 2, (point[1] + next[1]) / 2], polygon)) {
+            return true;
+        }
+    }
+    const center = [
+        points.reduce((sum, [x]) => sum + x, 0) / points.length,
+        points.reduce((sum, [, y]) => sum + y, 0) / points.length,
+    ];
+    return pointInPolygon(center, polygon);
+}
+function segmentsCross(a1, a2, b1, b2) {
+    const ab1 = cross(a1, a2, b1);
+    const ab2 = cross(a1, a2, b2);
+    const ba1 = cross(b1, b2, a1);
+    const ba2 = cross(b1, b2, a2);
+    return ab1 * ab2 < -EPSILON && ba1 * ba2 < -EPSILON;
+}
+function cross(a, b, point) {
+    return (b[0] - a[0]) * (point[1] - a[1]) - (b[1] - a[1]) * (point[0] - a[0]);
+}
+function pointInPolygon(point, polygon) {
+    let inside = false;
+    for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
+        const a = polygon[index];
+        const b = polygon[previous];
+        if (pointOnSegment(point, a, b))
+            return false;
+        const crosses = (a[1] > point[1]) !== (b[1] > point[1]) &&
+            point[0] < ((b[0] - a[0]) * (point[1] - a[1])) / (b[1] - a[1]) + a[0];
+        if (crosses)
+            inside = !inside;
+    }
+    return inside;
+}
+function pointOnSegment(point, a, b) {
+    if (Math.abs(cross(a, b, point)) > EPSILON)
+        return false;
+    return (point[0] >= Math.min(a[0], b[0]) - EPSILON &&
+        point[0] <= Math.max(a[0], b[0]) + EPSILON &&
+        point[1] >= Math.min(a[1], b[1]) - EPSILON &&
+        point[1] <= Math.max(a[1], b[1]) + EPSILON);
+}

package/dist/component-registry.d.ts

@@ -0,0 +1,16 @@
+import { type ComponentClass } from './component.js';
+import type { SceneRegistry } from './scene.js';
+/** The namespace returned by importing one project code module. */
+export type ComponentModule = Readonly<Record<string, unknown>>;
+/**
+ * Finds exported Component subclasses in project modules. Classes are keyed by
+ * their stable componentName, not by the export name, so minification and
+ * default exports do not change scene JSON.
+ */
+export declare function collectModuleComponents(modules: Iterable<ComponentModule>, warn?: (message: string) => void): Record<string, ComponentClass>;
+/**
+ * Adds project-owned component classes to a registry. Project code is the
+ * extension layer, so it deliberately wins a stable-name collision while
+ * making that shadowing visible to the host.
+ */
+export declare function mergeRegistryComponents(registry: SceneRegistry, project: Readonly<Record<string, ComponentClass>>, warn?: (message: string) => void): SceneRegistry;

package/dist/component-registry.js

@@ -0,0 +1,44 @@
+import { Component } from './component.js';
+/**
+ * Finds exported Component subclasses in project modules. Classes are keyed by
+ * their stable componentName, not by the export name, so minification and
+ * default exports do not change scene JSON.
+ */
+export function collectModuleComponents(modules, warn = console.warn) {
+    const components = {};
+    for (const module of modules) {
+        for (const value of Object.values(module)) {
+            if (typeof value !== 'function')
+                continue;
+            const Class = value;
+            if (!(Class.prototype instanceof Component))
+                continue;
+            // Without its own componentName a class inherits the base's, so nothing
+            // could reference it from scene JSON. Silently skipping it looks like
+            // the editor lost the file: say so instead.
+            if (typeof Class.componentName !== 'string' || Class.componentName === 'Component') {
+                warn(`[waica] component class "${Class.name || '(anonymous)'}" declares no ` +
+                    `static componentName — scenes cannot reference it`);
+                continue;
+            }
+            components[Class.componentName] = Class;
+        }
+    }
+    return components;
+}
+/**
+ * Adds project-owned component classes to a registry. Project code is the
+ * extension layer, so it deliberately wins a stable-name collision while
+ * making that shadowing visible to the host.
+ */
+export function mergeRegistryComponents(registry, project, warn = console.warn) {
+    for (const name of Object.keys(project)) {
+        if (registry.components[name]) {
+            warn(`[waica] project component "${name}" shadows registry component "${name}"`);
+        }
+    }
+    return {
+        ...registry,
+        components: { ...registry.components, ...project },
+    };
+}