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

package/dist/shim/field-descriptor/index.js

@@ -0,0 +1,326 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/field-descriptor — the shared FIELD-SHAPE vocabulary contract.
+ *
+ * WS Studio Controls Realignment §7 r2 CEO call C1 (ratified 2026-07-07): the architect's
+ * escalation was that a single FIELD shape — `{name, type, constraint, unit,
+ * description, engineVisible, widgetHint, widgetConfig, default}` — and its
+ * closed TYPE vocabulary were about to be re-derived THREE times (physics
+ * object schema, the new render-capability descriptors, and a future Rosetta
+ * `paramsSchema`) instead of owned once. This module is that ONE owner — the
+ * peer of `lib/shim/controls` (which owns the CONTROL-descriptor shape one
+ * layer up) and `lib/shim/frame-data` (which owns the data-bubble shape) —
+ * same layout convention (closed vocabulary + a throw-or-apply `normalize`,
+ * named ES-module exports).
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────────
+ *
+ * `lib/frqtl/objects/schema/index.js` (`ObjectSchema`) already declares
+ * ~200 fields across 16 kinds using EXACTLY this shape, documented only as a
+ * comment block (`type:'rect' → …`, `type:'rgb' → …`, …). Separately,
+ * `lib/frqtl/objects/objects/makeControlsForObject.js`'s `TYPE_DISPATCH` map
+ * independently enumerates the SAME 12 field types as its object keys — two
+ * hand-written lists that happen to agree today but have no shared owner
+ * enforcing that they always will (the exact schema-mirror-drift class root
+ * `CLAUDE.md` §Engineering Culture calls out: "the same data breaks in one
+ * consumer but not another"). `renderCapabilities()` (S5a item 2,
+ * `lib/frqtl/compat/renderer/providers/{p5,three}-provider.js`) needed the
+ * SAME field shape for a THIRD surface — the trigger for this extraction.
+ *
+ * ── Scope ─────────────────────────────────────────────────────────────────
+ *
+ * This module owns:
+ *   - `FIELD_TYPES`          — the closed field-TYPE vocabulary (12 members,
+ *     mechanically identical to `ObjectSchema`'s documented comment list AND
+ *     `makeControlsForObject.js`'s `TYPE_DISPATCH` keys — see the drift test).
+ *   - `FIELD_ENVELOPE_KEYS`  — the field-SHAPE envelope key list (documentation/
+ *     introspection use — NOT a required-keys gate; most fields omit most of
+ *     these optional keys, only `name`/`type`/`description` are mandatory).
+ *   - `normalizeFieldDescriptor(partial)` — throw-or-apply validation of ONE
+ *     field descriptor's envelope (name/type/description required; constraint/
+ *     unit/engineVisible/widgetHint/widgetConfig/default validated IF present).
+ *
+ * This module does NOT:
+ *   - Re-list or replace `ObjectSchema`'s ~200 existing per-kind field arrays —
+ *     those stay EXACTLY as authored (byte-identical); `ObjectSchema` merely
+ *     IMPORTS `FIELD_TYPES` from here to assert (at load time) that every field
+ *     it declares uses a member of the ONE vocabulary, instead of hand-copying
+ *     the type list into its own comment block as the only enforcement.
+ *   - Replace `lib/shim/controls`'s CONTROL-descriptor shape (`{kind, id, label,
+ *     min, max, step, value, fmt, onChange, bind, channel}`) — that is a
+ *     DIFFERENT, downstream shape (a UI/live-knob descriptor), consumed by a
+ *     factory that READS field descriptors of THIS shape and EMITS control
+ *     descriptors of THAT shape. The two are peers, not the same contract.
+ *
+ * Usage:
+ *   import { FIELD_TYPES, normalizeFieldDescriptor } from 'lib/shim/field-descriptor/index.js';
+ *   var f = normalizeFieldDescriptor({
+ *       name: 'godrays', type: 'number', unit: 'intensity',
+ *       constraint: { min: 0, max: 3 }, default: 0,
+ *       description: 'God-rays post-process intensity (render-only).'
+ *   });
+ */
+
+
+
+// ── Field type vocabulary (closed, 12 members) ──────────────────────────────
+//
+// Mechanically identical to the set actually used across ObjectSchema's field
+// declarations (lib/frqtl/objects/schema/index.js) and
+// makeControlsForObject.js's TYPE_DISPATCH keys — verified exhaustively by
+// lib/shim/field-descriptor/test/field-descriptor.test.mjs's drift assertion.
+// Adding a 13th type is a THREE-PLACE change (here, TYPE_DISPATCH, and any
+// descriptor that uses it) — the drift test makes forgetting one of the three
+// a CI failure rather than a silent runtime gap.
+//
+//   number     — numeric scalar; constraint: { min?, max?, integer? }
+//   boolean    — true | false
+//   string     — free string
+//   enum       — one value from constraint.values object
+//   enum-set   — array of zero or more values from constraint.values object
+//   rgb        — [r, g, b] (0-255 integers)
+//   rect       — { left, top, w, h } (+ optional z, d — WASM-only)
+//   rect-array — array of rect-shaped tuples
+//   readonly   — derived/computed: inspectable but not editable
+//   forbidden  — engine-owned topology: any write attempt throws
+//   object     — an arbitrary structured bag (e.g. an op-program)
+//   writable   — Frame-kind-only ACCESS-LEVEL tag (the actual value type is
+//                inferred from the live read — number/boolean/string/object)
+var FIELD_TYPES = Object.freeze([
+    'number', 'boolean', 'string', 'enum', 'enum-set',
+    'rgb', 'rect', 'rect-array', 'readonly', 'forbidden',
+    'object', 'writable'
+]);
+
+// ── Field envelope keys (documentation/introspection — NOT a required list) ─
+//
+// Every field descriptor MAY carry these keys; only name/type/description are
+// mandatory (validated by normalizeFieldDescriptor below). `default` is the
+// C1 addition renderCapabilities() descriptors need (a physics ObjectSchema
+// field's live value comes from the constructed object instead — `default`
+// was rarely populated there and stays optional here for that reason).
+var FIELD_ENVELOPE_KEYS = Object.freeze([
+    'name', 'type', 'constraint', 'unit', 'description',
+    'engineVisible', 'widgetHint', 'widgetConfig', 'default'
+]);
+
+function _isStr(v) { return typeof v === 'string' && v.length > 0; }
+function _isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+function _fail(name, msg) {
+    throw new Error('[lib/shim/field-descriptor] normalizeFieldDescriptor(name="' + String(name) +
+        '"): ' + msg + ' (FAIL-LOUD — throw-or-apply, never silently dropped/defaulted-around.)');
+}
+
+/**
+ * normalizeFieldDescriptor(partial) → full bag.
+ *
+ * THROW-OR-APPLY: a malformed field descriptor throws here — never silently
+ * dropped or coerced. Mandatory: `name` (non-empty string), `type` (member of
+ * FIELD_TYPES), `description` (non-empty string — every ObjectSchema field
+ * already carries one; see schema.test.mjs assertion (a)). Optional, validated
+ * IF present: `unit` (string), `constraint`/`widgetConfig` (plain object),
+ * `engineVisible` (boolean), `widgetHint` (string). `default` accepts ANY
+ * value (its shape depends on `type` — a number, a string, an array for rgb/
+ * rect, …) so it is NOT type-checked here.
+ *
+ * @param {object} partial
+ * @returns {object} a NEW object (input never mutated) carrying every input
+ *   key verbatim.
+ * @throws {Error} FAIL-LOUD on a missing/empty `name`, an unrecognized `type`,
+ *   a missing/empty `description`, or a mistyped optional key.
+ */
+function normalizeFieldDescriptor(partial) {
+    if (!partial || typeof partial !== 'object') {
+        throw new Error('[lib/shim/field-descriptor] normalizeFieldDescriptor requires a field ' +
+            'descriptor object; got ' + (partial === null ? 'null' : typeof partial) +
+            '. (FAIL-LOUD.)');
+    }
+    var name = partial.name;
+    if (!_isStr(name)) {
+        _fail(name, '"name" must be a non-empty string.');
+    }
+    var type = partial.type;
+    if (FIELD_TYPES.indexOf(type) === -1) {
+        _fail(name, '"type" must be one of [' + FIELD_TYPES.join(', ') + ']; got "' + String(type) + '".');
+    }
+    if (!_isStr(partial.description)) {
+        _fail(name, '"description" must be a non-empty string.');
+    }
+    if (partial.unit !== undefined && !_isStr(partial.unit)) {
+        _fail(name, '"unit", when present, must be a non-empty string.');
+    }
+    if (partial.constraint !== undefined && !_isPlainObject(partial.constraint)) {
+        _fail(name, '"constraint", when present, must be a plain object.');
+    }
+    if (partial.engineVisible !== undefined && typeof partial.engineVisible !== 'boolean') {
+        _fail(name, '"engineVisible", when present, must be a boolean.');
+    }
+    if (partial.widgetHint !== undefined && !_isStr(partial.widgetHint)) {
+        _fail(name, '"widgetHint", when present, must be a non-empty string.');
+    }
+    if (partial.widgetConfig !== undefined && !_isPlainObject(partial.widgetConfig)) {
+        _fail(name, '"widgetConfig", when present, must be a plain object.');
+    }
+
+    // Fresh bag — never mutate the caller's object (mirrors frame-data's
+    // normalizeDataBubble / controls' normalizeControlDescriptor convention).
+    var bag = {};
+    for (var k in partial) {
+        if (Object.prototype.hasOwnProperty.call(partial, k)) { bag[k] = partial[k]; }
+    }
+    bag.name = name;
+    bag.type = type;
+    return bag;
+}
+
+// ── UX presentation vocabulary (ws-experiments-walkthrough Bite 5b A0) ──────
+//
+// A per-KIND `ux:{}` block rides ON the ObjectSchema descriptor (peer of `fields`
+// — a presentation contract, NOT a parallel `UxSchema`; architect Q-A0). Its
+// closed value vocabularies live HERE, the PEER of FIELD_TYPES, so STUDIO's
+// overlay AND a headless game consume ONE list (the SAME hooks a game uses
+// programmatically — CEO §9). The vocab is READ DOWNWARD ONLY (shim → objects/
+// features); no lib/frqtl/objects file re-lists these strings, and
+// author-bbox-overlay.js (lib/features) FERRIES `UX_HANDLE_ZONES` (asserting its
+// own returned zone names are members) instead of being a second owner.
+//
+// R6 legacy tolerance: a descriptor with NO `ux` block ⇒ `normalizeUx(undefined)`
+// ⇒ today's behavior (resizable everywhere, 2D-draggable, all handle zones live,
+// marker shell design-only).
+// normalizeUx NEVER throws on an absent block — only on an INVALID member.
+
+// The bbox interaction zones hitBboxZone (author-bbox-overlay.js) can classify a
+// pointer into. 'move' = interior drag; 'scale-*' = a corner/edge resize handle.
+// This is the ONE owner; author-bbox-overlay.js ferries it (drift = load-time throw).
+var UX_HANDLE_ZONES = Object.freeze([
+    'move',
+    'scale-tl', 'scale-tr', 'scale-bl', 'scale-br',
+    'scale-t', 'scale-b', 'scale-l', 'scale-r'
+]);
+
+// The render modes a part may be cursor-dragged in. Only 2D: a 3D scene never cursor-drags
+// (reposition is the aim + SPACE carry), so there is no per-object 3D knob to declare.
+var UX_DRAGGABLE_MODES = Object.freeze(['2d']);
+
+// When a manipulable object's visual shell renders (generalizes the Bite-4b
+// `_designMarker` boolean at the ONE _visibleLargeObjects authority):
+//   design — only while authoring (Design mode). The Bite-4b marker default.
+//   run    — always visible (the CEO's "red light bulb" opt-in).
+//   never  — never drawn.
+var UX_SHELL_RENDER = Object.freeze(['design', 'run', 'never']);
+
+// The `ux` envelope keys (documentation/introspection — NOT a required list; a
+// partial ux block fills the rest from the legacy defaults below).
+var UX_ENVELOPE_KEYS = Object.freeze([
+    'resizable', 'draggable', 'handles', 'shellRender'
+]);
+
+// Keys a ux block may NOT carry any more, each with what replaced it (FAIL-LOUD on use).
+var UX_DELETED_KEYS = Object.freeze({
+    inspectorSections: 'the Inspector shows a DECLARED object through its own descriptor (no per-role section list)'
+});
+
+function _uxFail(msg) {
+    throw new Error('[lib/shim/field-descriptor] normalizeUx: ' + msg +
+        ' (FAIL-LOUD — throw-or-apply, never silently dropped/defaulted-around.)');
+}
+
+/**
+ * normalizeUx(partial) → full ux bag.
+ *
+ * THROW-OR-APPLY: an INVALID member throws here; an ABSENT block (undefined/null)
+ * yields the legacy defaults (today's behavior, R6). Every field is optional; a
+ * partial block fills the rest from the defaults.
+ *
+ *   resizable         — boolean (default true). false ⇒ scale handles are never
+ *                       offered even for the SELECTED object (its corners never
+ *                       resize; the first-and-every interaction is select/move).
+ *   draggable         — { '2d':boolean } (default true). false disables the 2D
+ *                       cursor-drag. (A 3D scene never cursor-drags; '3d' is not a key.)
+ *   handles           — string[] ⊆ UX_HANDLE_ZONES (default = ALL zones). The
+ *                       live interaction zones; a zone NOT listed is downgraded
+ *                       to 'move' by the overlay (never a resize on the selecting
+ *                       click). `resizable:false` is the ergonomic shorthand for
+ *                       handles:['move'].
+ *   shellRender       — one of UX_SHELL_RENDER (default 'design'). When the
+ *                       object's visual shell/marker paints.
+ *
+ * @param {object|null|undefined} partial
+ * @returns {{resizable:boolean, draggable:{'2d':boolean}, handles:string[], shellRender:string}}
+ */
+function normalizeUx(partial) {
+    var bag = {
+        resizable: true,
+        draggable: { '2d': true },
+        handles: UX_HANDLE_ZONES.slice(),
+        shellRender: 'design'
+    };
+    if (partial === null || partial === undefined) { return bag; }
+    if (typeof partial !== 'object' || Array.isArray(partial)) {
+        _uxFail('a ux block must be a plain object; got ' +
+            (Array.isArray(partial) ? 'array' : typeof partial) + '.');
+    }
+    Object.keys(UX_DELETED_KEYS).forEach(function (k) {
+        if (partial[k] !== undefined) { _uxFail('"' + k + '" is DELETED — ' + UX_DELETED_KEYS[k] + '.'); }
+    });
+    if (partial.resizable !== undefined) {
+        if (typeof partial.resizable !== 'boolean') { _uxFail('"resizable" must be a boolean.'); }
+        bag.resizable = partial.resizable;
+    }
+    if (partial.draggable !== undefined) {
+        if (!_isPlainObject(partial.draggable)) { _uxFail('"draggable" must be a { "2d" } object.'); }
+        Object.keys(partial.draggable).forEach(function (k) {
+            if (UX_DRAGGABLE_MODES.indexOf(k) === -1) {
+                _uxFail('"draggable.' + k + '" is not a draggable mode ([' + UX_DRAGGABLE_MODES.join(', ') +
+                    ']) — a 3D scene never cursor-drags.');
+            }
+        });
+        var dr = { '2d': true };
+        for (var m = 0; m < UX_DRAGGABLE_MODES.length; m++) {
+            var mode = UX_DRAGGABLE_MODES[m];
+            if (partial.draggable[mode] !== undefined) {
+                if (typeof partial.draggable[mode] !== 'boolean') {
+                    _uxFail('"draggable.' + mode + '" must be a boolean.');
+                }
+                dr[mode] = partial.draggable[mode];
+            }
+        }
+        bag.draggable = dr;
+    }
+    if (partial.handles !== undefined) {
+        if (!Array.isArray(partial.handles)) { _uxFail('"handles" must be an array of zone names.'); }
+        for (var h = 0; h < partial.handles.length; h++) {
+            if (UX_HANDLE_ZONES.indexOf(partial.handles[h]) === -1) {
+                _uxFail('"handles" entry "' + String(partial.handles[h]) + '" is not a member of ' +
+                    'UX_HANDLE_ZONES ([' + UX_HANDLE_ZONES.join(', ') + ']).');
+            }
+        }
+        bag.handles = partial.handles.slice();
+    } else if (partial.resizable === false) {
+        // Ergonomic shorthand: an explicitly non-resizable object offers ONLY move.
+        bag.handles = ['move'];
+    }
+    if (partial.shellRender !== undefined) {
+        if (UX_SHELL_RENDER.indexOf(partial.shellRender) === -1) {
+            _uxFail('"shellRender" must be one of [' + UX_SHELL_RENDER.join(', ') + ']; got "' +
+                String(partial.shellRender) + '".');
+        }
+        bag.shellRender = partial.shellRender;
+    }
+    return bag;
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    FIELD_TYPES,
+    FIELD_ENVELOPE_KEYS,
+    normalizeFieldDescriptor,
+    UX_HANDLE_ZONES,
+    UX_DRAGGABLE_MODES,
+    UX_SHELL_RENDER,
+    UX_ENVELOPE_KEYS,
+    normalizeUx
+};

package/dist/shim/frame-data/index.js

@@ -0,0 +1,224 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/frame-data — The data-bubble schema contract.
+ *
+ * Single authority for the FrameData.data bag shape (§6 of
+ * docs/internal/engine/ENGINE_CONTRACT.md). The bubble is GENERIC and engine-opaque:
+ * SECTION_KEYS = ['detection', 'string_map']. The engine interprets NOTHING in
+ * string_map — it ferries every key verbatim across the JS↔WASM boundary.
+ *
+ * The data bubble has two cross-engine reserved namespaces (+ a JS-only ext):
+ *   detection  — written by the engine (MARK/DETECT primitives). Contains
+ *                detector_name and any future detection tags.
+ *   string_map — op-program-writable via `set 0.data.<key> = StrLit(value)`;
+ *                a flat { key: string, ... } the engine carries opaque. ALL
+ *                render data rides here as opaque keys: color is
+ *                string_map['render.color'] (CSV 'r,g,b,a'); outline is
+ *                string_map['render.outline'] === 'true'. Sugar/renderer code
+ *                serializes on write and deserializes on read — there is NO
+ *                typed `render` section (RETIRED: FrameDataRender,
+ *                FrameMetaData.render, render_color SoA field, normalizeRender).
+ *   ext        — developer-extensible; engine carries opaque, never reads.
+ *                NOTE (D2 decision): ext is JS-only. The Rust side has no ext
+ *                field — serde_wasm_bindgen v0.6 cannot round-trip a free-form
+ *                map through JsValue without serde_json::Value (which drops its
+ *                contents). ext writes are carried through JS-only paths and are
+ *                not asserted in cross-engine conformance. If ext survives a
+ *                JS→WASM→JS round-trip, treat it as undefined behavior.
+ *
+ * The canonical section key list drives conformance (see §5 — the data-bubble
+ * round-trip oracle iterates over SECTION_KEYS to assert completeness).
+ *
+ * Usage:
+ *   import { SECTION_KEYS, normalizeDataBubble, RENDER_INTENT_KEYS,
+ *            normalizeRenderIntent } from 'lib/shim/frame-data/index.js';
+ */
+
+
+
+/**
+ * Canonical section key table.
+ * Conformance iterates this list — adding a section here MUST be accompanied
+ * by a conformance assertion (cross-engine oracle, §5 item 2).
+ *
+ * Sections:
+ *   detection  — engine-writable (MARK/DETECT); { detector_name: string|null }
+ *   string_map — op-program-writable via `set 0.data.<key> = StrLit(value)`;
+ *                flat object { key: string, ... }. Absent → null in normalized form.
+ *                Cross-engine (JS + WASM). Owner: this file + FrameMetaData (tick_data.rs).
+ *                ALL render hints ride here as opaque keys (render.color, render.outline);
+ *                there is no typed `render` section.
+ */
+// 'render' section RETIRED — color (and all render hints) are opaque user-space data on
+// string_map; the engine never carries a typed render section. Owner: this file + FrameMetaData.
+const SECTION_KEYS = ['detection', 'string_map'];
+// NOTE: 'ext' is deliberately excluded because it is not cross-engine assertable.
+
+/**
+ * Normalize a partial data bag to the full canonical shape.
+ *
+ * Rules:
+ *   - Each reserved section (detection, string_map) is present as an object or null.
+ *   - Absent → null (mirrors the JS toFrameData() :2872 and Rust skip_serializing_if).
+ *   - Extra keys inside a section are preserved (pass-through).
+ *   - The ext key is passed through as-is (JS-only, not normalized).
+ *
+ * @param {object|null|undefined} partial — partial data bag from a frame or FrameData
+ * @returns {{ detection: object|null, string_map: object|null, ext: any }}
+ */
+function normalizeDataBubble(partial) {
+    if (partial === null || partial === undefined) {
+        return { detection: null, string_map: null };
+    }
+    return {
+        detection: (partial.detection !== null && partial.detection !== undefined)
+            ? partial.detection
+            : null,
+        string_map: (partial.string_map !== null && partial.string_map !== undefined &&
+                     typeof partial.string_map === 'object')
+            ? partial.string_map
+            : null,
+        ext: partial.ext !== undefined ? partial.ext : undefined,
+    };
+}
+
+/**
+ * Normalize the detection sub-section.
+ *   detector_name: string|null
+ */
+function normalizeDetection(partial) {
+    if (!partial) return { detector_name: null };
+    return {
+        detector_name: (partial.detector_name !== null && partial.detector_name !== undefined)
+            ? String(partial.detector_name)
+            : null,
+    };
+}
+
+// ── Render-intent vocabulary (Part C) ────────────────────────────────────────
+//
+// Render-intent keys are opaque string_map keys that sugar objects and experiment
+// setups write to describe per-frame render intent. Providers deserialize them on
+// read — the engine carries them verbatim and interprets nothing (I1 preserved).
+//
+// Key list owned HERE (single source). Conformance assertions MUST be driven off
+// this list so that adding a key automatically extends the test surface.
+//
+// Priority in any provider:
+//   render.color (exact CSV r,g,b,a) > render.colorScheme ramp via LightColor > renderer default
+
+/**
+ * RENDER_INTENT_KEYS — the canonical set of render-intent string_map keys.
+ *
+ * Conformance tests iterate this list. To add a new render-intent key:
+ *   1. Add the key string here.
+ *   2. Add its allowed values to RENDER_INTENT_VALUES.
+ *   3. Update normalizeRenderIntent to pass it through.
+ *   4. Add a conformance assertion (cross-engine oracle).
+ *   5. Update both providers to consume it.
+ *
+ * Current keys:
+ *   render.color       — CSV 'r,g,b,a' exact RGBA override (highest priority); existing. OPEN-ID (no value set).
+ *   render.outline     — 'true' | 'false' (or absent); existing. ENUM.
+ *   render.shape       — 'ball' | 'box' | 'circle' | 'cube' | 'sphere' (per-frame shape; absent → renderer default). ENUM.
+ *                        'sphere' = a TRUE 3D instanced-sphere mesh (three, _is3D), symmetric with 'cube';
+ *                        in 2D / p5 it degrades to the filled 'ball' disc (no per-provider map — RenderShape
+ *                        is the one authority; the three sphere path is gated on _is3D like the cube path).
+ *   render.colorScheme — 'roygbiv' | 'warmcool' (named LightColor ramp; absent → default). ENUM.
+ *   render.mesh        — external-geometry asset id (e.g. an Objaverse glTF id); absent → sprite/cube path.
+ *                        OPEN-ID: no RENDER_INTENT_VALUES entry (accept-any-string); the renderer's RenderMesh
+ *                        resolver FAILS LOUD at the output boundary if the asset cannot load — never silent.
+ *   render.meshScale   — per-frame scale MULTIPLIER for the frame's render.mesh clone (a number as a string;
+ *                        local override of the experiment-wide setRenderOption('meshScale',…)). OPEN-ID.
+ *   render.meshRotation— per-frame euler rotation for the frame's render.mesh clone, a CSV of THREE radians
+ *                        'rx,ry,rz' (same unit as a LargeObject's lo.meshRotation → clone.rotation.set). OPEN-ID.
+ *                        (Bite 5b R3-3: previously written ad-hoc but undeclared + unread; declared
+ *                        here at the owner and read per-clone in three-provider's _layoutMeshClones.)
+ *
+ * Two contract shapes (architect ruling 2026-06-30):
+ *   ENUM key    — has a RENDER_INTENT_VALUES[] array; decoders ferry the array (no re-listing); conformance-validated.
+ *   OPEN-ID key — has NO RENDER_INTENT_VALUES entry → assertRenderIntentConformance accepts any string; the
+ *                 decoder/resolver owns load-time validation and fails loud. Covers render.color and render.mesh.
+ */
+const RENDER_INTENT_KEYS = [
+    'render.color',
+    'render.outline',
+    'render.shape',
+    'render.colorScheme',
+    'render.mesh',
+    'render.meshScale',      // OPEN-ID — per-frame mesh scale multiplier (R3-3)
+    'render.meshRotation'    // OPEN-ID — per-frame mesh euler radians CSV (R3-3)
+];
+
+/**
+ * RENDER_INTENT_VALUES — allowed values for each key (for validation).
+ * Keys without an entry accept any string (e.g. render.color is a CSV).
+ */
+const RENDER_INTENT_VALUES = {
+    'render.shape':       ['ball', 'box', 'circle', 'cube', 'sphere'],
+    'render.colorScheme': ['roygbiv', 'warmcool'],
+    'render.outline':     ['true', 'false']
+    // NOTE: render.color, render.mesh, render.meshScale, render.meshRotation are OPEN-ID keys —
+    // deliberately NO entry here (accept-any-string: a CSV / an asset id / a number / an euler CSV).
+    // Their decoders/resolvers own validation and fail loud at the boundary.
+};
+
+/**
+ * normalizeRenderIntent — ferry a partial render-intent bag to the full canonical shape.
+ *
+ * Reads only the keys declared in RENDER_INTENT_KEYS; copies them into the normalized
+ * bag if present; absent keys are omitted (not defaulted — the renderer defaults apply).
+ * This is the "ferry the bag" pattern: the caller never re-enumerates the key list.
+ *
+ * @param {object|null|undefined} partial — partial string_map or explicit intent object
+ * @returns {{ 'render.color'?: string, 'render.outline'?: string,
+ *             'render.shape'?: string, 'render.colorScheme'?: string }}
+ */
+function normalizeRenderIntent(partial) {
+    var bag = {};
+    if (!partial || typeof partial !== 'object') return bag;
+    for (var i = 0; i < RENDER_INTENT_KEYS.length; i++) {
+        var k = RENDER_INTENT_KEYS[i];
+        if (partial[k] !== undefined && partial[k] !== null) {
+            bag[k] = String(partial[k]);
+        }
+    }
+    return bag;
+}
+
+/**
+ * assertRenderIntentConformance — throw if any key in a string_map bag violates the contract.
+ *
+ * Validates values for keys whose allowed set is enumerated in RENDER_INTENT_VALUES.
+ * Keys with unconstrained values (render.color, render.outline) are passed through.
+ * Unknown keys outside RENDER_INTENT_KEYS are ignored (the engine carries all keys opaque).
+ *
+ * @param {object} bag — string_map object to validate
+ * @throws {Error} if a constrained key holds an unknown value
+ */
+function assertRenderIntentConformance(bag) {
+    if (!bag) return;
+    for (var i = 0; i < RENDER_INTENT_KEYS.length; i++) {
+        var k = RENDER_INTENT_KEYS[i];
+        var allowed = RENDER_INTENT_VALUES[k];
+        if (allowed && bag[k] !== undefined && allowed.indexOf(bag[k]) === -1) {
+            throw new Error(
+                'render-intent conformance: key "' + k + '" has invalid value "' + bag[k] +
+                '"; allowed: ' + allowed.join('|')
+            );
+        }
+    }
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    SECTION_KEYS,
+    normalizeDataBubble,
+    normalizeDetection,
+    RENDER_INTENT_KEYS,
+    RENDER_INTENT_VALUES,
+    normalizeRenderIntent,
+    assertRenderIntentConformance
+};

package/dist/shim/index.js

@@ -0,0 +1,67 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim — the unified shim router (was lib/common).
+ *
+ * ESM barrel: re-exports all named exports. A missing import is a hard
+ * FAIL-LOUD load error — no window.Common* ambient globals.
+ *
+ * Usage (under vite with alias 'lib' → repo-root/lib):
+ *   import { Bus, Runtime, EXPERIMENTS, engineRouter } from 'lib/shim';
+ *
+ * Usage (direct relative path):
+ *   import { Bus } from '../../lib/shim/index.js';
+ */
+
+export { Bus }           from './bus.js';
+export { Runtime }       from './runtime/index.js';
+export { EXPERIMENTS, EXPERIMENT_TIERS, experimentById, experimentIs3D,
+         isPublicExperiment, publicExperiments,
+         internalExperiments } from './registry/experiments.js';
+export { WALKTHROUGH, walkthroughIs3D, walkthroughModes, walkthroughGroup,
+         walkthroughById,
+         FIRST_CONTACT_WALKTHROUGH_ID,
+         defaultWalkthroughModeId, effectiveRenderState } from './registry/walkthrough.js';
+export { loadSceneSource, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
+// The host-side experiment-iframe guard (the false-200 trap). Exported from the
+// barrel so every host that frames an experiment page (lib/features/ide's GYM)
+// asserts against the SAME contract.
+export { EXPERIMENT_PAGE_MARKERS, HOST_SHELL_ROOT_SELECTOR, FRAME_VERDICTS,
+         DEFAULT_FRAME_TIMEOUT_MS, classifyFrameProbe, probeExperimentFrame,
+         paintFrameGuardOverlay, watchExperimentFrame } from './experiment-frame/index.js';
+export { engineRouter, DEV_CORE_PROFILE, DIST_PROFILE } from './engine/router.js';
+// Math backend registry — re-exported so lib/features can import from the shim
+// barrel (the sanctioned route) without reaching past the shim into lib/egpt directly.
+// Module identity is preserved: both the barrel re-export and any direct import of
+// MathBackendRegistry.js resolve to the SAME singleton because ESM caches by
+// canonical URL — there is only one MathBackendRegistry instance. The registry
+// module has zero imports; the JS reference core never enters this graph.
+export { MathBackendRegistry, MathBackendNotAvailableError } from '../egpt/js/model/backend/MathBackendRegistry.js';
+// Notebook spine (WS-NOTEBOOK-A1): the native format parser/serializer and the
+// per-notebook kernel. The kernel calls Runtime.runCell directly (no Bus
+// executor). Consumers (the A2 notebook pane) import these from the barrel.
+export { parse, serialize, normalize } from './notebook/format.js';
+export { NotebookKernel, NOTEBOOK_CELL_STATUS } from './notebook/kernel.js';
+// Cell-as-module resolver (WS-NOTEBOOK-IMPORT B2) — the host-neutral in-memory
+// blob closure logic. Re-exported so tests + any host can build the closure
+// (Runtime injects the browser blob minter; the resolver itself is DOM-free and
+// must NOT assume a pane exists — model-gate ruling 6).
+export {
+    canonKey, resolveRelativeKey, hasImport, splitImportsAndBody,
+    rewriteRelativeToSiblingBlobs, buildModuleClosure, compileEntryModuleSource
+} from './notebook/module-resolver.js';
+// Notebook webview-realm model (WS-NOTEBOOK-REALM): the FOURTH BYO pluggable
+// surface. ONE registry authority + the frozen view-handle contract + the in-app
+// transport (same-origin direct fast path). A realm pre-load
+// is an above-the-shim renderer env; the frqtl pre-load co-locates the engine.
+export * as RealmRegistry from './notebook/realm-registry.js';
+export { makeViewHandle, isViewHandle, assertSerializable } from './notebook/view-handle.js';
+export { inAppTransport } from './notebook/realm-transport.js';
+// Realm import map — buildImportMap (vendor manifest → `{ imports }`), buildRealmImportMap
+// (vendor + @frqtl/setups, through ONE router) and spliceRealmImportMap (the ONE splice the
+// served hosts, lib/server/realm-html.js, and the static bake, apps/ide/vite.config.js, both
+// call). PURE, DOM-free.
+export { buildImportMap, buildRealmImportMap, spliceRealmImportMap } from './notebook/vendor-importmap.js';
+// Canonical setup-factory bare-specifier surface — the manifest and its import-map fragment
+// (merged by buildRealmImportMap above). PURE, DOM-free.
+export { buildFrqtlSetupsImportMap, FRQTL_SETUPS_MANIFEST } from './notebook/frqtl-setups-importmap.js';