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

package/dist/frqtl/objects/objects/frqtl-control-sync.js

@@ -0,0 +1,272 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * frqtl-control-sync.js — TRIGGERED-PULL reconciliation across N widgets
+ * driving the SAME declared-once control (gym-controls-as-sugar FULL
+ * CONVERGENCE build, Stage ii item 4).
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * `makeControlSync(opts) → { register(id, widget)->unregisterFn, pull()->Promise,
+ * notify(trigger), dispose() }`.
+ *
+ * The North Star (§5 design constraint) is STUDIO live drive-and-placement
+ * — multiple users/widgets "batting a sun around" the SAME control. A single
+ * widget mutating a value is NOT reconciliation; N widgets (a page slider, a
+ * panel row, a standalone widget, a REMOTE panel over an iframe) must all
+ * REFLECT the SAME canonical state after ANY of them writes. `ControlSync`
+ * is the PULL side of that: it periodically (per its configured `trigger`)
+ * re-reads every registered control's CURRENT value (via the existing
+ * `listControls` verb — the RPC, reused unmodified: `frqtl-controls-panel.js`'s
+ * `listControls` now refreshes bind-based descriptors from LIVE state before
+ * serializing, see that file's own docstring) and calls `widget.setValue(value,
+ * valueText)` on every OTHER registered widget for that control id — a
+ * DISPLAY-ONLY write (`frqtl-control-slider.js`'s `setValue`, hard-tested to
+ * never fire `onChange`/`onInput`) so reconciliation can never itself trigger
+ * another write (no echo/feedback loop).
+ *
+ * `ControlSync` never pushes on every mutation — it is a TRIGGERED PULL,
+ * never a push-per-write subscription (there is no such subscription
+ * mechanism anywhere in this stack: `FrqtlApp.onTick` is a single
+ * slot, not a multi-listener event bus). `SYNC_TRIGGERS` is the CLOSED set of
+ * cadences a page may wire:
+ *
+ *   'manual' — the caller calls `sync.pull()` explicitly whenever it wants a
+ *              reconciliation pass (e.g. after a Reset button, or any
+ *              one-off event). No automatic wiring; no DEV-WARN.
+ *   'tick'   — the page's OWN existing `onTick` callback gets ONE opt-in line:
+ *              `sync.notify('tick')` — coalesced via `requestAnimationFrame`
+ *              (or a `setTimeout` fallback in non-browser/test contexts) so a
+ *              60Hz tick loop produces AT MOST one pull per animation frame,
+ *              never one RPC round-trip per tick.
+ *   'pause'  — the page wires ONE line into its pause/idle handler instead
+ *              (`sync.notify('pause')`) — reconcile only when the sim is not
+ *              actively running (the lower-chatter default for a multi-user
+ *              "batting a sun around" session: continuous ticking rarely
+ *              needs continuous cross-widget reconciliation, but a pause is
+ *              exactly when a user expects to see everyone's current state).
+ *
+ * A configured `trigger:'tick'`/`'pause'` that never receives its matching
+ * `notify()` call within `opts.devWarnMs` (default 3000ms) logs ONE
+ * `console.warn` (DEV-WARN — the page forgot its one-line wiring;
+ * this is a development aid, never a thrown error — a sync with a forgotten
+ * trigger is inert, not broken).
+ *
+ * ── Two pull sources (in-app vs remote — the SAME `listControls` verb) ───────
+ *
+ * `opts.registry` (in-app, same-window): pulls via
+ * `frqtl-controls-panel.js`'s exported `dispatch(registry, 'listControls',
+ * [name])` — the SAME single dispatch point the panel's in-app path and RPC
+ * responder already share (DRY: a THIRD consumer of one implementation, not
+ * a re-derived listing).
+ *
+ * `opts.handle` (remote, over an iframe/postMessage — the EXISTING
+ * RPC): pulls via `handle.call('listControls', [name])` — the identical RPC
+ * primitive `frqtl-controls-panel.js`'s `mount({mode:'iframe'})` already
+ * builds via `lib/shim/rpc`. `ControlSync` does not care which — both
+ * resolve to a `Promise<Array<{id,label,min,max,step,value,valueText}>>`.
+ *
+ * Exactly one of `opts.registry` / `opts.handle` is required.
+ *
+ * ── Performance constraints (build requirements, not suggestions) ────────────
+ *
+ * - rAF-coalesced: `notify()` schedules AT MOST one pending pull per
+ *   animation frame, however many times it is called within that frame.
+ * - Skip-if-unchanged: a widget only receives `setValue()` when its value
+ *   actually differs from the LAST value that widget was reconciled to (a
+ *   per-(control id) last-value cache, not per-widget — every widget bound
+ *   to the same id shares the comparison, so N widgets cost one comparison).
+ * - Stateless widgets: `frqtl-control-slider.js` holds no reconciliation
+ *   state of its own — `ControlSync` is the ONE place that decides "did this
+ *   change" and "who needs to hear about it", designed for N concurrent
+ *   writers from the outset (the pull always re-reads canonical state fresh;
+ *   there is no per-writer diffing).
+ * - Zero added engine reads: the pull rides `listControls`'s EXISTING
+ *   `getFrameProperty`/`TickData` accessors — `ControlSync` itself performs
+ *   no engine query of its own.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ * Zero physics. Pure reconciliation plumbing over the EXISTING accessor/RPC
+ * substrate — a synced widget reflects the IDENTICAL simulation state any
+ * other consumer of the same control would read, just with a bounded
+ * (rAF-coalesced) display latency.
+ */
+
+import { FrqtlControlsPanel as _ControlsPanelNode } from '../../parts/FrqtlControlsPanel.js';
+
+
+
+
+
+/** The closed, exported vocabulary of pull cadences — FAIL-LOUD on any other value. */
+var SYNC_TRIGGERS = Object.freeze(['manual', 'tick', 'pause']);
+
+function _raf(fn) {
+    if (typeof requestAnimationFrame === 'function') { return requestAnimationFrame(fn); }
+    // Non-browser (Node test) / older-browser fallback — same ~1-frame cadence.
+    return setTimeout(fn, 16);
+}
+
+/**
+ * makeControlSync(opts) → sync handle.
+ *
+ * @param {object} opts
+ * @param {string} opts.name — the registry instance name (matches
+ *   `exposeRegistry`'s registry / `mount`'s `opts.name`).
+ * @param {object} [opts.registry] — in-app pull source (a makeControlRegistry()
+ *   instance already `exposeRegistry`'d). Exactly one of registry/handle required.
+ * @param {{call:(fn:string,args:any[])=>Promise}} [opts.handle] — remote pull
+ *   source (an RPC handle — `lib/shim/rpc`'s `makeChannelRpc`/`makeInAppRpc`
+ *   shape, e.g. one already built by `frqtl-controls-panel.js`'s `mount()`).
+ * @param {'manual'|'tick'|'pause'} [opts.trigger='manual'] — the ONE cadence
+ *   this sync instance is wired for (per-instance, not per-call — a page
+ *   with both a tick-driven and a pause-driven need makes TWO sync instances).
+ * @param {number} [opts.devWarnMs=3000] — grace window before the DEV-WARN
+ *   fires for `trigger:'tick'|'pause'` with no matching `notify()` call yet.
+ * @returns {{
+ *   register: (id:string, widget:{setValue:Function}) => (() => void),
+ *   pull: () => Promise<void>,
+ *   notify: (trigger:string) => void,
+ *   dispose: () => void
+ * }}
+ * @throws {Error} FAIL-LOUD — missing `opts.name`, an unrecognized `opts.trigger`,
+ *   or neither/both of `opts.registry`/`opts.handle` supplied.
+ */
+function makeControlSync(opts) {
+    opts = opts || {};
+    if (!opts.name) {
+        throw new Error('[frqtl-control-sync] makeControlSync requires opts.name. (FAIL-LOUD.)');
+    }
+    var trigger = (opts.trigger !== undefined) ? opts.trigger : 'manual';
+    if (SYNC_TRIGGERS.indexOf(trigger) === -1) {
+        throw new Error('[frqtl-control-sync] opts.trigger must be one of [' + SYNC_TRIGGERS.join(', ') +
+            ']; got ' + JSON.stringify(trigger) + '. (FAIL-LOUD.)');
+    }
+    var hasRegistry = !!opts.registry;
+    var hasHandle = !!opts.handle;
+    if (hasRegistry === hasHandle) {
+        throw new Error('[frqtl-control-sync] makeControlSync requires EXACTLY ONE of opts.registry ' +
+            '(in-app pull) or opts.handle (remote RPC pull); got ' +
+            (hasRegistry ? 'both' : 'neither') + '. (FAIL-LOUD.)');
+    }
+
+    var name = opts.name;
+    var widgetsById = Object.create(null);   // id -> [{setValue}]
+    var lastValueById = Object.create(null); // id -> last value reconciled TO (skip-if-unchanged)
+    var pendingRaf = null;                   // rAF-coalescing token (non-null while a pull is scheduled)
+    var disposed = false;
+
+    // ── Pull source (exactly one path is active, decided once at construction) ──
+    function _rawPull() {
+        if (hasRegistry) {
+            return Promise.resolve(_ControlsPanelNode.dispatch(opts.registry, 'listControls', [name]));
+        }
+        return opts.handle.call('listControls', [name]);
+    }
+
+    /**
+     * register(id, widget) — a widget joins this control id's reconciliation
+     * set. `widget` must expose `setValue(value, valueText?)`
+     * (`frqtl-control-slider.js`'s mount() return, or any object with the
+     * same display-only method). Multiple widgets may register under the
+     * SAME id (that IS the multi-widget reconciliation case).
+     * @returns {() => void} unregister — removes only THIS widget.
+     * @throws {Error} FAIL-LOUD on a missing id or a widget without setValue.
+     */
+    function register(id, widget) {
+        if (!id || typeof id !== 'string') {
+            throw new Error('[frqtl-control-sync] register requires a non-empty string id. (FAIL-LOUD.)');
+        }
+        if (!widget || typeof widget.setValue !== 'function') {
+            throw new Error('[frqtl-control-sync] register("' + id + '") requires a widget exposing ' +
+                'setValue(value, valueText?) (frqtl-control-slider.js\'s mount() return). (FAIL-LOUD.)');
+        }
+        (widgetsById[id] = widgetsById[id] || []).push(widget);
+        return function unregister() {
+            var arr = widgetsById[id];
+            if (!arr) { return; }
+            var i = arr.indexOf(widget);
+            if (i !== -1) { arr.splice(i, 1); }
+        };
+    }
+
+    /**
+     * pull() — perform ONE reconciliation pass immediately (bypasses rAF
+     * coalescing — this IS the manual trigger's entry point, and is also
+     * called by `notify()` once per coalesced frame).
+     * @returns {Promise<void>}
+     */
+    function pull() {
+        return _rawPull().then(function (descs) {
+            if (disposed) { return; }
+            descs.forEach(function (d) {
+                var arr = widgetsById[d.id];
+                if (!arr || !arr.length) { return; } // no widget registered for this id — nothing to reconcile
+                // Skip-if-unchanged: ONE comparison per control id, shared across
+                // every widget registered under it (performance constraint).
+                if (lastValueById[d.id] === d.value) { return; }
+                lastValueById[d.id] = d.value;
+                arr.forEach(function (w) { w.setValue(d.value, d.valueText); });
+            });
+        });
+    }
+
+    // ── DEV-WARN: a configured tick/pause trigger that
+    // never receives its matching notify() within the grace window means the
+    // page forgot its one-line wiring. Cleared the FIRST time notify() fires
+    // for the configured trigger (even a single call proves it's wired).
+    var devWarnMs = (typeof opts.devWarnMs === 'number') ? opts.devWarnMs : 3000;
+    var devWarnTimer = null;
+    if (trigger === 'tick' || trigger === 'pause') {
+        devWarnTimer = setTimeout(function () {
+            devWarnTimer = null;
+            if (typeof console !== 'undefined' && console.warn) {
+                console.warn('[frqtl-control-sync] trigger:"' + trigger + '" was declared for "' + name +
+                    '" but notify("' + trigger + '") was never called within ' + devWarnMs + 'ms — did the ' +
+                    'page forget its one-line `sync.notify(\'' + trigger + '\')` call (inside its own onTick ' +
+                    'or pause handler)? (DEV-WARN — an un-notified sync is inert, not broken.)');
+            }
+        }, devWarnMs);
+    }
+
+    /**
+     * notify(firedTrigger) — the page's ONE opt-in line
+     * (`sync.notify('tick')` inside its existing onTick, or
+     * `sync.notify('pause')` inside its pause handler). A call for a
+     * DIFFERENT trigger than this instance is configured for is a silent
+     * no-op (lets a page share one sync-notify call site across multiple
+     * lifecycle hooks without each sync instance needing to filter itself
+     * out — see file docstring: one instance = one cadence).
+     * rAF-coalesced: any number of `notify()` calls within one animation
+     * frame schedule AT MOST one `pull()`.
+     */
+    function notify(firedTrigger) {
+        // 'manual' instances never auto-reconcile from notify() AT ALL — even a
+        // notify('manual') call is a no-op; manual mode's entry point is
+        // `sync.pull()` directly, called by the caller whenever it wants a pass.
+        if (trigger === 'manual') { return; }
+        if (firedTrigger !== trigger) { return; }
+        if (devWarnTimer) { clearTimeout(devWarnTimer); devWarnTimer = null; }
+        if (pendingRaf !== null) { return; } // already coalesced into a scheduled frame
+        pendingRaf = _raf(function () {
+            pendingRaf = null;
+            if (disposed) { return; }
+            pull();
+        });
+    }
+
+    function dispose() {
+        disposed = true;
+        if (devWarnTimer) { clearTimeout(devWarnTimer); devWarnTimer = null; }
+        widgetsById = Object.create(null);
+    }
+
+    return { register: register, pull: pull, notify: notify, dispose: dispose };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+var FrqtlControlSync = { makeControlSync: makeControlSync, SYNC_TRIGGERS: SYNC_TRIGGERS };
+
+export { FrqtlControlSync };
+

package/dist/frqtl/objects/objects/frqtl-control-widgets.js

@@ -0,0 +1,219 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * frqtl-control-widgets.js — THE widget table (presentation pass Item 2).
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * `resolveWidget(row)` → a widget NAME, from the kind-orthogonal `widget` seam
+ *   the schema owns (`ControlsSchema.WIDGETS`), falling back to the kind's
+ *   natural widget. This is the ONE place that decision is made.
+ *
+ * `mountWidget(hostEl, opts)` → `{ dispose(), setValue(value, valueText?) }`
+ *   — renders ONE control row, dispatching on `resolveWidget`. Every host (the
+ *   collection PANEL, the canvas OVERLAY) calls THIS; there is no second
+ *   widget-resolution authority anywhere.
+ *
+ *   opts.initial  — the serializable display row `{id,label,kind,widget,value,
+ *                   valueText,min,max,step,action,values}` (exactly what
+ *                   `FrqtlControlsPanel.dispatch(…, 'listControls', …)` returns).
+ *   opts.onInput  — `(value) => *|Promise<{value,valueText}>` for value widgets.
+ *   opts.onAction — `(actionName) => *|Promise<*>` for the `button` widget.
+ *
+ * ── DRY: the slider is DELEGATED, never re-implemented ───────────────────────
+ *
+ * `slider` hands straight to `frqtl-control-slider.js` — the ONE slider-rendering
+ * implementation, unchanged. This table adds only the widgets that did not exist:
+ * toggle/checkbox (a scalar 0/1 rendered as a switch — NOT a new kind, per the
+ * schema's rule), text (the string kind), and button (the action kind).
+ * `frqtl-controls-panel.js`'s renderRows consults THIS table instead of hardcoding
+ * the slider, so a second resolution authority never comes into existence.
+ *
+ * ── Layer 2: physics behaviour ──────────────────────────────────────────────
+ *
+ * ZERO physics — pure DOM plumbing over a caller-supplied row + callback. Driving
+ * a control through any widget in this table produces the IDENTICAL simulation
+ * effect as driving the same declared control anywhere else.
+ */
+
+import * as _ControlsSchemaNode from '../../../shim/controls/index.js';
+import { FrqtlControlSlider as _ControlSliderNode } from './frqtl-control-slider.js';
+
+
+
+
+
+/**
+ * WIDGET_BY_KIND — each control kind's NATURAL widget, used when a descriptor
+ * declares no explicit `widget`. Kinds with their own bespoke host UI
+ * (camera/matrix/loop) have no row: they are not rendered by this table.
+ */
+var WIDGET_BY_KIND = Object.freeze({
+    scalar: 'slider',
+    text:   'text',
+    action: 'button'
+});
+
+/**
+ * resolveWidget(row) — the ONE widget decision. An explicit `widget` (validated
+ * against ControlsSchema.WIDGETS by the schema owner) wins; otherwise the kind's
+ * natural widget; otherwise 'slider' (the historical default — every pre-Item-2
+ * row the panel rendered was a scalar slider, so this keeps them byte-identical).
+ * @param {object} row
+ * @returns {string} a ControlsSchema.WIDGETS member.
+ */
+function resolveWidget(row) {
+    var WIDGETS = _ControlsSchemaNode.WIDGETS;
+    if (row && row.widget) {
+        if (WIDGETS.indexOf(row.widget) === -1) {
+            throw new Error('[frqtl-control-widgets] unknown widget "' + row.widget + '" on control "' +
+                (row.id || '?') + '" — must be one of [' + WIDGETS.join(', ') + ']. (FAIL-LOUD.)');
+        }
+        return row.widget;
+    }
+    return (row && WIDGET_BY_KIND[row.kind]) || 'slider';
+}
+
+// ── Row chrome shared by the non-slider widgets ─────────────────────────────
+
+function _row() {
+    var el = document.createElement('div');
+    el.className = 'frqtl-control-widget-row';
+    el.style.cssText = 'display:flex;align-items:center;gap:8px;margin:4px 0;font:12px sans-serif;color:#ccc;';
+    return el;
+}
+function _label(text) {
+    var el = document.createElement('span');
+    el.textContent = text;
+    el.style.cssText = 'min-width:56px;';
+    return el;
+}
+function _settle(promiseLike, onValue, onError) {
+    Promise.resolve(promiseLike).then(onValue).catch(function (e) {
+        if (onError) { onError(e); }
+        if (typeof console !== 'undefined' && console.error) {
+            console.error('[frqtl-control-widgets] control dispatch failed:', e);
+        }
+    });
+}
+
+/** A checkbox over a SCALAR 0/1 (the schema's "a toggle IS a scalar" rule). */
+function _mountToggle(hostEl, initial, onInput, styleAsSwitch) {
+    var row = _row();
+    var box = document.createElement('input');
+    box.type = 'checkbox';
+    box.checked = !!Number(initial.value);
+    box.setAttribute('data-frqtl-control-id', initial.id);
+    if (styleAsSwitch) { box.style.cssText = 'width:16px;height:16px;accent-color:#ffb450;'; }
+    var val = document.createElement('span');
+    val.textContent = initial.valueText !== undefined ? initial.valueText : String(initial.value);
+    val.style.cssText = 'min-width:32px;text-align:right;color:#ffb450;';
+    box.addEventListener('change', function () {
+        _settle(onInput(box.checked ? 1 : 0), function (res) {
+            if (res && res.valueText !== undefined) { val.textContent = res.valueText; }
+        }, function () { val.textContent = 'ERR'; });
+    });
+    row.appendChild(_label(initial.label + ':'));
+    row.appendChild(box);
+    row.appendChild(val);
+    hostEl.appendChild(row);
+    return {
+        dispose: function () { if (row.parentNode) { row.parentNode.removeChild(row); } },
+        setValue: function (value, valueText) {
+            box.checked = !!Number(value);
+            val.textContent = (valueText !== undefined) ? valueText : String(value);
+        }
+    };
+}
+
+/** A free-text input over the `text` kind. */
+function _mountText(hostEl, initial, onInput) {
+    var row = _row();
+    var input = document.createElement('input');
+    input.type = 'text';
+    input.value = (initial.value !== undefined && initial.value !== null) ? String(initial.value) : '';
+    input.setAttribute('data-frqtl-control-id', initial.id);
+    input.style.cssText = 'flex:1;min-width:80px;background:#1b2330;color:#ddd;border:1px solid #33405a;' +
+        'border-radius:3px;padding:2px 4px;font:12px sans-serif;';
+    input.addEventListener('change', function () { _settle(onInput(input.value), function () {}); });
+    row.appendChild(_label(initial.label + ':'));
+    row.appendChild(input);
+    hostEl.appendChild(row);
+    return {
+        dispose: function () { if (row.parentNode) { row.parentNode.removeChild(row); } },
+        setValue: function (value) { input.value = (value === undefined || value === null) ? '' : String(value); }
+    };
+}
+
+/** A momentary button over the `action` kind. */
+function _mountButton(hostEl, initial, onAction) {
+    var row = _row();
+    var btn = document.createElement('button');
+    btn.type = 'button';
+    btn.textContent = initial.label;
+    btn.setAttribute('data-frqtl-control-id', initial.id);
+    btn.setAttribute('data-frqtl-control-action', initial.action || '');
+    btn.style.cssText = 'background:#26324a;color:#e6edf7;border:1px solid #3d4d6b;border-radius:3px;' +
+        'padding:3px 10px;font:12px sans-serif;cursor:pointer;';
+    btn.addEventListener('click', function () {
+        _settle(onAction(initial.action), function () {});
+    });
+    row.appendChild(btn);
+    hostEl.appendChild(row);
+    return {
+        dispose: function () { if (row.parentNode) { row.parentNode.removeChild(row); } },
+        // An action is stateless — reconciliation has nothing to write. Present so
+        // every widget shares ONE handle shape (ControlSync registers uniformly).
+        setValue: function () {}
+    };
+}
+
+/**
+ * mountWidget(hostEl, opts) — render one control row through the resolved widget.
+ * @param {HTMLElement} hostEl
+ * @param {object} opts — { initial, onInput?, onAction? }
+ * @returns {{dispose:Function, setValue:Function}}
+ * @throws {Error} FAIL-LOUD on a missing host, a missing row, an unknown widget,
+ *   or a widget whose required callback was not supplied.
+ */
+function mountWidget(hostEl, opts) {
+    opts = opts || {};
+    if (!hostEl) { throw new Error('[frqtl-control-widgets] mountWidget requires a host element. (FAIL-LOUD.)'); }
+    var initial = opts.initial;
+    if (!initial) { throw new Error('[frqtl-control-widgets] mountWidget requires opts.initial. (FAIL-LOUD.)'); }
+    var widget = resolveWidget(initial);
+
+    if (widget === 'button') {
+        if (typeof opts.onAction !== 'function') {
+            throw new Error('[frqtl-control-widgets] the "button" widget (control "' + initial.id +
+                '") requires opts.onAction. (FAIL-LOUD — never a dead button.)');
+        }
+        return _mountButton(hostEl, initial, opts.onAction);
+    }
+    if (typeof opts.onInput !== 'function') {
+        throw new Error('[frqtl-control-widgets] the "' + widget + '" widget (control "' + initial.id +
+            '") requires opts.onInput. (FAIL-LOUD.)');
+    }
+    if (widget === 'slider') {
+        // DELEGATED — the ONE slider implementation, not re-rendered here.
+        return _ControlSliderNode.mount(hostEl, { initial: initial, onInput: opts.onInput });
+    }
+    if (widget === 'toggle' || widget === 'checkbox') {
+        return _mountToggle(hostEl, initial, opts.onInput, widget === 'toggle');
+    }
+    if (widget === 'text') {
+        return _mountText(hostEl, initial, opts.onInput);
+    }
+    throw new Error('[frqtl-control-widgets] no renderer for widget "' + widget + '". (FAIL-LOUD.)');
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+var FrqtlControlWidgets = {
+    WIDGET_BY_KIND: WIDGET_BY_KIND,
+    resolveWidget: resolveWidget,
+    mountWidget: mountWidget
+};
+
+export { FrqtlControlWidgets };
+

package/dist/frqtl/objects/objects/frqtl-control-write-queue.js

@@ -0,0 +1,174 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * frqtl-control-write-queue.js — the WRITE-side symmetric primitive to
+ * `frqtl-control-sync.js`'s PULL-side coalescing (Studio Controls
+ * Realignment S4, design §2.3.4 — "add the symmetric primitive: an
+ * rAF-coalesced, last-write-wins-per-frame-per-control-id write queue").
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ * `makeControlWriteQueue(opts) → { write(id, fn), flushSync(), dispose() }`.
+ *
+ * `write(id, fn)` registers `fn` as the pending write for control `id`. Any
+ * number of `write()` calls for the SAME `id` within one animation frame
+ * collapse to ONE scheduled flush — the LAST `fn` registered wins (a fast
+ * slider drag firing many `input` events per frame does not fire the
+ * accessor once per event; it fires it once per frame, with the final
+ * value). Writes for DIFFERENT ids in the same frame all flush together
+ * (each is independent — one control's write never blocks another's).
+ *
+ * ── Canonical home (why HERE, beside frqtl-control-sync.js, not inside it) ───
+ *
+ * The design note explicitly allows either "in frqtl-control-sync.js or a
+ * sibling" — a SIBLING file is chosen: pull (`frqtl-control-sync.js`) and
+ * write (this file) are symmetric but INDEPENDENT concerns (a page/panel may
+ * want one without the other — e.g. a read-only remote observer widget never
+ * writes), and keeping them as two single-purpose files matches this
+ * directory's existing one-concern-per-file convention (`controlBind.js`
+ * execution vs `makeControlsForObject.js` generation vs
+ * `frqtl-controls-panel.js` transport). A merged file would force every pull
+ * consumer to also carry write-queue machinery it may not use.
+ *
+ * Loaded into the shared game layer (`lib/shim/engine/game-layer-manifest.js`
+ * `OBJECT_SCRIPTS`, alongside `controlBind.js`/`makeControlsForObject.js`/
+ * `frqtl-control-slider.js`/`frqtl-controls-panel.js`) — Studio's author
+ * iframe (`lib/features/ide/AuthorView.jsx`) can load ANY canonical
+ * experiment page, so it needs `cw.FrqtlControlWriteQueue` available
+ * regardless of which page is currently loaded, exactly the same "promoted
+ * from a per-page opt-in" reasoning as those four siblings (see the
+ * manifest's own comment block for the S3 precedent).
+ *
+ * ── FAIL-LOUD condition (non-negotiable) ────────────────────────────────────
+ *
+ * A throwing accessor write mid-drag MUST PROPAGATE — never be silently
+ * swallowed under last-write-wins coalescing. `flush()`/`flushSync()` below
+ * do NOT wrap the invocation of a pending write in try/catch: if the ONE
+ * surviving `fn` for an id throws, the exception propagates OUT of
+ * `flush()` (and therefore out of the rAF callback that called it — visible
+ * as an uncaught exception, exactly as visible as an uncoalesced synchronous
+ * throw would have been). This is NOT the same claim as "no id in a batch
+ * ever loses a write" — coalescing DISCARDING an earlier `fn` for the SAME id
+ * in favor of a later one is normal, intentional last-write-wins semantics,
+ * not error-swallowing. What must never happen is the QUEUE ITSELF catching
+ * and discarding the ONE fn that DOES run. (A caller MAY still wrap its own
+ * registered `fn` in its own try/catch for its own UX reasons — e.g. Studio's
+ * Inspector `commitField` logging a console.error — that is the caller's
+ * choice, not this file's; it is not "swallowed by coalescing".)
+ *
+ * If multiple DIFFERENT ids are pending in the same batch and an earlier id's
+ * fn throws, later ids in that SAME flush pass are skipped (the exception
+ * unwinds the loop) — mirroring what an uncoalesced synchronous caller doing
+ * the same writes back-to-back would also experience (one throw stops the
+ * sequence). Each id's write is independently re-attempted on ITS OWN next
+ * `write()` call, same as any other write.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ * Zero physics. Pure scheduling — coalescing WHEN an accessor write happens
+ * (once per animation frame instead of once per input event) never changes
+ * WHAT the write does; the applied value is byte-identical to calling the
+ * same accessor directly with the same (final) value.
+ */
+
+
+function _raf(fn) {
+    if (typeof requestAnimationFrame === 'function') { return requestAnimationFrame(fn); }
+    // Non-browser (Node test) / older-browser fallback — same ~1-frame cadence
+    // as frqtl-control-sync.js's own fallback.
+    return setTimeout(fn, 16);
+}
+
+function _cancelRaf(token) {
+    if (typeof cancelAnimationFrame === 'function') {
+        try { cancelAnimationFrame(token); } catch (e) { /* best-effort */ }
+    } else {
+        try { clearTimeout(token); } catch (e) { /* best-effort */ }
+    }
+}
+
+/**
+ * makeControlWriteQueue(opts) → write-queue handle.
+ *
+ * @param {object} [opts] — reserved for future options; no required fields today.
+ * @returns {{
+ *   write: (id:string, fn:Function) => void,
+ *   flushSync: () => void,
+ *   dispose: () => void
+ * }}
+ */
+function makeControlWriteQueue(opts) {
+    opts = opts || {};
+
+    var pending = Object.create(null); // id -> fn (LAST WRITE WINS per id per frame)
+    var pendingRaf = null;             // rAF-coalescing token (non-null while a flush is scheduled)
+    var disposed = false;
+
+    /**
+     * flush() — apply every pending write, one call each, in registration
+     * order. See file docstring's FAIL-LOUD condition: no try/catch here.
+     */
+    function flush() {
+        pendingRaf = null;
+        if (disposed) { return; }
+        var batch = pending;
+        pending = Object.create(null);
+        var ids = Object.keys(batch);
+        for (var i = 0; i < ids.length; i++) {
+            batch[ids[i]](); // FAIL-LOUD: a throw here propagates to the caller of flush()/flushSync().
+        }
+    }
+
+    /**
+     * write(id, fn) — register `fn` as the pending write for `id`. Schedules
+     * AT MOST one rAF-coalesced flush; any number of calls for ids already
+     * pending within the same frame just replace their fn (last-write-wins).
+     * @param {string} id — non-empty string, the control id this write targets.
+     * @param {Function} fn — zero-arg closure that performs the actual accessor
+     *   write (the caller closes over whatever value/target it needs).
+     * @throws {Error} FAIL-LOUD — missing/invalid id or fn.
+     */
+    function write(id, fn) {
+        if (disposed) { return; }
+        if (typeof id !== 'string' || !id) {
+            throw new Error('[frqtl-control-write-queue] write requires a non-empty string id. (FAIL-LOUD.)');
+        }
+        if (typeof fn !== 'function') {
+            throw new Error('[frqtl-control-write-queue] write("' + id + '") requires a function. (FAIL-LOUD.)');
+        }
+        pending[id] = fn; // last-write-wins-per-frame-per-control-id
+        if (pendingRaf !== null) { return; } // already coalesced into a scheduled frame
+        pendingRaf = _raf(flush);
+    }
+
+    /**
+     * flushSync() — apply all pending writes NOW, bypassing the rAF wait.
+     * Cancels any already-scheduled rAF/timeout first (avoids a double-flush).
+     * Exposed for tests (deterministic, no timer dependency) and for callers
+     * that need a guaranteed-applied write before proceeding synchronously
+     * (e.g. a Reset action right after a drag).
+     */
+    function flushSync() {
+        if (pendingRaf !== null) { _cancelRaf(pendingRaf); pendingRaf = null; }
+        flush();
+    }
+
+    /**
+     * dispose() — discard all pending writes (they never fire) and cancel any
+     * scheduled flush. Idempotent.
+     */
+    function dispose() {
+        if (disposed) { return; }
+        disposed = true;
+        pending = Object.create(null);
+        if (pendingRaf !== null) { _cancelRaf(pendingRaf); pendingRaf = null; }
+    }
+
+    return { write: write, flushSync: flushSync, dispose: dispose };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+var FrqtlControlWriteQueue = { makeControlWriteQueue: makeControlWriteQueue };
+
+export { FrqtlControlWriteQueue };
+