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

package/dist/shim/render/sun-look.js

@@ -0,0 +1,33 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/render/sun-look.js — the ONE owner of the SUN's look: its render-option bag.
+ *
+ * The values are the FINAL FX bag EXACTLY as played and captured in an export session
+ * (new_sun.png is the primary oracle; sun.png stays the historical dense reference), verbatim from
+ * the exported renderState. They are in the write door's shape — a BAG, what
+ * `runner.setRenderOptions(bag)` takes — and every key is a capability the three renderer declares.
+ *
+ *   SunLook.SUN_RENDER   — the sun's whole look (rung r8-sun's render rows).
+ *   SunLook.SUN_GODRAYS  — the god-ray pair, PICKED from SUN_RENDER: what another scene lights up
+ *                          "at the sun's settings" with (the mirror's 3D mode, the 3D DSE's switch).
+ *
+ * `godraySource` is NOT here: what the rays are computed from is each borrower's declared choice.
+ * The camera is NOT here: a pose is a rung row's view, not a look.
+ *
+ * Readers: `lib/shim/registry/walkthrough.js` (a named import) and a scene sketch (`SunLook`, the
+ * bridge's publication of this module until the game layer imports it). Zero physics: render
+ * options are read only by the renderer.
+ */
+
+
+var SUN_RENDER = Object.freeze({
+    shape: 'sphere', colorScheme: 'warmcool',
+    godrays: 1.08, godrayDensity: 1.085,
+    glowIntensity: 0.93, heat: 0.35, smoke: 0
+});
+
+// The pair other scenes light up "at the sun's settings" with — PICKED from SUN_RENDER, never re-typed.
+var SUN_GODRAYS = Object.freeze({ godrays: SUN_RENDER.godrays, godrayDensity: SUN_RENDER.godrayDensity });
+
+export { SUN_RENDER, SUN_GODRAYS };

package/dist/shim/render-state/apply.js

@@ -0,0 +1,262 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/render-state/apply.js — the ONE owner of the renderState contract AND of the procedure
+ * that applies a renderState bag to a booted runner.
+ *
+ * A renderState bag (renderer/seed load-time selections + render rows + camera + backdrop
+ * visibility + page controls) is replayed by every host: the GYM rung frame, STUDIO, the bundle's
+ * `bootRecipe`, the hosted eyes. They all come through `RenderState.apply` — directly (the bundle,
+ * which is its own page) or through the blank page's door `FrqtlPage.applyRenderState`
+ * (lib/frqtl/experiments/empty/index.html). A host never restates the procedure.
+ *
+ * ── Layer 1: API contract (named ES-module exports) ─────────────────────────────────────────────
+ *
+ *   apply(runner, bag, env) → { applied, retained, camera, preset, backdrop }
+ *       bag   — ANY renderState (raw or normalized); normalized here, so a registry bag and a saved
+ *               project's bag take one path.
+ *       env   — { knownNames: string[] }: `RenderCapabilitiesCommon.knownRenderCapabilityNames(
+ *               providers)` — the page's renderer registry is a page global, not the runner's.
+ *       Everything is RESOLVED before anything is written: a row no renderer declares, a camera
+ *       on a runner with no `cameraControl`, or a camera handle with no `presets` THROWS with the
+ *       runner untouched.
+ *       Rows     → `partitionRenderRows` against `runner.renderCapabilities()`, then ONE
+ *                  `runner.setRenderOptions(applied)` batch.
+ *       Camera   → `pickCameraReplay`: a preset the booted camera offers (`cameraControl.presets`)
+ *                  → `setPreset`, camera:'preset'; a preset it does not offer is NOT applied,
+ *                  camera:'retained' (the CALLER decides whether that is acceptable); an orbit →
+ *                  `setOrbit`, camera:'orbit'; no camera → null. `preset` names the preset applied
+ *                  or retained (null for an orbit or no camera).
+ *       Backdrop → `backdropOf(runner)`: a boolean `backdropVisible` →
+ *                  `runner.updateObjectProperty(lo, 'visible', v)`, backdrop:v. An ABSENT
+ *                  `backdropVisible` (null after normalizing) is not written — the scene's own
+ *                  `addBackdrop(…, {visible})` rules — and reports backdrop:null, as does no backdrop LO.
+ *       `pageControls` are NOT applied here: they are STUDIO's host-specific override.
+ *
+ *   backdropOf(runner)                   — THE answer to "which LO is the backdrop" for a host: the
+ *                                          census LO marked `backdrop === true`, or null. STUDIO's
+ *                                          save captures its visibility through it, so capture and
+ *                                          replay read one fact.
+ *   normalizeSavedRenderState(raw)       — tolerant normalizer for a LOADED bag (never throws).
+ *   pickCameraReplay(saved)              — pure decision: named preset over raw orbit.
+ *   partitionRenderRows(rows, declared, known) — apply / retain / throw, before anything is written.
+ *   renderRowsFromBag(bag)               — a { key: value } render-option bag as ordered rows.
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────────────────────────
+ *
+ * Zero physics. Replaying a value has the IDENTICAL effect as a user re-dragging the same control;
+ * the runner's own doors (`setRenderOptions`, `cameraControl`, `updateObjectProperty`) do the work.
+ */
+
+
+/** @returns {boolean} */
+function _isPlainObject(v) { return !!v && typeof v === 'object' && !Array.isArray(v); }
+
+/**
+ * @param {{camera?: {orbit?:object|null, preset?:string|null}|null}} saved — a normalized bag.
+ * @returns {{mode:'preset', name:string}|{mode:'orbit', orbit:object}|null}
+ *   `null` — no camera was captured (nothing to replay).
+ */
+function pickCameraReplay(saved) {
+    if (!saved || !saved.camera) { return null; }
+    var cam = saved.camera;
+    if (typeof cam.preset === 'string' && cam.preset.length > 0) {
+        return { mode: 'preset', name: cam.preset };
+    }
+    if (cam.orbit && typeof cam.orbit === 'object') {
+        return { mode: 'orbit', orbit: cam.orbit };
+    }
+    return null;
+}
+
+/**
+ * Tolerant normalizer for a saved module's `renderState` field — a stored record may be
+ * `undefined` (a pre-S6 legacy module), `null`, or a shape from another `version` — NEVER throws;
+ * every missing/malformed field degrades to a NEUTRAL default (empty array / null), one `apply`
+ * writes nothing for.
+ *
+ * @param {*} raw
+ * @returns {{
+ *   version: number,
+ *   renderer: string|null,
+ *   engine: string|null,
+ *   seed: string|null,
+ *   backdropVisible: boolean|null,
+ *   camera: {orbit:object|null, preset:string|null}|null,
+ *   render: {key:string, value:*}[],
+ *   pageControls: {id:string, value:*, bind:{object:string,prop:string}|null}[]
+ * }}
+ */
+function normalizeSavedRenderState(raw) {
+    var r = _isPlainObject(raw) ? raw : {};
+    var camera = null;
+    if (_isPlainObject(r.camera)) {
+        camera = {
+            orbit: _isPlainObject(r.camera.orbit) ? r.camera.orbit : null,
+            preset: (typeof r.camera.preset === 'string') ? r.camera.preset : null
+        };
+    }
+    return {
+        version: (typeof r.version === 'number') ? r.version : 1,
+        renderer: (typeof r.renderer === 'string' && r.renderer.length > 0) ? r.renderer : null,
+        engine: (typeof r.engine === 'string' && r.engine.length > 0) ? r.engine : null,
+        seed: (r.seed !== undefined && r.seed !== null && r.seed !== '') ? String(r.seed) : null,
+        backdropVisible: (typeof r.backdropVisible === 'boolean') ? r.backdropVisible : null,
+        camera: camera,
+        render: Array.isArray(r.render) ? r.render.filter(function (row) {
+            return _isPlainObject(row) && typeof row.key === 'string' && row.key.length > 0;
+        }) : [],
+        pageControls: Array.isArray(r.pageControls) ? r.pageControls.filter(function (row) {
+            return _isPlainObject(row) && typeof row.id === 'string' && row.id.length > 0;
+        }).map(function (row) {
+            return {
+                id: row.id,
+                value: row.value,
+                bind: (_isPlainObject(row.bind) && typeof row.bind.object === 'string' &&
+                       typeof row.bind.prop === 'string') ? { object: row.bind.object, prop: row.bind.prop } : null
+            };
+        }) : []
+    };
+}
+
+/**
+ * Resolve a bag's `render[]` rows against the renderer that will RECEIVE them, before anything is
+ * written. Each row falls in exactly one class:
+ *   - declared by the target        → `apply` (a `{key: value}` bag for ONE
+ *                                     `runner.setRenderOptions` call; a later row wins)
+ *   - declared by another renderer  → `retained` (NOT applied; the host decides what to do)
+ *   - declared by no renderer       → THROWS (a typo, or a deleted option)
+ *
+ * @param {{key:string, value:*}[]} rows
+ * @param {string[]} declaredNames — the target's `renderCapabilities()` names
+ * @param {string[]} knownNames — `RenderCapabilitiesCommon.knownRenderCapabilityNames(registry)`
+ * @returns {{apply: Object<string, *>, retained: {key:string, value:*}[]}}
+ * @throws {Error} on a row whose key no registered renderer declares, or bad arguments.
+ */
+function partitionRenderRows(rows, declaredNames, knownNames) {
+    if (!Array.isArray(rows) || !Array.isArray(declaredNames) || !Array.isArray(knownNames)) {
+        throw new Error('[render-state] partitionRenderRows(rows, declaredNames, knownNames) takes three ' +
+            'arrays. (FAIL-LOUD.)');
+    }
+    var apply = {};
+    var retained = [];
+    for (var i = 0; i < rows.length; i++) {
+        var row = rows[i];
+        if (declaredNames.indexOf(row.key) !== -1) {
+            apply[row.key] = row.value;
+        } else if (knownNames.indexOf(row.key) !== -1) {
+            retained.push({ key: row.key, value: row.value });
+        } else {
+            throw new Error('[render-state] saved render option "' + row.key + '" is declared by no ' +
+                'registered renderer (known: [' + knownNames.join(', ') + ']). (FAIL-LOUD: a typo or a ' +
+                'deleted option would otherwise silently change the picture.)');
+        }
+    }
+    return { apply: apply, retained: retained };
+}
+
+/**
+ * renderRowsFromBag(bag) — a render-option BAG (`{ key: value }`, the `runner.setRenderOptions`
+ * shape) as the ordered `[{ key, value }]` render rows a renderState carries, in the bag's own key
+ * order. The ONE place a bag becomes rows, so a look owned as a bag (lib/shim/render/sun-look.js)
+ * reaches a rung's renderState without a hand-typed row list.
+ *
+ * @param {Object<string, *>} bag
+ * @returns {{key:string, value:*}[]}
+ * @throws {Error} on a non-object or an array.
+ */
+function renderRowsFromBag(bag) {
+    if (!bag || typeof bag !== 'object' || Array.isArray(bag)) {
+        throw new Error('[render-state] renderRowsFromBag(bag) takes a plain { key: value } object; got ' +
+            (Array.isArray(bag) ? 'an array' : String(bag)) + '. (FAIL-LOUD.)');
+    }
+    return Object.keys(bag).map(function (k) { return { key: k, value: bag[k] }; });
+}
+
+/** The backdrop LargeObject in the runner's census (the one with `backdrop === true`), or null. */
+function backdropOf(runner) {
+    var los = runner && runner.largeObjects;
+    if (!Array.isArray(los)) {
+        throw new Error('[render-state] RenderState.backdropOf: runner.largeObjects is not the world\'s census ' +
+            '(an array) — the backdrop is found there and nowhere else. (FAIL-LOUD.)');
+    }
+    for (var i = 0; i < los.length; i++) {
+        if (los[i] && los[i].backdrop === true) { return los[i]; }
+    }
+    return null;
+}
+
+/**
+ * Apply a renderState bag to a booted runner — see the Layer 1 contract above.
+ *
+ * @param {object} runner — a booted FrqtlApp (its provider attached, its scene built).
+ * @param {*} bag — a renderState bag, raw or normalized.
+ * @param {{knownNames:string[]}} env
+ * @returns {{applied:Object<string,*>, retained:{key:string,value:*}[],
+ *            camera:'preset'|'orbit'|'retained'|null, preset:string|null, backdrop:boolean|null}}
+ * @throws {Error} on bad arguments, a row no renderer declares, a value its descriptor refuses, a
+ *   camera on a runner with no camera control, or any write the runner refuses.
+ */
+function apply(runner, bag, env) {
+    if (!runner || typeof runner.renderCapabilities !== 'function' || typeof runner.setRenderOptions !== 'function') {
+        throw new Error('[render-state] RenderState.apply(runner, bag, env): runner must be a booted FrqtlApp ' +
+            '(renderCapabilities + setRenderOptions). (FAIL-LOUD.)');
+    }
+    if (!env || !Array.isArray(env.knownNames)) {
+        throw new Error('[render-state] RenderState.apply(runner, bag, env): env.knownNames must be the page\'s ' +
+            'RenderCapabilitiesCommon.knownRenderCapabilityNames(providers) array. (FAIL-LOUD.)');
+    }
+    var n = normalizeSavedRenderState(bag);
+
+    // ── RESOLVE everything before anything is written ──
+    // Rows — partitioned against the booted renderer.
+    var parts = partitionRenderRows(
+        n.render,
+        runner.renderCapabilities().map(function (c) { return c.name; }),
+        env.knownNames
+    );
+    // Camera — preset over orbit; a preset the booted camera does not offer is reported, not applied.
+    var cam = pickCameraReplay(n);
+    var ctl = null, camera = null, preset = null;
+    if (cam) {
+        ctl = runner.cameraControl;
+        if (!ctl) {
+            throw new Error('[render-state] the bag declares a camera (' + JSON.stringify(n.camera) + ') but the ' +
+                'runner has no cameraControl — a declared view on a display with no pose control would look ' +
+                'fine and be wrong. (FAIL-LOUD.)');
+        }
+        if (cam.mode === 'preset') {
+            if (!Array.isArray(ctl.presets)) {
+                throw new Error('[render-state] the booted camera publishes no `presets` array — every ' +
+                    'getCameraControl() handle declares the presets it offers. (FAIL-LOUD.)');
+            }
+            preset = cam.name;
+            camera = (ctl.presets.indexOf(cam.name) === -1) ? 'retained' : 'preset';
+        } else {
+            camera = 'orbit';
+        }
+    }
+    // Backdrop — the one derivation: the census LO marked `backdrop === true`.
+    var lo = backdropOf(runner);
+
+    // ── WRITE ──
+    runner.setRenderOptions(parts.apply);   // ONE validated batch
+    if (camera === 'preset') { ctl.setPreset(cam.name); }
+    else if (camera === 'orbit') { ctl.setOrbit(cam.orbit); }
+    var backdrop = null;
+    if (lo && n.backdropVisible !== null) {
+        runner.updateObjectProperty(lo, 'visible', n.backdropVisible);
+        backdrop = n.backdropVisible;
+    }
+
+    return { applied: parts.apply, retained: parts.retained, camera: camera, preset: preset, backdrop: backdrop };
+}
+
+export {
+    apply,
+    backdropOf,
+    normalizeSavedRenderState,
+    pickCameraReplay,
+    partitionRenderRows,
+    renderRowsFromBag
+};

package/dist/shim/render-state/index.js

@@ -0,0 +1,74 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/render-state/index.js — the ESM door to the renderState contract.
+ *
+ * The contract and the APPLY procedure have ONE home: `lib/shim/render-state/apply.js`, an ES module
+ * the page (through experiments/_shared/boot.js), the parent realm and the sdk bundle all import.
+ * This module re-exports its namespace and members by name, so importers (STUDIO's save-state, the
+ * bundle codec, the walkthrough registry, the sdk esm entry) read the same object — never a copy.
+ *
+ * ── Layer 1: API contract ────────────────────────────────────────────────────
+ *
+ *   RenderState                        — the owner object: RenderState.apply(runner, bag, env).
+ *   normalizeSavedRenderState(raw)     — tolerant normalizer for a LOADED bag (never throws).
+ *   pickCameraReplay(saved)            — pure decision: named preset over raw orbit.
+ *   partitionRenderRows(rows, declared, known)
+ *                                      — resolve render rows against the TARGET renderer.
+ *   renderRowsFromBag(bag)             — a { key: value } bag as ordered [{ key, value }] rows.
+ *   applySavedUrlOverrides(src, over)  — pure URL-string mutation for the load-TIME
+ *                                        renderer/seed query params (lives here: the page never
+ *                                        builds its own iframe src).
+ *
+ * ── Layer 2: physics behavior ────────────────────────────────────────────────
+ *
+ * Zero physics — data shaping over a renderState bag.
+ */
+
+'use strict';
+
+// The one owner of the renderState contract and its apply procedure.
+import * as RenderState from './apply.js';
+import { normalizeSavedRenderState, pickCameraReplay, partitionRenderRows, renderRowsFromBag } from './apply.js';
+
+// ── applySavedUrlOverrides ───────────────────────────────────────────────────
+
+/**
+ * Set (or leave untouched) the `renderer`/`seed` query params on an
+ * experiment iframe `src` — the load-TIME axis of a saved render-state bag.
+ *
+ * @param {string} src — an iframe `src` (with or without an existing `?query`).
+ * @param {{renderer?:string|null, seed?:number|string|null}} [overrides]
+ * @returns {string} `src` with the requested overrides applied. Identical to
+ *   `src` when `overrides` is absent or every field is falsy/undefined.
+ */
+function applySavedUrlOverrides(src, overrides) {
+    if (typeof src !== 'string' || !overrides) { return src; }
+    if (Object.prototype.hasOwnProperty.call(overrides, 'egpt3D')) {
+        throw new Error('[render-state] applySavedUrlOverrides: `egpt3D` is DELETED — 3D-ness is the scene\'s ' +
+            'co-init call (exp.createScene), and the display is `renderer` (three IS the 3D display). (FAIL-LOUD.)');
+    }
+    var qIdx = src.indexOf('?');
+    var base = qIdx === -1 ? src : src.slice(0, qIdx);
+    var qs   = qIdx === -1 ? '' : src.slice(qIdx + 1);
+    var params = new URLSearchParams(qs);
+
+    if (overrides.renderer) { params.set('renderer', overrides.renderer); }
+    if (overrides.seed !== undefined && overrides.seed !== null && overrides.seed !== '') {
+        params.set('seed', String(overrides.seed));
+    }
+
+    var qsOut = params.toString();
+    return qsOut ? (base + '?' + qsOut) : base;
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    RenderState,
+    normalizeSavedRenderState,
+    pickCameraReplay,
+    applySavedUrlOverrides,
+    partitionRenderRows,
+    renderRowsFromBag
+};

package/dist/shim/rpc/index.js

@@ -0,0 +1,207 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * lib/shim/rpc — the request/response call() primitive (gym-controls-as-sugar
+ * Layer-A follow-up; gate 5 charter —
+ * "the reqId/pending/timeout request/response-call()-over-postMessage pattern
+ * is promoted to a SHIM PRIMITIVE the moment a second consumer needs it").
+ *
+ * Peer of `lib/shim/controls`, `lib/shim/frame-data`, `lib/shim/expr/ast-schema`,
+ * `lib/shim/page-params` — same layout convention: named ES-module exports, imported by
+ * page-context sugar (`lib/frqtl/parts/FrqtlControlsPanel.js`) and the IDE alike.
+ *
+ * ── API ──────────────────────────────────────────────────────────────────────
+ *
+ *   makeInAppRpc(dispatch) → { call(fn,args)->Promise, dispose() }
+ *     Same-realm (same window) calling — `dispatch` runs directly, wrapped in
+ *     a Promise for a uniform caller shape (no postMessage round-trip; there
+ *     is no cross-realm boundary to cross).
+ *
+ *   makeChannelRpc(channel, opts) → { call(fn,args)->Promise, dispose() }
+ *     Cross-realm calling over any `{post,subscribe}` channel (same- or
+ *     cross-origin — the mechanism does not care which). Builds the
+ *     reqId/pending/timeout request/response protocol; rejects on timeout
+ *     (`opts.callTimeoutMs`, default 3000) if the other side never replies —
+ *     the ONE MUST-HAVE this primitive adds over a bare channel: an
+ *     unresponsive/not-yet-booted target must not hang a caller's Promise
+ *     forever.
+ *
+ *   installRpcResponder(channel, dispatch, opts) → unsubscribeFn
+ *     The REALM/receiving side's counterpart to `makeChannelRpc`: listens on
+ *     `channel` for calls tagged `opts.tag`, invokes `dispatch(fn,args)`
+ *     (sync OR Promise-returning — both supported uniformly), replies with
+ *     the result or error. `dispatch`'s return value must be plain,
+ *     structured-clone-serializable data (this module does not itself assert
+ *     that — see the design-note below).
+ *
+ *   makeWindowPostMessageChannel(targetWindow, opts) → {post,subscribe}
+ *     A ready-made `window.postMessage`/`'message'`-event channel targeting
+ *     one specific window (an iframe's `contentWindow`, or `window.parent`)
+ *     — the shape `makeChannelRpc`/`installRpcResponder` accept.
+ *
+ * `opts.tag` is REQUIRED on `makeChannelRpc`/`installRpcResponder` — a short
+ * string namespacing this RPC user's postMessage traffic so two independent
+ * RPC users sharing one `window.postMessage` bus (e.g. this primitive AND
+ * the notebook realm's own `__frqtlRealm`-tagged traffic) never collide.
+ *
+ * ── Why this module exists ──────────────────────────────────────────────────
+ *
+ * `frqtl-controls-panel.js` once built this request/response protocol INLINE; the
+ * protocol is a shim primitive so the panel and every later consumer share one
+ * reqId/pending/timeout implementation.
+ */
+
+
+
+/**
+ * makeInAppRpc(dispatch) — same-realm (same window) RPC.
+ * @param {(fn: string, args: any[]) => *} dispatch — invoked directly; may
+ *   return a value or a Promise.
+ * @returns {{call: (fn: string, args: any[]) => Promise<*>, dispose: () => void}}
+ * @throws {Error} FAIL-LOUD if `dispatch` is not a function.
+ */
+function makeInAppRpc(dispatch) {
+    if (typeof dispatch !== 'function') {
+        throw new Error('[shim/rpc] makeInAppRpc requires a dispatch function. (FAIL-LOUD.)');
+    }
+    return {
+        call: function (fn, args) {
+            try { return Promise.resolve(dispatch(fn, args)); }
+            catch (e) { return Promise.reject(e); }
+        },
+        dispose: function () {}
+    };
+}
+
+/**
+ * makeChannelRpc(channel, opts) — cross-realm RPC over a `{post,subscribe}`
+ * channel (see `makeWindowPostMessageChannel` for a ready-made one).
+ * @param {{post: (msg:*) => void, subscribe: (handler:(msg:*)=>void) => (() => void)}} channel
+ * @param {object} opts
+ * @param {string} opts.tag — REQUIRED: a unique namespace for this RPC's wire traffic.
+ * @param {number} [opts.callTimeoutMs=3000] — per-call timeout.
+ * @returns {{call: (fn: string, args: any[]) => Promise<*>, dispose: () => void}}
+ * @throws {Error} FAIL-LOUD if `channel` lacks post/subscribe, or `opts.tag` is missing.
+ */
+function makeChannelRpc(channel, opts) {
+    opts = opts || {};
+    if (!channel || typeof channel.post !== 'function' || typeof channel.subscribe !== 'function') {
+        throw new Error('[shim/rpc] makeChannelRpc requires a channel with post/subscribe. (FAIL-LOUD.)');
+    }
+    var tag = opts.tag;
+    if (!tag) {
+        throw new Error('[shim/rpc] makeChannelRpc requires opts.tag (a unique namespace so ' +
+            'multiple RPC users sharing one postMessage bus never collide). (FAIL-LOUD.)');
+    }
+    var timeoutMs = (typeof opts.callTimeoutMs === 'number' && opts.callTimeoutMs > 0) ? opts.callTimeoutMs : 3000;
+    var pending = Object.create(null);
+    var reqCounter = 0;
+    var unsub = channel.subscribe(function (msg) {
+        if (!msg || msg.__rpcTag !== tag || msg.type !== 'rpc:result') { return; }
+        var p = pending[msg.reqId];
+        if (!p) { return; }
+        delete pending[msg.reqId];
+        if (msg.error) { p.reject(new Error('[shim/rpc] remote: ' + msg.error)); }
+        else { p.resolve(msg.value); }
+    });
+    return {
+        call: function (fn, args) {
+            return new Promise(function (resolve, reject) {
+                var reqId = ++reqCounter;
+                var timer = setTimeout(function () {
+                    if (!pending[reqId]) { return; } // already settled by a real reply
+                    delete pending[reqId];
+                    reject(new Error('[shim/rpc] "' + fn + '" timed out after ' + timeoutMs +
+                        'ms (tag "' + tag + '"). No responder installed on the other side? ' +
+                        '(installRpcResponder)'));
+                }, timeoutMs);
+                pending[reqId] = {
+                    resolve: function (v) { clearTimeout(timer); resolve(v); },
+                    reject: function (e) { clearTimeout(timer); reject(e); }
+                };
+                channel.post({ __rpcTag: tag, type: 'rpc:call', reqId: reqId, fn: fn, args: args });
+            });
+        },
+        dispose: function () { if (typeof unsub === 'function') { unsub(); } }
+    };
+}
+
+/**
+ * installRpcResponder(channel, dispatch, opts) — the REALM/receiving side.
+ * @param {{post: Function, subscribe: Function}} channel
+ * @param {(fn: string, args: any[]) => *} dispatch — may return a value or a Promise.
+ * @param {object} opts
+ * @param {string} opts.tag — MUST match the caller's `makeChannelRpc` tag.
+ * @returns {() => void} unsubscribe function.
+ * @throws {Error} FAIL-LOUD if `channel` lacks post/subscribe, or `opts.tag` is missing.
+ */
+function installRpcResponder(channel, dispatch, opts) {
+    opts = opts || {};
+    if (!channel || typeof channel.post !== 'function' || typeof channel.subscribe !== 'function') {
+        throw new Error('[shim/rpc] installRpcResponder requires a channel with post/subscribe. (FAIL-LOUD.)');
+    }
+    if (typeof dispatch !== 'function') {
+        throw new Error('[shim/rpc] installRpcResponder requires a dispatch function. (FAIL-LOUD.)');
+    }
+    var tag = opts.tag;
+    if (!tag) {
+        throw new Error('[shim/rpc] installRpcResponder requires opts.tag. (FAIL-LOUD.)');
+    }
+    return channel.subscribe(function (msg) {
+        if (!msg || msg.__rpcTag !== tag || msg.type !== 'rpc:call') { return; }
+        var reqId = msg.reqId;
+        Promise.resolve().then(function () {
+            return dispatch(msg.fn, msg.args);
+        }).then(function (value) {
+            channel.post({ __rpcTag: tag, type: 'rpc:result', reqId: reqId, value: value });
+        }, function (e) {
+            channel.post({
+                __rpcTag: tag, type: 'rpc:result', reqId: reqId,
+                error: (e && e.message) ? e.message : String(e)
+            });
+        });
+    });
+}
+
+/**
+ * makeWindowPostMessageChannel(targetWindow, opts) — a ready-made
+ * `{post,subscribe}` channel over `window.postMessage`/`'message'` events,
+ * scoped to one specific `targetWindow` (an iframe's `contentWindow`, or
+ * `window.parent`) — messages from any OTHER source are ignored.
+ * @param {Window} targetWindow — the window to post to / accept messages from.
+ * @param {object} [opts]
+ * @param {Window} [opts.selfWindow] — defaults to the global `window`.
+ * @returns {{post: Function, subscribe: Function}}
+ * @throws {Error} FAIL-LOUD if `targetWindow` or the self window is missing.
+ */
+function makeWindowPostMessageChannel(targetWindow, opts) {
+    opts = opts || {};
+    var selfWindow = opts.selfWindow || (typeof window !== 'undefined' ? window : null);
+    if (!targetWindow) {
+        throw new Error('[shim/rpc] makeWindowPostMessageChannel requires targetWindow. (FAIL-LOUD.)');
+    }
+    if (!selfWindow) {
+        throw new Error('[shim/rpc] makeWindowPostMessageChannel requires a self window (pass ' +
+            'opts.selfWindow outside a browser). (FAIL-LOUD.)');
+    }
+    return {
+        post: function (msg) { targetWindow.postMessage(msg, '*'); },
+        subscribe: function (handler) {
+            var listener = function (ev) {
+                if (ev.source !== targetWindow) { return; }
+                handler(ev.data);
+            };
+            selfWindow.addEventListener('message', listener);
+            return function () { selfWindow.removeEventListener('message', listener); };
+        }
+    };
+}
+
+// ── Export ────────────────────────────────────────────────────────────────────
+
+export {
+    makeInAppRpc,
+    makeChannelRpc,
+    installRpcResponder,
+    makeWindowPostMessageChannel
+};