@descix/frqtl-node 0.0.0-stage → 0.6.0-p0.1

package/dist/frqtl/objects/kinds-entry.js

@@ -0,0 +1,14 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * kinds-entry.js — the published door to the kind registry: `@descix/frqtl-web/kinds` and
+ * `@descix/frqtl-node/kinds`. Exactly the four names below, re-exported from THE registry (kinds.js — the
+ * same module instance every part registers in); the rest of kinds.js stays internal.
+ *
+ *   KINDS_EXPORTS   the published names (the parity gate holds both packages' ./kinds to this table)
+ */
+
+/** The names `./kinds` publishes. */
+export const KINDS_EXPORTS = Object.freeze(['registerKind', 'kindNamed', 'kindOf', 'registeredKinds']);
+
+export { registerKind, kindNamed, kindOf, registeredKinds } from './kinds.js';

package/dist/frqtl/objects/kinds.js

@@ -0,0 +1,190 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * kinds.js — THE kind registry: a kind registers when the module that defines it is imported.
+ *
+ *   registerKind(Class, { from, descriptor, defaults?, build?, palette? })
+ *       The kind's NAME IS `Class.name` — there is no name field (a `name` key is refused: it would
+ *       be a second derivation of the same fact). Fork = copy the part file, rename the class,
+ *       import it: the copy registers under its new name with no other edit.
+ *         from        REQUIRED — the defining module's own URL (`import.meta.url`), so a copied
+ *                     file carries the right value untouched; a duplicate registration names both
+ *         descriptor  REQUIRED — the editable-field contract, validated by schema/'s own validator
+ *                     (schema/validate-descriptor.js). It carries no `kind`: the registry stamps
+ *                     `descriptor.kind = Class.name`. A COMPOSED FORK passes its parent's registered
+ *                     descriptor (kindOf(Parent).descriptor): the registry registers a copy of it,
+ *                     stamped with the fork's own name — the parent's row is never touched
+ *         defaults    the construction defaults ObjectFactory merges under a config (ObjectSchema.defaultPropsFor)
+ *         build       (props, ctx, Class) → the declared part — ObjectFactory.create's per-kind step; Class is the
+ *                     class that registered (a composed fork passing its parent's build gets an instance of the
+ *                     FORK, stamped `_schemaKind = Class.name`). A kind
+ *                     with no build registers a descriptor only: ObjectFactory refuses to build it,
+ *                     naming the kind's own construction door
+ *         palette     { displayName, category, iconHint, rank } — present ⇔ STUDIO can DROP the kind
+ *                     (ObjectSchema.placeableCatalog, ordered by rank; equal ranks keep registration
+ *                     order, so a fork — a renamed copy — sits beside its original)
+ *       THROWS on an anonymous class, a malformed row, a name a scope descriptor already owns
+ *       (schema/scopes.js) unless the descriptor IS that scope row's object, or a second
+ *       registration of the same name.
+ *   kindNamed(name) → Class        THROWS when no module defining it was imported in this realm
+ *   kindOf(ClassOrName) → row|null  { name, Class, from, descriptor, defaults, build, palette } — the row and
+ *                                   its descriptor/defaults/palette are FROZEN (deeply): a fork reads its parent's
+ *                                   row and cannot change it
+ *   registeredKinds() → string[]   in registration order
+ *   placeableKinds() → rows with a palette, by rank (stable: equal ranks in registration order)
+ *
+ * A registry is an IMPORT fact: a realm has the kinds it imported. The boot imports the parts barrel
+ * (@descix/frqtl-web/parts), so every booted realm has every published part; a kind defined outside
+ * the parts directory registers when the module that uses it imports it. This file imports nothing
+ * of the parts, so the arrow runs part → registry, never back.
+ */
+
+import { validateDescriptor } from './schema/validate-descriptor.js';
+import { SCOPE_DESCRIPTORS } from './schema/scopes.js';
+
+/** The keys a registration row may carry. */
+export const KIND_ROW_KEYS = Object.freeze(['from', 'descriptor', 'defaults', 'build', 'palette']);
+/** The keys a palette entry carries. */
+export const PALETTE_KEYS = Object.freeze(['displayName', 'category', 'iconHint', 'rank']);
+
+const _rows = new Map();   // name → frozen row
+
+function _fail(msg) {
+    throw new Error('[kinds] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/**
+ * @param {Function} Class — the part's class (its name is the kind name)
+ * @param {{from: string, descriptor: object, defaults?: object, build?: Function, palette?: object}} row
+ * @returns {Function} Class
+ */
+export function registerKind(Class, row) {
+    if (typeof Class !== 'function') { _fail('registerKind(Class, row): Class must be the part\'s class (got ' + typeof Class + ').'); }
+    const name = Class.name;
+    if (!name) { _fail('registerKind: the class is anonymous — the kind name IS the class name, so a kind\'s class must be named.'); }
+    if (!row || typeof row !== 'object') { _fail('registerKind(' + name + ', row): row must be an object {' + KIND_ROW_KEYS.join(', ') + '}.'); }
+    if (Object.prototype.hasOwnProperty.call(row, 'name')) {
+        _fail('registerKind(' + name + '): a row carries no `name` — the kind name IS the class name (' + name + '). ' +
+            'To register under another name, rename the class.');
+    }
+    for (const k of Object.keys(row)) {
+        if (KIND_ROW_KEYS.indexOf(k) === -1) { _fail('registerKind(' + name + '): unknown row key "' + k + '" — a row carries ' + KIND_ROW_KEYS.join(', ') + '.'); }
+    }
+    if (typeof row.from !== 'string' || !row.from) {
+        _fail('registerKind(' + name + '): `from` is required — the defining module\'s own URL (from: import.meta.url).');
+    }
+    try { new URL(row.from); } catch (e) { _fail('registerKind(' + name + '): `from` must be a URL (import.meta.url), got ' + JSON.stringify(row.from) + '.'); }
+    // A scope row's name is refused — except to a kind whose descriptor IS that row's object (the
+    // LargeObject part registers the engine door's row by reference: still one owner, schema/scopes.js).
+    const scopeRow = Object.prototype.hasOwnProperty.call(SCOPE_DESCRIPTORS, name) ? SCOPE_DESCRIPTORS[name] : null;
+    if (scopeRow && row.descriptor !== scopeRow) {
+        _fail('registerKind(' + name + ', …): "' + name + '" is a SCOPE descriptor row (schema/scopes.js SCOPE_DESCRIPTORS) — ' +
+            'a scope is not a kind, and one name has one owner. Rename the class, or register the scope row ' +
+            'itself by reference (descriptor: SCOPE_DESCRIPTORS.' + name + ') (' + row.from + ').');
+    }
+    if (_rows.has(name)) {
+        _fail('kind "' + name + '" is already registered by ' + _rows.get(name).from + '; ' + row.from +
+            ' registers it again — rename the class in the copy.');
+    }
+    let descriptor = row.descriptor;
+    if (!descriptor || typeof descriptor !== 'object') { _fail('registerKind(' + name + '): `descriptor` is required.'); }
+    // A composed fork inherits a REGISTERED kind's descriptor: register a copy, stamped with the fork's name.
+    if (!scopeRow && _isRegisteredDescriptor(descriptor)) {
+        const copy = {};
+        for (const k of Object.keys(descriptor)) { if (k !== 'kind') { copy[k] = descriptor[k]; } }
+        descriptor = copy;
+    }
+    if (!scopeRow && Object.prototype.hasOwnProperty.call(descriptor, 'kind')) {
+        _fail('registerKind(' + name + '): the descriptor carries a `kind` — the registry stamps it from the class ' +
+            'name; a typed copy is a second derivation of the same fact. Delete the descriptor\'s kind line.');
+    }
+    validateDescriptor(name, descriptor);
+    if (row.defaults !== undefined && (row.defaults === null || typeof row.defaults !== 'object' || Array.isArray(row.defaults))) {
+        _fail('registerKind(' + name + '): `defaults` must be a props object when given.');
+    }
+    if (row.build !== undefined && typeof row.build !== 'function') {
+        _fail('registerKind(' + name + '): `build` must be a function (props, ctx) → part when given.');
+    }
+    if (row.palette !== undefined) {
+        const p = row.palette;
+        if (!p || typeof p !== 'object') { _fail('registerKind(' + name + '): `palette` must be {' + PALETTE_KEYS.join(', ') + '}.'); }
+        for (const k of Object.keys(p)) {
+            if (PALETTE_KEYS.indexOf(k) === -1) { _fail('registerKind(' + name + '): unknown palette key "' + k + '" — ' + PALETTE_KEYS.join(', ') + '.'); }
+        }
+        for (const k of ['displayName', 'category', 'iconHint']) {
+            if (typeof p[k] !== 'string' || !p[k]) { _fail('registerKind(' + name + '): palette.' + k + ' must be a non-empty string.'); }
+        }
+        if (typeof p.rank !== 'number' || !Number.isInteger(p.rank) || p.rank < 0) {
+            _fail('registerKind(' + name + '): palette.rank must be a non-negative integer (the palette order).');
+        }
+    }
+    if (!scopeRow) {   // a scope row carries its own kind (= its name)
+        Object.defineProperty(descriptor, 'kind', { value: name, enumerable: true, writable: false, configurable: false });
+    }
+    _rows.set(name, Object.freeze({
+        name: name,
+        Class: Class,
+        from: row.from,
+        descriptor: _deepFreeze(descriptor),
+        defaults: row.defaults === undefined ? undefined : _deepFreeze(Object.assign({}, row.defaults)),
+        build: row.build,
+        palette: row.palette ? Object.freeze(Object.assign({}, row.palette)) : undefined
+    }));
+    return Class;
+}
+
+/** Is `d` the descriptor object of a kind already registered (kindOf(Parent).descriptor)? */
+function _isRegisteredDescriptor(d) {
+    for (const r of _rows.values()) { if (r.descriptor === d) { return true; } }
+    return false;
+}
+
+/** Freeze `o` and every plain object / array under it (functions and class instances are left as they are). */
+function _deepFreeze(o) {
+    if (!o || typeof o !== 'object' || Object.isFrozen(o)) { return o; }
+    const proto = Object.getPrototypeOf(o);
+    if (proto !== Object.prototype && proto !== null && !Array.isArray(o)) { return o; }
+    Object.freeze(o);
+    for (const k of Object.keys(o)) { _deepFreeze(o[k]); }
+    return o;
+}
+
+/** The refusal an unregistered kind name reads — the import form, never a path. */
+export function unregisteredKindMessage(name) {
+    return 'kind "' + name + '" is not registered in this realm — import the module that defines it; ' +
+        'published parts: \'@descix/frqtl-web/parts\'';
+}
+
+/**
+ * @param {string} name
+ * @returns {Function} the registered class. THROWS when no module defining it was imported here.
+ */
+export function kindNamed(name) {
+    const row = _rows.get(name);
+    if (!row) { throw new Error('[kinds] ' + unregisteredKindMessage(name) + '. (FAIL-LOUD.)'); }
+    return row.Class;
+}
+
+/**
+ * @param {Function|string} classOrName
+ * @returns {object|null} the registration row
+ */
+export function kindOf(classOrName) {
+    if (typeof classOrName === 'string') { return _rows.get(classOrName) || null; }
+    if (typeof classOrName === 'function') {
+        const row = _rows.get(classOrName.name);
+        return (row && row.Class === classOrName) ? row : null;
+    }
+    return null;
+}
+
+/** @returns {string[]} the registered kind names, in registration order */
+export function registeredKinds() {
+    return Array.from(_rows.keys());
+}
+
+/** @returns {object[]} the rows STUDIO can drop, ordered by palette.rank (a stable sort: ties keep registration order) */
+export function placeableKinds() {
+    return Array.from(_rows.values()).filter(function (r) { return !!r.palette; })
+        .sort(function (a, b) { return a.palette.rank - b.palette.rank; });
+}

package/dist/frqtl/objects/objects/Box.js

@@ -0,0 +1,273 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Box — Engine-agnostic rectangular enclosure made of 4 LargeObject walls.
+ * Creates a rectangular enclosure with configurable wall thickness, collision type,
+ * and an optional slit (gap) on any one wall. Used by OvenBox (blackbody) and
+ * SlitScreen (double-slit) as the physical boundary primitive.
+ *
+ * Engine-agnostic: works with both the JS reference engine and the Rust/WASM engine.
+ */
+
+import { LargeObject } from '../../parts/LargeObject.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.js';
+import { CollisionActions } from '../../parts/CollisionActions.js';
+import { registerKind } from '../kinds.js';
+
+    // ── Imports ─────────────────────────────────────────────────────────
+
+    // ── Box ─────────────────────────────────────────────────────────────
+
+    /**
+     * Rectangular enclosure made of 4 LargeObject walls.
+     *
+     * Walls are positioned so their outer edges align with the **outer** rect
+     * (`left - wallThickness`, `top - wallThickness`, …). The caller supplies the
+     * inner rect; walls extend outward. A slit on one wall is implemented as two
+     * LargeObject segments (top and bottom) leaving a gap of `slit.height` pixels
+     * in the center.
+     *
+     * @param {Object} universe - The engine universe instance (JS or WASM).
+     * @param {Object} options - Configuration.
+     * @param {number} options.left - Inner box left X (physics pixels).
+     * @param {number} options.top - Inner box top Y (physics pixels).
+     * @param {number} options.width - Inner box width (physics pixels).
+     * @param {number} options.height - Inner box height (physics pixels).
+     * @param {number} [options.wallThickness=10] - Wall thickness in pixels. Walls
+     *   grow outward from the inner rect by this amount.
+     * @param {string} [options.collisionType='BOUNCE'] - Collision type applied to
+     *   all walls (a `CollisionTypes` constant).
+     * @param {Array<string>} [options.actions=[]] - Collision actions applied to all
+     *   walls (array of `CollisionActions` constants, e.g. `[BOUNCE, ABSORB]`).
+     * @param {Array<number>} [options.color=[120,120,120]] - Wall color `[r,g,b]`.
+     * @param {Object} [options.slit] - Optional slit configuration.
+     * @param {string} options.slit.wall - Which wall carries the slit:
+     *   `'right'` | `'left'` | `'top'` | `'bottom'`.
+     * @param {number} options.slit.height - Slit opening height (pixels).
+     *
+     * @deprecated V1 sugar, kept for byte-identical scenes (blackbody's OvenBox). V2 direction: four Wall{ collisionBehavior:'block' | 'bounce' } slabs (needs an opt-in fixed-axis flip to reproduce this wall program).
+     */
+    function Box(universe, options) {
+        options = options || {};
+
+        this.universe = universe;
+        this._schemaKind = 'Box';
+
+        var left = options.left;
+        var top = options.top;
+        var w = options.width;
+        var h = options.height;
+        var wt = options.wallThickness || 10;
+        var ct = options.collisionType || CollisionTypes.BOUNCE;
+        var actions = options.actions || [];
+        var color = options.color || [120, 120, 120];
+        var slit = options.slit || null;
+
+        // Outer rect (walls extend outward from inner box)
+        var outerLeft = left - wt;
+        var outerTop = top - wt;
+        var outerW = w + 2 * wt;
+        var outerH = h + 2 * wt;
+
+        this.walls = [];
+        this.innerRect = { left: left, top: top, w: w, h: h };
+        this.outerRect = { left: outerLeft, top: outerTop, w: outerW, h: outerH };
+        this.wallThickness = wt;
+
+        // Top wall
+        this.walls.push(new LargeObject(
+            universe,
+            [outerLeft, outerTop, outerW, wt],
+            ct, actions, 'TOP', 'bottom', null, 1, color
+        ));
+
+        // Bottom wall
+        this.walls.push(new LargeObject(
+            universe,
+            [outerLeft, outerTop + outerH - wt, outerW, wt],
+            ct, actions, 'BOTTOM', 'top', null, 1, color
+        ));
+
+        // Left wall
+        if (slit && slit.wall === 'left') {
+            this._createSlittedWall(universe, 'left', outerLeft, outerTop, outerH, wt, slit.height, ct, actions, color);
+        } else {
+            this.walls.push(new LargeObject(
+                universe,
+                [outerLeft, outerTop, wt, outerH],
+                ct, actions, 'LEFT', 'right', null, 1, color
+            ));
+        }
+
+        // Right wall
+        if (slit && slit.wall === 'right') {
+            this._createSlittedWall(universe, 'right', outerLeft + outerW - wt, outerTop, outerH, wt, slit.height, ct, actions, color);
+        } else {
+            this.walls.push(new LargeObject(
+                universe,
+                [outerLeft + outerW - wt, outerTop, wt, outerH],
+                ct, actions, 'RIGHT', 'left', null, 1, color
+            ));
+        }
+
+        // THE ONE UP-LINK on every wall LO this Box composed (a drawn wall resolves to the Box).
+        for (var _wi = 0; _wi < this.walls.length; _wi++) {
+            this.walls[_wi]._owner = this;   // THE ONE UP-LINK: the Box composed each wall LO
+        }
+    }
+
+    /**
+     * Create a wall with a slit (gap) in the middle.
+     * @private
+     */
+    Box.prototype._createSlittedWall = function (universe, side, wallX, outerTop, outerH, wt, slitHeight, ct, actions, color) {
+        var topSegH = (outerH - slitHeight) / 2;
+        var reposition = (side === 'left') ? 'right' : 'left';
+        var labelSuffix = side.toUpperCase();
+
+        // Top segment
+        this.walls.push(new LargeObject(
+            universe,
+            [wallX, outerTop, wt, topSegH],
+            ct, actions, labelSuffix + '_T', reposition, null, 1, color
+        ));
+
+        // Bottom segment
+        this.walls.push(new LargeObject(
+            universe,
+            [wallX, outerTop + outerH - topSegH - 1, wt, topSegH],
+            ct, actions, labelSuffix + '_B', reposition, null, 1, color
+        ));
+    };
+
+    /**
+     * Set collision type on all walls.
+     * @param {string} ct - CollisionTypes value
+     */
+    Box.prototype.setCollisionType = function (ct) {
+        for (var i = 0; i < this.walls.length; i++) {
+            this.walls[i].setCollisionType(ct);
+        }
+    };
+
+    /**
+     * Enable/disable all walls.
+     * @param {boolean} active
+     */
+    Box.prototype.setActive = function (active) {
+        for (var i = 0; i < this.walls.length; i++) {
+            this.walls[i].setActive(active);
+        }
+    };
+
+    /**
+     * Full teardown of what this Box composed: every wall LO leaves the world (dispose IS the
+     * removal). Idempotent (LargeObject.dispose guards itself).
+     */
+    Box.prototype.dispose = function () {
+        for (var i = 0; i < this.walls.length; i++) { this.walls[i].dispose(); }
+    };
+
+    // ── The kind (objects/kinds.js): descriptor, construction defaults, builder ──────────
+
+    /**
+     * Box — Rectangular enclosure made of 4 LargeObject walls (optionally with a slit).
+     * Constructor: Box(universe, options)
+     * options: { left, top, width, height, wallThickness, collisionType, actions, color, slit }
+     * Group wrapper: all wall sub-LargeObjects are stamped with the ONE up-link `_owner` = <this>.
+     */
+    var BoxDescriptor = {
+        description: 'A rectangular enclosure built from 4 LargeObject walls ' +
+            '(top, bottom, left, right). Any wall can optionally have a slit opening. ' +
+            'Used to confine particles, build cavities, or create directed channels. ' +
+            'Inner dimensions define the open cavity; walls extend outward by wallThickness.',
+        fields: [
+            {
+                name: 'left',
+                type: 'number',
+                constraint: { integer: true },
+                engineVisible: true,
+                description: 'Inner box left X position (physics pixels). The outer wall begins at left - wallThickness.'
+            },
+            {
+                name: 'top',
+                type: 'number',
+                constraint: { integer: true },
+                engineVisible: true,
+                description: 'Inner box top Y position (physics pixels). The outer wall begins at top - wallThickness.'
+            },
+            {
+                name: 'width',
+                type: 'number',
+                constraint: { min: 1, integer: true },
+                engineVisible: true,
+                description: 'Inner box width (physics pixels). Outer width = width + 2 * wallThickness.'
+            },
+            {
+                name: 'height',
+                type: 'number',
+                constraint: { min: 1, integer: true },
+                engineVisible: true,
+                description: 'Inner box height (physics pixels). Outer height = height + 2 * wallThickness.'
+            },
+            {
+                name: 'wallThickness',
+                type: 'number',
+                constraint: { min: 1, integer: true },
+                engineVisible: true,
+                unit: 'px',
+                description: 'Thickness of each wall in physics pixels (default 10). Walls extend outward from the inner box.'
+            },
+            {
+                name: 'collisionType',
+                type: 'enum',
+                constraint: { values: CollisionTypes },
+                engineVisible: true,
+                description: 'Collision type applied to all four walls (e.g. BOUNCE confines particles inside).'
+            },
+            {
+                name: 'actions',
+                type: 'enum-set',
+                constraint: { values: CollisionActions },
+                engineVisible: true,
+                description: 'Actions applied on collision for all four walls (e.g. [BOUNCE, ABSORB]).'
+            },
+            {
+                name: 'color',
+                type: 'rgb',
+                engineVisible: false,
+                live: true,
+                description: 'Render color [r, g, b] for all four walls (render-only). A live edit fans ' +
+                    'out to every wall the group owns (the `_owner` fan-out in updateObjectProperty).'
+            }
+        ]
+    };
+
+    registerKind(Box, {
+        from: import.meta.url,
+        descriptor: BoxDescriptor,
+        defaults: {
+        left: 60, top: 60,
+        width: 80, height: 80,
+        wallThickness: 10,
+        collisionType: 'BOUNCE',
+        actions: [],
+        color: [120, 120, 120]
+        },
+        build: function (props, ctx, Class) {
+            var BoxCls = Class;   // the class that registered (a composed fork's own class)
+            var box = new BoxCls(ctx.runner.universe, Object.assign({
+                left: props.left != null ? props.left : Math.round(ctx.x - 40),
+                top:  props.top  != null ? props.top  : Math.round(ctx.y - 40),
+                width: 80, height: 80,
+                wallThickness: 10, collisionType: 'BOUNCE', actions: [], color: [120, 120, 120]
+            }, props));
+            box._schemaKind = Class.name;
+            return box;
+        }
+    });
+
+    // ── Export ───────────────────────────────────────────────────────────
+
+    export { Box };
+

package/dist/frqtl/objects/objects/Bullet.js

@@ -0,0 +1,155 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Bullet — Engine-agnostic moving projectile sugar.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * A small `LargeObject` that advances horizontally each tick via
+ * `universe.updateObjectProperty(handle, 'LargeObject', 'rect', [...])`.
+ * The tick function is pushed onto `universe.experimentTickFunctions` so the
+ * Bullet self-drives: no external per-tick call needed.
+ *
+ * @param {Object} universe - Engine universe instance (JS or WASM compat shim),
+ *   already init'd (init() is called by the enclosing setup factory, not here).
+ * @param {Object} [opts] - Configuration overrides.
+ * @param {number} [opts.x]    - Left edge of the bullet rect (pixels). Default: 0.
+ * @param {number} [opts.y]    - Top edge of the bullet rect (pixels). Default: canvas centre.
+ * @param {number} [opts.w=8]  - Bullet rect width (pixels). Units: pixels.
+ * @param {number} [opts.h=8]  - Bullet rect height (pixels). Units: pixels.
+ * @param {number} [opts.speed=2] - Horizontal advance per tick (pixels/tick). Positive = rightward.
+ *   Keeps within [−1,+1] per-axis speed limit PER MECHANISM — the bullet itself is not a
+ *   quantum, so this limit does not apply here. OBSERVED: speed 2 makes the wake
+ *   dense enough to trigger aggregation into bigger frames. speed 1 makes a wispy trail.
+ * @param {string} [opts.collisionType='BOUNCE'] - CollisionTypes value for quanta that
+ *   intersect the bullet. BOUNCE = deflect quanta (generates the most billowing wake).
+ *   NONE = ghost (visual-only, no physics). WALL = stops quanta dead (hard shadow).
+ * @param {Array}  [opts.color=[40,40,40]] - RGB color for the bullet LO rect (renderer).
+ * @param {string} [opts.name='bullet'] - LargeObject name tag.
+ *
+ * @property {Object} lo     - The underlying LargeObject instance.
+ * @property {*}      handle - The engine handle for the LargeObject (opaque).
+ * @property {number} vx     - Current horizontal speed (px/tick).
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ *
+ * The moving exclude region (BOUNCE) compresses quanta in front and deflects
+ * them to the sides, identical to the static `block 2` shadow in the
+ * Wave-Interference experiment. **The billowing wake is free physics** — no
+ * explicit wake/smoke code.
+ *
+ * When the enclosing setup factory also enables `universe.withInterQuantumCollisions`
+ * and registers extra dimensions (the Blackbody aggregation mechanic), the compressed
+ * quanta behind the bullet parent up the voxel-size ladder into bigger frames. The
+ * renderer (three-provider.js) sizes each puff by `frame.rect.w`, so the emergent
+ * frame-size variation produces the smoke-billow effect: faster bullet → more compression
+ * → more collisions → bigger frames → more prominent puffs.
+ *
+ * The bullet wraps the canvas if `opts.wrap` is true (default: false — the bullet
+ * exits at the right edge and the tick function becomes a no-op when out of bounds).
+ * Set `opts.loop` to restart from the left when the bullet exits the right edge.
+ */
+
+import { LargeObject } from '../../parts/LargeObject.js';
+import { CollisionTypes } from '../../parts/CollisionTypes.js';
+import { ObjectSchema } from '../schema/index.js';
+
+
+    // ── Bullet ──────────────────────────────────────────────────────────────
+
+    /**
+     * Create a moving projectile and register its advance tick function.
+     *
+     * @param {Object} universe - Already-init'd universe (JS or WASM).
+     * @param {Object} [opts]   - See module-level JSDoc above.
+     */
+    function Bullet(universe, opts) {
+        opts = opts || {};
+
+        // The world rect the co-init call wrote (EGPTUniverse.create({rect})) — the ONE size.
+        var world = ObjectSchema.worldRect(universe.universe_rect, 'Bullet universe.universe_rect');
+        var cw = world.w;
+        var ch = world.h;
+
+        var bw   = opts.w    !== undefined ? opts.w    : 8;
+        var bh   = opts.h    !== undefined ? opts.h    : 8;
+        var bx   = opts.x    !== undefined ? opts.x    : 0;
+        var by   = opts.y    !== undefined ? opts.y    : Math.floor(ch / 2) - Math.floor(bh / 2);
+        var vx   = opts.speed         !== undefined ? opts.speed         : 2;
+        var ct   = opts.collisionType !== undefined ? opts.collisionType : CollisionTypes.BOUNCE;
+        var col  = opts.color         !== undefined ? opts.color         : [40, 40, 40];
+        var name = opts.name          !== undefined ? opts.name          : 'bullet';
+        var loop = opts.loop !== undefined ? !!opts.loop : true;
+        // Eject mode for the BOUNCE op-program. 2D default 'closest' (4 faces); a 3D scene
+        // (activeAxes.z) passes 'closest3d' so quanta can be pushed out the near/far z faces too.
+        var repo = opts.reposition !== undefined ? opts.reposition : 'closest';
+
+        // Mutable state — advanced by the tick function below.
+        // rect is [left, top, w, h] (is_centered=false convention, same as LargeObject).
+        var _left = bx;
+        var _top  = by;
+
+        this.lo = new LargeObject(
+            universe,
+            [_left, _top, bw, bh],
+            CollisionTypes.NONE, ['BOUNCE'],
+            name, repo, null, 1,
+            col
+        );
+        // ── Render shape (renderer-only hints; physics is unaffected) ──────────────
+        // shape:'box' → the provider wraps the LO with a 3D BoxGeometry (a solid cube of
+        // w×h×depth) instead of a flat plane, so the projectile reads as a real 3D object
+        // from every angle. A box has volume, so it does NOT billboard. Any other shape
+        // (default: a flat plane) billboards to face the camera (a disc coming AT the viewer).
+        this.lo.shape = (opts.shape !== undefined) ? opts.shape : 'box';
+        this.lo.depth = (opts.depth !== undefined) ? opts.depth : bw;   // cube z-extent
+        if (this.lo.shape === 'box') {
+            this.lo.billboard = false;                                   // a cube doesn't billboard
+        } else {
+            this.lo.billboard = (opts.billboard !== undefined) ? !!opts.billboard : true;
+        }
+        this.handle = this.lo.handle;
+        this.vx     = vx;
+
+        var self = this;
+
+        /**
+         * Advance the bullet one tick.
+         * Registered on universe.experimentTickFunctions so this runs as Phase A
+         * injection for the next tick.
+         *
+         * When the bullet exits the right edge (left > cw) and opts.loop is true,
+         * it wraps back to the left edge so the demo runs continuously.
+         * When loop is false the rect is left at the exit position — the LO
+         * still exists but no longer intersects any quanta.
+         */
+        this.tick = function () {
+            _left += self.vx;
+            if (_left > cw) {
+                if (loop) {
+                    _left = -bw;   // re-enter from left
+                } else {
+                    return;        // off-screen — stop advancing
+                }
+            }
+            // Mutate the JS LargeObject wrapper's rect so the RENDERER moves the bullet —
+            // it reads the world census entry's .rect each frame. `universe.updateObjectProperty`
+            // does NOT touch the JS wrapper (only FrqtlApp.updateObjectProperty does —
+            // see wasm-engine.js:513-516 + FrqtlApp.js:422); the bullet tick-fn only
+            // has `universe`, so we mirror that wrapper-mutate here (Rectangle .left/.top setters).
+            self.lo.rect.left = _left;
+            self.lo.rect.top  = _top;
+            // Move the engine-side collision region too, so the compression wake follows the bullet.
+            universe.updateObjectProperty(
+                self.handle, 'LargeObject', 'rect',
+                [_left, _top, bw, bh]
+            );
+        };
+
+        universe.experimentTickFunctions.push(this.tick);
+    }
+
+    // ── Export ───────────────────────────────────────────────────────────────
+
+    export { Bullet };
+