@descix/frqtl-node 0.6.0-p0.2 → 0.6.0-p4.1

package/dist/shim/project/index.js

@@ -4,16 +4,31 @@
  * project/index.js — the `./project` entry of BOTH packages: the specifier table, the link site and the
  * project identity, re-exported from their owners (this file owns nothing).
  *
- *   FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor    specifiers.js
- *   linkProject                                      link.js
+ *   FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor,
+ *   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', 'linkProject', 'projectIdentity']);
+export const PROJECT_EXPORTS = Object.freeze(['FRQTL_WEB_SPECIFIERS', 'libPathOf', 'importMapFor', 'pageImportMapFor',
+    '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 } from './specifiers.js';
-export { linkProject } from './link.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 }>   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,20 +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 } — 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).
+ *     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' }` —
@@ -40,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) { … }';
@@ -165,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)) {
@@ -214,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.');
     }
 }
 
@@ -240,25 +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, string>}>}
+ * @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') {
@@ -271,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) {
@@ -281,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
@@ -298,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;
@@ -317,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 {
@@ -334,7 +464,10 @@ export async function linkProject(project) {
             urls[p] = m.url;
         }
         const ns = await import(urls[entry]);
-        return { buildExperiment: _entryFunction(ns, entry), files: g.bytes };
+        const held = { files: heldFiles, entry: entry, mint: mint };
+        if (project.bare !== undefined) { held.bare = project.bare; }
+        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(); } }
     }
@@ -357,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 () {} };
 }
 
 /**

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 });
+}

package/dist/shim/project/parts-module.js

@@ -0,0 +1,67 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * parts-module.js — THE mapping from a kind's defining module to the specifier a sketch imports it by.
+ *
+ *   moduleOfKind(from, urls) → '@descix/frqtl-web/parts' | '<project path>' | null
+ *       from   the kind row's `from` (objects/kinds.js registerKind: the defining module's own URL)
+ *       urls   the minted URL of every project file, by path ({ 'parts/MyEmitter.js': 'blob:…' }) — what
+ *              the last linkProject returned (link.js), or null when no project is linked
+ *     A part file of THIS copy of the package (packageRoot() + 'frqtl/parts/<File>.js') is a package part:
+ *     the barrel's specifier. A project file's minted URL is that file's project path. Anything else (an
+ *     internal kind under frqtl/objects/, a module outside the package) has no importable specifier: null.
+ *
+ *   importSpecifierOf(module, entry) → the specifier `entry` writes in an import line for `module`
+ *       a package specifier as it is; a project path relative to the entry's own folder ('./parts/X.js').
+ *
+ * Consumers: the declared census (FrqtlApp: each runner.declared row's `module`) and the parts writer's
+ * one added import line (parts-writer.js, through RecipeContext.toSketch). Nobody else maps a `from`.
+ */
+
+import { packageRoot } from '../../frqtl/compat/package-root.js';
+import { FRQTL_WEB_SPECIFIERS } from './specifiers.js';
+
+const _BARREL = FRQTL_WEB_SPECIFIERS.find(function (r) { return r.libPath === 'frqtl/parts/index.js'; });
+if (!_BARREL) {
+    throw new Error('[parts-module] FRQTL_WEB_SPECIFIERS has no row for the parts barrel (frqtl/parts/index.js). (FAIL-LOUD.)');
+}
+/** The specifier a package part is imported by: the parts barrel's row. */
+export const PARTS_SPECIFIER = _BARREL.specifier;
+
+const _PART_FILE = /^frqtl\/parts\/[A-Za-z_$][\w$]*\.js$/;
+
+/**
+ * @param {string} from — a kind row's `from` URL
+ * @param {Object<string,string>|null} urls — project path → minted URL, from the last link
+ * @returns {string|null}
+ */
+export function moduleOfKind(from, urls) {
+    if (typeof from !== 'string' || !from) {
+        throw new TypeError('[parts-module] moduleOfKind(from, urls): from is the kind row\'s module URL (got ' +
+            JSON.stringify(from) + '). (FAIL-LOUD.)');
+    }
+    const root = packageRoot();
+    if (from.startsWith(root) && _PART_FILE.test(from.slice(root.length))) { return PARTS_SPECIFIER; }
+    if (urls) {
+        for (const p of Object.keys(urls)) { if (urls[p] === from) { return p; } }
+    }
+    return null;
+}
+
+/**
+ * @param {string} module — moduleOfKind's answer (never null here)
+ * @param {string} entry — the importing file's project path (the sketch, 'sketch.js')
+ * @returns {string}
+ */
+export function importSpecifierOf(module, entry) {
+    if (typeof module !== 'string' || !module) {
+        throw new TypeError('[parts-module] importSpecifierOf(module, entry): a module specifier or project path. (FAIL-LOUD.)');
+    }
+    if (module.startsWith('@')) { return module; }
+    const from = entry.split('/');
+    from.pop();
+    const to = module.split('/');
+    while (from.length && to.length > 1 && from[0] === to[0]) { from.shift(); to.shift(); }
+    const up = from.map(function () { return '..'; });
+    return (up.length ? up.join('/') + '/' : './') + to.join('/');
+}