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

package/dist/frqtl/objects/ObjectFactory.js

@@ -0,0 +1,297 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * ObjectFactory — registry-driven construction of all placeable object kinds.
+ *
+ * This is the ONE canonical construction path for every IDE-placeable kind.
+ * It was extracted from lib/features/ide/project-design.js `buildObject` in
+ * Phase 1 of the ObjectFactory refactor so the construction logic lives in
+ * the objects layer (engine-agnostic) rather than in the IDE feature layer.
+ *
+ * API:
+ *   ObjectFactory.create(kind, config, ctx)
+ *     kind   — placeable kind string (e.g. 'QuantumEmitter', 'SlitScreen')
+ *     config — override props (merged over schema defaultProps)
+ *     ctx    — { runner, x, y, fromPalette? }
+ *              The world size is READ from ctx.runner.canvas_rect — the rect the scene's
+ *              co-init call wrote (exp.createCanvas(w, h, cfg) / exp.createScene(w, h, d, cfg));
+ *              ctx carries no size of its own.
+ *     returns: the DECLARED part (recorded in ctx.runner.declared); THROWS on a kind no
+ *              module registered in this realm, on any build result that is not a handle,
+ *              and on a member LO whose `_owner` chain does not end at the part
+ *
+ *   ObjectFactory.list()   → ObjectSchema.placeableCatalog()
+ *   ObjectFactory.kinds()  → the registered kinds that carry a build
+ *
+ * Construction: the kind's registry row (objects/kinds.js — the part module registered its
+ * descriptor, defaults and build when it was imported) → the generic checks below → the row's
+ * `build(props, ctx)`.
+ *
+ * Behavior contract:
+ *   - Every special case from buildObject is preserved verbatim:
+ *       • QuantumEmitter / PointSource / SphereEmitter: the emitter + a visual
+ *         LargeObject marker it OWNS (attachMarker); the emitter is returned.
+ *       • A builder stamps nothing: each part stamps `_owner` on what it composed,
+ *         and create() declares the returned part with the LOs the build added.
+ *       • PointSource opts dict re-pass (_wavelength, _optColor, _emergentPhysics).
+ *       • layer → observedDimensions=[layer] (null = all dims).
+ *       • SlitLightSource: THROWS naming the pairing (needs a paired SlitScreen).
+ *       • Unknown kind: THROW naming the registered kinds + the V2 replacement.
+ */
+
+import { ObjectSchema } from './schema/index.js';
+import { kindOf, registeredKinds, unregisteredKindMessage } from './kinds.js';
+import { setupSphereEmitter3D } from './setup/setupSphereEmitter3D.js';
+import { SphereEmitter } from '../parts/SphereEmitter.js';
+import { V1_REPLACEMENTS } from './v1-replacements.js';
+
+    // ── Internal helpers ──────────────────────────────────────────────────────
+
+    function _deepCopy(obj) {
+        if (obj === null || typeof obj !== 'object') { return obj; }
+        if (Array.isArray(obj)) { return obj.map(_deepCopy); }
+        var out = {};
+        for (var k in obj) {
+            if (Object.prototype.hasOwnProperty.call(obj, k)) { out[k] = _deepCopy(obj[k]); }
+        }
+        return out;
+    }
+
+    /**
+     * Merge schema defaultProps with caller overrides and return the merged props.
+     * @param {string} kind
+     * @param {object|null} config  — override props (caller-supplied)
+     * @returns {object}
+     */
+    // Construction defaults come from ObjectSchema.defaultPropsFor(kind) — the ONE
+    // per-kind default bag (the `defaults` the kind registered with, objects/kinds.js). NOT from
+    // placeableCatalog(): the palette answers "what can be DROPPED in STUDIO", which
+    // is a strictly smaller set (V2 stock only) than "what a recipe can construct".
+    //
+    function _mergeProps(kind, config) {
+        var defaults = _deepCopy(ObjectSchema.defaultPropsFor(kind));
+        return Object.assign({}, defaults, config || {});
+    }
+
+    // ── CONSTRUCTION_ADAPTERS — ObjectFactory's OWN cross-kind config vocabulary ──
+    //
+    // `create()` already threw on an unknown KIND with the registered list and the
+    // V1→V2 replacement. It never looked at the config's PROP KEYS, so
+    // `create('Wall', { collisonBehavior: 'bounce' })` built a wall that ignored the
+    // typo and silently used its own default — the same silence the setup-factory gate
+    // removes one layer up.
+    //
+    // The schema descriptor alone is NOT the legal set. These keys are read by the
+    // builders (or forwarded verbatim into an object constructor) while being declared
+    // by no kind's field list, so validating on the descriptor alone would reject
+    // working callers. They are ObjectFactory's own construction API — it owns the call
+    // shape — so they are declared HERE, and `objectfactory-prop-keys.test.mjs` asserts
+    // each one is genuinely reachable rather than a list someone widened to silence a
+    // failure.
+    var CONSTRUCTION_ADAPTERS = [
+        // Geometry/identity every builder resolves a rect and a name from. `x`/`y` are
+        // read by RecipeContext.addObject to build ctx before create() runs.
+        'x', 'y', 'w', 'h', 'left', 'top', 'rect', 'layer', 'name',
+        // `preset` is expanded by the OBJECT constructor (Wall.expandWallPreset), not by
+        // a builder — it reaches the constructor through the forwarded props bag.
+        'preset',
+        // Codegen round-trip adapters: a PointSource's construction-only opts, which codegen
+        // writes back onto its config (lib/features/ide/codegen.js).
+        '_wavelength', '_optColor', '_emergentPhysics'
+    ];
+
+    // ── FORWARDED — kinds whose config bag is a PART's option bag, not just a descriptor ──
+    //
+    // A facade kind hands its config to a setup factory, so its legal set includes that
+    // factory's vocabulary. Measured: `emissionBoxSide` is a real SphereEmitter option
+    // that the descriptor does not declare, and gating on the descriptor alone would
+    // reject the walkthrough's own recipes.
+    //
+    // CONSUMED, never retyped: `setupSphereEmitter3D.OPTIONS` and
+    // `SphereEmitter.FACADE_OPTIONS` are the owners' exported contracts.
+    function _forwardedVocabulary(kind) {
+        if (kind !== 'SphereEmitter') { return []; }
+        var out = [];
+        var f = setupSphereEmitter3D;
+        var o = SphereEmitter;
+        if (f.OPTIONS) { out = out.concat(f.OPTIONS); }
+        // Retired names pass THROUGH this gate so the owner's specific migration message
+        // wins over a generic "unknown prop key" (the a1f1b324 control-D ordering, again).
+        if (f.RETIRED_OPTIONS) { out = out.concat(f.RETIRED_OPTIONS); }
+        if (o.FACADE_OPTIONS) { out = out.concat(o.FACADE_OPTIONS); }
+        return out;
+    }
+
+    /**
+     * Throw on a config key that no kind, default, adapter or forwarded vocabulary
+     * declares. Every list is DERIVED (from the schema `create()` already resolved, or
+     * from an owner's export) — nothing here re-enumerates another module's fields.
+     */
+    function _assertPropKeys(kind, config) {
+        if (!config) { return; }
+        var descriptor = ObjectSchema.get(kind);
+        if (!descriptor || !descriptor.fields) { return; }
+
+        var legal = {};
+        descriptor.fields.forEach(function (f) { legal[f.name] = true; });
+        Object.keys(ObjectSchema.defaultPropsFor(kind)).forEach(function (k) { legal[k] = true; });
+        CONSTRUCTION_ADAPTERS.forEach(function (k) { legal[k] = true; });
+        _forwardedVocabulary(kind).forEach(function (k) { legal[k] = true; });
+
+        var unknown = Object.keys(config).filter(function (k) { return !legal[k]; });
+        if (!unknown.length) { return; }
+
+        var declaredFields = descriptor.fields.map(function (f) { return f.name; }).sort();
+        throw new Error(
+            '[ObjectFactory] create("' + kind + '"): unknown prop key' +
+            (unknown.length > 1 ? 's' : '') + ' ' + unknown.map(function (k) {
+                return '"' + k + '"';
+            }).join(', ') + '. The builder reads only declared props, so this would have ' +
+            'been merged in, read by nobody, and the object built with ITS OWN default — ' +
+            'a different scene than the one you wrote, with no signal. "' + kind +
+            '" declares: ' + declaredFields.join(', ') +
+            '. Construction adapters: ' + CONSTRUCTION_ADAPTERS.slice().sort().join(', ') + '.'
+        );
+    }
+
+    /**
+     * A `writeOnly` descriptor field is a live reposition ADAPTER (a SphereEmitter's or a Tunnel's
+     * `rect`): it moves a built part, and its read getter derives from the part's real position
+     * fields. It is never a construction key — the part is built from those real fields — so a
+     * config carrying one THROWS here rather than being dropped silently by the builder.
+     */
+    function _refuseWriteOnlyKeys(kind, config) {
+        if (!config) { return; }
+        var descriptor = ObjectSchema.get(kind);
+        if (!descriptor || !descriptor.fields) { return; }
+        var wo = descriptor.fields.filter(function (fd) { return fd.writeOnly === true && config[fd.name] !== undefined; });
+        if (!wo.length) { return; }
+        var real = descriptor.fields.filter(function (fd) { return !fd.writeOnly; }).map(function (fd) { return fd.name; });
+        throw new Error('[ObjectFactory] create("' + kind + '"): "' + wo[0].name + '" is a write-only reposition ' +
+            'adapter (it moves a built ' + kind + '), not a construction key. Declare the position with the ' +
+            'fields the part is built from: ' + real.join(', ') + '. (FAIL-LOUD.)');
+    }
+
+
+    // How many objects of `kind` this runner has declared — the ordinal a numbered default name
+    // ('emitter N', 'source N') carries.
+    function declaredCount(runner, kind) {
+        return runner.declared.filter(function (d) { return d._schemaKind === kind; }).length;
+    }
+
+    // ── ObjectFactory ─────────────────────────────────────────────────────────
+
+    var ObjectFactory = {
+        /**
+         * Construct a placeable object of the given kind and DECLARE it: the part the builder
+         * returns (never one of its members) is recorded in `ctx.runner.declared` with the census LOs
+         * the build added as its members and the host tick-functions the build pushed
+         * (`FrqtlApp.declare` — this is its ONE call site). What a
+         * declaring call (`exp.addObject`, a palette drop, a codegen replay) produced is what STUDIO
+         * holds; a part's composition is never declared.
+         *
+         * FAIL-LOUD: an unknown kind THROWS naming the registered kinds and, when
+         * the kind is a removed V1 part, its V2 replacement composition. A recipe
+         * whose builder no longer exists must never half-run into a scene with
+         * missing parts.
+         *
+         * @param {string|Function} kind — the kind name, or its registered class
+         * @param {object|null} config  — override props (merged over schema defaultProps)
+         * @param {object} ctx          — { runner, x, y, fromPalette? } (the size is runner.canvas_rect)
+         * @returns {object}            — the declared part (a Tunnel, not its plate; a SphereEmitter, not its marker)
+         * @throws {Error} on a kind no module registered here, a kind registered without a build,
+         *                 a ctx without a runner, or a build result that is not a handle
+         */
+        create: function (kind, config, ctx) {
+            if (!ctx || !ctx.runner) {
+                throw new Error('[ObjectFactory] create("' + kind + '"): ctx.runner is required — ' +
+                    'pass { runner, x, y }.');
+            }
+            if (typeof kind === 'function') {
+                // A kind is named by its class: the class itself is the import-form spelling.
+                if (!kindOf(kind)) {
+                    throw new Error('[ObjectFactory] create: the class ' + (kind.name || '(anonymous)') + ' is not a ' +
+                        'registered kind in this realm — ' + unregisteredKindMessage(kind.name || '?') + '. (FAIL-LOUD.)');
+                }
+                kind = kind.name;
+            }
+            var row = kindOf(kind);
+            if (!row) {
+                var msg = '[ObjectFactory] create: unknown kind "' + kind + '". Registered kinds: ' +
+                    ObjectFactory.kinds().slice().sort().join(', ') + '. The ' + unregisteredKindMessage(kind) + '.';
+                if (Object.prototype.hasOwnProperty.call(V1_REPLACEMENTS, kind)) {
+                    msg += ' "' + kind + '" is a retired V1 part, not a published part — compose ' + V1_REPLACEMENTS[kind] + ' instead ' +
+                        '(docs/internal/engine/V2_PARTS_CLASSIFICATION.md).';
+                }
+                throw new Error(msg + ' (FAIL-LOUD.)');
+            }
+            if (typeof row.build !== 'function') {
+                throw new Error('[ObjectFactory] create: kind "' + kind + '" registers a descriptor only — it is not ' +
+                    'constructed by ObjectFactory; construct it with new ' + kind + '(…) (' + row.from + '). (FAIL-LOUD.)');
+            }
+
+            // ORDER IS LOAD-BEARING: the unknown-KIND throw runs first (it names the V1→V2
+            // replacement), then the prop-key check, then the merge. Validating props for a
+            // kind that does not exist would replace a useful migration message with a
+            // confusing field list.
+            _assertPropKeys(kind, config);
+            _refuseWriteOnlyKeys(kind, config);
+
+            var props = _mergeProps(kind, config);
+
+            var runner = ctx.runner;
+            var before = new Set(runner.largeObjects);
+            var tfs = (runner.universe && Array.isArray(runner.universe.experimentTickFunctions))
+                ? runner.universe.experimentTickFunctions : null;
+            var ticksBefore = new Set(tfs || []);
+            var handle = row.build(props, ctx, row.Class);   // the registry builds the class that registered
+            if (handle === null || typeof handle !== 'object') {
+                throw new Error('[ObjectFactory] create("' + kind + '"): the builder returned ' +
+                    (handle === null ? 'null' : typeof handle) + ', not a handle. Every kind returns ' +
+                    'the object it built or throws naming what is missing — a non-handle here is a ' +
+                    'part silently absent from the scene. (FAIL-LOUD.)');
+            }
+            if (typeof runner.declare !== 'function') {
+                throw new Error('[ObjectFactory] create("' + kind + '"): ctx.runner has no declare() — the ' +
+                    'runner (FrqtlApp) owns the declared-object registry every created part is recorded in. ' +
+                    '(FAIL-LOUD.)');
+            }
+            // THE ONE REGISTRATION SITE: what a declaring call produced is the declared object; its
+            // members are exactly the census LOs the build added (each must resolve up `_owner` to it).
+            var members = runner.largeObjects.filter(function (lo) { return !before.has(lo); });
+            if (!members.length) {
+                throw new Error('[ObjectFactory] create("' + kind + '"): the build put nothing in the world — ' +
+                    'every part draws at least one LO, so a part with none is silently absent from the ' +
+                    'scene. (FAIL-LOUD.)');
+            }
+            // ... and the host tick-functions it pushed are the declaration's too (an emitter's emit
+            // fn, an absorb radiator): behaviour the declaration owns, so codegen may write it down.
+            var tfsAfter = (runner.universe && Array.isArray(runner.universe.experimentTickFunctions))
+                ? runner.universe.experimentTickFunctions : [];
+            var ticks = tfsAfter.filter(function (fn) { return !ticksBefore.has(fn); });
+            runner.declare(handle, members, ticks);
+            return handle;
+        },
+
+        /**
+         * Returns the schema-driven palette catalog.
+         * Delegates to ObjectSchema.placeableCatalog().
+         * @returns {Array}
+         */
+        list: function () {
+            return ObjectSchema.placeableCatalog();
+        },
+
+        /**
+         * The registered kinds that carry a build (constructible through create()).
+         * @returns {string[]}
+         */
+        kinds: function () {
+            return registeredKinds().filter(function (k) { return typeof kindOf(k).build === 'function'; });
+        }
+    };
+
+    // ── Export ────────────────────────────────────────────────────────────────
+
+export { ObjectFactory, declaredCount };
+

package/dist/frqtl/objects/RecipeContext.js

@@ -0,0 +1,322 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * RecipeContext — the recipe facade (`exp`) a scene's buildExperiment(exp) is evaluated against.
+ *
+ * A scene's FIRST statement co-initializes its display and its universe — one call, one rect,
+ * named by the renderer it initializes (the Pixi `new Application({width, height})` / p5
+ * `createCanvas(w, h)` line of a FRQTL sketch):
+ *
+ *   exp.createCanvas(w, h, worldCfg)       p5:    a 2D canvas AND a 2D universe of exactly w×h
+ *   exp.createScene(w, h, d, worldCfg)     three: a 3D scene AND a 3D universe w×h×d
+ *
+ * That call is the ONLY place a world size is written: the facade is constructed SIZELESS
+ * (`{canvasParentId, seed, onTick, …}`) and builds its runner INSIDE the call
+ * (`new FrqtlApp({canvasW: w, canvasH: h, …})` → `runner.createCanvas()` →
+ * `universe.init(...FrqtlWorldInit.initArgs(cfg))`). `worldCfg` is the world
+ * vocabulary minus what the call owns (`FrqtlWorldInit.INIT_CFG`; a size, `activeAxes` or
+ * `depth` in it THROWS naming this call). 2D ⇒ the engine's {x,y} default; 3D ⇒ {x,y,z} and the
+ * explicit depth d.
+ *
+ *   exp.world                     the ONE readable answer: frozen {renderer, w, h, d, cfg}
+ *   exp.addObject(kind, config)   ObjectFactory.create(kind, config, ctx) sugar
+ *   exp.addTickFunction(fn)       universe.experimentTickFunctions.push
+ *   exp.render(bag)               runner.setRenderOptions(bag)
+ *   exp.build(buildFn)            run the recipe WITHOUT starting the loop (a sketch held as
+ *                                 TEXT is a project, linked first: lib/shim/project/link.js linkProject)
+ *   exp.run(buildFn)              build (if needed) + start the loop
+ *   exp.runner / .universe        the runner the co-init call built
+ *   exp.is3D                      world.renderer === 'three'
+ *
+ * FAIL-LOUD: every member that needs the world THROWS before the call; a second call in one
+ * recipe run THROWS; a call naming a renderer the host did not boot THROWS; a recipe that returns
+ * without a world THROWS from build(); `exp.init(cfg)` is DELETED and throws naming the two
+ * methods. None degrades to a default size.
+ *
+ * The page's facade: build()/run() make THIS facade the page's experiment (`pageExperiment()`,
+ * read by a host frame through the page door as FrqtlPage.experiment); the runner it built is the
+ * page's runner once its loop starts (FrqtlApp `pageRunner()`).
+ */
+
+import { FrqtlApp } from './FrqtlApp.js';
+import { ObjectFactory } from './ObjectFactory.js';
+import { FrqtlWorldInit } from './setup/_worldInit.js';
+import * as FrqtlDisplay from '../compat/renderer/display-slot.js';
+import { refuseRetiredDoors } from '../compat/engine.js';
+
+    /** The world-init contract (objects/setup/_worldInit.js). */
+    function _worldInit() {
+        return FrqtlWorldInit;
+    }
+
+    /** The display slot's booted renderer name (FrqtlDisplay — the ONE display owner). */
+    function _bootedRenderer() {
+        var n = FrqtlDisplay.name();
+        if (!n) {
+            throw new Error('[RecipeContext] no display is booted (FrqtlDisplay.name() is empty): the host ' +
+                'boots the renderer the scene\'s registry row names (renderState.renderer) before the ' +
+                'scene runs. (FAIL-LOUD.)');
+        }
+        return n;
+    }
+
+    var COINIT = 'exp.createCanvas(w, h, cfg) (p5, 2D) or exp.createScene(w, h, d, cfg) (three, 3D)';
+    var NO_WORLD = '[RecipeContext] the scene has not created its world — its first statement is ' + COINIT + '.';
+
+    // The ctor options a SIZELESS facade forwards to the runner it builds (everything but a size).
+    var RUNNER_OPTS = ['canvasParentId', 'seed', 'tickHz', 'drawHz', 'stepsPerFrame', 'onTick', 'onReady', 'engine'];
+    var FACADE_OPTS = RUNNER_OPTS.concat(['deferCanvas']);
+
+    /**
+     * @param {Object} [opts] — `{canvasParentId, seed, onTick, onReady, tickHz, drawHz, stepsPerFrame,
+     *   engine, deferCanvas}`. NO size and NO 3D flag: the scene's co-init call states both.
+     *   `deferCanvas:true` leaves `runner.createCanvas()` to a host mount seam (the notebook realm).
+     */
+    function RecipeContext(opts) {
+        opts = opts || {};
+        Object.keys(opts).forEach(function (k) {
+            if (FACADE_OPTS.indexOf(k) === -1) {
+                throw new Error('[RecipeContext] unknown option "' + k + '" — the facade is SIZELESS: it takes ' +
+                    FACADE_OPTS.join(', ') + '. A world size (canvasW/canvasH) or 3D-ness is the scene\'s, ' +
+                    'stated by ' + COINIT + '. (FAIL-LOUD.)');
+            }
+        });
+        this._opts   = opts;
+        this._runner = null;    // built by the co-init call
+        this._world  = null;    // set by the co-init call; reset by build()
+        this._built  = false;
+        this._buildFn = null;
+    }
+
+    function _requireWorld(self) {
+        if (!self._world) { throw new Error(NO_WORLD); }
+    }
+
+    Object.defineProperty(RecipeContext.prototype, 'world', { get: function () { return this._world; } });
+    Object.defineProperty(RecipeContext.prototype, 'runner', {
+        get: function () { _requireWorld(this); return this._runner; }
+    });
+    Object.defineProperty(RecipeContext.prototype, 'universe', {
+        get: function () { _requireWorld(this); return this._runner.universe; }
+    });
+    /** READ-ONLY: did THIS scene make a 3D world? The method it called answers (three ⇔ 3D). */
+    Object.defineProperty(RecipeContext.prototype, 'is3D', {
+        get: function () { _requireWorld(this); return this._world.renderer === 'three'; }
+    });
+
+    // ── the co-init call ─────────────────────────────────────────────────────────────
+
+    function _coinit(self, method, renderer, w, h, d, cfg) {
+        var where = 'RecipeContext.' + method;
+        if (self._world) {
+            throw new Error('[' + where + '] one world per scene: this recipe already created ' +
+                JSON.stringify({ renderer: self._world.renderer, w: self._world.w, h: self._world.h, d: self._world.d }) +
+                '. (FAIL-LOUD.)');
+        }
+        [['w', w], ['h', h]].concat(renderer === 'three' ? [['d', d]] : []).forEach(function (p) {
+            if (typeof p[1] !== 'number' || !(p[1] > 0)) {
+                throw new Error('[' + where + '] ' + p[0] + ' must be a positive number (got ' + JSON.stringify(p[1]) +
+                    ') — every scene states its whole world' + (p[0] === 'd' ? '; the engine\'s cube default is not relied on' : '') +
+                    '. (FAIL-LOUD.)');
+            }
+        });
+        cfg = cfg || {};
+        var W = _worldInit();
+        W.assertInitCfg(where + '(…, cfg)', cfg, null);
+        var booted = _bootedRenderer();
+        if (booted !== renderer) {
+            var err = new Error('[' + where + '] the scene calls ' + method + ' (' + renderer + ') but the host ' +
+                'booted "' + booted + '" — the host\'s display (a registry row\'s renderState.renderer, bootScene\'s ' +
+                'opts.renderer) and the scene disagree. (FAIL-LOUD.)');
+            err.frqtlRequiredRenderer = renderer;
+            err.frqtlBootedRenderer = booted;
+            throw err;
+        }
+        if (self._runner) {
+            // Restart on the same page replays the same single call: the runner (and its canvas)
+            // already ARE that world. A different world needs a fresh page.
+            var r = self._runner.canvas_rect;
+            if (r.w !== w || r.h !== h || self._runner._depth !== (renderer === 'three' ? d : null) ||
+                self._runner._is3D !== (renderer === 'three')) {
+                throw new Error('[' + where + '] this page already holds a ' + r.w + 'x' + r.h + ' world; a scene ' +
+                    'with a different world needs a fresh page. (FAIL-LOUD.)');
+            }
+        } else {
+            var ropts = { canvasW: w, canvasH: h, is3D: renderer === 'three' };
+            if (renderer === 'three') { ropts.canvasD = d; }
+            RUNNER_OPTS.forEach(function (k) { if (self._opts[k] !== undefined) { ropts[k] = self._opts[k]; } });
+            self._runner = new FrqtlApp(ropts);
+            if (!self._opts.deferCanvas) { self._runner.createCanvas(); }
+        }
+        var u = self._runner.universe;
+        var args = W.initArgs(cfg);
+        if (renderer === 'three') {
+            args[1].activeAxes = { x: true, y: true, z: true };
+            args[1].depth = d;
+        }
+        // A (re-)inited world has no declared objects; the recipe re-declares what it builds.
+        self._runner.clearDeclared();
+        W.applyPreInit(cfg, u);   // pre-init world keys (iframeIntervalSeconds) — the engine reads them at init
+        u.init.apply(u, args);
+        self._world = Object.freeze({ renderer: renderer, w: w, h: h, d: renderer === 'three' ? d : null,
+                                      cfg: Object.freeze(Object.assign({}, cfg)) });
+        return self;
+    }
+
+    /** p5: a 2D canvas AND a 2D universe of exactly w×h. */
+    RecipeContext.prototype.createCanvas = function (w, h, cfg) {
+        if (arguments.length > 3) {
+            throw new Error('[RecipeContext.createCanvas] takes (w, h, cfg) — a 2D world has no depth; a 3D ' +
+                'world is exp.createScene(w, h, d, cfg). (FAIL-LOUD.)');
+        }
+        return _coinit(this, 'createCanvas', 'p5', w, h, null, cfg);
+    };
+
+    /** three: a 3D scene AND a 3D universe w×h×d (d REQUIRED). */
+    RecipeContext.prototype.createScene = function (w, h, d, cfg) {
+        return _coinit(this, 'createScene', 'three', w, h, d, cfg);
+    };
+
+    // ── deleted: init(cfg) / initCfg ─────────────────────────────────────────────────
+    RecipeContext.prototype.init = function () {
+        throw new Error('[RecipeContext] exp.init(cfg) is DELETED — a scene states its world, size included, ' +
+            'with ' + COINIT + '. (FAIL-LOUD: a saved module carrying exp.init( must be re-saved.)');
+    };
+    Object.defineProperty(RecipeContext.prototype, 'initCfg', {
+        get: function () {
+            throw new Error('[RecipeContext] exp.initCfg is DELETED — read exp.world ({renderer, w, h, d, cfg}). (FAIL-LOUD.)');
+        }
+    });
+
+    // ── parts, tick-fns, render ──────────────────────────────────────────────────────
+
+    RecipeContext.prototype.addObject = function (kind, config) {
+        _requireWorld(this);
+        var x = (config && config.x != null) ? config.x : 0;
+        var y = (config && config.y != null) ? config.y : 0;
+        var ctx = { runner: this._runner, cw: null, x: x, y: y };
+        return ObjectFactory.create(kind, config, ctx);
+    };
+
+    RecipeContext.prototype.addTickFunction = function (fn) {
+        _requireWorld(this);
+        var fns = this._runner.universe.experimentTickFunctions;
+        fns.push(fn);
+        return fns.length - 1;
+    };
+
+    /** Name the recipe's LOOK in one call — a pure ferry to `runner.setRenderOptions(bag)`. */
+    RecipeContext.prototype.render = function (bag) {
+        _requireWorld(this);
+        this._runner.setRenderOptions(bag);
+        return this;
+    };
+
+    // ── build / run ──────────────────────────────────────────────────────────────────
+
+    /**
+     * Tear down the scene a previous build put on THIS runner, before a same-runner rebuild
+     * (`restart()`, a re-applied module on a live page): FAIL-LOUD, never a sweep.
+     *
+     * OWNERSHIP: `universe.experimentTickFunctions` is the SCENE's (primitive #3) — rebuilt by the
+     * replay, so the old scene's entries must all be gone first. `runner.addTickListener` is the
+     * HOST's (a recorder, a live chart, a per-tick lerp) and SURVIVES the rebuild untouched.
+     *
+     *   1. stop the loop;
+     *   2. read the scene's UNDECLARED tick-fns (`exp.addTickFunction`) while the registry still
+     *      says which fns the declared parts own;
+     *   3. remove every declared object through `runner.removeObject` — the one per-part path
+     *      (registry drop → its own dispose() → census check, which THROWS naming a part whose
+     *      dispose() left a tick-fn or an LO behind);
+     *   4. splice the undeclared fns read at step 2;
+     *   5. ASSERT the list is empty — a survivor is a tick-fn nothing owned, never cleared for it.
+     */
+    function _teardownSceneForRebuild(self) {
+        var runner = self._runner;
+        runner.stop();
+        var fns = runner.universe.experimentTickFunctions;
+        var undeclared = runner.undeclaredTickFunctions();
+        var declared = runner.declared.slice();
+        for (var i = declared.length - 1; i >= 0; i--) { runner.removeObject(declared[i]); }
+        for (var j = 0; j < undeclared.length; j++) {
+            var at = fns.indexOf(undeclared[j]);
+            if (at !== -1) { fns.splice(at, 1); }
+        }
+        if (fns.length) {
+            throw new Error('[RecipeContext.build] rebuilding on the same runner: ' + fns.length + ' tick-function(s) ' +
+                'of the previous scene survived its teardown (' + fns.map(function (fn, k) {
+                    return fn.name ? fn.name : '<anonymous #' + k + '>'; }).join(', ') + ') — no declared part ' +
+                'owned them and the scene did not add them (exp.addTickFunction). Host per-tick work belongs ' +
+                'on runner.addTickListener, which survives a rebuild. (FAIL-LOUD.)');
+        }
+    }
+
+    /**
+     * Run a recipe WITHOUT starting the loop. Resets `world` first, so a re-run replays the same
+     * single co-init call; a recipe that returns without creating its world THROWS. On a runner a
+     * previous build already holds, the previous scene is torn down first (_teardownSceneForRebuild:
+     * the scene's tick-fns go, the host's tick listeners stay). A successful build RETAINS its
+     * replay on the runner (`runner.retainSceneReplay`), so `runner.restart()` — and a sketch's
+     * declared `restart` control — replays this build on the same runner and canvas.
+     */
+    RecipeContext.prototype.build = function (buildFn) {
+        if (buildFn && typeof buildFn === 'function') {
+            this._buildFn = buildFn;
+            if (this._runner) { _teardownSceneForRebuild(this); }
+            this._world = null;
+            buildFn(this);
+            if (!this._world) {
+                throw new Error('[RecipeContext.build] the scene never created its world — its first statement ' +
+                    'must be ' + COINIT + '. (FAIL-LOUD.)');
+            }
+            this._built = true;
+            var self = this;
+            this._runner.retainSceneReplay(function () { return self.build(self._buildFn); });
+        }
+        setPageExperiment(this);
+        return this;
+    };
+
+    RecipeContext.prototype.run = function (buildFn) {
+        if (buildFn && typeof buildFn === 'function' && !this._built) { this.build(buildFn); }
+        _requireWorld(this);
+        setPageExperiment(this);
+        this._runner.start();
+    };
+
+    // The world-init contract is NOT a RecipeContext static: reading one of its names THROWS.
+    ['INIT_CFG', 'assertInitCfg', 'initArgs'].forEach(function (name) {
+        Object.defineProperty(RecipeContext, name, {
+            get: function () {
+                throw new Error('RecipeContext.' + name + ' does not exist: the world-cfg contract is ' +
+                    'FrqtlWorldInit.' + name + ' (objects/setup/_worldInit.js).');
+            }
+        });
+    });
+
+    /** Retired facade members → the message reading one throws (compat/engine.js refuseRetiredDoors). */
+    var RETIRED_RECIPE_DOORS = Object.freeze({
+        buildSource: '[RecipeContext] exp.buildSource(src) is retired — a sketch held as text is a project: boot it ' +
+            'with bootProject(mount, { files: { "sketch.js": src }, entry: "sketch.js" }) (@descix/frqtl-web/boot), or ' +
+            're-scene a booted facade with exp.build((await linkProject({ files, entry, mint })).buildExperiment) ' +
+            '(lib/shim/project/link.js). (FAIL-LOUD.)'
+    });
+    refuseRetiredDoors(RecipeContext.prototype, RETIRED_RECIPE_DOORS);
+
+    // ── The page's experiment ─────────────────────────────────────────────────
+    // The facade a page built its scene through (or, on the empty page, the sizeless facade it
+    // constructed for hosts to apply scenes against). The page door (experiments/_shared/page-door.js)
+    // reads it as FrqtlPage.experiment — this is its ONE store.
+    var _pageExperiment = null;
+    /** @param {RecipeContext} exp */
+    function setPageExperiment(exp) {
+        if (!(exp instanceof RecipeContext)) {
+            throw new TypeError('[RecipeContext] setPageExperiment(exp): expected a RecipeContext. (FAIL-LOUD.)');
+        }
+        _pageExperiment = exp;
+    }
+    /** @returns {RecipeContext|null} */
+    function pageExperiment() { return _pageExperiment; }
+
+    export { RecipeContext, RETIRED_RECIPE_DOORS, setPageExperiment, pageExperiment };
+