@descix/frqtl-node 0.6.0-p0.2 → 0.6.0-p4.1

package/dist/frqtl/compat/renderer/lo-drawn-center.js

@@ -28,6 +28,16 @@
  *     z absent  → [cx − w/2, cy − h/2, w, h], and cz must be 0 — a z-less rect sits at z-centre
  *                 0 by the rule above, so any other cz THROWS rather than being dropped.
  *
+ * A HAND places on the pixel lattice (frames sit on integer pixels; a hand between pixels is a
+ * screen-scale artifact), so every hand write is snapped once, here:
+ *
+ *   snapRectPosition(t) → a rect write tuple with its POSITION on the lattice: `Math.round` of left,
+ *     top (and z of a 6-tuple); the size (w, h, d) is returned byte-identical — a hand moves, it never
+ *     resizes.
+ *   snapCenter(c) → a centre ([x, y] / [x, y, z]) with every component rounded.
+ *   Both are called by the hand doors only (FrqtlApp.placeDeclaredAt; STUDIO's drag / resize write). A
+ *   value typed into a field is the user's literal and is never snapped; no build path calls them.
+ *
  * ── The drawn VOLUME and the center-ray hit (STUDIO's aim) ──────────────────────
  *
  * The same rect also owns the VOLUME the aim ray tests and the shadow-surround paints, so the
@@ -94,6 +104,7 @@ function rectAtCenter(rect, center) {
 var DEG = Math.PI / 180;
 
 /** The rect's z-extent: d ?? w when it carries z (the engine's z-capable rectangle), else 0. */
+function zExtent(rect) { return _zExtent(rect); }
 function _zExtent(rect) {
     if (!hasZ(rect)) { return 0; }
     return (typeof rect.d === 'number') ? rect.d : rect.w;
@@ -220,9 +231,39 @@ function firstHit(origin, dir, volumes, margin) {
     return best;
 }
 
+function _finiteTuple(v, who, lengths) {
+    if (!Array.isArray(v) || lengths.indexOf(v.length) === -1 ||
+        !v.every(function (n) { return typeof n === 'number' && isFinite(n); })) {
+        throw new TypeError('[LoDrawnCenter.' + who + '] ' + lengths.join(' or ') + ' finite numbers; got ' +
+            JSON.stringify(v) + '. (FAIL-LOUD.)');
+    }
+}
+
+/**
+ * snapRectPosition(t) — a hand's rect write with its position on the pixel lattice, its size untouched.
+ * @param {number[]} t — [left, top, w, h] or [left, top, z, w, h, d] (RECT_TUPLE order) @returns {number[]}
+ */
+function snapRectPosition(t) {
+    _finiteTuple(t, 'snapRectPosition', [4, 6]);
+    var npos = t.length === 6 ? 3 : 2;
+    return t.map(function (n, i) { return i < npos ? Math.round(n) : n; });
+}
+
+/**
+ * snapCenter(c) — a hand's centre write on the pixel lattice: every component rounded.
+ * @param {number[]} c — [x, y] or [x, y, z] @returns {number[]}
+ */
+function snapCenter(c) {
+    _finiteTuple(c, 'snapCenter', [2, 3]);
+    return c.map(function (n) { return Math.round(n); });
+}
+
 export {
     drawnCenter,
     rectAtCenter,
+    snapRectPosition,
+    snapCenter,
+    zExtent,
     hasZ,
     drawnVolume,
     rayIntersect,

package/dist/frqtl/experiments/_shared/boot-failure.js

@@ -0,0 +1,60 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * boot-failure.js — THE one boot-failure overlay painter.
+ *
+ *   paintBootFailure(axis, msg)   paint a FAIL-LOUD overlay for a boot axis ('engine' | 'renderer')
+ *   setBootOverlayHost(el)        scope later overlays into `el` (the boot's `overlayHost`)
+ *
+ * A leaf: the boot module (boot.js) and any runner that discovers a boot fault after the boot
+ * (FrqtlApp's empty-display-slot diagnosis) paint through this ONE painter.
+ */
+
+const AXIS_STYLE = {
+    engine:   { id: 'egpt-engine-error',   marker: 'data-egpt-engine-error',   bg: '#1a0000', fg: '#ff6b6b', border: '#b6161c' },
+    renderer: { id: 'egpt-renderer-error', marker: 'data-egpt-renderer-error', bg: '#000a1a', fg: '#6b9eff', border: '#1640b6' }
+};
+let _overlayHost = null;
+
+/** The element the next overlays paint into (null = the full viewport) — set by the boot from its opts. */
+export function setBootOverlayHost(el) { _overlayHost = el || null; }
+
+/**
+ * THE boot-failure overlay: scoped into the boot's overlay host when one was given, else the full
+ * viewport. One overlay per axis (a second failure on the same axis does not stack). Console-loud too.
+ *
+ * @param {'engine'|'renderer'} axis  'engine' covers every non-renderer boot failure (engine, game layer, sketch)
+ * @param {string} msg
+ */
+export function paintBootFailure(axis, msg) {
+    const st = AXIS_STYLE[axis];
+    if (!st) { throw new Error('[boot] paintBootFailure: axis must be engine | renderer (got ' + JSON.stringify(axis) + ')'); }
+    if (typeof console !== 'undefined' && console.error) { console.error(msg); }
+    function paint() {
+        if (_overlayHost) {
+            if (_overlayHost.querySelector && _overlayHost.querySelector('[' + st.marker + ']')) { return; }
+            const b = document.createElement('div');
+            b.setAttribute(st.marker, '1');
+            b.setAttribute('data-egpt-boot-error', '1');
+            b.style.cssText = 'position:absolute;inset:0;z-index:9998;background:' + st.bg + ';color:' + st.fg + ';' +
+                'font:12px/1.5 ui-monospace,Menlo,Consolas,monospace;padding:14px;white-space:pre-wrap;overflow:auto;' +
+                'border:2px solid ' + st.border + ';';
+            b.textContent = msg;
+            const cs = getComputedStyle(_overlayHost);
+            if (!cs || cs.position === 'static') { _overlayHost.style.position = 'relative'; }
+            _overlayHost.appendChild(b);
+            return;
+        }
+        if (document.getElementById(st.id)) { return; }
+        const b = document.createElement('div');
+        b.id = st.id;
+        b.setAttribute('data-egpt-boot-error', '1');
+        b.style.cssText = 'position:fixed;inset:0;z-index:99999;background:' + st.bg + ';color:' + st.fg + ';' +
+            'font:13px/1.55 ui-monospace,Menlo,Consolas,monospace;padding:22px;white-space:pre-wrap;overflow:auto;' +
+            'border:2px solid ' + st.border + ';';
+        b.textContent = msg;
+        (document.body || document.documentElement).appendChild(b);
+    }
+    if (document.body) { paint(); } else { addEventListener('DOMContentLoaded', paint); }
+}
+

package/dist/frqtl/objects/FrqtlApp.js

@@ -62,6 +62,8 @@
  */
 
 import { ObjectSchema } from './schema/index.js';
+import { kindOf as _kindRow } from './kinds.js';
+import { moduleOfKind } from '../../shim/project/parts-module.js';
 import { FrqtlCapture } from './instruments/capture.js';
 import * as FrqtlDisplay from '../compat/renderer/display-slot.js';
 import * as RendererProviderContract from '../compat/renderer/renderer-provider-contract.js';
@@ -867,9 +869,19 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
      * THROWS here instead of leaking an unresolvable LO into the scene. `tickFns` are the host
      * tick-functions the build pushed (an emitter's emit fn, an absorb radiator): what the
      * declaration owns besides what it draws. THROWS on a re-declaration.
-     * @param {Object} handle @param {Array} members @param {Array} [tickFns] @returns {Object} handle
-     */
-    FrqtlApp.prototype.declare = function (handle, members, tickFns) {
+     *
+     * `row` = { kind } (ObjectFactory.create): the census fields every declared object carries, read as
+     * `d.inParts` / `d.module` off a runner.declared entry (not enumerable, not writable):
+     *   inParts  — true when the object came from the sketch's `export const parts` block (exp.declare),
+     *              or was written into it since (RecipeContext.toSketch); false for a code declaration.
+     *              Set only by RecipeContext, the parts block's one owner (_adoptIntoParts)
+     *   module   — the specifier a sketch imports its kind by (lib/shim/project/parts-module.js
+     *              moduleOfKind over the kind row's `from` and the project files the facade last linked):
+     *              '@descix/frqtl-web/parts', a project path, or null (an internal kind)
+     * @param {Object} handle @param {Array} members @param {Array} [tickFns] @param {{kind: string}} [row]
+     * @returns {Object} handle
+     */
+    FrqtlApp.prototype.declare = function (handle, members, tickFns, row) {
         if (!handle || typeof handle !== 'object') {
             throw new TypeError('[FrqtlApp.declare] a declared object is a handle, got ' + typeof handle + '. (FAIL-LOUD.)');
         }
@@ -893,15 +905,67 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
                     'object. (FAIL-LOUD.)');
             }
         }
+        var kind = (row && row.kind) || handle._schemaKind;
+        var kr = kind ? _kindRow(kind) : null;
+        _setCensusRow(handle, {
+            inParts: false,
+            module: kr ? moduleOfKind(kr.from, this._projectUrls || null) : null
+        });
         return handle;
     };
 
+    // The census fields of each declared object (FrqtlApp.declare). Keyed by the handle; read through two
+    // getters defined on it, so `runner.declared[i].inParts` / `.module` are fields of the one census.
+    var _censusRows = new WeakMap();
+    function _setCensusRow(handle, r) {
+        _censusRows.set(handle, r);
+        if (!Object.prototype.hasOwnProperty.call(handle, 'inParts')) {
+            Object.defineProperty(handle, 'inParts', { configurable: true, enumerable: false,
+                get: function () { var x = _censusRows.get(this); return x ? x.inParts : false; } });
+            Object.defineProperty(handle, 'module', { configurable: true, enumerable: false,
+                get: function () { var x = _censusRows.get(this); return x ? x.module : null; } });
+        }
+    }
+
+    // THE HAND MARK: a declared object a device door wrote since the writer last ran (updateObjectProperty —
+    // a drag, a resize, an Inspector or knob write — and placeDeclaredAt — a carry, a lab's hand). The writer
+    // (RecipeContext.toSketch) writes, or refuses, ONLY marked objects: a part its own scene code moves (a
+    // bullet's flight tick-function) is the run, not a hand.
+    function _markHand(app, x) {
+        var list = app._declared;
+        if (!list || !list.length) { return; }   // nothing declared: no object a writer could write
+        var d = app.declaredOf(x);
+        if (d) { (app._handTouched || (app._handTouched = new Set())).add(d); }
+    }
+    /** _takeHandTouched() → the declared objects a device door wrote since the last call; the call clears the mark. */
+    FrqtlApp.prototype._takeHandTouched = function () {
+        var out = this._handTouched || new Set();
+        this._handTouched = new Set();
+        return out;
+    };
+
+    /**
+     * _adoptIntoParts(d) — `d` is an entry of the parts block (its key is its name): declared there (exp.declare)
+     * or written there (RecipeContext.toSketch). RecipeContext's alone, the parts block's one owner.
+     */
+    FrqtlApp.prototype._adoptIntoParts = function (d) {
+        var x = _censusRows.get(d);
+        if (!x) { throw new Error('[FrqtlApp] _adoptIntoParts: "' + (d && d.name) + '" is not a declared object. (FAIL-LOUD.)'); }
+        x.inParts = true;
+    };
+
+    /** beginWorld() — a (re-)inited world has not stepped: its last TickData is gone (worldTick reads 0, repaint draws nothing). */
+    FrqtlApp.prototype.beginWorld = function () {
+        this._lastTickData = null;
+    };
+
     /** clearDeclared() — empty the registry. Called where the world re-inits (FrqtlApp.setup, and the
      *  RecipeContext co-init exp.createCanvas / exp.createScene): a fresh world has no declared objects. */
     FrqtlApp.prototype.clearDeclared = function () {
         this._declared = [];
         this._declaredMembers = new Map();
         this._declaredTicks = new Map();
+        this._handTouched = new Set();   // a fresh world holds no hand
     };
 
     /**
@@ -1077,6 +1141,14 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
      */
     FrqtlApp.prototype.updateObjectProperty = function (lo, prop, value) {
         if (!lo) return;
+        // A parts entry's name IS its key: no door renames it (toSketch refuses, setDeclared throws, and so does this),
+        // whether addressed by its declared handle or by a member LO of it (declaredOf walks the owner chain).
+        var entry = prop === 'name' ? this.declaredOf(lo) : null;
+        if (entry && entry.inParts) {
+            throw new TypeError('[FrqtlApp.updateObjectProperty] "name" of the parts entry "' + entry.name + '": ' +
+                FrqtlApp.RENAME_REFUSAL + ' (FAIL-LOUD.)');
+        }
+        _markHand(this, lo);
 
         // Every shipped object class STAMPS `_schemaKind` (LargeObject, QuantumEmitter,
         // PointSource, Wall, DetectorWall, SphereEmitter, …), so the
@@ -1443,6 +1515,7 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
      *   where the object now IS (`centerOf`).
      */
     FrqtlApp.prototype.placeDeclaredAt = function (d, point) {
+        _markHand(this, d);
         this._requireDeclared(d, 'placeDeclaredAt');
         if (!Array.isArray(point) || (point.length !== 2 && point.length !== 3) ||
             !point.every(function (v) { return typeof v === 'number' && isFinite(v); })) {
@@ -1463,9 +1536,10 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
                 zHeld = Math.abs(k[2]) > FrqtlApp.Z_HOLD_EPS;
                 k = [k[0], k[1], 0];
             }
-            this.updateObjectProperty(d, 'rect', L.rectAtCenter(d.rect, k));
+            // A hand places on the pixel lattice (LoDrawnCenter: the position snaps, the size is kept).
+            this.updateObjectProperty(d, 'rect', L.snapRectPosition(L.rectAtCenter(d.rect, k)));
         } else {
-            this.updateObjectProperty(d, 'center', k);
+            this.updateObjectProperty(d, 'center', LoDrawnCenter.snapCenter(k));
         }
         return { center: this.centerOf(d), zHeld: zHeld };
     };
@@ -1556,6 +1630,9 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
     /** Beyond this |z| (world px) a carried centre is not expressible by a z-LESS rect (it sits
      *  at z-centre 0 — lo-drawn-center): the object stays on the z = 0 plane and says Z HELD. */
     FrqtlApp.Z_HOLD_EPS = 1e-6;
+    /** The one wording of "a parts entry is never renamed by a hand" (updateObjectProperty, RecipeContext). */
+    FrqtlApp.RENAME_REFUSAL = 'the key is the name — a rename is a new key in `parts` (with every reference to it, ' +
+        'in code) or a fork of the sketch; a hand never writes a `name` into an entry.';
 
     var AIM_OFF = 'off', AIM_ROAMING = 'roaming', AIM_READY = 'grab-ready', AIM_GRABBED = 'grabbed';
 
@@ -2182,9 +2259,10 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
     /**
      * retainSceneReplay(fn) — the ONE retainer of "how this runner's scene was built", so
      * `restart()` can replay it. Whichever path built the scene sets it: `setup(factory, opts)`
-     * retains its factory replay; `RecipeContext.build(sketch)` retains `exp.build(sketch)`. A later
-     * build replaces the earlier retention (the runner holds ONE scene).
-     * @param {Function} fn — replays the scene; its return value is restart()'s.
+     * retains its factory replay; `RecipeContext.build(sketch)` retains its rebuild (a sketch built from
+     * linked text re-links the facade's CURRENT text — what the writer last wrote — and builds that). A
+     * later build replaces the earlier retention (the runner holds ONE scene).
+     * @param {Function} fn — replays the scene; its return value (or the value its promise resolves) is restart()'s.
      */
     FrqtlApp.prototype.retainSceneReplay = function (fn) {
         if (typeof fn !== 'function') {
@@ -2195,25 +2273,24 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
     };
 
     /**
-     * restart() — the PAGE-LEVEL restart primitive (presentation pass Item 2,
-     * E-P2b): stop → replay the RETAINED scene (`retainSceneReplay` — a setup
-     * factory's world + part steps with its ORIGINAL opts, or a sketch's `exp.build(sketch)`
-     * on the same runner and canvas) → start. The scene returns to tick 0 IN-PAGE: no reload,
-     * so the camera orbit, render options and any host wiring survive. The declared `restart`
-     * control (controlAction.js) routes here for every host.
+     * restart() → Promise — the PAGE-LEVEL restart primitive: stop → replay the RETAINED scene
+     * (`retainSceneReplay` — a setup factory's world + part steps with its ORIGINAL opts, a sketch's
+     * rebuild on the same runner and canvas, or — for a sketch built from linked text — a re-link of the
+     * facade's current text, then its build) → start. The scene returns to tick 0 IN-PAGE: no reload, so
+     * the camera orbit, render options and any host wiring survive. The declared `restart` control
+     * (controlAction.js) routes here for every host.
      *
-     * Teardown runs EXACTLY ONCE — the replay owns it (`setup()` calls the previous
-     * setupResult's `dispose()`; a sketch build tears the previous scene down first —
-     * RecipeContext.build), so this method must NOT dispose again (double teardown was the
-     * stacking-regression this seam was built to avoid).
+     * ALWAYS a Promise. A replay that returns a plain value (a factory, a function-built sketch) has run
+     * and the loop has restarted before restart() returns; its promise resolves at once. A replay that
+     * returns a promise (a re-link) resolves after the rebuild and the start. Every caller awaits it.
      *
-     * DISTINCT BY DESIGN from STUDIO's codegen Restart (AuthorView), which rebuilds
-     * a persisted DESIGN and reloads the page: that one is STUDIO chrome and stays
-     * where it is. This one replays the already-loaded module.
+     * Teardown runs EXACTLY ONCE — the replay owns it (`setup()` calls the previous setupResult's
+     * `dispose()`; a sketch build tears the previous scene down first — RecipeContext.build), so this
+     * method must NOT dispose again.
      *
-     * @returns {*} the replay's result (a setup result, or the sketch's facade).
-     * @throws {Error} FAIL-LOUD when nothing built a scene on this runner (there is nothing
-     *   to replay) — never a silent no-op.
+     * @returns {Promise<*>} the replay's result (a setup result, or the sketch's facade).
+     * @throws {Error} FAIL-LOUD when nothing built a scene on this runner (there is nothing to replay) —
+     *   never a silent no-op; a failed replay REJECTS.
      */
     FrqtlApp.prototype.restart = function () {
         if (typeof this._sceneReplay !== 'function') {
@@ -2222,12 +2299,19 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
                 '(FAIL-LOUD — a restart with nothing to replay would silently do nothing.)');
         }
         this.stop();
-        var result = this._sceneReplay();
-        this._lastTickData = null;
-        // Always resume: "restart" means run the scene again from tick 0 — a restart
-        // that left the loop paused would read as a dead button.
-        this.start();
-        return result;
+        var self = this;
+        function resume(result) {
+            self.beginWorld();
+            // Always resume: "restart" means run the scene again from tick 0 — a restart
+            // that left the loop paused would read as a dead button.
+            self.start();
+            return result;
+        }
+        var result;
+        try { result = this._sceneReplay(); }
+        catch (err) { return Promise.reject(err); }
+        if (result && typeof result.then === 'function') { return result.then(resume); }
+        return Promise.resolve(resume(result));
     };
 
     // ── Renderer resolution ────────────────────────────────────────────────
@@ -2493,6 +2577,28 @@ import { paintBootFailure } from '../experiments/_shared/boot-failure.js';
         return this._tickSuspend;
     };
 
+    /**
+     * runner.worldTick — READ-ONLY: the tick of THIS world: 0 before its first step, else the last delivered tick.
+     * The 0 is a stated fact, not a default: `_lastTickData` is null until the world's first step, and beginWorld()
+     * (the co-init and restart()) is the one writer of that null. It does NOT read `universe.tick`: the compat wrapper
+     * keeps that field across a re-init until the next doTick, so after a restart it still answers the previous
+     * world's tick. Every runner holds a world (its universe is built at construction), whether a sketch built it
+     * through the replay door or a page built it by hand, so this always answers. THROWS when a delivered tick is not
+     * a whole number ≥ 0.
+     */
+    Object.defineProperty(FrqtlApp.prototype, 'worldTick', {
+        configurable: true,
+        get: function () {
+            if (this._lastTickData === null) { return 0; }
+            var t = this._lastTickData && this._lastTickData.universeData && this._lastTickData.universeData.tick;
+            if (!(typeof t === 'number' && t >= 0 && t % 1 === 0)) {
+                throw new Error('[FrqtlApp.worldTick] the last delivered TickData carries tick ' + String(t) +
+                    ', not a whole number ≥ 0. (FAIL-LOUD.)');
+            }
+            return t;
+        }
+    });
+
     /** @returns {boolean} whether the tick clock is currently held. */
     Object.defineProperty(FrqtlApp.prototype, 'ticksSuspended', {
         configurable: true,

package/dist/frqtl/objects/ObjectFactory.js

@@ -95,8 +95,7 @@ import { V1_REPLACEMENTS } from './v1-replacements.js';
         // `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).
+        // A PointSource's construction-only opts (its builder reads them; no descriptor field).
         '_wavelength', '_optColor', '_emergentPhysics'
     ];
 
@@ -187,7 +186,7 @@ import { V1_REPLACEMENTS } from './v1-replacements.js';
          * 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
+         * declaring call (`exp.addObject`, `exp.declare`, a palette drop) produced is what STUDIO
          * holds; a part's composition is never declared.
          *
          * FAIL-LOUD: an unknown kind THROWS naming the registered kinds and, when
@@ -264,11 +263,11 @@ import { V1_REPLACEMENTS } from './v1-replacements.js';
                     '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.
+            // fn, an absorb radiator): behaviour the declaration owns.
             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);
+            runner.declare(handle, members, ticks, { kind: kind });
             return handle;
         },