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

package/dist/frqtl/objects/instruments/hosted-eyes.js

@@ -66,10 +66,11 @@
  *
  * A SceneRecord alone cannot open a host: it is identity plus reproduction pins, with no
  * scene spec in it. So the API takes the PAIR — record + `{kind:'project', files, entry}`, the
- * project whose entry's default export is `buildExperiment(exp)` (a one-string sketch, such as the
- * module `designToModule` emits, is `{ files: { 'sketch.js': text }, entry: 'sketch.js' }`). The
+ * project whose entry's default export is `buildExperiment(exp)` (a one-string sketch, such as a
+ * shipped scene file, is `{ files: { 'sketch.js': text }, entry: 'sketch.js' }`). The
  * page links it through its one door and stamps the project's identity (projectIdentity) as the
- * record's `sourceSha256`; this process computes the same identity from the same files, and the
+ * record's `sourceSha256`; this process computes the same identity from the same linked set
+ * (lib/shim/project/link.js linkedFiles — frqtl.json and the module files; a README rides unhashed), and the
  * open-time record check holds the two equal. A caller without one is REPLAY-grade
  * (an ad-hoc tick-fn scene, a live-edited scene, a bare raster row) and is REFUSED in
  * RENDERER_CONTRACT §10.3's own vocabulary: there is nothing to regenerate FROM, and a
@@ -132,6 +133,8 @@ import { FrqtlCaptureHost } from './capture-host.js';
 import { FrqtlVision } from '../../parts/FrqtlVision.js';
 import { FrqtlCapture } from './capture.js';
 import { projectIdentity, projectBytes } from '../../../shim/project/identity.js';
+import { linkedFiles, entryOf } from '../../../shim/project/link.js';
+import { libPathOf } from '../../../shim/project/specifiers.js';
 
 
     /** The contracts this instrument consumes, by static import (it is a node-only module). */
@@ -145,22 +148,29 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
     }
 
     /**
-     * The URL, AS THE PAGE SEES IT, of a module beside this file. The canonical page sits at
-     * `frqtl/experiments/empty/index.html` of the same lib-identity tree in every host (source
-     * placement is identity), so a module's page URL is its path relative to that page's
-     * directory, resolved against the page's own URL. The in-page routines import the PAGE's
-     * module instances from these URLs — never a copy. @private
+     * The URL, AS THE PAGE SEES IT, of a module beside this file. MODULES sit at their
+     * lib-relative paths in lib/ and in every dist, so a module's lib path is its path from this
+     * tree's lib root. The PAGE does not: the dev mount serves it inside the lib tree, a dist
+     * re-anchors it (`<dist>/experiments/empty/`, the graph beside or under a build directory),
+     * so where the page sits says nothing about where its modules are. The page's own import map
+     * does — every row is its lib root plus a lib path (lib/shim/project/specifiers.js
+     * `importMapFor`, rendered for each placement) — so the lib root is asked of the page
+     * (`_IN_PAGE_LIB_ROOT` on `PAGE_ANCHOR`) and each module's lib path resolved against it.
+     * The in-page routines import the PAGE's module instances from these URLs — never a copy.
+     * @private
      */
-    var EMPTY_PAGE_DIR = path.dirname(fileURLToPath(new URL('../../experiments/empty/index.html', import.meta.url)));
-    function _pageModuleUrl(pageUrl, moduleUrl) {
-        var rel = path.relative(EMPTY_PAGE_DIR, fileURLToPath(moduleUrl)).split(path.sep).join('/');
-        return new URL(rel, pageUrl).href;
+    var LIB_ROOT_DIR = fileURLToPath(new URL('../../../', import.meta.url));
+    var PAGE_ANCHOR_SPECIFIER = '@descix/frqtl-web/parts';
+    var PAGE_ANCHOR = { specifier: PAGE_ANCHOR_SPECIFIER, libPath: libPathOf(PAGE_ANCHOR_SPECIFIER) };
+    function _pageModuleUrl(pageLibRoot, moduleUrl) {
+        var rel = path.relative(LIB_ROOT_DIR, fileURLToPath(moduleUrl)).split(path.sep).join('/');
+        return new URL(rel, pageLibRoot).href;
     }
-    /** The modules the capture-host KIND's in-page routines import, for the page at `pageUrl`. @private */
-    function _inPageModules(pageUrl) {
+    /** The modules the capture-host KIND's in-page routines import, for a page whose lib root is `pageLibRoot`. @private */
+    function _inPageModules(pageLibRoot) {
         return {
-            captureHost: _pageModuleUrl(pageUrl, import.meta.resolve('./capture-host.js')),
-            captureEnvelope: _pageModuleUrl(pageUrl, import.meta.resolve('../../../shim/render/capture-envelope.js'))
+            captureHost: _pageModuleUrl(pageLibRoot, import.meta.resolve('./capture-host.js')),
+            captureEnvelope: _pageModuleUrl(pageLibRoot, import.meta.resolve('../../../shim/render/capture-envelope.js'))
         };
     }
 
@@ -183,7 +193,8 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
     // ── The REGENERATE gate ───────────────────────────────────────────────────
 
     /**
-     * assertHostable({sceneRecord, sceneSource}) — throw-or-return, in §10.3's vocabulary.
+     * assertHostable({sceneRecord, sceneSource}) — throw-or-return the entry, in §10.3's vocabulary. The entry is
+     * THE entry rule's answer (link.js entryOf): the entry frqtl.json names, else sceneSource.entry.
      * @private
      */
     function _assertHostable(opts) {
@@ -205,18 +216,20 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                 '(more files beside it for a project with forked parts). (FAIL-LOUD.)');
         }
         if (!src || typeof src !== 'object' || src.kind !== 'project' ||
-            !src.files || typeof src.files !== 'object' || Object.keys(src.files).length === 0 ||
-            typeof src.entry !== 'string' || !src.entry) {
+            !src.files || typeof src.files !== 'object' || Object.keys(src.files).length === 0) {
             throw new Error('[FrqtlHostedEyes.open] this scene is REPLAY-grade, not ' +
                 'REGENERATE-grade: hosting re-RUNS the scene in another process, so a ' +
                 'SceneRecord alone is not enough (it is identity + reproduction pins, with no ' +
-                'scene spec in it). Pass the pair — sceneSource: { kind: "project", files, entry } — ' +
+                'scene spec in it). Pass the pair — sceneSource: { kind: "project", files, entry? } (entry optional when ' +
+                'files carries the frqtl.json that names it) — ' +
                 'where the entry\'s default export is buildExperiment(exp) and the canonical empty ' +
                 'page links it. An ad-hoc tick-fn scene, a live-edited scene or a ' +
                 'bare raster row has nothing to regenerate FROM, and a silently approximate ' +
                 're-run is the one failure a content-addressed corpus cannot detect afterwards. ' +
                 '(FAIL-LOUD — see RENDERER_CONTRACT.md §10.3.)');
         }
+        // THE entry rule (link.js entryOf): frqtl.json's entry, a given one equal to it, else the given one.
+        return entryOf(src.files, src.entry);
     }
 
     /**
@@ -362,11 +375,11 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
     // ── The boot wait: every way it can fail is a NAMED refusal ─────────────────
 
     /**
-     * Where a published dist at `url`'s origin serves the one page. `url` is always
-     * `_pageUrlFor`'s absolute href, so its origin is known. @private
+     * Where a published dist serves the one page — under the dist's own URL, which may be an
+     * origin root or a sub-path, so it is named, not computed from `url`. @private
      */
-    function _distEmptyPage(url) {
-        return new URL(url).origin + '/experiments/empty/index.html';
+    function _distEmptyPage() {
+        return '<dist>/experiments/empty/index.html';
     }
 
     /** D — the URL did not serve (an HTTP status other than 2xx, or a navigation error). @private */
@@ -374,7 +387,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
         return new Error('[FrqtlHostedEyes.open] ' + url + ' did not serve: ' + what + '. That is ' +
             'a deployment fact, not a scene problem — the hosted eyes boot ONLY the canonical empty ' +
             'experiment page lib/frqtl/experiments/empty/index.html as your deployment serves it ' +
-            '(a published dist at this origin serves it at ' + _distEmptyPage(url) + '); point ' +
+            '(a published dist serves it at ' + _distEmptyPage() + ', <dist> being the URL the dist is served at); point ' +
             '`pageUrl` at it, or serve it. Nothing was booted. (FAIL-LOUD.)');
     }
 
@@ -383,7 +396,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
         return new Error('[FrqtlHostedEyes.open] ' + url + ' is not the canonical empty experiment ' +
             'page: it loaded (HTTP ' + status + ') and defines no window.FrqtlPage. The hosted eyes ' +
             'boot ONLY lib/frqtl/experiments/empty/index.html (in a published dist: ' +
-            _distEmptyPage(url) + ') and apply your scene into it. They never host an app page, the ' +
+            _distEmptyPage() + ') and apply your scene into it. They never host an app page, the ' +
             'IDE, or a page of your own: a page that boots and edits its own scene cannot be ' +
             'regenerated from {sceneRecord, sceneSource}. To see your own page, capture IN it ' +
             'through FrqtlVision (the in-page face). To drive it from node, use your own browser; ' +
@@ -470,16 +483,10 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
             }
             applied = window.FrqtlPage.applyRenderState(args.renderState);
         }
-        // ESTABLISH THE CLOCK with one step, deliberately. Applying a recipe RE-INITS the
-        // universe, and neither the host's retained TickData nor the compat universe's own
-        // `tick` field is cleared by that re-init — both keep reporting the blank page's last
-        // value until the next tick overwrites them (observed: a freshly regenerated scene
-        // read as "tick 10"). Every later read here is exact BECAUSE this process is the only
-        // stepper (the RAF loop is stopped above), so the fix is to make the first reading a
-        // real one rather than to trust a cache the re-init left behind. It costs nothing the
-        // contract was not already charging: a capture before the first tick is REFUSED
-        // anyway ("no tick has run yet" — never an empty buffer), so tick 1 is the earliest
-        // capturable coordinate of any scene.
+        // ESTABLISH THE CLOCK with one step, deliberately: applying a recipe begins a world that has not stepped
+        // (runner.worldTick 0, no TickData yet), and a capture before the first tick is REFUSED ("no tick has run yet"
+        // — never an empty buffer), so tick 1 is the earliest capturable coordinate of any scene. Every later read is
+        // exact because this process is the only stepper (the RAF loop is stopped above).
         r.step();
         return { renderState: applied };
     };
@@ -545,8 +552,8 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                     return;
                 }
                 try {
-                    var td = r.step();
-                    resolve((td && td.universeData) ? td.universeData.tick : null);
+                    r.step();
+                    resolve(r.worldTick);
                 } catch (e) { reject(e); }
             })();
         });
@@ -554,8 +561,35 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
 
     /** The current tick, read (never advanced). */
     var _IN_PAGE_TICK = function () {
-        var td = window.FrqtlPage.runner._lastTickData;
-        return (td && td.universeData) ? td.universeData.tick : null;
+        var r = window.FrqtlPage.runner;
+        if (!r) { throw new Error('[FrqtlHostedEyes/in-page] there is no runner to read a tick from (FrqtlPage.runner). (FAIL-LOUD.)'); }
+        return r.worldTick;
+    };
+
+    /**
+     * The page's lib root, resolved by the PAGE's import map: `anchor.specifier` resolves to the lib
+     * root plus `anchor.libPath`. A `blob:` module asks, because `import.meta.resolve` is the
+     * browser's own resolution against the document's map (the link site's blob modules resolve
+     * their imports the same way).
+     */
+    var _IN_PAGE_LIB_ROOT = async function (anchor) {
+        var url = URL.createObjectURL(new Blob(['export default import.meta.resolve(' +
+            JSON.stringify(anchor.specifier) + ');'], { type: 'text/javascript' }));
+        var resolved;
+        try { resolved = (await import(url)).default; }
+        catch (e) {
+            throw new Error('[FrqtlHostedEyes/in-page] this page\'s import map does not resolve ' +
+                JSON.stringify(anchor.specifier) + ' (' + ((e && e.message) || String(e)) + ') — the canonical ' +
+                'empty page carries the specifier table\'s import map; nothing can locate its modules ' +
+                'without it. (FAIL-LOUD.)');
+        }
+        finally { URL.revokeObjectURL(url); }
+        if (typeof resolved !== 'string' || resolved.slice(-anchor.libPath.length) !== anchor.libPath) {
+            throw new Error('[FrqtlHostedEyes/in-page] ' + JSON.stringify(anchor.specifier) + ' resolved to ' +
+                JSON.stringify(resolved) + ', which does not end in its lib path ' + JSON.stringify(anchor.libPath) +
+                ' — the page\'s import map is not the specifier table\'s rendering. (FAIL-LOUD.)');
+        }
+        return resolved.slice(0, resolved.length - anchor.libPath.length);
     };
 
     /** Point the ONE camera and redraw — pose is a still coordinate, set before capture. */
@@ -572,6 +606,99 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
         return cam.getOrbit();
     };
 
+    // ── The Record door, in the page (lib/frqtl/objects/record/Record.js through FrqtlPage.experiment) ──
+    // The page's facade owns the Record; these routines only forward to it, so the folder a node host gets
+    // is the one the page's own door wrote (one implementation, every host). The open Record and a film
+    // in flight are parked on the page under ONE name, `__frqtlHostedRecord`.
+
+    /** exp.startRecord() on the page's facade; parks the Record. */
+    var _IN_PAGE_RECORD_START = async function () {
+        var exp = window.FrqtlPage.experiment;
+        if (!exp || typeof exp.startRecord !== 'function') {
+            throw new Error('[FrqtlHostedEyes/in-page] this page has no FrqtlPage.experiment facade to record.');
+        }
+        var rec;
+        // A refusal crosses the page boundary as data, so its err.record reaches node (page.evaluate keeps only a message).
+        try { rec = await exp.startRecord(); }
+        catch (e) { if (e && e.record) { return { refused: { message: e.message, record: e.record } }; } throw e; }
+        window.__frqtlHostedRecord = { rec: rec, film: null };
+        return { tick: rec.tick };
+    };
+
+    /** rec.film(opts) begins: its first segment subscribes before this returns (the drive gate waits on it). */
+    var _IN_PAGE_RECORD_FILM_BEGIN = function (opts) {
+        var p = window.__frqtlHostedRecord;
+        if (!p || !p.rec) { throw new Error('[FrqtlHostedEyes/in-page] no Record is open — eyes.record.start() first.'); }
+        if (p.film) { throw new Error('[FrqtlHostedEyes/in-page] a film is already running — await it first.'); }
+        p.film = p.rec.film(opts);
+        p.film.then(null, function () {});
+        return true;
+    };
+
+    /** The film's clip spans, when it ends. */
+    var _IN_PAGE_RECORD_FILM_END = function () {
+        var p = window.__frqtlHostedRecord;
+        var f = p && p.film;
+        if (!f) { throw new Error('[FrqtlHostedEyes/in-page] no film is running.'); }
+        return f.then(function (spans) { p.film = null; return spans; }, function (e) { p.film = null; throw e; });
+    };
+
+    /** rec.stop() → the folder, each clip's bytes as base64 (the one encoder, capture-envelope.js). */
+    var _IN_PAGE_RECORD_STOP = async function (args) {
+        var p = window.__frqtlHostedRecord;
+        if (!p || !p.rec) { throw new Error('[FrqtlHostedEyes/in-page] no Record is open — eyes.record.start() first.'); }
+        var CE = await import(args.modules.captureEnvelope);
+        var out;
+        // A refused stop() leaves the Record open (still parked); its err.record crosses as data.
+        try { out = await p.rec.stop(); }
+        catch (e) { if (e && e.record) { return { refused: { message: e.message, record: e.record } }; } throw e; }
+        window.__frqtlHostedRecord = null;
+        if (out.empty) { return { empty: true }; }
+        var files = {};
+        Object.keys(out.files).forEach(function (k) {
+            var v = out.files[k];
+            files[k] = typeof v === 'string' ? { text: v } : { base64: CE.bytesToBase64(v) };
+        });
+        return { files: files, record: out.record, clips: out.clips };
+    };
+
+    /** One act through the page's own doors: toSketch({by}), setDeclared(name, patch, {by}), placeDeclaredAt(name, point). */
+    var _IN_PAGE_ACT = async function (args) {
+        var exp = window.FrqtlPage.experiment;
+        var r = window.FrqtlPage.runner;
+        if (args.door === 'toSketch') { return exp.toSketch(args.opts); }
+        if (args.door === 'setDeclared') { return exp.setDeclared(args.name, args.patch, args.opts); }
+        if (args.door === 'placeDeclaredAt') {
+            var d = r.declared.find(function (o) { return o.name === args.name; });
+            if (!d) { throw new Error('[FrqtlHostedEyes/in-page] no declared object is named ' + JSON.stringify(args.name) + '.'); }
+            var res = r.placeDeclaredAt(d, args.point);
+            r.repaint();
+            return res;
+        }
+        throw new Error('[FrqtlHostedEyes/in-page] unknown act door ' + JSON.stringify(args.door) + '.');
+    };
+
+    /** A page refusal `{ refused: { message, record } }` → a thrown Error carrying `.record`, as in a page. @private */
+    function _rethrowRefused(out) {
+        if (out && out.refused) {
+            var e = new Error(out.refused.message);
+            e.record = out.refused.record;
+            throw e;
+        }
+        return out;
+    }
+
+    /** A page folder (text | base64 per path) → { path: string | Uint8Array }. @private */
+    function _folderFromPage(out) {
+        if (out.empty) { return { empty: true }; }
+        var files = {};
+        Object.keys(out.files).forEach(function (k) {
+            var v = out.files[k];
+            files[k] = (v.text !== undefined) ? v.text : new Uint8Array(Buffer.from(v.base64, 'base64'));
+        });
+        return { files: files, record: out.record, clips: out.clips };
+    }
+
     // ── open() ────────────────────────────────────────────────────────────────
 
     /**
@@ -583,8 +710,9 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
      *   world the source's co-init call built). Supplying any of them is an EXPECTATION, checked
      *   after boot and THROWN on mismatch — never a request; a stated bound that is not a
      *   positive integer is refused before a browser is acquired.
-     * @param {{kind:'project', files:Object<string,string>, entry:string}} opts.sceneSource — the
-     *   REGENERATE-grade scene: a project, linked in the page by its one door.
+     * @param {{kind:'project', files:Object<string,string>, entry?:string}} opts.sceneSource — the
+     *   REGENERATE-grade scene: a project, linked in the page by its one door. `entry` is optional when
+     *   `files` carries the frqtl.json that names it (a different one is refused).
      * @param {object} [opts.renderState] — the declared LOOK, ferried: a renderState bag (for a
      *   rung, `effectiveRenderState(rung, mode)`; or a saved project's bag). Its `renderer` boots
      *   the page; its rows, camera and backdrop are applied by `FrqtlPage.applyRenderState` before
@@ -595,7 +723,8 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
      *   `setPose` after open overrides its camera. Omit it for a scene's PLAIN render.
      * @param {string} opts.pageUrl — the canonical empty experiment page in YOUR deployment
      *   (dev server: `<origin>/frqtl/experiments/empty/index.html`; published dist:
-     *   `<origin>/experiments/empty/index.html`). Required rather than guessed: the address of
+     *   `<dist>/experiments/empty/index.html`, where `<dist>` is the dist's URL — an origin root
+     *   or a sub-path). Required rather than guessed: the address of
      *   a deployment is not something a library may invent.
      * @param {object} opts.browserType — a Playwright browser type (`chromium`). The
      *   `@descix/frqtl-node/eyes` entry supplies the packaged default; passing your own IS the
@@ -619,14 +748,14 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
     /** @private — the body; see `open` for the contract. */
     function _open(opts) {
         var C = _contracts();
-        _assertHostable(opts);
+        var entry = _assertHostable(opts);
         _assertBoundShape(opts.sceneRecord, C.RS);
         var declared = _declaredRenderState(opts, opts.sceneRecord, C.RST);
         if (!opts.pageUrl || typeof opts.pageUrl !== 'string') {
             throw new Error('[FrqtlHostedEyes.open] `pageUrl` is REQUIRED: the URL of the ' +
                 'CANONICAL empty experiment page (lib/frqtl/experiments/empty/index.html) in your ' +
                 'deployment — a dev server exposes it at its /frqtl mount, a published dist at ' +
-                '<origin>/experiments/empty/index.html. A library may not invent the address of ' +
+                '<dist>/experiments/empty/index.html (<dist> = the URL the dist is served at). A library may not invent the address of ' +
                 'your deployment, and it must not ship a second copy of that page. (FAIL-LOUD.)');
         }
         if (!opts.browserType || typeof opts.browserType.launch !== 'function') {
@@ -641,7 +770,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
         var sourceRef = (record.sourceRef === undefined || record.sourceRef === null)
             ? null : String(record.sourceRef);
 
-        var browser = null, page = null;
+        var browser = null, page = null, modules = null;
         return Promise.resolve(opts.browserType.launch({
             headless: true,
             args: Array.isArray(opts.launchArgs) ? opts.launchArgs : _defaultLaunchArgs()
@@ -690,7 +819,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                     })
                     .then(function () {
                         return page.evaluate(_IN_PAGE_APPLY,
-                            { files: opts.sceneSource.files, entry: opts.sceneSource.entry, sourceRef: sourceRef, renderState: declared });
+                            { files: opts.sceneSource.files, entry: entry, sourceRef: sourceRef, renderState: declared });
                     })
                     .then(function (applied) {
                         return page.evaluate(_IN_PAGE_DISPLAY).then(function (disp) {
@@ -735,6 +864,11 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                 _assertLanded(boot.renderState);
             });
         }).then(function () {
+            // Asked of the FINAL page (after any display reload), once: the in-page routines import
+            // its module instances from these URLs.
+            return page.evaluate(_IN_PAGE_LIB_ROOT, PAGE_ANCHOR);
+        }).then(function (pageLibRoot) {
+            modules = _inPageModules(pageLibRoot);
             return page.evaluate(_IN_PAGE_SCENE);
         }).then(function (pageScene) {
             // The caller's `build`/`projection`, if any, were an EXPECTATION about what the
@@ -760,7 +894,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                             'is closed. Open a new one; a capture surface that silently ' +
                             'resurrected a browser would leak processes by design. (FAIL-LOUD.)');
                     }
-                    return page.evaluate(C.CH.IN_PAGE_CAPTURE, { stage: stage, modules: _inPageModules(page.url()) })
+                    return page.evaluate(C.CH.IN_PAGE_CAPTURE, { stage: stage, modules: modules })
                         .then(function (env) { return C.CH.decodeStillEnvelope(env); });
                 },
                 record: function (recordOpts) {
@@ -775,14 +909,14 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                     var signal = recordOpts.signal || null;
                     var pageOpts = {};
                     for (var k in recordOpts) { if (k !== 'signal') { pageOpts[k] = recordOpts[k]; } }
-                    var begun = page.evaluate(C.CH.IN_PAGE_RECORD_BEGIN, { id: id, opts: pageOpts, modules: _inPageModules(page.url()) });
+                    var begun = page.evaluate(C.CH.IN_PAGE_RECORD_BEGIN, { id: id, opts: pageOpts, modules: modules });
                     gate.opened = begun.then(null, function () {});
                     var onAbort = null;
                     var aborted = null;
                     if (signal) {
                         var sendAbort = function () {
                             return begun.then(function () {
-                                return page.evaluate(C.CH.IN_PAGE_RECORD_ABORT, { id: id, modules: _inPageModules(page.url()) });
+                                return page.evaluate(C.CH.IN_PAGE_RECORD_ABORT, { id: id, modules: modules });
                             });
                         };
                         if (signal.aborted) { aborted = sendAbort(); }
@@ -793,7 +927,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                     }
                     var detach = function () { if (onAbort) { signal.removeEventListener('abort', onAbort); } };
                     return begun.then(function () {
-                        return page.evaluate(C.CH.IN_PAGE_RECORD_END, { id: id, modules: _inPageModules(page.url()) });
+                        return page.evaluate(C.CH.IN_PAGE_RECORD_END, { id: id, modules: modules });
                     }).then(function (env) {
                         detach();
                         // A failed ABORT delivery is surfaced, never swallowed.
@@ -820,7 +954,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
             );
             inst.attachCaptureHost(host);
 
-            return projectIdentity({ files: projectBytes(opts.sceneSource.files) }).then(function (sha) {
+            return projectIdentity({ files: projectBytes(linkedFiles(opts.sceneSource.files)) }).then(function (sha) {
                 inst.setSourceSha256(sha);
                 return inst.sceneRecord();
             }).then(function (nodeScene) {
@@ -835,7 +969,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                         'them. (FAIL-LOUD — a hosted still filed under the wrong scene verifies ' +
                         'forever against the wrong header.)');
                 }
-                return _handle(browser, page, host, inst, nodeScene, gate, timeout);
+                return _handle(browser, page, host, inst, nodeScene, gate, timeout, modules);
             });
         }).catch(function (e) {
             // A half-opened handle that leaked a browser would poison the zero-orphans gate
@@ -854,7 +988,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
     }
 
     /** The consumer-facing handle. @private */
-    function _handle(browser, page, host, inst, scene, gate, timeout) {
+    function _handle(browser, page, host, inst, scene, gate, timeout, modules) {
         var self = {
             /**
              * The SAME face as everywhere else: getScene / getStill / stages / toPNG, and
@@ -867,7 +1001,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
             /** The node-side SceneRecord (page-extended) + its content id. */
             scene: scene,
 
-            /** @returns {Promise<number|null>} the page's current tick — READ, never advanced. */
+            /** @returns {Promise<number>} the world's own tick (runner.worldTick: 0 before its first step) — READ, never advanced. */
             tick: function () { return page.evaluate(_IN_PAGE_TICK); },
 
             /**
@@ -886,7 +1020,7 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                         'non-negative integer coordinate; got ' + String(n) + '. (FAIL-LOUD.)'));
                 }
                 return gate.opened.then(function () { return self.tick(); }).then(function (now) {
-                    var at = (typeof now === 'number') ? now : 0;
+                    var at = now;
                     if (at > n) {
                         throw new Error('[FrqtlHostedEyes.driveToTick] the hosted world is ' +
                             'already at tick ' + at + ', past ' + n + '. A world runs forward ' +
@@ -970,6 +1104,42 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
                 return file;
             },
 
+            /**
+             * The Record door, forwarded to the PAGE's facade (lib/frqtl/objects/record/Record.js): the folder is
+             * the one the page's own door writes, so a node host and a page produce the same files for the same acts.
+             * The handle has no re-authoring door: a Record opened by `eyes.record.start()` closes only by
+             * `eyes.record.stop()`. A refusal carries `err.record = { changes, clips }`, as in a page.
+             *   start()      exp.startRecord() → the Record's tick (0)
+             *   film(opts)   rec.film(opts) → its clip spans. Drive the world while it films:
+             *                `const f = eyes.record.film(o); await eyes.driveToTick(n); await f`
+             *   stop()       rec.stop() → { files: { path: string | Uint8Array }, record, clips } | { empty: true }
+             */
+            record: {
+                start: function () {
+                    return page.evaluate(_IN_PAGE_RECORD_START).then(_rethrowRefused).then(function (o) { return o.tick; });
+                },
+                film: function (opts) {
+                    var begun = page.evaluate(_IN_PAGE_RECORD_FILM_BEGIN, opts);
+                    gate.opened = begun.then(null, function () {});
+                    return begun.then(function () { return page.evaluate(_IN_PAGE_RECORD_FILM_END); });
+                },
+                stop: function () {
+                    return page.evaluate(_IN_PAGE_RECORD_STOP, { modules: modules }).then(_rethrowRefused).then(_folderFromPage);
+                }
+            },
+
+            /**
+             * Acts through the page's own doors (the writer's rows come from these, never from node):
+             *   toSketch({ by })                 exp.toSketch
+             *   setDeclared(name, patch, { by }) exp.setDeclared
+             *   placeDeclaredAt(name, [x, y, z?]) runner.placeDeclaredAt on the declared object of that name
+             */
+            act: {
+                toSketch: function (opts) { return page.evaluate(_IN_PAGE_ACT, { door: 'toSketch', opts: opts }); },
+                setDeclared: function (name, patch, opts) { return page.evaluate(_IN_PAGE_ACT, { door: 'setDeclared', name: name, patch: patch, opts: opts }); },
+                placeDeclaredAt: function (name, point) { return page.evaluate(_IN_PAGE_ACT, { door: 'placeDeclaredAt', name: name, point: point }); }
+            },
+
             /** Close the managed browser. Symmetric with open(), idempotent. */
             dispose: function () { return host.dispose(); }
         };
@@ -980,5 +1150,46 @@ import { projectIdentity, projectBytes } from '../../../shim/project/identity.js
 
     var FrqtlHostedEyes = { open: open };
 
-    export { FrqtlHostedEyes };
+    /**
+     * writeRecordFolder(folder, dir) — write a Record folder (what `eyes.record.stop()` resolves) to `dir`, each path
+     * verbatim: text as UTF-8, clip bytes as they are. The ONE node writer of the folder.
+     * REFUSES (throws): an empty Record (`{ empty: true }` is a state with no folder); a `dir` that exists and is not
+     * empty (a Record is never written over another); a path that is absolute or climbs out of `dir`.
+     * @param {{ files: Object<string, string|Uint8Array> }} folder
+     * @param {string} dir
+     * @returns {string[]} the paths written, in the folder's order
+     */
+    function writeRecordFolder(folder, dir) {
+        if (folder && folder.empty === true) {
+            throw new Error('[FrqtlHostedEyes] writeRecordFolder: this Record is empty — no change and no clip — a state with no folder. (FAIL-LOUD.)');
+        }
+        if (!folder || !folder.files || typeof folder.files !== 'object') {
+            throw new Error('[FrqtlHostedEyes] writeRecordFolder(folder, dir): folder is what eyes.record.stop() resolves, { files, record, clips }. (FAIL-LOUD.)');
+        }
+        if (typeof dir !== 'string' || !dir) { throw new Error('[FrqtlHostedEyes] writeRecordFolder(folder, dir): dir is a directory path. (FAIL-LOUD.)'); }
+        const root = path.resolve(dir);
+        if (fs.existsSync(root) && fs.readdirSync(root).length) {
+            throw new Error('[FrqtlHostedEyes] writeRecordFolder: ' + root + ' exists and is not empty — a Record is never written over another; ' +
+                'name a new directory. (FAIL-LOUD.)');
+        }
+        const paths = Object.keys(folder.files);
+        for (const p of paths) {
+            const at = path.resolve(root, p);
+            if (path.isAbsolute(p) || (at !== root && !at.startsWith(root + path.sep))) {
+                throw new Error('[FrqtlHostedEyes] writeRecordFolder: the folder path ' + JSON.stringify(p) + ' is not inside the folder. (FAIL-LOUD.)');
+            }
+            const v = folder.files[p];
+            if (typeof v !== 'string' && !(v instanceof Uint8Array)) {
+                throw new Error('[FrqtlHostedEyes] writeRecordFolder: ' + JSON.stringify(p) + ' is neither text nor bytes. (FAIL-LOUD.)');
+            }
+        }
+        for (const p of paths) {
+            const at = path.resolve(root, p);
+            fs.mkdirSync(path.dirname(at), { recursive: true });
+            fs.writeFileSync(at, folder.files[p]);
+        }
+        return paths;
+    }
+
+    export { FrqtlHostedEyes, writeRecordFolder };
 

package/dist/frqtl/objects/objects/QuantumEmitter.js

@@ -597,7 +597,7 @@ import { declaredCount } from '../ObjectFactory.js';
                 type: 'rect',
                 engineVisible: true,
                 description: 'Canonical bounding rect ' + ValueNormalizer.rectTupleText(4) + ' — repositions the single emission ' +
-                    'source rect. WS Studio Controls Realignment S4: routed through ' +
+                    'source rect. Routed through ' +
                     'QuantumEmitter.setSourceRect() (mutates emState.sourceRects directly — the ' +
                     'RETIRED provider ABI updateEmitterSourceRects no longer exists post-G-EMIT-2). ' +
  'The emitter moves its own marker.'