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

package/dist/frqtl/objects/record/Record.js

@@ -0,0 +1,326 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * Record.js — THE live owner of a Record (the sketch-projects design §6): its change rows, its own clock and
+ * its clips. Opened by the facade (`const rec = await exp.startRecord()`, RecipeContext); serialized by the one
+ * writer, lib/shim/project/record-format.js serializeRecordFolder.
+ *
+ *   rec.changes              READ-ONLY: the rows so far, a new deep-frozen copy per read (open or closed).
+ *   rec.tick                 READ-ONLY. The Record's OWN clock: 0 when it opens, +1 per world tick the runner
+ *                            delivers (runner.addTickListener, which survives a rebuild), so it climbs across
+ *                            every re-run inside the Record's world (setDeclared, restart) while the runner's
+ *                            own tick restarts at 0. Every row's tick and every clip span is on this clock.
+ *   await rec.film({ seconds, fps, everyTicks, stage? })
+ *                            ceil(seconds / 10) back-to-back FrqtlVision recordings of equal frame count, each
+ *                            CLIP_SECONDS long; seconds below CLIP_SECONDS.min are refused. Resolves the clip
+ *                            spans it filmed. The host keeps the world ticking (its loop, or a driver).
+ *   await rec.stop()         → { files, record, clips: [{ file, firstTick, lastTick }] } | { empty: true }.
+ *                            REJECTS (the Record stays open): a change and no clip, a change after the last
+ *                            clip ends, a clip still being filmed, any fault recordFolderFaults finds in its
+ *                            own folder.
+ *   rec.closed               a Promise that settles once, when the Record closes: the stop() value plus
+ *                            `closedBy: 'stop'`, or — when the facade's world is re-authored (a build of
+ *                            text that is not the held text) — the folder of the world before, with
+ *                            `closedBy: 'reauthor'` (rejected when that folder is refused, as stop() is).
+ *                            A refused close nobody READ (the getter records the read) makes the facade's
+ *                            next exp.startRecord() reject, naming it.
+ *   err.record               every rejection of stop() and of `closed` carries { changes, clips } — the
+ *                            Record's rows and clip spans — so a host can name them unheld instead of losing them.
+ *
+ * `closedBy` and the clip spans are the host's (a lab's own `filmed` list); record.json never carries them.
+ *
+ * WHERE ITS PARTS COME FROM — nothing here captures a second time:
+ *   rows    the writer's own edits at act end (RecipeContext.toSketch / setDeclared call `_row`); only what
+ *           was WRITTEN makes a row;
+ *   clips   every FrqtlVision.record on this runner while the Record is open (FrqtlVision asks
+ *           `openRecordOf(runner)` and hands the recording to `_clipFor`); a recording whose frames / fps
+ *           falls outside CLIP_SECONDS is refused before it is encoded;
+ *   parts   parts.before / parts.after = linkProject(held text).module.parts at open / at close, each kind
+ *           by the name the kinds registry resolves (kindNamed);
+ *   project the held files at close, under project/.
+ */
+
+import { FrqtlVision } from '../../parts/FrqtlVision.js';
+import { linkProject } from '../../../shim/project/link.js';
+import { serializeRecordFolder, CLIP_SECONDS, BY, CHANGE_KEYS } from '../../../shim/project/record-format.js';
+import { kindNamed } from '../kinds.js';
+import { _setOpenRecord, openRecordOf } from './open-record.js';
+
+function _fail(msg) {
+    throw new Error('[Record] ' + msg + ' (FAIL-LOUD.)');
+}
+
+function _bytesOfBase64(b64) {
+    var bin = atob(b64);
+    var out = new Uint8Array(bin.length);
+    for (var i = 0; i < bin.length; i++) { out[i] = bin.charCodeAt(i); }
+    return out;
+}
+
+/** linkProject(held).module.parts → { name: [registered kind name, props] } in key order. */
+async function _partsOf(held) {
+    var linked = await linkProject(held);
+    var parts = linked.module && linked.module.parts;
+    if (!parts || typeof parts !== 'object') {
+        _fail('the held sketch exports no `parts` block — a Record writes parts.before/after from `export const parts`.');
+    }
+    var out = {};
+    Object.keys(parts).forEach(function (name) {
+        var e = parts[name];
+        var Kind = Array.isArray(e) ? e[0] : null;
+        if (typeof Kind !== 'function') { _fail('parts.' + name + ' carries no kind class.'); }
+        kindNamed(Kind.name);   // the name the registry resolves (THROWS naming an unregistered kind)
+        out[name] = [Kind.name, e[1]];
+    });
+    return out;
+}
+
+/** The held project's files, copied (text values). */
+function _heldFiles(held) {
+    return Object.assign({}, held.files);
+}
+
+/**
+ * @param {object} exp — the RecipeContext that opens it (its runner and its held project)
+ * @private — construct through exp.startRecord()
+ */
+function Record(exp) {
+    var self = this;
+    this._exp = exp;
+    this._runner = exp.runner;
+    this._tick = 0;
+    this._rows = [];
+    this._clips = [];
+    this._inflight = 0;
+    this._open = true;
+    this._stopping = false;
+    this._filmArm = null;
+    this._before = null;
+    this._closedSettle = null;
+    this._closedRead = false;
+    this._refused = null;
+    this._closed = new Promise(function (resolve, reject) { self._closedSettle = { resolve: resolve, reject: reject }; });
+    // Observed here so node does not crash on an unhandled rejection; a refused close nobody read is LOUD at the next
+    // act instead (RecipeContext.startRecord refuses until `rec.closed` has been read).
+    this._closed.then(null, function () {});
+    this._settled = this._closed.then(function () {}, function () {});
+    this._onTick = function () { self._tick += 1; };
+    this._off = this._runner.addTickListener(this._onTick);
+    _setOpenRecord(this._runner, this);
+}
+
+Object.defineProperty(Record.prototype, 'tick', { get: function () { return this._tick; } });
+/** A deep-frozen copy. */
+function _frozen(v) {
+    if (v === null || typeof v !== 'object') { return v; }
+    var o = Array.isArray(v) ? v.map(_frozen) : Object.keys(v).reduce(function (a, k) { a[k] = _frozen(v[k]); return a; }, {});
+    return Object.freeze(o);
+}
+/**
+ * rec.changes — the rows so far, a NEW deep-frozen copy per read (record.json's `changes` vocabulary), on an open or a
+ * closed Record. One act's rows: `const n = rec.changes.length; await exp.toSketch({ by }); rec.changes.slice(n)`.
+ */
+Object.defineProperty(Record.prototype, 'changes', { get: function () {
+    return _frozen(this._rows.map(function (r) { var o = {}; CHANGE_KEYS.forEach(function (k) { o[k] = r[k]; }); return o; }));
+} });
+/** rec.closed — reading it records that the host has heard how the Record closed. */
+Object.defineProperty(Record.prototype, 'closed', { get: function () { this._closedRead = true; return this._closed; } });
+
+/** Attach what the Record holds to a refusal — `err.record = { changes, clips }` — so a host can name it unheld. */
+Record.prototype._carry = function (err) {
+    var e = (err instanceof Error) ? err : new Error(String(err));
+    e.record = {
+        changes: this._rows.map(function (r) { return JSON.parse(JSON.stringify(r)); }),
+        clips: this._clips.map(function (c) { return { firstTick: c.firstTick, lastTick: c.lastTick }; })
+    };
+    return e;
+};
+
+/** Read parts.before (the held text at open). @private */
+Record.prototype._ready = async function (held) {
+    this._held = held;
+    this._before = await _partsOf(held);
+    return this;
+};
+
+/** Throws unless `by` is one of BY (while a Record is open, every act names who acted). */
+Record.requireBy = function (by, where) {
+    if (BY.indexOf(by) === -1) {
+        throw new TypeError('[' + where + '] a Record is open: the act names who acted — { by: ' + BY.map(function (b) {
+            return JSON.stringify(b); }).join(' | ') + ' } (record-format.js BY); got ' + JSON.stringify(by) + '. (FAIL-LOUD.)');
+    }
+    return by;
+};
+
+/** One change row, at the Record's current tick, in the order acted. @private */
+Record.prototype._row = function (row) {
+    if (!this._open) { _fail('this Record is closed — no row is written into it.'); }
+    if (this._stopping) { _fail('this Record is stopping — an act during stop() belongs to the next Record.'); }
+    this._rows.push({ tick: this._tick, name: row.name, op: row.op, by: row.by, from: row.from, to: row.to });
+};
+
+/**
+ * The clip hook. FrqtlVision calls it with the normalized record() request, BEFORE it subscribes; it THROWS
+ * when the request cannot be a CLIP_SECONDS clip, and otherwise returns the recording's session:
+ *   sample(i)        called as frame i is sampled (inside the tick fan-out), reads this Record's tick
+ *   check(frames)    called before the encoder is finalized; THROWS outside CLIP_SECONDS
+ *   end(envelope)    the encoded clip joins the Record (ignored once the Record is closed)
+ *   drop()           the recording failed
+ * @private
+ */
+Record.prototype._clipFor = function (req) {
+    var self = this;
+    var span = CLIP_SECONDS.min + '–' + CLIP_SECONDS.max + ' s';
+    var advice = 'film inside an open Record with rec.film({ seconds, fps, everyTicks }), or record ' + span +
+        ' (frames / fps) per clip';
+    var planned = null;
+    if (req.stopAt.ticks !== undefined) { planned = Math.min(req.maxFrames, Math.floor(req.stopAt.ticks / req.everyTicks) + 1); }
+    var bound = planned === null ? req.maxFrames : planned;
+    var secs = function (n) { return n / req.fps; };
+    if ((planned !== null && (secs(planned) < CLIP_SECONDS.min || secs(planned) > CLIP_SECONDS.max)) ||
+        (planned === null && secs(bound) < CLIP_SECONDS.min)) {
+        _fail('a Record is open on this runner, so this recording is one of its clips, and a clip is ' + span +
+            ' long: this one is ' + (planned !== null ? secs(planned) : 'at most ' + secs(bound)) + ' s (' + bound +
+            ' frames at ' + req.fps + ' fps) — ' + advice + '.');
+    }
+    var arm = this._filmArm;
+    this._filmArm = null;
+    var ticks = [];
+    var done = false;
+    this._inflight += 1;
+    function settle() { if (!done) { done = true; self._inflight -= 1; } }
+    return {
+        sample: function (i) {
+            ticks[i] = self._tick;
+            if (arm && i === req.maxFrames - 1) { var next = arm.onLast; arm = null; next(); }
+        },
+        check: function (frames) {
+            if (secs(frames) < CLIP_SECONDS.min || secs(frames) > CLIP_SECONDS.max) {
+                settle();
+                _fail('a Record is open on this runner, so this recording is one of its clips, and a clip is ' + span +
+                    ' long: this one stopped at ' + secs(frames) + ' s (' + frames + ' frames at ' + req.fps + ' fps) — ' + advice + '.');
+            }
+        },
+        end: function (env) {
+            settle();
+            if (!self._open) { return; }
+            var n = env.track.frames.length;
+            self._clips.push({ bytes: _bytesOfBase64(env.encoded.bytes), firstTick: ticks[0], lastTick: ticks[n - 1] });
+        },
+        drop: function () { settle(); }
+    };
+};
+
+/**
+ * rec.film({ seconds, fps, everyTicks, stage? }) → Promise<[{ file?, firstTick, lastTick }]> — ceil(seconds/10)
+ * back-to-back segments of equal frame count. Each segment's recording is started INSIDE the previous one's last
+ * sampled tick (the tick fan-out dispatches a snapshot, so the next subscription fires from the next tick): the
+ * segments are contiguous on the world's clock whatever drives it. REFUSES: seconds below CLIP_SECONDS.min, a
+ * seconds × fps that does not split into equal whole-frame segments.
+ */
+Record.prototype.film = function (opts) {
+    var self = this;
+    try {
+        if (!this._open) { _fail('this Record is closed — open the next one (exp.startRecord()) to film.'); }
+        if (!opts || typeof opts !== 'object') { _fail('rec.film({ seconds, fps, everyTicks, stage? })'); }
+        Object.keys(opts).forEach(function (k) {
+            if (['seconds', 'fps', 'everyTicks', 'stage'].indexOf(k) === -1) { _fail('rec.film takes { seconds, fps, everyTicks, stage? }, not "' + k + '".'); }
+        });
+        var s = opts.seconds, fps = opts.fps, every = opts.everyTicks;
+        if (typeof s !== 'number' || !isFinite(s) || s < CLIP_SECONDS.min) {
+            _fail('rec.film: seconds is at least ' + CLIP_SECONDS.min + ' (CLIP_SECONDS), got ' + JSON.stringify(s) + '.');
+        }
+        if (!Number.isInteger(fps) || fps < 1) { _fail('rec.film: fps is a whole number ≥ 1 (the playback rate), got ' + JSON.stringify(fps) + '.'); }
+        if (!Number.isInteger(every) || every < 1) { _fail('rec.film: everyTicks is a whole number ≥ 1 (the capture cadence in ticks), got ' + JSON.stringify(every) + '.'); }
+        var n = Math.ceil(s / CLIP_SECONDS.max);
+        var total = s * fps;
+        if (!Number.isInteger(total) || total % n !== 0) {
+            _fail('rec.film: ' + s + ' s at ' + fps + ' fps is ' + total + ' frames, which does not split into ' + n +
+                ' equal whole-frame segments of at most ' + CLIP_SECONDS.max + ' s — choose seconds × fps divisible by ' + n + '.');
+        }
+        var f = total / n;
+        var req = { everyTicks: every, fps: fps, maxFrames: f, stopAt: { ticks: (f - 1) * every } };
+        if (opts.stage !== undefined) { req.stage = opts.stage; }
+        var vision = FrqtlVision.attach(this._runner);
+        var first = this._clips.length;
+        // One deferred per segment: segment k+1 exists once segment k sampled its last frame.
+        var segs = [];
+        for (var k = 0; k < n; k++) {
+            (function () { var d = {}; d.promise = new Promise(function (res, rej) { d.resolve = res; d.reject = rej; }); segs.push(d); })();
+        }
+        var started = [];
+        var start = function (k) {
+            started[k] = true;
+            self._filmArm = (k < n - 1) ? { onLast: function () { start(k + 1); } } : null;
+            var p = vision.record(req);
+            segs[k].resolve(p);
+            p.then(function () {
+                if (k + 1 < n && !started[k + 1]) {
+                    segs[k + 1].reject(new Error('[Record.film] segment ' + (k + 1) + ' of ' + n + ' ended without sampling its last frame, ' +
+                        'so segment ' + (k + 2) + ' never started. (FAIL-LOUD.)'));
+                }
+            }, function (e) {
+                self._filmArm = null;
+                for (var j = k + 1; j < n; j++) { if (!started[j]) { started[j] = true; segs[j].reject(e); } }
+            });
+        };
+        start(0);
+        return Promise.all(segs.map(function (d) { return d.promise; })).then(function () {
+            return self._clips.slice(first).map(function (c) { return { firstTick: c.firstTick, lastTick: c.lastTick }; });
+        });
+    } catch (e) { return Promise.reject(e); }
+};
+
+/** Serialize this Record's folder from `held` (the files it snapshots). @private */
+Record.prototype._folder = async function (held) {
+    var after = await _partsOf(held);
+    return serializeRecordFolder({
+        changes: this._rows.slice(), clips: this._clips.slice(),
+        partsBefore: this._before, partsAfter: after, project: _heldFiles(held)
+    });
+};
+
+/** Detach from the world (no row, tick or clip after this). @private */
+Record.prototype._detach = function () {
+    this._open = false;
+    if (this._off) { this._off(); this._off = null; }
+    _setOpenRecord(this._runner, null);
+    this._exp._record = null;
+};
+
+/** rec.stop() — see the module docstring. */
+Record.prototype.stop = async function () {
+    var self = this;
+    var refuse = function (msg) { try { _fail(msg); } catch (e) { throw self._carry(e); } };
+    if (!this._open) { refuse('this Record is already closed' + (this._closedBy ? ' (closedBy: ' + this._closedBy + ')' : '') + ' — read rec.closed.'); }
+    if (this._stopping) { refuse('stop() is already running.'); }
+    if (this._inflight) { refuse(this._inflight + ' clip(s) are still being filmed — await rec.film (or the record()) before stop().'); }
+    this._stopping = true;
+    var out;
+    try { out = await this._folder(this._exp._project); }
+    catch (e) { throw this._carry(e); }
+    finally { this._stopping = false; }
+    this._closedBy = 'stop';
+    this._detach();
+    this._closedSettle.resolve(Object.assign({}, out, { closedBy: 'stop' }));
+    return out;
+};
+
+/**
+ * The facade re-authors its world: close with the folder of the world BEFORE (`held` = the held project before
+ * the build). Synchronous detach; the folder settles `closed`. @private
+ */
+Record.prototype._closeOnReauthor = function (held) {
+    var self = this;
+    this._closedBy = 'reauthor';
+    this._detach();
+    this._folder(held).then(function (out) {
+        self._closedSettle.resolve(Object.assign({}, out, { closedBy: 'reauthor' }));
+    }, function (e) {
+        self._refused = self._carry(e);
+        self._refused.closedBy = 'reauthor';
+        self._closedSettle.reject(self._refused);
+    });
+};
+
+export { Record, openRecordOf };

package/dist/frqtl/objects/record/open-record.js

@@ -0,0 +1,22 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * open-record.js — which Record is open on a runner: the ONE store FrqtlVision asks (its clip hook) and the
+ * Record writes. One open Record per runner; a second open is refused by the facade (RecipeContext.startRecord).
+ *
+ *   openRecordOf(runner) → Record | null
+ */
+
+var _open = new WeakMap();
+
+/** @param {object} runner @returns {object|null} the Record open on it */
+function openRecordOf(runner) {
+    return (runner && _open.get(runner)) || null;
+}
+
+/** @private — Record.js only */
+function _setOpenRecord(runner, rec) {
+    if (rec) { _open.set(runner, rec); } else { _open.delete(runner); }
+}
+
+export { openRecordOf, _setOpenRecord };

package/dist/frqtl/parts/FrqtlVision.js

@@ -183,6 +183,7 @@ import * as CaptureEnvelope from '../../shim/render/capture-envelope.js';
 import { CameraPath } from './CameraPath.js';
 import { FrqtlCaptureHost } from '../objects/instruments/capture-host.js';
 import { vendorUrl } from '../compat/vendor.js';
+import { openRecordOf } from '../objects/record/open-record.js';
 
 function _rgba8Format(RS) { return RS.STAGE_FORMATS[RS.finalStage()]; }
 
@@ -574,16 +575,24 @@ function _record(runner, RS, opts) {
             'localhost). The encoder is not optional — there is no second path');
     }
 
+    // THE CLIP HOOK: while a Record is open on this runner, every recording is one of its clips. The Record
+    // refuses a request that cannot be a CLIP_SECONDS clip (before anything subscribes) and keeps the clip's
+    // ticks and bytes; this recorder holds no Record state of its own (objects/record/Record.js _clipFor).
+    var openRec = openRecordOf(runner);
+    var clip = openRec ? openRec._clipFor(req) : null;
+
     // Everything that can THROW synchronously happens BEFORE the sampler subscribes: a
     // CameraPath refused at attach (no pose control, an undeclared pose field) must not leave
     // a subscribed sampler holding the clock behind a rejection nobody can reach.
     var path = null;
     if (req.stopAt.path) {
-        path = CameraPath.attach(runner, {
-            waypoints: req.stopAt.path.waypoints,
-            loop: !!req.stopAt.path.loop,
-            waypointTimeoutMs: req.stopAt.path.waypointTimeoutMs
-        });
+        try {
+            path = CameraPath.attach(runner, {
+                waypoints: req.stopAt.path.waypoints,
+                loop: !!req.stopAt.path.loop,
+                waypointTimeoutMs: req.stopAt.path.waypointTimeoutMs
+            });
+        } catch (e) { if (clip) { clip.drop(); } throw e; }
     }
     var frames = [];
     var inflight = [];
@@ -628,6 +637,7 @@ function _record(runner, RS, opts) {
                 _fail('record', 'the recording stopped before a single still was captured — nothing to ' +
                     'encode. Is the runner advancing ticks?');
             }
+            if (clip) { clip.check(frames.length); }
             return encodeChain;
         }).then(function (enc) {
             return enc.output.finalize().then(function () { return enc.output.getMimeType(); })
@@ -654,7 +664,11 @@ function _record(runner, RS, opts) {
                         truncated: truncated
                     });
                 });
-        }).then(settle.resolve, function (e) {
+        }).then(function (env) {
+            if (clip) { clip.end(env); }
+            settle.resolve(env);
+        }, function (e) {
+            if (clip) { clip.drop(); }
             encoderReady.then(function (enc) { return enc.output.cancel(); }).then(null, function () {});
             settle.reject(e);
         });
@@ -670,6 +684,7 @@ function _record(runner, RS, opts) {
             return true;
         },
         onStill: function (p, i) {
+            if (clip) { clip.sample(i); }
             var handled = p.then(function (still) {
                 if (i === 0) {
                     scene = still.scene;

package/dist/shim/bundle/index.js

@@ -1,121 +1,137 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * lib/shim/bundle/index.js — the recipe-bundle assembler + importer
- * The canonical owner of the bundle format
- * (design §2): a folder that zips for download —
+ * lib/shim/bundle/index.js — Export and Import of a project folder.
  *
- *   experiment.js      ← THE source of truth (the buildExperiment(exp) recipe)
- *   experiment.frqnb   ← teaching/gallery projection (notebook/format.serialize)
- *   index.html         ← standalone host (@descix/frqtl-web bootProject over the served folder)
- *   manifest.json      ← Module envelope minus `source` + bundle-only fields (E1)
- *   preview.png        ← optional golden screenshot
+ * A project is a folder (the stored row's owner is
+ * lib/shim/storage/folders.js). The Export IS the folder, zipped, plus the host page that boots it:
  *
- * PURE + DOM-free: emits/consumes `Uint8Array`. STUDIO's export button and any
- * future DeSciX publisher CONSUME this — passing the generated `experiment.js`
- * source + envelope + renderState DOWN (this module never imports codegen/
- * save-state — those live above the shim; the arrow stays one-way). The browser
- * `Blob`+`a.click` download trigger is a THIN feature-side helper.
+ *   exportFolder(files, renderState, { sdkVersion }) → zipBytes
+ *       the zip holds EXACTLY the folder's files plus a generated `index.html` (indexHtml.js: bootProject over the
+ *       served folder, frqtl.json naming the entry, the boot bag inlined by its one writer).
+ *   importArchive(bytes, fileName) → { files, renderState }   (a normalized folder row)
+ *       a zip      → its files minus `index.html`, whose boot bag (indexHtml.js readBootBag) becomes renderState;
+ *                    it must carry frqtl.json at its root (an archive with no index.html imports with
+ *                    renderState null)
+ *       one `.js`  → the one-file project { 'sketch.js': text, 'frqtl.json': manifestFor({ name: <basename>,
+ *                    entry: 'sketch.js' }) }, renderState null — a 3D sketch then fails loud at boot on the
+ *                    renderer (the existing named refusal); nothing guesses a display
+ *       REFUSED, naming the migration: a zip carrying `experiment.js` or `manifest.json`, or a JSON v4 module
+ *       envelope — the retired export format. REFUSED by rule: a one-file `.mjs` (frqtl.json's entry rule admits a
+ *       `.js` entry only), anything else.
  *
- * Layer 2 (physics): none — pure format/packaging.
+ * PURE + DOM-free (Uint8Array in and out). The browser download and file read are lib/features/ide/bundle-export.js.
+ * zip.js (the STORE zip) is imported by the Record too; its API is frozen. Layer 2 (physics): none.
  */
 
 'use strict';
 
-import { buildManifest, manifestToEnvelope } from './manifest.js';
-import { buildFrqnb } from './frqnb.js';
-import { buildIndexHtml } from './indexHtml.js';
-import { zipStore, unzipStore, textBytes, bytesText } from './zip.js';
-import { normalizeSavedRenderState } from '../render-state/index.js';
+import { zipStore, unzipStore, textBytes } from './zip.js';
+import { buildIndexHtml, readBootBag } from './indexHtml.js';
+import { normalizeFolderRow, EXPORT_PAGE } from '../storage/folders.js';
+import { MANIFEST_FILE, MANIFEST_KEYS, parseManifest, serializeManifest, manifestFor } from '../project/manifest.js';
 
-// ── Canonical bundle file names ──────────────────────────────────────────────
-export var FILE_EXPERIMENT_JS   = 'experiment.js';
-export var FILE_EXPERIMENT_FRQNB = 'experiment.frqnb';
-export var FILE_INDEX_HTML       = 'index.html';
-export var FILE_MANIFEST_JSON    = 'manifest.json';
-export var FILE_PREVIEW_PNG      = 'preview.png';
+/** The files of the retired export format (the v4 envelope's bundle). */
+export var RETIRED_ARCHIVE_FILES = Object.freeze(['experiment.js', 'manifest.json']);
 
-/**
- * Assemble a recipe bundle from a Module envelope + bundle inputs.
- *
- * Conceptually the dispatch's `(source, envelopeMeta, renderState, previewPngBytes,
- * sdkVersion)`: here `source` + `renderState` + `envelopeMeta` arrive together AS
- * the Module envelope (the exact shape STUDIO's Save path already builds), so the
- * bundle↔envelope round-trip is a clean identity. `manifest` ferries the envelope
- * minus `source` (E1) — no field re-enumeration.
- *
- * @param {object} envelope — a `lib/shim/storage/modules.js` Module envelope
- *   (`{id,name,source,renderState,…}`; `source` = the recipe, REQUIRED).
- * @param {object} opts
- * @param {string} opts.sdkVersion — REQUIRED CDN pin (derived, never a literal).
- * @param {Uint8Array|null} [opts.previewPngBytes] — preview image bytes, or null.
- * @param {string} [opts.stage='600x400'] — canvas stage for the .frqnb projection.
- * @param {string} [opts.prose] — optional teaching blurb for the .frqnb markdown.
- * @returns {{files: {name:string, bytes:Uint8Array}[], zipBytes: Uint8Array}}
- */
-export function assembleBundle(envelope, opts) {
-    if (!envelope || typeof envelope !== 'object') {
-        throw new Error('[bundle] assembleBundle(envelope): envelope must be an object.');
-    }
-    if (typeof envelope.source !== 'string' || envelope.source.length === 0) {
-        throw new Error('[bundle] assembleBundle: envelope.source (the recipe) is required.');
-    }
-    opts = opts || {};
-    var preview = (opts.previewPngBytes instanceof Uint8Array && opts.previewPngBytes.length > 0)
-        ? opts.previewPngBytes : null;
+var RETIRED = 'this is the retired export format; the project folder replaced it (frqtl.json + sketch.js)';
+var SKETCH = 'sketch.js';
 
-    var manifest = buildManifest(envelope, {
-        sdkVersion: opts.sdkVersion,
-        preview: preview ? FILE_PREVIEW_PNG : null
-    });
+var _strict = new TextDecoder('utf-8', { fatal: true });
 
-    var normalizedRs = normalizeSavedRenderState(envelope.renderState);
-
-    var files = [
-        { name: FILE_EXPERIMENT_JS,    bytes: textBytes(envelope.source) },
-        { name: FILE_EXPERIMENT_FRQNB, bytes: textBytes(buildFrqnb({
-            name: envelope.name, source: envelope.source,
-            renderState: normalizedRs, stage: opts.stage, prose: opts.prose
-        })) },
-        { name: FILE_INDEX_HTML,       bytes: textBytes(buildIndexHtml({
-            name: envelope.name, sdkVersion: opts.sdkVersion, renderState: normalizedRs,
-            scripts: Array.isArray(envelope.scripts) ? envelope.scripts : []   // the envelope's setup-factory delta
-        })) },
-        { name: FILE_MANIFEST_JSON,    bytes: textBytes(JSON.stringify(manifest, null, 2)) }
-    ];
-    if (preview) { files.push({ name: FILE_PREVIEW_PNG, bytes: preview }); }
-
-    return { files: files, zipBytes: zipStore(files) };
+function _fail(msg) {
+    throw new Error('[bundle] ' + msg + ' (FAIL-LOUD.)');
 }
 
 /**
- * Import a recipe bundle: recover the Module envelope (source re-attached from
- * `experiment.js` per E1) + the preview bytes.
- *
- * @param {Uint8Array} zipBytes — a bundle `.zip` (from `assembleBundle`).
- * @returns {{envelope: object, previewPngBytes: Uint8Array|null}}
+ * @param {Object<string,string>} files — the folder (frqtl.json + its files)
+ * @param {object|null} renderState — the host's boot bag (normalized by its owner through the folder row)
+ * @param {{sdkVersion: string}} opts — the `@descix/frqtl-web` pin the page imports (derived, never a literal)
+ * @returns {Uint8Array} the zip
  */
-export function importBundle(zipBytes) {
-    var entries = unzipStore(zipBytes);
-    var byName = Object.create(null);
-    for (var i = 0; i < entries.length; i++) { byName[entries[i].name] = entries[i].bytes; }
+export function exportFolder(files, renderState, opts) {
+    var row = normalizeFolderRow({ files: files, renderState: renderState });
+    var sdkVersion = opts && opts.sdkVersion;
+    var name = parseManifest(row.files[MANIFEST_FILE]).name;
+    var entries = Object.keys(row.files).map(function (p) { return { name: p, bytes: textBytes(row.files[p]) }; });
+    entries.push({ name: EXPORT_PAGE, bytes: textBytes(buildIndexHtml({ name: name, sdkVersion: sdkVersion, renderState: row.renderState })) });
+    return zipStore(entries);
+}
+
+function _isZip(bytes) {
+    return bytes.length >= 4 && bytes[0] === 0x50 && bytes[1] === 0x4b &&
+        ((bytes[2] === 0x03 && bytes[3] === 0x04) || (bytes[2] === 0x05 && bytes[3] === 0x06));
+}
 
-    if (!byName[FILE_MANIFEST_JSON]) {
-        throw new Error('[bundle] importBundle: ' + FILE_MANIFEST_JSON + ' missing from the archive.');
+function _text(bytes, what) {
+    try { return _strict.decode(bytes); }
+    catch (e) { _fail(what + ' is not UTF-8 text — a project folder holds text files only.'); }
+}
+
+function _baseName(fileName) {
+    var base = String(fileName).split(/[\\/]/).pop();
+    return base;
+}
+
+function _fromZip(bytes) {
+    var entries = unzipStore(bytes).filter(function (e) { return !/\/$/.test(e.name); });
+    var names = entries.map(function (e) { return e.name; });
+    var retired = RETIRED_ARCHIVE_FILES.filter(function (f) { return names.indexOf(f) !== -1; });
+    if (retired.length) {
+        _fail('the archive carries ' + retired.join(' and ') + ': ' + RETIRED + '.');
     }
-    if (!byName[FILE_EXPERIMENT_JS]) {
-        throw new Error('[bundle] importBundle: ' + FILE_EXPERIMENT_JS + ' missing from the archive.');
+    if (names.indexOf(MANIFEST_FILE) === -1) {
+        _fail('the archive carries no ' + MANIFEST_FILE + ' at its root — a project archive is the folder zipped ' +
+            '(frqtl.json + sketch.js + …), as an Export writes it.');
     }
+    var files = {};
+    var renderState = null;
+    entries.forEach(function (e) {
+        var text = _text(e.bytes, '"' + e.name + '"');
+        if (e.name === EXPORT_PAGE) { renderState = readBootBag(text); return; }
+        files[e.name] = text;
+    });
+    return normalizeFolderRow({ files: files, renderState: renderState });
+}
 
-    var manifest;
-    try {
-        manifest = JSON.parse(bytesText(byName[FILE_MANIFEST_JSON]));
-    } catch (e) {
-        throw new Error('[bundle] importBundle: ' + FILE_MANIFEST_JSON + ' is not valid JSON — ' + (e && e.message));
+function _fromJson(text) {
+    var raw;
+    try { raw = JSON.parse(text); }
+    catch (e) { _fail('the file is neither a project archive (.zip) nor a sketch (.js), and not valid JSON either.'); }
+    if (raw && typeof raw === 'object' && ('schemaVersion' in raw || 'scripts' in raw) && 'source' in raw) {
+        _fail('the file is a v4 module envelope: ' + RETIRED + '.');
     }
-    var source = bytesText(byName[FILE_EXPERIMENT_JS]);
-    var envelope = manifestToEnvelope(manifest, source);
-    var previewPngBytes = byName[FILE_PREVIEW_PNG] || null;
+    _fail('the JSON file is not a project — Import takes a project archive (.zip) or one sketch (.js).');
+}
+
+function _fromSketch(text, fileName) {
+    var base = _baseName(fileName);
+    var name = base.replace(/\.js$/, '');
+    if (!name) { _fail('the sketch file "' + base + '" has no name before ".js".'); }
+    var files = {};
+    files[MANIFEST_FILE] = serializeManifest(manifestFor({ name: name, entry: SKETCH }));
+    files[SKETCH] = text;
+    return normalizeFolderRow({ files: files, renderState: null });
+}
 
-    return { envelope: envelope, previewPngBytes: previewPngBytes };
+/**
+ * @param {Uint8Array} bytes
+ * @param {string} fileName — the imported file's name (a one-file sketch's basename is its project name)
+ * @returns {Readonly<{files: Object<string,string>, renderState: object}>}
+ */
+export function importArchive(bytes, fileName) {
+    if (!(bytes instanceof Uint8Array)) { _fail('importArchive(bytes, fileName): bytes is a Uint8Array.'); }
+    if (typeof fileName !== 'string' || fileName.length === 0) { _fail('importArchive(bytes, fileName): the file\'s name.'); }
+    if (_isZip(bytes)) { return _fromZip(bytes); }
+    var base = _baseName(fileName);
+    if (/\.mjs$/i.test(base)) {
+        var entryRule = MANIFEST_KEYS.filter(function (r) { return r.key === 'entry'; })[0].rule;
+        _fail('"' + base + '" is a .mjs module — a one-file Import takes a .js sketch, because a project\'s entry is ' +
+            entryRule + ' (frqtl.json, lib/shim/project/manifest.js MANIFEST_KEYS). Rename it to .js and import it again.');
+    }
+    var text = _text(bytes, '"' + base + '"');
+    if (/\.js$/.test(base)) { return _fromSketch(text, base); }
+    if (/\.json$/i.test(base) || /^\s*\{/.test(text)) { return _fromJson(text); }
+    _fail('"' + base + '" is not a project — Import takes a project archive (.zip, as an Export writes it) or one ' +
+        'sketch (.js).');
 }