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

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,32 +22,50 @@
  *              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
- * 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.
+ * 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, a part-internal row imported
+ * by any file but a part file (parts/*.js), any other specifier;
+ * 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.
+ *
+ * An error raised while the project EVALUATES (a duplicate kind, a throw at module top) is rethrown with every minted
+ * URL in its message named by its project path and every package file URL by its specifier (_namePaths).
  *
- *   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' }` —
  * sketchProject(text) is that shape's one writer inside the tree (SKETCH_ENTRY its entry path).
  */
 
-import { libPathOf, FRQTL_WEB_PACKAGE, FRQTL_WEB_SPECIFIERS } from './specifiers.js';
+import { libPathOf, tierOf, specifierOfLibPath, 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) { … }';
@@ -116,6 +138,14 @@ function _publishedList() {
     return FRQTL_WEB_SPECIFIERS.map(function (r) { return r.specifier + (r.specifier.endsWith('/') ? '<file>' : ''); }).join(', ');
 }
 
+/** The tier a forked part's internals carry (specifiers.js SPECIFIER_TIERS). */
+const PART_INTERNAL = 'part-internal';
+
+/** A project file under parts/ (a part file: the only importer of a part-internal module). */
+function _isPartFile(p) {
+    return /^parts\/[^/]+\.m?js$/.test(p);
+}
+
 function _isPackage(spec) {
     return spec === FRQTL_WEB_PACKAGE || spec.startsWith(FRQTL_WEB_PACKAGE + '/');
 }
@@ -169,12 +199,21 @@ 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)) {
                     _fail('"' + p + '" imports "' + imp.spec + '" — not a published specifier; the table ' +
                         '(lib/shim/project/specifiers.js FRQTL_WEB_SPECIFIERS) offers: ' + _publishedList() + '.');
                 }
+                if (tierOf(imp.spec) === PART_INTERNAL && !_isPartFile(p)) {
+                    _fail('"' + p + '" imports "' + imp.spec + '" — a part-internal module is imported by a part file ' +
+                        '(parts/*.js), never by a sketch — a sketch imports parts by @descix/frqtl-web/parts.');
+                }
                 list.push(Object.assign({ kind: 'package' }, imp));
             } else {
                 _fail('"' + p + '" imports "' + imp.spec + '" — a project file imports another project file by a ' +
@@ -218,17 +257,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); });
+}
+
 /**
- * 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.
+ * 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;
+}
+
+/**
+ * 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 +312,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 +402,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 +413,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 +433,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 +453,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 {
@@ -338,15 +479,40 @@ export async function linkProject(project) {
             minted.push(m);
             urls[p] = m.url;
         }
-        const ns = await import(urls[entry]);
-        const held = { files: g.files, entry: entry, mint: mint };
+        let ns;
+        try { ns = await import(urls[entry]); }
+        catch (err) { throw _namePaths(err, urls); }
+        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(); } }
     }
 }
 
+/**
+ * An error raised while the project evaluates, with every minted URL in its message replaced by the project path
+ * it names (byte-identical files share one minted URL: all their paths), and every package file URL by its
+ * specifier — so a duplicate kind reads "kind "Wall" is already registered by @descix/frqtl-web/parts/Wall.js;
+ * parts/Wall2.js registers it again". The SAME error is rethrown (its stack kept): enrichment, never a catch.
+ */
+function _namePaths(err, urls) {
+    if (!err || typeof err.message !== 'string') { return err; }
+    const byUrl = new Map();
+    for (const p of Object.keys(urls)) { byUrl.set(urls[p], (byUrl.get(urls[p]) || []).concat(p)); }
+    let msg = err.message;
+    for (const [url, paths] of [...byUrl.entries()].sort(function (a, b) { return b[0].length - a[0].length; })) {
+        msg = msg.split(url).join(paths.join(' (= ') + (paths.length > 1 ? ', byte-identical)' : ''));
+    }
+    const root = packageRoot();
+    msg = msg.replace(new RegExp(root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '([^\\s;,)\'"]+)', 'g'), function (m, lp) {
+        return specifierOfLibPath(lp) || m;
+    });
+    try { err.message = msg; } catch (_) { /* a frozen error keeps its own text */ }
+    return err;
+}
+
 /** The entry path of a one-string sketch held as a project. */
 export const SKETCH_ENTRY = 'sketch.js';
 
@@ -364,10 +530,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 () {} };
 }
 
 /**

package/dist/shim/project/manifest.js

@@ -0,0 +1,151 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * manifest.js — THE owner of `frqtl.json`, the one file a host reads first in a project folder.
+ *
+ *   MANIFEST_FILE                 'frqtl.json' — its path at the project root
+ *   MANIFEST_KEYS                 the typed key table, in the order a manifest is written
+ *   normalizeManifest(partial)    → the full bag (frozen, keys in MANIFEST_KEYS order; an absent optional key
+ *                                   stays absent). THROWS on an unknown key, a missing required key, a value
+ *                                   of the wrong type or outside its row's rule — each naming the key.
+ *   parseManifest(text)           strict JSON → normalizeManifest. Any valid JSON formatting reads.
+ *   serializeManifest(bag)        JSON.stringify(the normalized bag, null, 2) + '\n' — THE writer of every
+ *                                   system-made manifest (one-file Import, Save As, projectOf).
+ *   manifestFor({ name, entry })  the one constructor of a fresh bag: kind 'scene', no version.
+ *
+ * A manifest holds what the folder IS — its name, its kind, its entry module, the author's own version
+ * string — and nothing about how a host boots it: display, seed, camera and render rows are the HOST's
+ * renderState, kept beside the folder, never in this file. `version` is never interpreted.
+ *
+ * Consumers ferry the normalized bag; none re-lists these keys (gate: lib/shim/project/test/manifest.test.mjs,
+ * driven off MANIFEST_KEYS).
+ */
+
+import { checkProjectPath } from './identity.js';
+
+/** The manifest's path at the project root. */
+export const MANIFEST_FILE = 'frqtl.json';
+
+function _fail(msg) {
+    throw new Error('[' + MANIFEST_FILE + '] ' + msg + ' (FAIL-LOUD.)');
+}
+
+function _keyList() {
+    return MANIFEST_KEYS.map(function (r) { return r.key; }).join(', ');
+}
+
+/**
+ * THE typed key table. Each row: `key`; `type` (the JSON type of its value); `required`; `rule` (a
+ * sentence naming what a legal value is); `check(value)` — throws naming the key when the value breaks
+ * the rule (the type is checked first, from `type`).
+ * @type {ReadonlyArray<{key: string, type: 'string', required: boolean, rule: string, check: function(*): void}>}
+ */
+export const MANIFEST_KEYS = Object.freeze([
+    Object.freeze({
+        key: 'name', type: 'string', required: true,
+        rule: 'a non-empty string — the project\'s name',
+        check: function (v) {
+            if (v.length === 0) { _fail('"name" is empty — a project\'s name is a non-empty string.'); }
+        }
+    }),
+    Object.freeze({
+        key: 'kind', type: 'string', required: true,
+        rule: '"scene" (a notebook project, "notebook", comes with P5)',
+        check: function (v) {
+            if (v === 'notebook') {
+                _fail('"kind": "notebook" — a notebook project comes with P5 (notebooks on projects); a project ' +
+                    'today is "kind": "scene".');
+            }
+            if (v !== 'scene') {
+                _fail('"kind": ' + JSON.stringify(v) + ' is not a project kind — "scene", or "notebook" (P5).');
+            }
+        }
+    }),
+    Object.freeze({
+        key: 'entry', type: 'string', required: true,
+        rule: 'a root-relative project path ending ".js" — the module whose default export is buildExperiment(exp)',
+        check: function (v) {
+            try { checkProjectPath(v); }
+            catch (e) { _fail('"entry": ' + String((e && e.message) || e)); }
+            if (!v.endsWith('.js')) {
+                _fail('"entry": ' + JSON.stringify(v) + ' does not end ".js" — the entry is the project module whose ' +
+                    'default export is buildExperiment(exp).');
+            }
+        }
+    }),
+    Object.freeze({
+        key: 'version', type: 'string', required: false,
+        rule: 'the author\'s own string, never interpreted (optional)',
+        check: function () {}
+    })
+]);
+
+/**
+ * @param {object} partial — the manifest's keys (an absent optional key, or one whose value is undefined, is absent)
+ * @returns {Readonly<{name: string, kind: 'scene', entry: string, version?: string}>}
+ */
+export function normalizeManifest(partial) {
+    if (!partial || typeof partial !== 'object' || Array.isArray(partial)) {
+        _fail('a manifest is an object { ' + _keyList() + ' } (got ' +
+            (Array.isArray(partial) ? 'an array' : partial === null ? 'null' : typeof partial) + ').');
+    }
+    const known = MANIFEST_KEYS.map(function (r) { return r.key; });
+    const unknown = Object.keys(partial).filter(function (k) { return known.indexOf(k) === -1; });
+    if (unknown.length) {
+        _fail('unknown key' + (unknown.length > 1 ? 's ' : ' ') + unknown.map(function (k) { return JSON.stringify(k); }).join(', ') +
+            ' — a manifest holds exactly MANIFEST_KEYS (lib/shim/project/manifest.js): ' + _keyList() +
+            '. How a host boots the folder (display, seed, camera, render rows) is its renderState, kept beside the folder.');
+    }
+    const bag = {};
+    for (const row of MANIFEST_KEYS) {
+        const v = partial[row.key];
+        if (v === undefined) {
+            if (row.required) { _fail('"' + row.key + '" is REQUIRED — ' + row.rule + '.'); }
+            continue;
+        }
+        if (typeof v !== row.type) {
+            _fail('"' + row.key + '" is ' + (v === null ? 'null' : typeof v) + ' — ' + row.rule + '.');
+        }
+        row.check(v);
+        bag[row.key] = v;
+    }
+    return Object.freeze(bag);
+}
+
+/**
+ * @param {string} text — the bytes of frqtl.json, decoded
+ * @returns {Readonly<object>} the normalized bag
+ */
+export function parseManifest(text) {
+    if (typeof text !== 'string') {
+        _fail('parseManifest(text): the text of ' + MANIFEST_FILE + ' (got ' + typeof text + ').');
+    }
+    let raw;
+    try { raw = JSON.parse(text); }
+    catch (e) { _fail('is not valid JSON: ' + String((e && e.message) || e) + '.'); }
+    return normalizeManifest(raw);
+}
+
+/**
+ * @param {object} bag — normalized here first, so the writer never writes a manifest its reader refuses
+ * @returns {string}
+ */
+export function serializeManifest(bag) {
+    return JSON.stringify(normalizeManifest(bag), null, 2) + '\n';
+}
+
+/**
+ * @param {{name: string, entry: string}} spec
+ * @returns {Readonly<object>} the normalized bag { name, kind: 'scene', entry }
+ */
+export function manifestFor(spec) {
+    if (!spec || typeof spec !== 'object') {
+        _fail('manifestFor({ name, entry }) (got ' + (spec === null ? 'null' : typeof spec) + ').');
+    }
+    const stray = Object.keys(spec).filter(function (k) { return k !== 'name' && k !== 'entry'; });
+    if (stray.length) {
+        _fail('manifestFor({ name, entry }) takes the name and the entry only (got ' + stray.join(', ') +
+            ') — a fresh project is kind "scene" with no version; any other bag goes through normalizeManifest.');
+    }
+    return normalizeManifest({ name: spec.name, kind: 'scene', entry: spec.entry });
+}