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

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/engine/router.js

@@ -148,7 +148,7 @@ var DIST_PROFILE = buildDistProfile('../..');
 // lib/shim/engine/test/router.test.mjs asserts them against the two
 // package.json#version fields so a forgotten bump fails `make verify`, not a
 // silent stale-CDN-URL bug.
-var CDN_SDK_VERSION = '0.6.0-p1.1';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
+var CDN_SDK_VERSION = '0.6.0-p4.1';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
 var CDN_MATH_SDK_VERSION = '0.3.2';  // sdk/egpt-math-sdk/package.json#version — bound by router.test.mjs; bumped with each npm publish
 
 /**
@@ -507,7 +507,7 @@ var _assertProfileParity = (function () {
  * // CDN mode (static hosting — the artifact host shell has no server, no page anchor):
  * const cdnRouter = engineRouter({ mode: 'cdn', engine: 'wasm' });
  * console.log(cdnRouter.resolve('compat/engine.js'));
- * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p1.1/dist/frqtl/compat/engine.js'
+ * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p4.1/dist/frqtl/compat/engine.js'
  *
  * // CDN mode, self-hosted: a copy of dist/ served from the consumer's own origin:
  * const selfHosted = engineRouter({ mode: 'cdn', engine: 'wasm', base: 'https://example.org/vendor/frqtl-web/dist' });

package/dist/shim/index.js

@@ -22,7 +22,7 @@ export { WALKTHROUGH, walkthroughIs3D, walkthroughModes, walkthroughGroup,
          walkthroughById,
          FIRST_CONTACT_WALKTHROUGH_ID,
          defaultWalkthroughModeId, effectiveRenderState } from './registry/walkthrough.js';
-export { loadSceneSource, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
+export { projectOf, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
 // The host-side experiment-iframe guard (the false-200 trap). Exported from the
 // barrel so every host that frames an experiment page (lib/features/ide's GYM)
 // asserts against the SAME contract.

package/dist/shim/notebook/format.js

@@ -99,7 +99,7 @@ export const PROSE_CELL_TYPES = Object.freeze(['markdown']);
  *       e.g. `setupDoubleSlit`). Absent → `'factory'`, so every existing notebook is
  *       byte-identical.
  *     - `'recipe'`: the module's DEFAULT export is a `buildExperiment(exp)` RECIPE (a single
- *       RecipeContext arg — the sketch form codegen / `buildFrqnb` / the scene files
+ *       RecipeContext arg — the sketch form the scene files
  *       write). The shim builds a
  *       `frqtl.RecipeContext` and runs `exp.build(buildExperiment)` (the canonical
  *       co-init call + `addObject()` recipe path), NOT the factory signature.

package/dist/shim/notebook/store.js

@@ -5,9 +5,8 @@
  *
  * Thin CRUD helpers that persist a serialized <frqtl-notebook> document on top
  * of any StorageProvider (lib/shim/storage/index.js) using the "notebooks"
- * namespace.  Mirrors the shape of lib/shim/storage/modules.js and
- * lib/shim/storage/projects.js — ONE persistent-store pattern across Studio
- * projects, Studio modules, and Notebooks.
+ * namespace, through the shared namespace-CRUD factory
+ * (lib/shim/storage/make-namespace-store.js).
  *
  * ── Why this lives in lib/shim ──────────────────────────────────────────────
  *

package/dist/shim/project/index.js

@@ -5,17 +5,30 @@
  * project identity, re-exported from their owners (this file owns nothing).
  *
  *   FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor,
- *   pageImportMapFor                                 specifiers.js
+ *   pageImportMapFor, FRQTL_WEB_HOST_SPECIFIERS      specifiers.js (the host rows: a host page reads the
+ *                                                    dist root from its own map through them)
  *   linkProject, sketchProject, SKETCH_ENTRY         link.js
  *   projectIdentity                                  identity.js
+ *   MANIFEST_FILE, MANIFEST_KEYS, normalizeManifest,
+ *   parseManifest, serializeManifest, manifestFor    manifest.js (THE owner of frqtl.json)
+ *   RECORD_FILES, RECORD_KEYS, CHANGE_KEYS, OPS, BY,
+ *   CLIP_SECONDS, CLIP_NAME, clipName, jsonText,
+ *   recordFolderFaults                               record-format.js (THE owner of the Record folder's shape)
  *
  * PROJECT_EXPORTS is this entry's export list; a conformance test holds the module's exports equal to
  * it, and the package gate holds it equal across @descix/frqtl-web and @descix/frqtl-node.
  */
 
 export const PROJECT_EXPORTS = Object.freeze(['FRQTL_WEB_SPECIFIERS', 'libPathOf', 'importMapFor', 'pageImportMapFor',
-    'linkProject', 'sketchProject', 'SKETCH_ENTRY', 'projectIdentity']);
+    'FRQTL_WEB_HOST_SPECIFIERS',
+    'linkProject', 'sketchProject', 'SKETCH_ENTRY', 'projectIdentity',
+    'MANIFEST_FILE', 'MANIFEST_KEYS', 'normalizeManifest', 'parseManifest', 'serializeManifest', 'manifestFor',
+    'RECORD_FILES', 'RECORD_KEYS', 'CHANGE_KEYS', 'OPS', 'BY', 'CLIP_SECONDS', 'CLIP_NAME', 'clipName', 'jsonText',
+    'recordFolderFaults']);
 
-export { FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor, pageImportMapFor } from './specifiers.js';
+export { FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor, pageImportMapFor, FRQTL_WEB_HOST_SPECIFIERS } from './specifiers.js';
 export { linkProject, sketchProject, SKETCH_ENTRY } from './link.js';
 export { projectIdentity } from './identity.js';
+export { MANIFEST_FILE, MANIFEST_KEYS, normalizeManifest, parseManifest, serializeManifest, manifestFor } from './manifest.js';
+export { RECORD_FILES, RECORD_KEYS, CHANGE_KEYS, OPS, BY, CLIP_SECONDS, CLIP_NAME, clipName, jsonText,
+    recordFolderFaults } from './record-format.js';

package/dist/shim/project/link.js

@@ -1,15 +1,19 @@
 /* Copyright 2023-2026 by Essam Abadir */
 
 /**
- * link.js — THE link site: a project (one or more ES module files held as text, or a served folder)
- * becomes imported modules, and its entry's default export is the scene.
+ * link.js — THE link site: a project (a folder of files held as text, or a served folder) becomes imported
+ * modules, and its entry's default export is the scene.
  *
- *   linkProject(project) → Promise<{ buildExperiment, files, urls, project }>   files: { path: Uint8Array } — the bytes linked
- *     project = { files: { 'sketch.js': text, 'parts/X.js': text, … }, entry, mint, bare? }
- *             | { url: '<served folder>/', entry, mint?, bare? }
+ *   linkProject(project) → Promise<{ buildExperiment, module, manifest, files, urls, project }>   THE result contract
+ *     project = { files: { 'frqtl.json': text, 'sketch.js': text, 'parts/X.js': text, 'README.md': text, … }, entry?, mint, bare? }
+ *             | { url: '<served folder>/', entry?, mint, bare? }
  *       url    absolute, or relative to the document's base URL in a page ('./'); ends in "/"
- *       entry  REQUIRED — the root-relative path of the file whose default export is
- *              `function buildExperiment(exp)`
+ *       entry  the root-relative path of the module whose default export is `function buildExperiment(exp)`.
+ *              It comes from frqtl.json (manifest.js, the one owner) when the project carries one; an `entry`
+ *              given beside a manifest must EQUAL manifest.entry, or the link REJECTS naming both. With neither
+ *              a manifest nor an entry the link REJECTS naming frqtl.json. A served folder's
+ *              `<url>frqtl.json` is fetched first; a 404 there is allowed only when `entry` is given (then
+ *              there is no manifest).
  *       mint   REQUIRED — the host's (text, path) → { url, release? }: `blobMint` in a page, `dataMint` in
  *              node. Hosts differ ONLY here. A served folder is minted too: each file is fetched ONCE, as
  *              bytes; those bytes are the identity, and the same bytes, decoded once (UTF-8, fatal), are
@@ -18,24 +22,37 @@
  *              lib-identity path (specifiers.js libPathOf) under THIS copy's package root
  *              (compat/package-root.js), so a project links against the very modules its boot loaded.
  *              A host whose modules are not served one file per URL (frqtl-web.min.js) passes its own.
- *     resolves { buildExperiment, files, urls, project } — files is the project's BYTES by path (fetched, for a
- *       served folder; the UTF-8 encoding of each text, for a file map), the input of projectIdentity
- *       (identity.js); urls is each file's minted URL by path (a forked part registers its kind `from` that
- *       URL — lib/shim/project/parts-module.js maps it back to the path); project is the linked project as
- *       TEXT — { files: { path: text }, entry, mint, bare? } — what a facade holds and re-links
- *       (RecipeContext.build(linked)). A served folder's project is its decoded files.
+ *     resolves
+ *       buildExperiment  the entry's default export
+ *       module           the entry module's namespace (its `parts` block is `module.parts`)
+ *       manifest         frqtl.json's normalized bag (manifest.js normalizeManifest), or null when the project
+ *                        was linked by `entry` alone
+ *       files            THE LINKED SET's bytes by path — frqtl.json and every module file (linkedFiles): fetched,
+ *                        for a served folder; the UTF-8 encoding of each text, for a file map. The input of
+ *                        projectIdentity (identity.js).
+ *       urls             each module's minted URL by path (a forked part registers its kind `from` that URL —
+ *                        lib/shim/project/parts-module.js maps it back to the path)
+ *       project          the linked project as TEXT — { files: { path: text }, entry, mint, bare? } — what a facade
+ *                        holds and re-links (RecipeContext.build(linked)). For a file map its files are EVERY file
+ *                        given (frqtl.json and README.md included), so a facade's sketch is the whole folder; for a
+ *                        served folder they are the files fetched, decoded.
  *
- * In a project, a file imports another project file by a RELATIVE specifier, and the package by
+ * THE LINKED SET (linkedFiles(files) → the sub-map): frqtl.json plus every MODULE file — a path ending ".js" or
+ * ".mjs" — a pure path function of the folder, so every host hashes one set. Each module file must be reached
+ * from the entry; any other file (README.md, notes.txt) travels with the folder, unlinked and unhashed.
+ *
+ * In a project, a module imports another project module by a RELATIVE specifier, and the package by
  * `@descix/frqtl-web/...`; nothing else. Relative specifiers are rewritten to the minted URLs of the files
  * they name, in topological order (a file is minted after everything it imports). REFUSED before anything
  * is minted, each naming the file, the specifier and the reason: a relative specifier that climbs out of
- * the root (package internals have no public specifier), one that names no project file (never an HTTP
+ * the root (package internals have no public specifier), one that names a non-module path (not ".js" /
+ * ".mjs": a data file, an extensionless name, frqtl.json), one that names no project file (never an HTTP
  * sibling), a @descix/frqtl-web specifier that is not a row of FRQTL_WEB_SPECIFIERS, any other specifier;
- * an import cycle among project files; a file-map entry the entry never reaches (a project is exactly the
- * module graph its entry reaches, so every host hashes one set); a served file that is not UTF-8; a missing or non-function
- * default export of the entry, a missing entry, an empty project. Every argument error REJECTS.
+ * an import cycle among project files; a module file the entry never reaches; an invalid frqtl.json; a
+ * served file that is not UTF-8; a missing or non-function default export of the entry, a missing entry,
+ * an empty project. Every argument error REJECTS.
  *
- *   blobMint(text) → { url, release() }   a `blob:` module URL (a page)
+ *   blobMint(text) → { url, release() }   a `blob:` module URL (a page), one per byte-identical text
  *   dataMint(text) → { url, release() }   a `data:` module URL (node)
  *
  * A one-string sketch is the one-file project: `{ files: { 'sketch.js': text }, entry: 'sketch.js' }` —
@@ -44,6 +61,7 @@
 
 import { libPathOf, FRQTL_WEB_PACKAGE, FRQTL_WEB_SPECIFIERS } from './specifiers.js';
 import { checkProjectPath, projectBytes } from './identity.js';
+import { MANIFEST_FILE, parseManifest } from './manifest.js';
 import { packageRoot } from '../../frqtl/compat/package-root.js';
 
 const SKETCH_FORM = 'export default function buildExperiment(exp) { … }';
@@ -169,6 +187,11 @@ async function _walk(entry, sourceOf) {
                     _fail('"' + p + '" imports "' + imp.spec + '" — outside the project; package internals have no ' +
                         'public specifier (a project file imports the package by a @descix/frqtl-web/... row).');
                 }
+                if (!isModulePath(target)) {
+                    _fail('"' + p + '" imports "' + imp.spec + '" (' + target + '), which is not a module path — a project ' +
+                        'imports only its module files (' + MODULE_EXTENSIONS.join(' / ') + '); any other file of the folder ' +
+                        '(a data file, an extensionless name, ' + MANIFEST_FILE + ') travels with it unlinked.');
+                }
                 list.push(Object.assign({ kind: 'file', target: target }, imp));
             } else if (_isPackage(imp.spec)) {
                 if (!_isPublished(imp.spec)) {
@@ -218,17 +241,46 @@ function _rewrite(text, list, urlOf) {
     return out;
 }
 
+/** The extensions of a project MODULE file; every other path of a folder is a non-module file. */
+const MODULE_EXTENSIONS = Object.freeze(['.js', '.mjs']);
+
+/** A project path names a module file (".js" / ".mjs"). */
+function isModulePath(p) {
+    return MODULE_EXTENSIONS.some(function (x) { return p.endsWith(x); });
+}
+
+/**
+ * THE LINKED SET of a folder: the sub-map of `files` holding frqtl.json and every module file (".js" /
+ * ".mjs"), values as given (text or bytes). A pure function of the paths, so every host — a page door,
+ * hosted eyes in node — hashes one set; the link refuses a folder whose module files the entry does not
+ * all reach, so for a folder that links this IS the set linked. Any other file passes through unhashed.
+ * @param {Object<string, *>} files
+ * @returns {Object<string, *>}
+ */
+export function linkedFiles(files) {
+    if (!files || typeof files !== 'object') {
+        _fail('linkedFiles(files): files is the map { path: text | bytes } (got ' + (files === null ? 'null' : typeof files) + ').');
+    }
+    const out = {};
+    for (const p of Object.keys(files)) {
+        if (p === MANIFEST_FILE || isModulePath(p)) { out[p] = files[p]; }
+    }
+    return out;
+}
+
 /**
- * A project is EXACTLY the module graph its entry reaches, so every host hashes one set: a served folder is
- * that set by construction, and a file map may hold nothing else. REFUSES a file-map entry the walk did not
- * reach, naming it.
+ * Every module file of a file map is reached from the entry (a project's modules are exactly the graph its
+ * entry imports, so linkedFiles is the set linked). REFUSES an unreached one, naming it.
  */
 function _refuseUnreached(project, g) {
     if (project.files === undefined) { return; }
-    const unused = Object.keys(project.files).filter(function (p) { return !Object.prototype.hasOwnProperty.call(g.files, p); });
+    const unused = Object.keys(linkedFiles(project.files)).filter(function (p) {
+        return p !== MANIFEST_FILE && !Object.prototype.hasOwnProperty.call(g.files, p);
+    });
     if (unused.length) {
-        _fail('unused project file "' + unused[0] + '" — a project holds the files its entry imports' +
-            (unused.length > 1 ? ' (also unused: ' + unused.slice(1).join(', ') + ')' : '') + '.');
+        _fail('unused project file "' + unused[0] + '" — a project holds the module files its entry imports' +
+            (unused.length > 1 ? ' (also unused: ' + unused.slice(1).join(', ') + ')' : '') + '; a non-module file ' +
+            '(README.md) travels with the folder unlinked.');
     }
 }
 
@@ -244,26 +296,84 @@ function _entryFunction(ns, entry) {
     return ns.default;
 }
 
+/** The served folder's frqtl.json: { manifest, text, bytes }, or null on a 404. One fetch. */
+async function _fetchManifest(base) {
+    const u = new URL(MANIFEST_FILE, base).href;
+    let res;
+    try { res = await fetch(u); }
+    catch (e) { _fail('fetching "' + MANIFEST_FILE + '" (' + u + ') failed: ' + String((e && e.message) || e) + '.'); }
+    if (res.status === 404) { return null; }
+    if (!res.ok) { _fail('"' + MANIFEST_FILE + '" is not served at ' + u + ' (HTTP ' + res.status + ').'); }
+    const raw = new Uint8Array(await res.arrayBuffer());
+    let text;
+    try { text = _UTF8.decode(raw); }
+    catch (e) { _fail('"' + MANIFEST_FILE + '" is not valid UTF-8 (' + u + ').'); }
+    let manifest;
+    try { manifest = parseManifest(text); }
+    catch (e) {
+        const type = res.headers && typeof res.headers.get === 'function' ? res.headers.get('content-type') : null;
+        _fail('the served ' + MANIFEST_FILE + ' (' + u + ', HTTP ' + res.status + (type ? ', ' + type : '') + ') is refused: ' +
+            String((e && e.message) || e) + ' — a host that answers a missing file with a page serves no 404, so a folder ' +
+            'there carries its own ' + MANIFEST_FILE + '.');
+    }
+    return { manifest: manifest, text: text, bytes: raw };
+}
+
+/**
+ * The entry: frqtl.json's when the project carries one (a given `entry` must equal it), else the given one.
+ * @returns {string}
+ */
+function _entryOf(given, manifest) {
+    if (manifest) {
+        if (given !== undefined && given !== manifest.entry) {
+            _fail('entryOf: `entry` "' + given + '" disagrees with ' + MANIFEST_FILE + '\'s "entry" "' + manifest.entry +
+                '" — the manifest names the entry; drop `entry`, or make the two equal.');
+        }
+        return manifest.entry;
+    }
+    if (given === undefined) {
+        _fail('entryOf: no entry — the project carries no ' + MANIFEST_FILE + ' (manifest.js; manifestFor({ name, entry }) ' +
+            'writes one) and no `entry` was given (a one-string sketch: { files: { "sketch.js": text }, entry: "sketch.js" }).');
+    }
+    return given;
+}
+
+/**
+ * entryOf(files, given) → the project's entry path — THE entry rule (every host asks it, never a copy): the entry
+ * frqtl.json names (read through its owner, parseManifest) when `files` carries one, and a `given` entry must equal
+ * it; else `given`. THROWS naming the rule: a disagreeing entry, no frqtl.json and no entry, an invalid frqtl.json.
+ * Not on PROJECT_EXPORTS (like linkedFiles).
+ * @param {Object<string, string>} files
+ * @param {string} [given]
+ * @returns {string}
+ */
+export function entryOf(files, given) {
+    const has = files && Object.prototype.hasOwnProperty.call(files, MANIFEST_FILE);
+    return _entryOf(given, has ? parseManifest(files[MANIFEST_FILE]) : null);
+}
+
 /**
  * @param {object} project — see the file header
- * @returns {Promise<{buildExperiment: function, files: Object<string, Uint8Array>, urls: Object<string, string>,
- *   project: {files: Object<string, string>, entry: string, mint: function, bare?: function}}>}
+ * @returns {Promise<{buildExperiment: function, module: object, manifest: ?object, files: Object<string, Uint8Array>,
+ *   urls: Object<string, string>, project: {files: Object<string, string>, entry: string, mint: function, bare?: function}}>}
  */
 export async function linkProject(project) {
     if (!project || typeof project !== 'object') {
-        _fail('linkProject(project): project is { files, entry, mint } or { url, entry } (got ' + typeof project + ').');
+        _fail('linkProject(project): project is { files, mint } or { url, mint } (+ `entry` when it carries no ' +
+            MANIFEST_FILE + ') (got ' + typeof project + ').');
     }
-    const entry = project.entry;
-    if (typeof entry !== 'string' || !entry) {
-        _fail('linkProject: `entry` is REQUIRED — the path of the file whose default export is the scene ' +
-            '(a one-string sketch: { files: { "sketch.js": text }, entry: "sketch.js" }).');
+    const given = project.entry;
+    if (given !== undefined) {
+        if (typeof given !== 'string' || !given) {
+            _fail('linkProject: `entry` is the root-relative path of the module whose default export is the scene (got ' +
+                JSON.stringify(given) + ').');
+        }
+        checkProjectPath(given);
     }
-    checkProjectPath(entry);
     const hasFiles = project.files !== undefined;
     const hasUrl = project.url !== undefined;
     if (hasFiles === hasUrl) {
-        _fail('linkProject: a project is EITHER { files, entry } OR { url, entry } (got ' +
-            (hasFiles ? 'both' : 'neither') + ').');
+        _fail('linkProject: a project is EITHER { files } OR { url } (got ' + (hasFiles ? 'both' : 'neither') + ').');
     }
     const mint = project.mint;
     if (typeof mint !== 'function') {
@@ -276,7 +386,8 @@ export async function linkProject(project) {
     }
 
     let sourceOf;
-    let base = null;
+    let found = null;   // frqtl.json: { manifest, text, bytes }
+    let encoded = null;
     if (hasFiles) {
         const files = project.files;
         if (!files || typeof files !== 'object' || Object.keys(files).length === 0) {
@@ -286,7 +397,10 @@ export async function linkProject(project) {
             checkProjectPath(p);
             if (typeof files[p] !== 'string') { _fail('linkProject: file "' + p + '" is not text.'); }
         }
-        const encoded = projectBytes(files);
+        encoded = projectBytes(files);
+        if (Object.prototype.hasOwnProperty.call(files, MANIFEST_FILE)) {
+            found = { manifest: parseManifest(files[MANIFEST_FILE]), text: files[MANIFEST_FILE], bytes: encoded[MANIFEST_FILE] };
+        }
         sourceOf = async function (p, from, spec) {
             if (!Object.prototype.hasOwnProperty.call(files, p)) {
                 _fail(from === undefined
@@ -303,7 +417,8 @@ export async function linkProject(project) {
         if (typeof project.url !== 'string' || !project.url.endsWith('/')) {
             _fail('linkProject({ url }): url is the served project folder, ending in "/" (got ' + JSON.stringify(project.url) + ').');
         }
-        base = _folderUrl(project.url);
+        const base = _folderUrl(project.url);
+        found = await _fetchManifest(base);
         sourceOf = async function (p, from, spec) {
             const u = new URL(p, base).href;
             let res;
@@ -322,10 +437,20 @@ export async function linkProject(project) {
             return { text: text, bytes: raw };
         };
     }
+    const manifest = found ? found.manifest : null;
+    const entry = _entryOf(given, manifest);
+    if (!isModulePath(entry)) {
+        _fail('linkProject: the entry "' + entry + '" is not a module path (' + MODULE_EXTENSIONS.join(' / ') + ').');
+    }
 
     const g = await _walk(entry, sourceOf);
     _refuseUnreached(project, g);
 
+    // The linked set's bytes: a file map's through linkedFiles (its owner); a served folder's are what was fetched.
+    const bytes = hasFiles ? linkedFiles(encoded) : linkedFiles(Object.assign(found ? { [MANIFEST_FILE]: found.bytes } : {}, g.bytes));
+    const heldFiles = hasFiles ? Object.assign({}, project.files)
+        : Object.assign(found ? { [MANIFEST_FILE]: found.text } : {}, g.files);
+
     const urls = {};
     const minted = [];
     try {
@@ -339,9 +464,10 @@ export async function linkProject(project) {
             urls[p] = m.url;
         }
         const ns = await import(urls[entry]);
-        const held = { files: g.files, entry: entry, mint: mint };
+        const held = { files: heldFiles, entry: entry, mint: mint };
         if (project.bare !== undefined) { held.bare = project.bare; }
-        return { buildExperiment: _entryFunction(ns, entry), files: g.bytes, urls: Object.assign({}, urls), project: held };
+        return { buildExperiment: _entryFunction(ns, entry), module: ns, manifest: manifest, files: bytes,
+            urls: Object.assign({}, urls), project: held };
     } finally {
         for (const m of minted) { if (typeof m.release === 'function') { m.release(); } }
     }
@@ -364,10 +490,22 @@ export function sketchProject(text) {
     return { files: files, entry: SKETCH_ENTRY };
 }
 
-/** A `blob:` module URL for `text` (a page). */
+/** One `blob:` URL per byte-identical module text in this page (blobMint's memo). */
+const _blobUrls = new Map();
+
+/**
+ * A `blob:` module URL for `text` (a page). MEMOIZED by text for the page's lifetime: a re-link of the same text
+ * (restart, a Record's parts reads) gets the same URL, so the ESM cache keeps ONE instance and a project's own part
+ * file registers its kind once — node's `data:` URLs are content-addressed the same way. `release()` is a no-op:
+ * the URL stays valid for the next link of those bytes.
+ */
 export function blobMint(text) {
-    const url = URL.createObjectURL(new Blob([text], { type: 'text/javascript' }));
-    return { url: url, release: function () { URL.revokeObjectURL(url); } };
+    let url = _blobUrls.get(text);
+    if (!url) {
+        url = URL.createObjectURL(new Blob([text], { type: 'text/javascript' }));
+        _blobUrls.set(text, url);
+    }
+    return { url: url, release: function () {} };
 }
 
 /**