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

package/dist/shim/notebook/view-handle.js

@@ -0,0 +1,202 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * @module view-handle
+ * @description
+ * The FROZEN host↔realm contract. Produced by `makeViewHandle(impl)`.
+ *
+ * The frozen handle surface (all async-shaped):
+ * ```
+ *   inject(name, data)  → Promise<void>           // host → realm data push
+ *   call(fn, args)      → Promise<result>          // host → realm invoke + result
+ *   on(event, cb)       → unsubFn                  // realm → host event stream
+ *   start()             → Promise<void>            // control-plane game-loop verbs
+ *   stop()              → Promise<void>
+ *   step()              → Promise<tickData|void>
+ *   dispose()           → Promise<void>
+ * ```
+ *
+ * Every method is async-shaped so a marshalling host (the hosted-eyes page-evaluate
+ * seam, a BYO realm host) sees the same signatures as the in-app direct-scripting
+ * transport. Cell code never branches on transport.
+ *
+ * VETO-CLASS #1: `inject(name, data)` payloads and `on(event, payload)` event
+ * payloads MUST be structured-clone-serializable. `assertSerializable` enforces
+ * this at the boundary — FAIL-LOUD regardless of transport.
+ */
+
+/**
+ * @typedef {object} ViewHandle
+ * @property {string} transport
+ *   DERIVED label from the transport, `'in-app'` today (truth-in-labeling — never hardcoded by a consumer).
+ * @property {(name: string, data: *) => Promise<void>} inject
+ *   Push a serializable value into the realm environment. VETO-CLASS #1 enforced.
+ * @property {(fn: string, args: *[]) => Promise<*>} call
+ *   Invoke a named function in the realm and resolve its result.
+ * @property {(event: string, cb: Function) => Function} on
+ *   Subscribe to a realm event. Returns an unsubscribe function.
+ * @property {() => Promise<void>} start  — start the realm game loop.
+ * @property {() => Promise<void>} stop   — pause the realm game loop.
+ * @property {() => Promise<*>}    step   — advance one tick; resolves with tick data.
+ * @property {() => Promise<void>} dispose — tear down the realm.
+ */
+
+'use strict';
+
+/* ── structured-clone serializability check (VETO-CLASS #1 enforcement) ───────
+ *
+ * structuredClone is available in Node 17+ and every modern browser. We attempt a
+ * clone and surface a FAIL-LOUD error naming the offending plane on failure. We do
+ * NOT keep the clone (the realm impl receives the original by value/marshal); the
+ * clone is purely the serializability gate. A function, DOM node, live runner,
+ * class instance with methods, etc. throws — exactly the refs a marshalling host (the
+ * hosted-eyes page-evaluate seam, a BYO realm host) cannot carry. */
+
+/**
+ * Assert that `value` is structured-clone-serializable.
+ *
+ * Throws a `TypeError` (FAIL-LOUD) if the value cannot be cloned — e.g. a function,
+ * DOM node, live runner handle, or class instance with methods. Falls back to a
+ * JSON round-trip on runtimes without `structuredClone` (Node < 17 / old browsers).
+ *
+ * @param {*} value — the data-plane payload to validate.
+ * @param {string} [ctx] — context label for the error message (e.g. `'inject("x") payload'`).
+ * @returns {*} `value` unchanged (pass-through for inline use).
+ * @throws {TypeError} if the value is not structured-clone-serializable.
+ */
+export function assertSerializable(value, ctx) {
+    var label = ctx || 'data-plane payload';
+    if (typeof structuredClone !== 'function') {
+        // No structuredClone (very old runtime): fall back to a JSON round-trip,
+        // which is STRICTER (also rejects functions/undefined) — still FAIL-LOUD,
+        // never a silent pass.
+        try {
+            JSON.parse(JSON.stringify(value));
+        } catch (e) {
+            throw new TypeError('[view-handle] ' + label + ' is not serializable (JSON fallback): ' +
+                (e && e.message ? e.message : String(e)) + ' (VETO-CLASS #1 — the data plane must be ' +
+                'structured-clone-serializable so a marshalling host is not a fork.)');
+        }
+        return value;
+    }
+    try {
+        structuredClone(value);
+    } catch (e) {
+        throw new TypeError('[view-handle] ' + label + ' is not structured-clone-serializable: ' +
+            (e && e.message ? e.message : String(e)) + ' (VETO-CLASS #1 — never pass a live object ' +
+            'ref/function/DOM node across the handle data plane; a marshalling host cannot carry it.)');
+    }
+    return value;
+}
+
+/* ── normalize a possibly-sync impl method into a Promise ─────────────────── */
+function _toPromise(fn, args) {
+    try {
+        return Promise.resolve(fn.apply(null, args));
+    } catch (e) {
+        return Promise.reject(e);
+    }
+}
+
+/**
+ * Wrap a transport-specific implementation into a frozen view handle.
+ *
+ * The returned handle enforces VETO-CLASS #1 (structured-clone check) on `inject`
+ * payloads and on `on(event, cb)` emitted payloads. Every method is async-shaped.
+ * The handle is `Object.freeze`d — a cell cannot monkey-patch the contract.
+ *
+ * @param {object} impl — the transport-specific implementation object.
+ * @param {(name: string, data: *) => void|Promise<void>} impl.inject
+ * @param {(fn: string, args: *[]) => *|Promise<*>} impl.call
+ * @param {(event: string, cb: Function) => Function} impl.on
+ * @param {() => void|Promise<void>} [impl.start]
+ * @param {() => void|Promise<void>} [impl.stop]
+ * @param {() => *|Promise<*>} [impl.step]
+ * @param {() => void|Promise<void>} impl.dispose
+ * @param {'in-app'} [impl._transport] — DERIVED transport label (truth-in-labeling).
+ * @returns {ViewHandle} frozen handle with IDENTICAL API regardless of transport.
+ * @throws {Error} if required methods (`inject`, `call`, `on`, `dispose`) are missing.
+ *
+ * @example
+ * // In-app descriptor (same-origin direct scripting):
+ * const handle = makeViewHandle({
+ *   _transport: 'in-app',
+ *   inject: (name, data) => { window._realmEnv[name] = data; },
+ *   call:   (fn, args)   => window._realmEnv[fn](...args),
+ *   on:     (ev, cb)     => { /* subscribe * / return () => {}; },
+ *   start:  ()           => window._realmEnv.start(),
+ *   stop:   ()           => window._realmEnv.stop(),
+ *   step:   ()           => window._realmEnv.step(),
+ *   dispose:()           => { window._realmEnv = null; }
+ * });
+ */
+export function makeViewHandle(impl) {
+    if (!impl || typeof impl.inject !== 'function' || typeof impl.call !== 'function' ||
+        typeof impl.on !== 'function' || typeof impl.dispose !== 'function') {
+        throw new Error('[view-handle] makeViewHandle requires an impl with ' +
+            'inject/call/on/dispose (start/stop/step optional but recommended). (FAIL-LOUD.)');
+    }
+
+    var handle = {
+        // Diagnostic, DERIVED transport label (truth-in-labeling — never hardcoded
+        // by a consumer; reflects how this handle actually marshals).
+        transport: impl._transport || 'in-app',
+
+        // ── DATA plane (serializability-gated) ──────────────────────────────
+        inject: function (name, data) {
+            if (typeof name !== 'string' || !name) {
+                return Promise.reject(new Error('[view-handle] inject: name must be a non-empty string.'));
+            }
+            try { assertSerializable(data, 'inject("' + name + '") payload'); }
+            catch (e) { return Promise.reject(e); }
+            return _toPromise(impl.inject, [name, data]);
+        },
+
+        // ── host → realm invoke + result ────────────────────────────────────
+        call: function (fn, args) {
+            return _toPromise(impl.call, [fn, args]);
+        },
+
+        // ── realm → host event stream ───────────────────────────────────────
+        // We WRAP the caller's cb so the emitted payload is asserted serializable
+        // at the boundary (VETO-CLASS #1 applies to BOTH inject AND on payloads).
+        // A non-serializable emit FAILS LOUD via the wrapper's throw — never a
+        // silent same-origin-only pass that would break under a marshalling host.
+        on: function (event, cb) {
+            if (typeof cb !== 'function') {
+                throw new Error('[view-handle] on("' + String(event) + '"): cb must be a function.');
+            }
+            var guarded = function (payload) {
+                assertSerializable(payload, 'on("' + String(event) + '") event payload');
+                cb(payload);
+            };
+            var unsub = impl.on(event, guarded);
+            return (typeof unsub === 'function') ? unsub : function () {};
+        },
+
+        // ── CONTROL plane (exempt from serializability — no rich data) ───────
+        start: function () { return impl.start ? _toPromise(impl.start, []) : Promise.resolve(); },
+        stop:  function () { return impl.stop  ? _toPromise(impl.stop, [])  : Promise.resolve(); },
+        step:  function () { return impl.step  ? _toPromise(impl.step, [])  : Promise.resolve(); },
+
+        // ── teardown ────────────────────────────────────────────────────────
+        dispose: function () { return _toPromise(impl.dispose, []); }
+    };
+
+    return Object.freeze(handle);
+}
+
+/**
+ * Duck-type a value as a frozen view handle.
+ *
+ * Used by the notebook pane to decide whether a cell's `out=`/`bind=` binding
+ * value is a realm handle to script vs a plain data binding.
+ *
+ * @param {*} v
+ * @returns {boolean} `true` if `v` has `inject`, `call`, `on`, and `dispose` functions.
+ */
+export function isViewHandle(v) {
+    return !!(v && typeof v === 'object' &&
+        typeof v.inject === 'function' && typeof v.call === 'function' &&
+        typeof v.on === 'function' && typeof v.dispose === 'function');
+}

package/dist/shim/notebook/warmup.js

@@ -0,0 +1,102 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * warmup — the PURE warm-up-before-derive helper for the realm→kernel binding seam
+ * NO DOM / engine / Runtime / Bus import, so a test
+ * exercises it with a fake handle WITHOUT a browser.
+ *
+ * THE PROBLEM IT SOLVES: a DECLARED canvas that `produces` a binding mounts its
+ * realm-internal runner at tick ~0. Deriving the produced value immediately (via
+ * `deriveProducedBindings`) reads the detector histogram BEFORE any particle has
+ * crossed the stage — an EMPTY `{}`. The chart then faithfully renders nothing.
+ *
+ * THE BASELINE FIX (one-shot, static): step the realm a DETERMINISTIC number of ticks
+ * through the FROZEN handle's control-plane `step()` so the detector accumulates, THEN
+ * derive + commit. The warmup count is DECLARED on the canvas (`produceAfter="N"`,
+ * parsed by format.js); when omitted it falls back to `defaultTicks`.
+ *
+ *   warmUpRealm(handle, produceAfter, defaultTicks, maxTicks) → Promise<number>
+ *
+ * Returns the number of ticks actually stepped (for the host to log / a test to assert).
+ *
+ * FAIL-LOUD: a missing handle or a `handle.step` that throws PROPAGATES (the caller
+ * surfaces it as a pane overlay and commits NOTHING). A NEGATIVE / non-integer
+ * `produceAfter` (a malformed authored attr) FAILS LOUD here — never silently
+ * clamped-to-zero, which would re-introduce the empty-histogram bug under a typo.
+ *
+ * FOLLOW-UP (interactive review): the live `on('tick')` same-cell chart and
+ * arbitrary-import path supersede this static one-shot warmup. This module is the
+ * baseline only.
+ */
+
+'use strict';
+
+/**
+ * Default warmup tick count when a `produces`-declaring canvas omits `produceAfter`.
+ * 600 is sized for the canonical double-slit stage (480x480): the SlitLightSource emits
+ * at x=20, the DetectorWall sits at x≈352 (wavelength=64), and a particle covers ≤1px/tick
+ * relative to its parent — so the leading edge needs ≥332 ticks to reach the detector, and
+ * 600 gives a comfortable margin for a clearly non-empty histogram.
+ *
+ * SINGLE SOURCE OF TRUTH: imported by notebook-pane/index.js (the in-app host), so no
+ * consumer duplicates the literal.
+ */
+export var DEFAULT_PRODUCE_AFTER_TICKS = 600;
+
+/**
+ * Hard cap on warmup ticks. Defends against an absurd authored `produceAfter` value that
+ * would starve the event loop. Imported alongside DEFAULT_PRODUCE_AFTER_TICKS.
+ */
+export var MAX_PRODUCE_AFTER_TICKS = 100000;
+
+/**
+ * Resolve the declared `produceAfter` attribute (a verbatim string from format.js) to an
+ * integer tick count, FAIL-LOUD on a malformed value. Empty / undefined → `defaultTicks`.
+ *
+ * @param {string|number|undefined} produceAfter — the canvas `produceAfter` attribute.
+ * @param {number} defaultTicks — fallback when the attribute is empty/absent.
+ * @returns {number} a non-negative integer tick count.
+ * @throws {Error} FAIL-LOUD when the attribute is present but not a non-negative integer.
+ */
+export function resolveWarmupTicks(produceAfter, defaultTicks) {
+    if (produceAfter === undefined || produceAfter === null || produceAfter === '') {
+        return defaultTicks;
+    }
+    // Accept a number or an integer-string; reject anything else FAIL-LOUD (a typo'd
+    // attribute must not silently become 0 — that re-introduces the empty histogram).
+    var n = (typeof produceAfter === 'number') ? produceAfter : Number(String(produceAfter).trim());
+    if (!Number.isInteger(n) || n < 0) {
+        throw new Error('[warmup] produceAfter must be a non-negative integer tick count; got "' +
+            produceAfter + '". (FAIL-LOUD — a malformed warmup count would silently empty the ' +
+            'produced histogram.)');
+    }
+    return n;
+}
+
+/**
+ * Warm up the realm a deterministic number of ticks before its produced binding is derived.
+ *
+ * @param {object} handle — the FROZEN view-handle (must expose `step()`).
+ * @param {string|number|undefined} produceAfter — the declared warmup tick count (canvas attr).
+ * @param {number} [defaultTicks=0] — fallback warmup when `produceAfter` is empty.
+ * @param {number} [maxTicks=Infinity] — hard cap (defends against an absurd authored N).
+ * @returns {Promise<number>} the number of ticks actually stepped.
+ * @throws {Error} FAIL-LOUD on a missing handle / a non-stepping handle / a malformed
+ *   `produceAfter` / a `handle.step()` that throws.
+ *
+ * The handle's `step()` is async-shaped (Promise) on both transports — each step is
+ * AWAITED so the realm advances one engine tick per iteration deterministically.
+ */
+export async function warmUpRealm(handle, produceAfter, defaultTicks, maxTicks) {
+    if (!handle || typeof handle.step !== 'function') {
+        throw new Error('[warmup] warmUpRealm requires a frozen view-handle with step(). (FAIL-LOUD.)');
+    }
+    var want = resolveWarmupTicks(produceAfter, (typeof defaultTicks === 'number') ? defaultTicks : 0);
+    var cap = (typeof maxTicks === 'number' && isFinite(maxTicks)) ? maxTicks : Infinity;
+    var ticks = Math.min(want, cap);
+    for (var i = 0; i < ticks; i++) {
+        // CONTROL-plane step (exempt from serializability). One engine tick per await.
+        await handle.step();
+    }
+    return ticks;
+}

package/dist/shim/package.json

@@ -0,0 +1,4 @@
+{
+  "private": true,
+  "type": "module"
+}

package/dist/shim/page-params/index.js

@@ -0,0 +1,213 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/page-params — the URL-param routing-table contract for canonical
+ * experiment pages (gym-controls-as-sugar item 0 — the param contract designed
+ * properly and built with the controls).
+ *
+ * Peer of `lib/shim/frame-data`, `lib/shim/expr/ast-schema`, `lib/shim/controls` —
+ * same layout convention: a closed vocabulary exported as named ES-module exports,
+ * imported by node tests, the boot module and the IDE alike.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ *
+ * Page-side readers each read their OWN URL param from the page URL; the key
+ * string is never a hand-typed literal at the reader:
+ *   - `lib/frqtl/experiments/_shared/fx-experiment.js` reads `seed`.
+ *   - `lib/frqtl/experiments/_shared/boot.js` reads `renderer`, `engine` and the
+ *     HOST-COMPOSITION token `chrome`.
+ *
+ * A `reader` need not be a `_shared` boot file: `stepping`
+ * is read by ONE experiment page's own inline sketch, because it is a
+ * per-universe PHYSICS option that page ferries into its own `universe.init()`
+ * — the registry's job is that the KEY NAME has exactly one owner, wherever the
+ * single reader lives (see that entry's own note for the hoist rule when a
+ * second page wants it).
+ *
+ * This module codifies that vocabulary as ONE table (`PAGE_PARAMS`) plus a
+ * sibling table for the host-token (`HOST_TOKENS`) — converged design decision:
+ * `chrome` differs in KIND from the other four (see HOST_TOKENS doc below), so
+ * it does NOT belong in PAGE_PARAMS even though it is also page-URL-driven.
+ *
+ * ── Delivery: an ES-module import ───────────────────────────────────────────
+ *
+ * Every reader imports `KEYS` (or a table) from this module — `boot.js` statically,
+ * so the key names are bound before the page's boot runs; no reader carries a
+ * literal copy of a key.
+ *
+ * ── page-params is a STATIC ROUTING REGISTRY, not a control schema ──────────
+ *
+ * Unlike `lib/shim/controls` (live, runtime-mutable descriptors with a
+ * throw-or-apply `normalize()`), page-params is LOAD-TIME-ONLY: every entry is
+ * read exactly once, at page boot, from the URL. There is deliberately NO
+ * `normalize()` here — the tables are frozen static data, not runtime input to
+ * validate. The two contracts are ADJACENT (both are consumed by the same
+ * experiment pages, and the controls-panel work touches both) but are
+ * NEVER unified into one schema/kind-union.
+ *
+ * Usage:
+ *   import { KEYS, PAGE_PARAMS, HOST_TOKENS, FORWARDABLE_PARAMS } from 'lib/shim/page-params/index.js';
+ *   var seed = new URLSearchParams(location.search).get(KEYS.SEED);
+ *   // host-side (features/apps, forwarding a deep link into an embedded iframe):
+ *   FORWARDABLE_PARAMS.forEach(function (key) { ... });
+ */
+
+
+
+/**
+ * KEYS — the canonical URL param key strings, named for ergonomic/live-import
+ * access (`window.PageParams.KEYS.SEED` reads better at a call site than
+ * `window.PageParams.PAGE_PARAMS[0].key`). Every `PAGE_PARAMS` entry's `key`
+ * field references one of these — same value, same reference — so `KEYS` and
+ * `PAGE_PARAMS` can never drift apart.
+ */
+var KEYS = Object.freeze({
+    SEED:               'seed',
+    RENDERER:           'renderer',
+    ENGINE:             'engine',
+    STEPPING:           'stepping'
+});
+
+/**
+ * PAGE_PARAMS — every URL param a canonical experiment page's SHARED reader
+ * modules accept, `{ key, reader, forward, why? }`:
+ *   key     — one of KEYS.
+ *   reader  — a repo-root-relative path to the file that reads this key. The
+ *             conformance test derives its per-key source-file assertion FROM
+ *             this field — never a test-side hand map (schema-mirror-drift
+ *             discipline: the owner exports the reader location, consumers/
+ *             tests ferry it).
+ *   forward — true: a HOST embedding the page in an iframe (the GYM, a future
+ *             control panel, …) may forward this key from its own URL.
+ *             false: never forward (see `why`).
+ *   why     — REQUIRED when forward is false (conformance-checked).
+ */
+var PAGE_PARAMS = Object.freeze([
+    Object.freeze({
+        key:     KEYS.SEED,
+        reader:  'lib/frqtl/experiments/_shared/fx-experiment.js',
+        forward: true
+    }),
+    Object.freeze({
+        key:     KEYS.RENDERER,
+        reader:  'lib/frqtl/experiments/_shared/boot.js',
+        forward: true
+    }),
+    Object.freeze({
+        key:     KEYS.STEPPING,
+        reader:  'lib/frqtl/experiments/single-source-interference/index.html',
+        forward: true
+        // Circulation §2: `stepping`
+        // selects the WAVE-WALK STEPPING SAMPLER for one universe —
+        // 'fixed' (deterministic error-accumulator walk, the engine's serde default)
+        // vs 'average' (the historic per-axis Bernoulli walk). It is a PER-UNIVERSE
+        // PHYSICS option, so it is read at the PAGE plane and ferried RAW into that
+        // page's own `universe.init(..., { stepping })` options — deliberately NOT by
+        // the boot module, which selects the BACKEND (`?engine=`, forward:false). Putting
+        // a physics knob in the backend selection would conflate the two axes.
+        //
+        // forward:true — unlike `?engine=`, no host owns a competing stepping authority,
+        // and a host embedding this page for an A/B (the GYM Compare shape) forwarding
+        // its own `?stepping=` is exactly the intended use (the `?renderer=`/`?seed=`
+        // precedent). The value is NEVER validated or defaulted page-side: an absent
+        // param means the key is omitted from the init bag so the ENGINE's default
+        // (the Rust `Stepping` serde enum, `Fixed`) is the ONE authority for it, and a
+        // garbage value rides through to `universe.init()`, which throws naming both
+        // legal samplers (one validator, zero second interpreters).
+        //
+        // SCALING (pre-registered, not built): a PAGE_PARAMS entry names ONE reader.
+        // When a SECOND page consumes `?stepping=`, HOIST the read into one shared
+        // reader module and repoint this entry — never a second entry for the same
+        // key, never a copy-pasted inline read.
+    }),
+    Object.freeze({
+        key:     KEYS.ENGINE,
+        reader:  'lib/frqtl/experiments/_shared/boot.js',
+        forward: false,
+        why: 'the host\'s own physics-engine selector (e.g. the GYM\'s Benchmark/' +
+             'Compare engine dropdown) is the SOLE authority for this axis; ' +
+             'forwarding an outer ?engine= would let it silently override an ' +
+             'explicit host choice, which is exactly the engine-sniffing-from-' +
+             'above-the-shim class of bug this codebase forbids elsewhere'
+    })
+]);
+
+/**
+ * HOST_TOKENS — host-composition tokens: they change what the PAGE's own chrome
+ * renders, never a physics or render parameter, so the `{key, reader, forward,
+ * why}` shape does not fit them: `{ key, appliedBy, forward, why, acceptedValues }`.
+ *   appliedBy      — the file that applies the token.
+ *   acceptedValues — the CLOSED set of legal values for this token (frozen
+ *                    array). The single canonical vocabulary — never
+ *                    hand-duplicated by a consumer (`lib/features/ide/presets.js`'s
+ *                    `withHostChrome` and `boot.js`'s `applyChrome` both read
+ *                    THIS list).
+ *
+ * ── WHEN should a host set `chrome=canvas`? (the criterion, canonical home) ──
+ *
+ * A host sets `chrome=canvas` IFF its own chrome REPLICATES-OR-SUPERSETS the
+ * embedded experiment page's own control surface — i.e. the host provides an
+ * equivalent (or richer) way to reach every knob the experiment's own
+ * `.experiment-controls`/metrics chrome would otherwise show, so showing the
+ * page's raw chrome bar inside the host's viewport would be pure redundancy,
+ * never a loss of capability. Two worked, OPPOSITE applications of this ONE
+ * rule (read them side by side — this is not "some hosts hide chrome,
+ * others don't" as a per-host preference; it is one test with two different
+ * answers):
+ *   - The GYM (`CompareView.jsx`):
+ *     OMITS `chrome=` entirely (full chrome renders in-iframe). The GYM's own
+ *     host chrome is deliberately minimal (Run/Pause/camera/rates only) — it
+ *     does NOT replicate the physics-parametric controls (temperature,
+ *     wavelength, density sweeps, …) every experiment declares, so hiding the
+ *     experiment's own chrome would strictly REMOVE capability from the GYM
+ *     user with no host-side equivalent to fall back on.
+ *   - Studio (`AuthorView.jsx`, "Studio adoption"): SETS
+ *     `chrome=canvas`. Studio's own chrome already replicates-or-supersets
+ *     the experiment's control surface for its purposes: a Design/Run/Pause
+ *     topbar, an Effects palette (backdrop/water toggles), and a fully
+ *     generic per-object schema Inspector that can edit ANY field of ANY
+ *     authored object — a SUPERSET of what any single experiment's own
+ *     control bar could show. Showing the raw chrome bar too would be
+ *     redundant and cramped inside Studio's constrained canvas pane, exactly
+ *     the "gallery-tile-style, host-chrome-owns-everything" case this token
+ *     was built for.
+ * A future host applies the SAME test: does my own chrome already cover
+ * (or exceed) what the embedded page's chrome offers? If yes → `chrome=
+ * canvas`. If no (the host chrome is thinner than the experiment's own) →
+ * omit `chrome=` and let the experiment's own chrome render.
+ */
+var HOST_TOKENS = Object.freeze([
+    Object.freeze({
+        key:            'chrome',
+        appliedBy:      'lib/frqtl/experiments/_shared/boot.js',
+        forward:        false,
+        acceptedValues: Object.freeze(['canvas']),
+        why: 'chrome is a HOST-COMPOSITION decision (whether the experiment\'s own ' +
+             'control chrome DOM renders), never a per-experiment physics/render ' +
+             'parameter; forwarding it from an outer host URL into an embedded ' +
+             'iframe would reintroduce the hidden-experiment-chrome bug fixed in ' +
+             'WS gym-controls-as-sugar Bite 2 (the GYM must always show the ' +
+             'experiment\'s own full chrome, never chrome=canvas — see the ' +
+             '"WHEN should a host set chrome=canvas" doc above for the general ' +
+             'criterion, not just the GYM\'s specific answer to it)'
+    })
+]);
+
+/**
+ * FORWARDABLE_PARAMS — derived: every PAGE_PARAMS key with forward:true, in
+ * table order. THE ONLY list a host may use to forward params into an embedded
+ * experiment-page iframe (`lib/features/ide/presets.js` `buildExperimentFrameSrc`
+ * consumes this — no host re-derives its own hand list).
+ */
+var FORWARDABLE_PARAMS = Object.freeze(
+    PAGE_PARAMS.filter(function (p) { return p.forward; }).map(function (p) { return p.key; })
+);
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    KEYS,
+    PAGE_PARAMS,
+    HOST_TOKENS,
+    FORWARDABLE_PARAMS
+};

package/dist/shim/project/identity.js

@@ -0,0 +1,112 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * identity.js — THE project identity: one published function over a project's files.
+ *
+ *   projectIdentity(project) → Promise<string>   lowercase hex sha256
+ *       project — { files: { '<path>': Uint8Array, … } } — BYTES, never text (any other keys are ignored)
+ *   projectBytes(files) → { '<path>': Uint8Array }  the bytes a { path: text } map denotes (UTF-8)
+ *
+ * A host passes the bytes it ran: the linker hashes the bytes it fetched (a served folder) or the UTF-8
+ * encoding of the text it was handed (a file map, projectBytes); node hands a file's Buffer. A BOM is part
+ * of a file's bytes, so it is part of the identity (a decoder strips it only from the executed text).
+ *
+ * The byte recipe (one recipe from the first pre-release on; there is no normalization):
+ *   for each file, in ascending BYTE order of its path (UTF-8),
+ *     the path   (UTF-8, '/'-separated, root-relative, no leading './')   then a 0x00 byte
+ *     the decimal byte length of the file (ASCII digits)                   then a 0x00 byte
+ *     the file's raw bytes
+ *   then the sha256 of the whole stream.
+ *
+ * Swapping the order of the input keys cannot change the value (the path order is canonical); one
+ * flipped byte, or a dropped trailing newline, does. A path that is empty, absolute, starts with './'
+ * or climbs with '..' is REFUSED, never repaired: a repaired path would hash a project the caller did
+ * not hand in.
+ *
+ * Hashing is the platform's `crypto.subtle` (a global in a page and in node ≥ 19): one source, no host
+ * branch. Gate: lib/shim/project/test/identity.test.mjs (an independent printf | shasum pipeline).
+ */
+
+const _enc = new TextEncoder();
+
+function _fail(msg) {
+    throw new Error('[identity] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/** @param {Uint8Array} a @param {Uint8Array} b @returns {number} byte-order comparison */
+function _byteCompare(a, b) {
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) { if (a[i] !== b[i]) { return a[i] - b[i]; } }
+    return a.length - b.length;
+}
+
+/**
+ * THE project-path rule (identity and the linker both apply it): root-relative, '/'-separated, no
+ * leading './', no empty / '.' / '..' segment. THROWS naming the path.
+ * @param {string} p
+ */
+export function checkProjectPath(p) {
+    if (!p) { _fail('a project file has an empty path.'); }
+    if (p.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(p)) { _fail('"' + p + '" is absolute — a project path is root-relative.'); }
+    if (p.startsWith('./')) { _fail('"' + p + '" starts with "./" — a project path carries no leading "./".'); }
+    if (p.indexOf('\\') !== -1) { _fail('"' + p + '" uses "\\" — a project path is "/"-separated.'); }
+    if (p.split('/').some((seg) => seg === '' || seg === '.' || seg === '..')) {
+        _fail('"' + p + '" has an empty, "." or ".." segment — a project path names one file under the root.');
+    }
+}
+
+/**
+ * The bytes a { path: text } map denotes: each text UTF-8 encoded. THROWS on a non-string value.
+ * @param {Object<string, string>} files
+ * @returns {Object<string, Uint8Array>}
+ */
+export function projectBytes(files) {
+    if (!files || typeof files !== 'object') {
+        _fail('projectBytes(files): files is the map { path: text } (got ' + typeof files + ').');
+    }
+    const out = {};
+    for (const p of Object.keys(files)) {
+        if (typeof files[p] !== 'string') { _fail('projectBytes: file "' + p + '" is not text (got ' + typeof files[p] + ').'); }
+        out[p] = _enc.encode(files[p]);
+    }
+    return out;
+}
+
+/**
+ * @param {{files: Object<string, Uint8Array>}} project
+ * @returns {Promise<string>} the lowercase hex sha256
+ */
+export async function projectIdentity(project) {
+    const files = project && project.files;
+    if (!files || typeof files !== 'object') {
+        _fail('projectIdentity(project): project.files is the map { path: bytes } (got ' + typeof files + ').');
+    }
+    const rows = Object.keys(files).map((p) => {
+        checkProjectPath(p);
+        const v = files[p];
+        if (!(v instanceof Uint8Array)) {
+            _fail('file "' + p + '" is not bytes (got ' + typeof v + ') — the identity is over the bytes a host ran; ' +
+                'a { path: text } map goes through projectBytes(files) first.');
+        }
+        return { path: _enc.encode(p), bytes: v };
+    });
+    if (rows.length === 0) { _fail('projectIdentity(project): the project has no files.'); }
+    rows.sort((a, b) => _byteCompare(a.path, b.path));
+    const chunks = [];
+    let total = 0;
+    for (const r of rows) {
+        const len = _enc.encode(String(r.bytes.length));
+        for (const c of [r.path, Uint8Array.of(0), len, Uint8Array.of(0), r.bytes]) { chunks.push(c); total += c.length; }
+    }
+    const stream = new Uint8Array(total);
+    let at = 0;
+    for (const c of chunks) { stream.set(c, at); at += c.length; }
+    const subtle = (typeof crypto !== 'undefined') ? crypto.subtle : null;
+    if (!subtle || typeof subtle.digest !== 'function') {
+        _fail('crypto.subtle.digest is unavailable — the project identity is a content hash with no second hashing path.');
+    }
+    const view = new Uint8Array(await subtle.digest('SHA-256', stream));
+    let hex = '';
+    for (let i = 0; i < view.length; i++) { hex += (view[i] < 16 ? '0' : '') + view[i].toString(16); }
+    return hex;
+}

package/dist/shim/project/index.js

@@ -0,0 +1,19 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * project/index.js — the `./project` entry of BOTH packages: the specifier table, the link site and the
+ * project identity, re-exported from their owners (this file owns nothing).
+ *
+ *   FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor    specifiers.js
+ *   linkProject                                      link.js
+ *   projectIdentity                                  identity.js
+ *
+ * PROJECT_EXPORTS is this entry's export list; a conformance test holds the module's exports equal to
+ * it, and the package gate holds it equal across @descix/frqtl-web and @descix/frqtl-node.
+ */
+
+export const PROJECT_EXPORTS = Object.freeze(['FRQTL_WEB_SPECIFIERS', 'libPathOf', 'importMapFor', 'linkProject', 'projectIdentity']);
+
+export { FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor } from './specifiers.js';
+export { linkProject } from './link.js';
+export { projectIdentity } from './identity.js';