@descix/frqtl-node 0.6.0-p1.1 → 0.6.0-p4.1

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

@@ -69,7 +69,8 @@
  * 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,7 @@ 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';
 
 
@@ -191,7 +193,8 @@ import { libPathOf } from '../../../shim/project/specifiers.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) {
@@ -213,18 +216,20 @@ import { libPathOf } from '../../../shim/project/specifiers.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);
     }
 
     /**
@@ -478,16 +483,10 @@ import { libPathOf } from '../../../shim/project/specifiers.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 };
     };
@@ -553,8 +552,8 @@ import { libPathOf } from '../../../shim/project/specifiers.js';
                     return;
                 }
                 try {
-                    var td = r.step();
-                    resolve((td && td.universeData) ? td.universeData.tick : null);
+                    r.step();
+                    resolve(r.worldTick);
                 } catch (e) { reject(e); }
             })();
         });
@@ -562,8 +561,9 @@ import { libPathOf } from '../../../shim/project/specifiers.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;
     };
 
     /**
@@ -606,6 +606,99 @@ import { libPathOf } from '../../../shim/project/specifiers.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() ────────────────────────────────────────────────────────────────
 
     /**
@@ -617,8 +710,9 @@ import { libPathOf } from '../../../shim/project/specifiers.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
@@ -654,7 +748,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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') {
@@ -725,7 +819,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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) {
@@ -860,7 +954,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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) {
@@ -875,7 +969,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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
@@ -894,7 +988,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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
@@ -907,7 +1001,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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); },
 
             /**
@@ -926,7 +1020,7 @@ import { libPathOf } from '../../../shim/project/specifiers.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 ' +
@@ -1010,6 +1104,42 @@ import { libPathOf } from '../../../shim/project/specifiers.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(); }
         };
@@ -1020,5 +1150,46 @@ import { libPathOf } from '../../../shim/project/specifiers.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 };