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

package/dist/frqtl/scenes/mirror-route.js

@@ -19,102 +19,119 @@
 // captured descriptor DATA) keeps the population bounded so FPS stays healthy, Restart-safe.
 //
 // ONE MODE-AWARE SOURCE. The mode strip selects the RENDERER the host boots
-// (renderState.renderer), and this scene reads it ONCE, before its world: `three` ⇒
+// (renderState.renderer), and this scene reads it ONCE, inside buildExperiment: `three` ⇒
 // exp.createScene (a 600x400x600 world), else exp.createCanvas (600x400). The ring geometry,
-// tilts, colours, laser and gate are the SAME in both modes (2D≡3D); `IS3D` guards exactly
-// these deltas:
+// tilts, colours, laser and gate are the SAME in both modes (2D≡3D). `parts` is written in the
+// 3D default mode, and flat2D (below) derives the 2D block from it — the scene's own statement of
+// two of its deltas:
 //   (a) every mirror is a 3D SLAB — a z-slab centred on the beam plane z=0, rendered as a plate;
 //   (b) the laser is VOLUMETRIC (is2D:false — it braids in y AND z; the slab depth catches the
-//       z-braid; its tilted xy faces reflect by the 2θ law, its near/far z-faces bounce vz);
+//       z-braid; its tilted xy faces reflect by the 2θ law, its near/far z-faces bounce vz).
+// `IS3D` guards the rest, in code after exp.declare:
 //   (c) two invisible destroy z-collimators flush with the slab z-band;
-//   (d) the population counter carries a z-slab covering the WHOLE universe z-band;
+//   (d) the population counter carries a z-slab covering the WHOLE universe z-band (the emitter's
+//       gateCounter names it, so it stays a code declaration);
 //   (e) MOVE/LOOK camera joysticks (the OMNI_3D pattern).
 // The 3D mode's render intent — god-rays at the sun's settings, computed from the light
 // particles only (godraySource 'leaf'), and the 'table-top' camera — rides the registry mode's
 // renderState (lib/shim/registry/walkthrough.js), whose god-ray VALUES are the sun's, owned by
 // lib/shim/render/sun-look.js.
 
-import { CameraControls, SphereEmitter } from '@descix/frqtl-web/parts';
+import { CameraControls, SphereEmitter, Wall } from '@descix/frqtl-web/parts';
 import * as FrqtlDisplay from '@descix/frqtl-web/compat/renderer/display-slot.js';
 
-export const parts = {};
+const W = 600, H = 400, WORLD_D = 600;   // THE WORLD this scene states (its co-init call below)
+const f = Math.min(W, H) / 600;
+// R 225·f: adjacent decagon vertices sit 2R·sin18° ≈ 0.618R apart vs slab
+// height ~110·f, so the mirrors separate with clear gaps. Fit: R + rotated-slab half-diagonal
+// (≈55·f) stays inside min(W,H)/2 with margin.
+const CX = Math.round(W / 2), CY = Math.round(H / 2), R = Math.round(225 * f), HOP = 3, ROT = 12;
+// CAP 6400 / burst 8 (brightness retune): a VERY BRIGHT braid. The cap is
+// LIVE-controllable off the population counter (select 'population' in Layers → Inspector
+// 'Population Gate').
+const SW = Math.max(10, Math.round(14 * f)), SH = Math.max(70, Math.round(110 * f)), CAP = 6400;
+// SD — the 3D slab z-depth: a 2:1 tile (twice the slab height, z-centred on the beam plane).
+// The scene z-collimator clamps ALL quanta to this band, so every mirror provably faces every
+// alive quantum.
+const SD = 2 * SH;
+// Each mirror a DIFFERENT colour = its identity (a red→magenta rainbow); the recolor hook
+// stamps that colour onto every particle it reflects (string_map['render.color']).
+const PAL = [[255,60,60],[255,140,0],[255,220,0],[150,230,40],[40,210,90],[0,210,190],[0,170,255],[70,90,255],[150,70,235],[235,50,190]];
+// Hit-order vertices of the {10/3} star (m1..m10 named IN the order the beam visits them).
+const order = []; for (var k = 0; k < 10; k++) { order.push((k * HOP) % 10); }
+const D2R = Math.PI / 180;
+const vpos = function (v) { var a = (v * 36 + ROT) * D2R; return [CX + R * Math.cos(a), CY + R * Math.sin(a)]; };
+const pos = order.map(vpos);
+const deg = function (a) { return ((a * 180 / Math.PI) % 360 + 360) % 360; };
+const angOf = function (p, q) { return deg(Math.atan2(q[1] - p[1], q[0] - p[0])); };
+// Per-mirror IN-PLANE orientation from the in/out chords: ori = (in+out−180)/2, branch chosen
+// so the engine reflect law out = 180 + 2·ori − in reproduces the outgoing chord exactly.
+// Orientation is z-axis rotation, so the 3D slab depth adds NO new angle.
+const ORI = [];
+for (var j = 0; j < 10; j++) {
+  var pr = pos[(j + 9) % 10], cu = pos[j], nx = pos[(j + 1) % 10];
+  var inA = angOf(pr, cu), outA = angOf(cu, nx);
+  var o = (((inA + outA - 180) / 2) % 360 + 360) % 360;
+  var op = ((180 + 2 * o - inA) % 360 + 360) % 360;
+  if (Math.abs(((op - outA + 540) % 360) - 180) > 0.5) { o = (o + 90) % 360; }
+  ORI.push(o);
+}
+// The NARROW STRAIGHT-WALK laser (the exemplar): the SAME emitter as Rung 1
+// (Straight Walk) — preset 'particle-walk', every walk-character field INHERITED from the same
+// factory defaults (chargeMode 'positive', dim 0 = 'light' P=1, fundamentalWaveLength 64 → the
+// λ16 braided transverse ripple) — with ONLY the deliberate loop deltas: (a) a 2px source line
+// (emissionBoxSide 2 vs r1's default 10), (b) seated on the m10→m1 leg JUST CLEAR of m10 (70·f
+// past its vertex > the rotated-slab half-diagonal ≈55·f) and aimed along the leg (the longest
+// clear throw: leg 1.618R ≈ 364·f), (c) a burst of 8/tick, and (d) the DECLARED emission gate.
+const pS = pos[9], p0 = pos[0];
+const dx = p0[0] - pS[0], dy = p0[1] - pS[1], L = Math.hypot(dx, dy), ux = dx / L, uy = dy / L;
+const emit = [Math.round(pS[0] + 70 * f * ux), Math.round(pS[1] + 70 * f * uy)];
+// EMISSION-CAP GATE as DECLARED DATA (the blackbody-thermostat pattern):
+// emissionCap + gateCounter compile at CONSTRUCTION into a host tick-fn reading
+// Wall.getLiveCount on the background counter named 'population' (placed below — the by-name
+// reference resolves lazily on the first tick). The closed loop has NO sink, so the gate pauses
+// emission at the cap and resumes below it: the population plateaus. Restart-safe: the parts
+// writer keeps the two fields in the entry and the rebuilt emitter recompiles the gate (no free recipe tick-fn).
+// is2D: false (the 3D default) opens activeAxes.z — the volumetric laser; flat2D writes it true.
+// The parts, written in the 3D default mode (the mode strip's default): the laser, then the ten mirrors at the
+// star vertices — each its own colour + the recolor tag, each a 3D SLAB (z-slab -SD/2..SD/2). 2D is derived from
+// this block by flat2D below.
+export const parts = {
+  source: [SphereEmitter, { preset: 'particle-walk', is2D: false, center: emit, orientationDeg: angOf(pS, p0), emissionBoxSide: 2, burstSize: 8, emissionCap: CAP, gateCounter: 'population' }],
+  m1: [Wall, { rect: [Math.round(pos[0][0] - SW / 2), Math.round(pos[0][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[0], color: PAL[0], hooks: ['recolor'] }],
+  m2: [Wall, { rect: [Math.round(pos[1][0] - SW / 2), Math.round(pos[1][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[1], color: PAL[1], hooks: ['recolor'] }],
+  m3: [Wall, { rect: [Math.round(pos[2][0] - SW / 2), Math.round(pos[2][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[2], color: PAL[2], hooks: ['recolor'] }],
+  m4: [Wall, { rect: [Math.round(pos[3][0] - SW / 2), Math.round(pos[3][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[3], color: PAL[3], hooks: ['recolor'] }],
+  m5: [Wall, { rect: [Math.round(pos[4][0] - SW / 2), Math.round(pos[4][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[4], color: PAL[4], hooks: ['recolor'] }],
+  m6: [Wall, { rect: [Math.round(pos[5][0] - SW / 2), Math.round(pos[5][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[5], color: PAL[5], hooks: ['recolor'] }],
+  m7: [Wall, { rect: [Math.round(pos[6][0] - SW / 2), Math.round(pos[6][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[6], color: PAL[6], hooks: ['recolor'] }],
+  m8: [Wall, { rect: [Math.round(pos[7][0] - SW / 2), Math.round(pos[7][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[7], color: PAL[7], hooks: ['recolor'] }],
+  m9: [Wall, { rect: [Math.round(pos[8][0] - SW / 2), Math.round(pos[8][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[8], color: PAL[8], hooks: ['recolor'] }],
+  m10: [Wall, { rect: [Math.round(pos[9][0] - SW / 2), Math.round(pos[9][1] - SH / 2), SW, SH], z: -Math.round(SD / 2), depth: SD, collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[9], color: PAL[9], hooks: ['recolor'] }],
+};
+
+/** This scene's 2D delta, stated once: the same keys in the same order, each props copied with its z-slab
+ *  (z, depth) dropped and is2D written true where it is spelled. Pure; adds no key. */
+function flat2D(parts) {
+  const out = {};
+  for (const key of Object.keys(parts)) {
+    const props = Object.assign({}, parts[key][1]);
+    delete props.z;
+    delete props.depth;
+    if ('is2D' in props) { props.is2D = true; }
+    out[key] = [parts[key][0], props];
+  }
+  return out;
+}
 
 export default function buildExperiment(exp) {
   // The booted display (the host's renderState.renderer) decides which world this mode makes.
   var IS3D = FrqtlDisplay.name() === 'three';
-  var W = 600, H = 400, WORLD_D = 600;   // THE WORLD this scene states (its co-init call below)
-  var f = Math.min(W, H) / 600;
-  // R 225·f: adjacent decagon vertices sit 2R·sin18° ≈ 0.618R apart vs slab
-  // height ~110·f, so the mirrors separate with clear gaps. Fit: R + rotated-slab half-diagonal
-  // (≈55·f) stays inside min(W,H)/2 with margin.
-  var CX = Math.round(W / 2), CY = Math.round(H / 2), R = Math.round(225 * f), HOP = 3, ROT = 12;
-  // CAP 6400 / burst 8 (brightness retune): a VERY BRIGHT braid. The cap is
-  // LIVE-controllable off the population counter (select 'population' in Layers → Inspector
-  // 'Population Gate').
-  var SW = Math.max(10, Math.round(14 * f)), SH = Math.max(70, Math.round(110 * f)), CAP = 6400;
-  // SD — the 3D slab z-depth: a 2:1 tile (twice the slab height, z-centred on the beam plane).
-  // The scene z-collimator clamps ALL quanta to this band, so every mirror provably faces every
-  // alive quantum.
-  var SD = 2 * SH;
-  // Each mirror a DIFFERENT colour = its identity (a red→magenta rainbow); the recolor hook
-  // stamps that colour onto every particle it reflects (string_map['render.color']).
-  var PAL = [[255,60,60],[255,140,0],[255,220,0],[150,230,40],[40,210,90],[0,210,190],[0,170,255],[70,90,255],[150,70,235],[235,50,190]];
-  // Hit-order vertices of the {10/3} star (m1..m10 named IN the order the beam visits them).
-  var order = []; for (var k = 0; k < 10; k++) { order.push((k * HOP) % 10); }
-  var D2R = Math.PI / 180;
-  var vpos = function (v) { var a = (v * 36 + ROT) * D2R; return [CX + R * Math.cos(a), CY + R * Math.sin(a)]; };
-  var pos = order.map(vpos);
-  var deg = function (a) { return ((a * 180 / Math.PI) % 360 + 360) % 360; };
-  var angOf = function (p, q) { return deg(Math.atan2(q[1] - p[1], q[0] - p[0])); };
-  // Per-mirror IN-PLANE orientation from the in/out chords: ori = (in+out−180)/2, branch chosen
-  // so the engine reflect law out = 180 + 2·ori − in reproduces the outgoing chord exactly.
-  // Orientation is z-axis rotation, so the 3D slab depth adds NO new angle.
-  var ORI = [];
-  for (var j = 0; j < 10; j++) {
-    var pr = pos[(j + 9) % 10], cu = pos[j], nx = pos[(j + 1) % 10];
-    var inA = angOf(pr, cu), outA = angOf(cu, nx);
-    var o = (((inA + outA - 180) / 2) % 360 + 360) % 360;
-    var op = ((180 + 2 * o - inA) % 360 + 360) % 360;
-    if (Math.abs(((op - outA + 540) % 360) - 180) > 0.5) { o = (o + 90) % 360; }
-    ORI.push(o);
-  }
-  // The NARROW STRAIGHT-WALK laser (the exemplar): the SAME emitter as Rung 1
-  // (Straight Walk) — preset 'particle-walk', every walk-character field INHERITED from the same
-  // factory defaults (chargeMode 'positive', dim 0 = 'light' P=1, fundamentalWaveLength 64 → the
-  // λ16 braided transverse ripple) — with ONLY the deliberate loop deltas: (a) a 2px source line
-  // (emissionBoxSide 2 vs r1's default 10), (b) seated on the m10→m1 leg JUST CLEAR of m10 (70·f
-  // past its vertex > the rotated-slab half-diagonal ≈55·f) and aimed along the leg (the longest
-  // clear throw: leg 1.618R ≈ 364·f), (c) a burst of 8/tick, and (d) the DECLARED emission gate.
-  var pS = pos[9], p0 = pos[0];
-  var dx = p0[0] - pS[0], dy = p0[1] - pS[1], L = Math.hypot(dx, dy), ux = dx / L, uy = dy / L;
-  var emit = [Math.round(pS[0] + 70 * f * ux), Math.round(pS[1] + 70 * f * uy)];
-  // EMISSION-CAP GATE as DECLARED DATA (the blackbody-thermostat pattern):
-  // emissionCap + gateCounter compile at CONSTRUCTION into a host tick-fn reading
-  // Wall.getLiveCount on the background counter named 'population' (placed below — the by-name
-  // reference resolves lazily on the first tick). The closed loop has NO sink, so the gate pauses
-  // emission at the cap and resumes below it: the population plateaus. Restart-safe: codegen
-  // captures the two fields and the rebuilt emitter recompiles the gate (no free recipe tick-fn).
-  // is2D:!IS3D opens activeAxes.z in 3D — the volumetric laser.
-  var SRC = {
-    preset: 'particle-walk', is2D: !IS3D, center: emit, orientationDeg: angOf(pS, p0),
-    emissionBoxSide: 2, burstSize: 8,
-    emissionCap: CAP, gateCounter: 'population'
-  };
+  var P = IS3D ? parts : flat2D(parts);
   // THE WORLD — first, then parts: a 3D scene + universe (600x400x600) or a 2D canvas + universe.
-  if (IS3D) { exp.createScene(W, H, WORLD_D, SphereEmitter.worldCfg(SRC)); }
-  else      { exp.createCanvas(W, H, SphereEmitter.worldCfg(SRC)); }
-  exp.declare(parts);
-  exp.addObject('SphereEmitter', SRC);
-  // The ten mirrors at the star vertices — each its own colour + the recolor tag. In 3D each is a
-  // SLAB (z-slab −SD/2..SD/2); in 2D the bag is EMPTY, so the wall is the flat mirror.
-  var ZSLAB = IS3D ? { z: -Math.round(SD / 2), depth: SD } : {};
-  for (var i = 0; i < 10; i++) {
-    var p = pos[i];
-    exp.addObject('Wall', Object.assign(
-      { rect: [Math.round(p[0] - SW / 2), Math.round(p[1] - SH / 2), SW, SH] }, ZSLAB,
-      { collisionBehavior: 'bounce', bounceDirection: 'reflect', orientationDeg: ORI[i],
-        name: 'm' + (i + 1), color: PAL[i], hooks: ['recolor'] }));
-  }
+  if (IS3D) { exp.createScene(W, H, WORLD_D, SphereEmitter.worldCfg(P.source[1])); }
+  else      { exp.createCanvas(W, H, SphereEmitter.worldCfg(P.source[1])); }
+  exp.declare(P);
   if (IS3D) {
     // SCENE Z-COLLIMATOR (without it the z lets things pass through instead of
     // reflecting): the legs' z-braid diffuses lap over lap; any quantum beyond the mirrors'

package/dist/shim/bundle/index.js

@@ -1,121 +1,143 @@
 /* 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) {
+        var tops = names.map(function (n) { return n.split('/')[0]; }).filter(function (t, i, a) { return a.indexOf(t) === i; });
+        if (tops.length === 1 && names.indexOf(tops[0] + '/' + MANIFEST_FILE) !== -1 &&
+            names.every(function (n) { return n.indexOf(tops[0] + '/') === 0; })) {
+            _fail('the archive carries no ' + MANIFEST_FILE + ' at its root — the archive holds the folder `' + tops[0] + '/` rather ' +
+                'than its contents — zip the folder\'s CONTENTS (' + MANIFEST_FILE + ' at the root), as an Export writes it.');
+        }
+        _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).');
 }

package/dist/shim/bundle/indexHtml.js

@@ -1,21 +1,24 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * lib/shim/bundle/indexHtml.js — the standalone `index.html` projection of a
- * recipe bundle.
+ * lib/shim/bundle/indexHtml.js — the generated `index.html` of an exported project folder: the HOST PAGE,
+ * and the ONE writer + ONE parser of the boot bag it carries.
  *
- * A byte-template host that boots the bundle folder as a SERVED PROJECT: `bootProject(mount,
- * { url: './', entry: 'experiment.js' }, { renderState })` from `@descix/frqtl-web@<pin>` on the CDN. The
- * recipe is a sketch module whose imports name the published self-reference (`@descix/frqtl-web/...`);
- * the page's import map carries those rows and the scene doors' row, rendered by the ONE table
- * (`pageImportMapFor(<the pinned dist root>/)`, lib/shim/project/specifiers.js), so the sketch resolves
- * to the SAME module URLs the boot loads. The pinned dist root is the router's one spelling
- * (`cdnDistBaseFor`); the `@<pin>` is the passed-in `sdkVersion` (DERIVED at export time — never a
- * literal here).
+ *   buildIndexHtml({ name, sdkVersion, renderState }) → the page text
+ *   readBootBag(html)                                  → the renderState it carries (the import's one reader)
+ *   BOOT_BAG_ID                                        'frqtl-boot' — the bag's element id
  *
- * DRY: `experiment.js` stays the ONE source of truth — the page links it where it is served rather than
- * embedding a second copy. `renderState` (small, manifest-derived) is embedded inline as JSON. A page
- * opened via `file://` cannot fetch the project: the error says to serve the folder over http.
+ * The page boots the folder it sits in as a SERVED PROJECT: `bootProject(mount, { url: './' }, { renderState })`
+ * from `@descix/frqtl-web@<pin>` on the CDN. `frqtl.json` names the entry (P2a: the linker reads it first), so
+ * the page names no file. The import map is the ONE table's (`pageImportMapFor(<the pinned dist root>/)`,
+ * lib/shim/project/specifiers.js), so a sketch's `@descix/frqtl-web/...` imports resolve to the same module URLs
+ * the boot loads. The pinned dist root is the router's one spelling (`cdnDistBaseFor`); the pin is the passed-in
+ * `sdkVersion` (derived at export time, never a literal here).
+ *
+ * The boot bag — the host's renderState, which never enters frqtl.json or the project identity — is embedded as
+ * `<script type="application/json" id="frqtl-boot">`, `<` escaped so no payload closes the element. The page reads
+ * it from that element; an Import reads it back with readBootBag and drops the page. A page opened via `file://`
+ * cannot fetch the folder: it says to serve the folder over http.
  *
  * Layer 2 (physics): none — pure host projection.
  */
@@ -25,41 +28,38 @@
 import { pageImportMapFor, FRQTL_WEB_BOOT } from '../project/specifiers.js';
 import { cdnDistBaseFor } from '../engine/router.js';
 
+/** The boot bag's element id. */
+export var BOOT_BAG_ID = 'frqtl-boot';
+
+var _BAG_OPEN = '<script type="application/json" id="' + BOOT_BAG_ID + '">';
+var _BAG_CLOSE = '</script>';
+
 function _escapeHtml(s) {
     return String(s == null ? '' : s)
         .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
-/** Safe inline-JSON: escape `<` so a `</script>`-like payload can't break out. */
+/** Safe inline JSON: `<` escaped so a `</script>`-like payload cannot break out. */
 function _inlineJson(obj) {
     return JSON.stringify(obj == null ? null : obj).replace(/</g, '\\u003c');
 }
 
 /**
- * Build the standalone `index.html` for a recipe bundle.
- *
  * @param {object} args
- * @param {string} args.name        — project name (page title).
- * @param {string} args.sdkVersion  — the `@descix/frqtl-web@<pin>` version (REQUIRED).
- * @param {object} [args.renderState] — normalized renderState bag (inlined as JSON;
- *                                     forwarded to bootProject's `{renderState}`).
- * @param {string[]} [args.scripts] — the v4 envelope's setup-factory delta (inlined as JSON): nothing
- *                                     classic is left to load, so the page REFUSES a non-empty list at boot,
- *                                     naming the fix (import the factory in the sketch).
- * @param {string} [args.recipeFile='experiment.js'] — the project's entry file.
- * @returns {string} the complete `index.html`.
+ * @param {string} args.name        — the project's name (frqtl.json `name`; the page title)
+ * @param {string} args.sdkVersion  — the `@descix/frqtl-web@<pin>` version (REQUIRED)
+ * @param {object|null} args.renderState — the normalized boot bag (null boots with the page's defaults)
+ * @returns {string} the complete `index.html`
  */
 export function buildIndexHtml(args) {
     args = args || {};
     if (typeof args.sdkVersion !== 'string' || args.sdkVersion.length === 0) {
-        throw new Error('[bundle/indexHtml] buildIndexHtml: args.sdkVersion is REQUIRED (the CDN pin).');
+        throw new Error('[bundle/indexHtml] buildIndexHtml: args.sdkVersion is REQUIRED (the CDN pin). (FAIL-LOUD.)');
+    }
+    if (typeof args.name !== 'string' || args.name.length === 0) {
+        throw new Error('[bundle/indexHtml] buildIndexHtml: args.name is the project\'s frqtl.json name. (FAIL-LOUD.)');
     }
-    var name = (typeof args.name === 'string' && args.name.length > 0) ? args.name : 'FRQTL Recipe';
-    var recipeFile = (typeof args.recipeFile === 'string' && args.recipeFile.length > 0)
-        ? args.recipeFile : 'experiment.js';
     var importMapJson = _inlineJson(pageImportMapFor(cdnDistBaseFor(args.sdkVersion) + '/'));
-    var renderStateJson = _inlineJson(args.renderState || null);
-    var scriptsJson = _inlineJson(Array.isArray(args.scripts) ? args.scripts : []);
 
     return [
         '<!DOCTYPE html>',
@@ -67,7 +67,7 @@ export function buildIndexHtml(args) {
         '<head>',
         '  <meta charset="UTF-8">',
         '  <meta name="viewport" content="width=device-width, initial-scale=1">',
-        '  <title>' + _escapeHtml(name) + ' — FRQTL</title>',
+        '  <title>' + _escapeHtml(args.name) + ' — FRQTL</title>',
         '  <style>',
         '    html,body{margin:0;height:100%;background:#0b0b0f;color:#ddd;',
         '      font:14px/1.5 ui-sans-serif,system-ui,sans-serif;}',
@@ -80,23 +80,21 @@ export function buildIndexHtml(args) {
         '<body>',
         '  <div id="frqtl-mount"></div>',
         '  <pre id="frqtl-err"></pre>',
+        '  ' + _BAG_OPEN + _inlineJson(args.renderState) + _BAG_CLOSE,
         '  <script type="importmap">' + importMapJson + '</script>',
         '  <script type="module">',
         '    import { bootProject } from ' + JSON.stringify(FRQTL_WEB_BOOT.specifier) + ';',
-        '    const RENDER_STATE = ' + renderStateJson + ';',
-        '    const SCRIPTS = ' + scriptsJson + ';',
+        '    const renderState = JSON.parse(document.getElementById(' + JSON.stringify(BOOT_BAG_ID) + ').textContent);',
         '    const mount = document.getElementById("frqtl-mount");',
         '    const errBox = document.getElementById("frqtl-err");',
         '    function fail(title, detail){',
         '      errBox.style.display = "block";',
         '      errBox.textContent = title + "\\n\\n" + detail;',
         '    }',
-        '    if (SCRIPTS.length > 0) {',
-        '      fail("FRQTL project boot refused", "scripts " + JSON.stringify(SCRIPTS) + " is a classic setup-factory delta, and nothing classic is left to load — import the factory in the sketch (it imports what it uses from @descix/frqtl-web/...).");',
-        '    } else if (location.protocol === "file:") {',
-        '      fail("Serve this folder over http", "e.g. `npx serve` — a file:// page cannot fetch ' + _escapeHtml(recipeFile) + '.");',
+        '    if (location.protocol === "file:") {',
+        '      fail("Serve this folder over http", "e.g. `npx serve` — a file:// page cannot fetch the project files.");',
         '    } else {',
-        '      bootProject(mount, { url: new URL("./", location.href).href, entry: ' + JSON.stringify(recipeFile) + ' }, { renderState: RENDER_STATE })',
+        '      bootProject(mount, { url: new URL("./", location.href).href }, { renderState: renderState })',
         '        .catch((e) => fail("FRQTL project boot failed", String(e && e.stack || e)));',
         '    }',
         '  </script>',
@@ -105,3 +103,32 @@ export function buildIndexHtml(args) {
         ''
     ].join('\n');
 }
+
+/**
+ * THE parser of the boot bag: the renderState an exported page carries (null when it carries none).
+ * THROWS when the page holds no bag element, or more than one, or one that is not JSON.
+ * @param {string} html
+ * @returns {object|null}
+ */
+export function readBootBag(html) {
+    if (typeof html !== 'string') {
+        throw new Error('[bundle/indexHtml] readBootBag(html): the page text (got ' + typeof html + '). (FAIL-LOUD.)');
+    }
+    var at = html.indexOf(_BAG_OPEN);
+    if (at === -1) {
+        throw new Error('[bundle/indexHtml] the index.html carries no boot bag (<script type="application/json" id="' +
+            BOOT_BAG_ID + '">) — it is not the page an Export writes. (FAIL-LOUD.)');
+    }
+    if (html.indexOf(_BAG_OPEN, at + 1) !== -1) {
+        throw new Error('[bundle/indexHtml] the index.html carries two boot bags — an Export writes one. (FAIL-LOUD.)');
+    }
+    var start = at + _BAG_OPEN.length;
+    var end = html.indexOf(_BAG_CLOSE, start);
+    if (end === -1) {
+        throw new Error('[bundle/indexHtml] the boot bag element is not closed. (FAIL-LOUD.)');
+    }
+    try { return JSON.parse(html.slice(start, end)); }
+    catch (e) {
+        throw new Error('[bundle/indexHtml] the boot bag is not valid JSON: ' + ((e && e.message) || e) + '. (FAIL-LOUD.)');
+    }
+}

package/dist/shim/controls/index.js

@@ -101,7 +101,7 @@
 //   action — a MOMENTARY verb: {id,label,action} where `action` is a member of
 //            the closed ACTIONS vocabulary below. Stateless (no `value`, no
 //            read-back) and serializable by NAME, so a declared array of them
-//            round-trips through codegen with no new machinery. Actions are
+//            round-trips through the scene's text with no new machinery. Actions are
 //            deliberately NOT expressed as a `bind` — a bind is a property
 //            read/write pair, and `get()` of "restart" is meaningless.
 //