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

package/dist/shim/host/host-view.js

@@ -0,0 +1,228 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * host-view.js — the ONE declarer of the DeSciX host view for an app DOCUMENT.
+ *
+ * A DeSciX shell hosts the app beside its chat (SplitView, its default) unless the app asks for
+ * another view. This module asks — once, through the app-side SDK (`DeSciXAppSDK.js`, vendored
+ * by the publisher beside the page) — and RECORDS on `document.documentElement.dataset.descixView`
+ * which host state it met. The mode is a parameter; the policy lives at the call site.
+ *
+ * Every host state is a row of HOST_VIEW_OUTCOMES. No row throws and no row writes to
+ * console.error: the page's job is physics and layout is the host's, so a missing host is a
+ * truthful record, never a crash and never a cry-wolf console line. Whether an absence is
+ * LEGITIMATE is decided by a gate at the plane that knows (FRAQTL's static URL gate, egpt-frqtl's
+ * refresh-site refusal), not here.
+ *
+ * Two SDK rules shape the order of operations:
+ *   - The SDK's `view` getter console.errors on a standalone page AND on a shell that does not
+ *     publish `view`. So `view` is read only after `ready()` resolved `mode:'shell'` AND its
+ *     `members` list names `view`.
+ *   - `view.set()` on a host that renders a bare iframe validates and returns the mode while
+ *     nothing moves. `view.available()` is the only instrument that tells the two apart, so it
+ *     is consulted here, before `set`, and nowhere else.
+ *
+ * A caller that names a declared second choice (`fallback`) is answered off the shell's PUBLISHED list,
+ * `view.MODES`, read before any `set`: the asked mode when listed, else the fallback when listed (recorded as
+ * the `fallback` row, the refusal and the mode set in the detail), else nothing (`unoffered`). A `set` is never
+ * retried and never decided by its error: a shell that lists a mode and then refuses it is a contract violation.
+ */
+
+/**
+ * The app-side SDK file this declarer consumes. It is PUBLISHER-provided: vendored beside the
+ * page by the site that publishes the static bundle, never shipped in the bundle.
+ */
+export const HOST_SDK_SCRIPT = 'DeSciXAppSDK.js';
+
+/**
+ * The attribute that declares a file host-provided, on the element that consumes it, in the
+ * bytes the browser executes. Both the bundle gate (the file must be ABSENT from the bundle) and
+ * the publisher (the file must be PRESENT beside the page) read the set from this attribute.
+ */
+export const HOST_PROVIDED_ATTR = 'data-frqtl-host-provided';
+
+/**
+ * The publisher's front page, beside the IDE entry (router.js::STATIC_APP_PAGE). PUBLISHER-provided
+ * like HOST_SDK_SCRIPT: the static build declares it once as `<link rel="home" href=HOST_FRONT_PAGE
+ * HOST_PROVIDED_ATTR>` (apps/ide/vite.config.js), the bundle gate asserts the bundle does not ship
+ * it, and lib/features/ide/home-link.js::homeHrefOf reads the declaration back.
+ */
+export const HOST_FRONT_PAGE = 'index.html';
+
+/** The closed table of host states. `setCalls` is how many times `view.set` runs in that row. */
+export const HOST_VIEW_OUTCOMES = Object.freeze([
+    { id: 'pending', setCalls: 0,
+      means: 'awaiting DeSciX.ready(); a ready() that never settles stays here' },
+    { id: 'requested', setCalls: 1,
+      means: 'shell listening: view.available() true and view.set(mode) returned mode; recorded as requested:<mode>' },
+    { id: 'fallback', setCalls: 1,
+      means: 'shell listening; view.MODES lacks the asked mode and offers the caller\'s declared fallback: view.set(fallback) returned it; recorded as fallback:<asked mode>, the refusal and the mode set in dataset.descixViewDetail' },
+    { id: 'unoffered', setCalls: 0,
+      means: 'shell listening; view.MODES offers neither the asked mode nor the declared fallback; recorded as unoffered:<asked mode>, the list in dataset.descixViewDetail' },
+    { id: 'not-listening', setCalls: 0,
+      means: 'shell publishes view but view.available() is false (bare-iframe host); the host owns the layout' },
+    { id: 'view-unpublished', setCalls: 0,
+      means: 'shell resolved, but its members do not include view' },
+    { id: 'standalone', setCalls: 0,
+      means: 'ready() resolved standalone: this page is the top window, no shell above it' },
+    { id: 'embedded-no-bridge', setCalls: 0,
+      means: 'this page is framed and no ancestor carries a readable bus (the SDK rejects ready() here today)' },
+    { id: 'sdk-absent', setCalls: 0,
+      means: 'window.DeSciX is undefined: the publisher-provided DeSciXAppSDK.js is not beside this page' },
+    { id: 'contract-violated', setCalls: null,
+      means: 'the SDK or host broke its published shape; the edge is named in dataset.descixViewDetail (CONTRACT_VIOLATIONS)' },
+].map(Object.freeze));
+
+/** The closed edges of `contract-violated`, each with its own `view.set` call count. */
+export const CONTRACT_VIOLATIONS = Object.freeze({
+    'no-ready':           Object.freeze({ setCalls: 0, means: 'window.DeSciX has no ready() function' }),
+    'ready-rejected':     Object.freeze({ setCalls: 0, means: 'ready() rejected while the SDK reports a mode other than embedded-no-bridge' }),
+    'ready-unknown-mode': Object.freeze({ setCalls: 0, means: 'ready() resolved a mode that is not shell, standalone or embedded-no-bridge' }),
+    'ready-no-members':   Object.freeze({ setCalls: 0, means: 'ready() resolved shell without a members array' }),
+    'view-listed-absent': Object.freeze({ setCalls: 0, means: 'members names view but the view getter returned nothing' }),
+    'view-no-available':  Object.freeze({ setCalls: 0, means: 'view has no available() function' }),
+    'view-no-set':        Object.freeze({ setCalls: 0, means: 'view has no set() function' }),
+    'available-threw':    Object.freeze({ setCalls: 0, means: 'view.available() threw' }),
+    'view-no-modes':      Object.freeze({ setCalls: 0, means: 'a fallback was given but view.MODES is not published' }),
+    'set-threw':          Object.freeze({ setCalls: 1, means: 'view.set(mode) threw (or view.set(fallback), the mode view.MODES offered)' }),
+    'set-returned-other': Object.freeze({ setCalls: 1, means: 'view.set(mode) returned something other than the mode it was asked for' }),
+});
+
+const ROW_IDS = new Set(HOST_VIEW_OUTCOMES.map((r) => r.id));
+
+function messageOf(e) {
+    return (e && e.message) ? String(e.message) : String(e);
+}
+
+/**
+ * Write a row to the document record. Refuses (throws) a row or edge the tables do not list:
+ * that is a defect in THIS module, never a host state.
+ */
+function record(root, row, { suffix = '', detail } = {}) {
+    if (!ROW_IDS.has(row)) { throw new Error(`host-view: '${row}' is not a HOST_VIEW_OUTCOMES row`); }
+    const value = row + suffix;
+    if (root) {
+        root.dataset.descixView = value;
+        if (detail === undefined) { delete root.dataset.descixViewDetail; } else { root.dataset.descixViewDetail = detail; }
+    }
+    return detail === undefined ? { row, record: value } : { row, record: value, detail };
+}
+
+function violated(root, edge, specifics) {
+    if (!Object.prototype.hasOwnProperty.call(CONTRACT_VIOLATIONS, edge)) {
+        throw new Error(`host-view: '${edge}' is not a CONTRACT_VIOLATIONS edge`);
+    }
+    return record(root, 'contract-violated', { detail: `${edge}: ${specifics}` });
+}
+
+/** The SDK's own live mode, read without touching any member getter. */
+function liveMode(sdk) {
+    try { return sdk.mode; } catch (e) { return undefined; }
+}
+
+/**
+ * Ask the host for `mode`, once, and record which host state was met.
+ *
+ * @param {object} args
+ * @param {object|undefined} args.sdk  the app-side SDK object (`window.DeSciX`), or undefined
+ * @param {string} args.mode           the view to ask for: a mode the shell's `view.MODES` offers
+ * @param {string} [args.fallback]     the caller's declared second choice, asked only when `view.MODES` does not
+ *                                     offer `mode` (a non-empty string other than `mode`)
+ * @param {{dataset: object}} [args.root] where the record is written; defaults to
+ *                                     `document.documentElement` when a document exists
+ * @returns {Promise<{row: string, record: string, detail?: string}>}
+ */
+export async function declareHostView({ sdk, mode, fallback, root } = {}) {
+    if (typeof mode !== 'string' || mode === '') {
+        throw new TypeError(`host-view: declareHostView needs a view mode string (got ${JSON.stringify(mode)})`);
+    }
+    if (fallback !== undefined && (typeof fallback !== 'string' || fallback === '' || fallback === mode)) {
+        throw new TypeError(`host-view: a fallback is a non-empty view mode string other than mode ${JSON.stringify(mode)} (got ${JSON.stringify(fallback)})`);
+    }
+    const target = root || (typeof document !== 'undefined' ? document.documentElement : null);
+
+    if (sdk === undefined || sdk === null) { return record(target, 'sdk-absent'); }
+    if (typeof sdk.ready !== 'function') {
+        return violated(target, 'no-ready', `window.DeSciX is a ${typeof sdk} without ready()`);
+    }
+
+    record(target, 'pending');
+    let ready;
+    try {
+        ready = await sdk.ready();
+    } catch (e) {
+        const now = liveMode(sdk);
+        if (now === 'embedded-no-bridge') {
+            return record(target, 'embedded-no-bridge', { detail: `ready() rejected: ${messageOf(e)}` });
+        }
+        return violated(target, 'ready-rejected', `SDK mode ${JSON.stringify(now)}; ${messageOf(e)}`);
+    }
+
+    const resolved = ready && ready.mode;
+    if (resolved === 'standalone') { return record(target, 'standalone'); }
+    if (resolved === 'embedded-no-bridge') { return record(target, 'embedded-no-bridge'); }
+    if (resolved !== 'shell') {
+        return violated(target, 'ready-unknown-mode', `ready() resolved mode ${JSON.stringify(resolved)}`);
+    }
+    if (!Array.isArray(ready.members)) {
+        return violated(target, 'ready-no-members', 'ready() resolved shell without a members array');
+    }
+    if (!ready.members.includes('view')) {
+        return record(target, 'view-unpublished', { detail: `members: ${ready.members.join(',')}` });
+    }
+
+    const view = sdk.view;
+    if (!view) { return violated(target, 'view-listed-absent', 'members names view; the getter returned ' + String(view)); }
+    if (typeof view.available !== 'function') { return violated(target, 'view-no-available', 'view.available is ' + typeof view.available); }
+    if (typeof view.set !== 'function') { return violated(target, 'view-no-set', 'view.set is ' + typeof view.set); }
+
+    let listening;
+    try {
+        listening = view.available();
+    } catch (e) {
+        return violated(target, 'available-threw', messageOf(e));
+    }
+    if (!listening) { return record(target, 'not-listening'); }
+
+    // With a declared fallback the published list decides which ONE mode is asked; without one, the asked mode is.
+    let ask = mode;
+    if (fallback !== undefined) {
+        const modes = view.MODES;
+        if (!modes || typeof modes !== 'object') {
+            return violated(target, 'view-no-modes', 'fallback given but view.MODES is not published (got ' + String(modes) + ')');
+        }
+        const offered = Object.values(modes);
+        const list = '[' + offered.join(', ') + ']';
+        if (!offered.includes(mode)) {
+            if (!offered.includes(fallback)) {
+                return record(target, 'unoffered', { suffix: ':' + mode,
+                    detail: `view.MODES ${list} offers neither "${mode}" nor the fallback "${fallback}"` });
+            }
+            ask = fallback;
+        }
+        if (ask === fallback) {
+            let gotFallback;
+            try {
+                gotFallback = view.set(fallback);
+            } catch (e) {
+                return violated(target, 'set-threw', messageOf(e));
+            }
+            if (gotFallback !== fallback) {
+                return violated(target, 'set-returned-other', `asked ${fallback}, set returned ${JSON.stringify(gotFallback)}`);
+            }
+            return record(target, 'fallback', { suffix: ':' + mode,
+                detail: `refused: "${mode}" is not in view.MODES ${list}; set: ${fallback}` });
+        }
+    }
+
+    let got;
+    try {
+        got = view.set(ask);
+    } catch (e) {
+        return violated(target, 'set-threw', messageOf(e));
+    }
+    if (got !== ask) {
+        return violated(target, 'set-returned-other', `asked ${ask}, set returned ${JSON.stringify(got)}`);
+    }
+    return record(target, 'requested', { suffix: ':' + ask });
+}

package/dist/shim/host/index.js

@@ -0,0 +1,18 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * index.js — the published door to the host-view declarer: `@descix/frqtl-web/host-view` and
+ * `@descix/frqtl-node/host-view`. Exactly the names below, re-exported from THE declarer (host-view.js); its
+ * static-build vocabulary (HOST_PROVIDED_ATTR, HOST_FRONT_PAGE) stays FRAQTL's own.
+ *
+ *   HOST_VIEW_EXPORTS   the published names (the parity gate holds both packages' ./host-view to this table)
+ *
+ * A consuming app calls `declareHostView({ sdk: window.DeSciX, mode, fallback? })` once, under its own policy, and
+ * reads the outcome off `document.documentElement.dataset.descixView` (a HOST_VIEW_OUTCOMES row). HOST_SDK_SCRIPT is
+ * the publisher-provided SDK file the app vendors beside its page.
+ */
+
+/** The names `./host-view` publishes. */
+export const HOST_VIEW_EXPORTS = Object.freeze(['declareHostView', 'HOST_VIEW_OUTCOMES', 'CONTRACT_VIOLATIONS', 'HOST_SDK_SCRIPT']);
+
+export { declareHostView, HOST_VIEW_OUTCOMES, CONTRACT_VIOLATIONS, HOST_SDK_SCRIPT } from './host-view.js';

package/dist/shim/index.js

@@ -7,7 +7,7 @@
  * FAIL-LOUD load error — no window.Common* ambient globals.
  *
  * Usage (under vite with alias 'lib' → repo-root/lib):
- *   import { Bus, Runtime, EXPERIMENTS, engineRouter } from 'lib/shim';
+ *   import { Bus, Runtime, sceneGroups, engineRouter } from 'lib/shim';
  *
  * Usage (direct relative path):
  *   import { Bus } from '../../lib/shim/index.js';
@@ -15,9 +15,7 @@
 
 export { Bus }           from './bus.js';
 export { Runtime }       from './runtime/index.js';
-export { EXPERIMENTS, EXPERIMENT_TIERS, experimentById, experimentIs3D,
-         isPublicExperiment, publicExperiments,
-         internalExperiments } from './registry/experiments.js';
+export { sceneGroups, SHOWCASE_GROUP } from './registry/scene-roster.js';
 export { WALKTHROUGH, walkthroughIs3D, walkthroughModes, walkthroughGroup,
          walkthroughById,
          FIRST_CONTACT_WALKTHROUGH_ID,

package/dist/shim/notebook/kernel.js

@@ -148,7 +148,7 @@ export class NotebookKernel {
     }
 
     /* ── scope ──────────────────────────────────────────────────────────────
-     * THE SCOPE RULE (FRAQTL issue #67): a math value's scope IS this kernel's
+     * THE SCOPE RULE: a math value's scope IS this kernel's
      * binding scope. On the shipped WASM dist an EGPT value is an arena handle,
      * so if the arena is drained while a binding still names one, that binding is
      * a dead handle and the next cell dies with `arena:stale-handle`. The two

package/dist/shim/notebook/setup-builder.js

@@ -288,7 +288,7 @@ export function parseSeed(seed) {
  *     canvas boots the same scene as every other surface.
  *
  *   shape='recipe': the module's DEFAULT export is a `buildExperiment(exp)` RECIPE — a SINGLE
- *     RecipeContext arg (the sketch form codegen and the scene files write). Template:
+ *     RecipeContext arg (the sketch form the scene files and the parts writer write). Template:
  *       const buildExperiment = (await import('<module>')).default;   // FAIL-LOUD if not a function
  *       const exp = frqtl.RecipeContext({ seed, deferCanvas: true });   // SIZELESS
  *       exp.build(buildExperiment);          // runs its co-init call + addObject() — NO start
@@ -298,7 +298,7 @@ export function parseSeed(seed) {
  *     recipe takes NO knob bag — a non-empty `opts` on a recipe canvas FAILS LOUD
  *     (rather than silently dropping it).
  *
- * WHY the template checks `buildExperiment` but not `exp` (FRAQTL #73): the two values
+ * WHY the template checks `buildExperiment` but not `exp`: the two values
  * have different OWNERS. `buildExperiment` is read off the module namespace by this template
  * itself, so nothing but this template can vouch for it — hence the emitted FAIL-LOUD check.
  * `exp` comes from `frqtl.RecipeContext(...)`, a caps.frqtl member: its owner

package/dist/shim/package.json

@@ -1,4 +1,5 @@
 {
   "private": true,
+  "license": "SEE LICENSE IN LICENSE.md",
   "type": "module"
 }

package/dist/shim/page-params/index.js

@@ -64,8 +64,7 @@
 var KEYS = Object.freeze({
     SEED:               'seed',
     RENDERER:           'renderer',
-    ENGINE:             'engine',
-    STEPPING:           'stepping'
+    ENGINE:             'engine'
 });
 
 /**
@@ -85,7 +84,7 @@ var KEYS = Object.freeze({
 var PAGE_PARAMS = Object.freeze([
     Object.freeze({
         key:     KEYS.SEED,
-        reader:  'lib/frqtl/experiments/_shared/fx-experiment.js',
+        reader:  'lib/frqtl/experiments/empty/index.html',
         forward: true
     }),
     Object.freeze({
@@ -93,33 +92,6 @@ var PAGE_PARAMS = Object.freeze([
         reader:  'lib/frqtl/experiments/_shared/boot.js',
         forward: true
     }),
-    Object.freeze({
-        key:     KEYS.STEPPING,
-        reader:  'lib/frqtl/experiments/single-source-interference/index.html',
-        forward: true
-        // Circulation §2: `stepping`
-        // selects the WAVE-WALK STEPPING SAMPLER for one universe —
-        // 'fixed' (deterministic error-accumulator walk, the engine's serde default)
-        // vs 'average' (the historic per-axis Bernoulli walk). It is a PER-UNIVERSE
-        // PHYSICS option, so it is read at the PAGE plane and ferried RAW into that
-        // page's own `universe.init(..., { stepping })` options — deliberately NOT by
-        // the boot module, which selects the BACKEND (`?engine=`, forward:false). Putting
-        // a physics knob in the backend selection would conflate the two axes.
-        //
-        // forward:true — unlike `?engine=`, no host owns a competing stepping authority,
-        // and a host embedding this page for an A/B (the GYM Compare shape) forwarding
-        // its own `?stepping=` is exactly the intended use (the `?renderer=`/`?seed=`
-        // precedent). The value is NEVER validated or defaulted page-side: an absent
-        // param means the key is omitted from the init bag so the ENGINE's default
-        // (the Rust `Stepping` serde enum, `Fixed`) is the ONE authority for it, and a
-        // garbage value rides through to `universe.init()`, which throws naming both
-        // legal samplers (one validator, zero second interpreters).
-        //
-        // SCALING (pre-registered, not built): a PAGE_PARAMS entry names ONE reader.
-        // When a SECOND page consumes `?stepping=`, HOIST the read into one shared
-        // reader module and repoint this entry — never a second entry for the same
-        // key, never a copy-pasted inline read.
-    }),
     Object.freeze({
         key:     KEYS.ENGINE,
         reader:  'lib/frqtl/experiments/_shared/boot.js',

package/dist/shim/project/fork.js

@@ -0,0 +1,293 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * fork.js — THE fork transform: a part file's text becomes the text of its renamed copy, `parts/<To>.js`.
+ *
+ *   forkPartText(text, { from, to, libPath, files }) → { text, imports }
+ *     text     the source part file's exact bytes, as text
+ *     from     the class name the file registers (its kind name)
+ *     to       the new class name (the fork's kind name)
+ *     libPath  where the source lives: a package lib-identity path ('frqtl/parts/Wall.js') or, for a fork of a
+ *              fork, the project path of the held file ('parts/MyWall.js')
+ *     files    the project's files by path ({} when none) — a fork never overwrites one
+ *   imports    [{ from, to }] — each import specifier of the source and the specifier the copy writes
+ *
+ * The text is parsed once (parts-writer.js parseModule: the vendored acorn's one importer). The copy differs from the source
+ * in exactly three kinds of range, and every other byte (comments, docstrings, the schema, every string) is the
+ * source's byte:
+ *   1. THE CLASS BINDING. `to` replaces the module-scope binding `from`: its declaration's id and every reference
+ *      that resolves to it (`registerKind(Wall, …)`, `Wall.prototype…`, `instanceof Wall`, `export { Wall }`). A
+ *      same-named binding in an inner scope, a property key and a string are untouched.
+ *   2. THE PALETTE NAME. The registerKind row's `palette.displayName` string becomes `to`, so a palette lists the
+ *      fork by its own name. Every other property of the row is the source's byte.
+ *   3. THE IMPORTS. A package part's relative import is rewritten to the package specifier naming the SAME file
+ *      (specifiers.js specifierOfLibPath — a part file under frqtl/parts/ → the parts prefix row; frqtl/objects/
+ *      kinds.js → @descix/frqtl-web/kinds when every imported name is in KINDS_EXPORTS; anything else its own
+ *      row). A fork of a fork keeps its relative imports (they name project files beside it) and its package
+ *      specifiers as they are. A fork never copies a non-part module: a second copy of a registry or a schema
+ *      would split one fact.
+ *
+ * REFUSED (throws, naming the part): `to` is not an identifier or is a reserved word; `to` equals `from`; `to` is
+ * already a registered kind, or `parts/<to>.js` is already a project file; `from` is a kind FORK_REFUSED names
+ * (with its reason); the file declares no module-scope `from`; a relative import with no row (naming the import).
+ *
+ *   FORK_REFUSED   { <kind>: reason } — the kinds no fork copies, each with the census reason (fork.test.mjs
+ *                  G-CENSUS derives the set from the part files and holds it equal to this table)
+ */
+
+import { kindOf } from '../../frqtl/objects/kinds.js';
+import { KINDS_EXPORTS } from '../../frqtl/objects/kinds-entry.js';
+import { specifierOfLibPath } from './specifiers.js';
+import { isIdentifierName, parseModule } from './parts-writer.js';
+
+/** The kinds a fork refuses, each with why (the census: a scope row, or the class name used as a string). */
+export const FORK_REFUSED = Object.freeze({
+    LargeObject: 'LargeObject is a scope row (schema/scopes.js SCOPE_DESCRIPTORS) and passes \'LargeObject\' as the engine ' +
+        'scope name to universe.updateObjectProperty — a copy would be a second scope row',
+    PointSource: 'PointSource numbers its default name with declaredCount(ctx.runner, \'PointSource\') — a copy would ' +
+        'number itself in its parent\'s sequence (the class name used as a string)'
+});
+
+/** The lib-identity path of the parts directory, and the kinds registry a part imports. */
+const PARTS_DIR = 'frqtl/parts/';
+const KINDS_LIB = 'frqtl/objects/kinds.js';
+
+function _fail(msg) {
+    throw new Error('[fork] ' + msg + ' (FAIL-LOUD.)');
+}
+
+/** The children of an AST node (every key holding a node or an array of nodes). */
+function _children(n) {
+    const out = [];
+    for (const k of Object.keys(n)) {
+        if (k === 'type' || k === 'start' || k === 'end' || k === 'loc' || k === 'range') { continue; }
+        const v = n[k];
+        if (Array.isArray(v)) { for (const c of v) { if (c && typeof c.type === 'string') { out.push(c); } } }
+        else if (v && typeof v.type === 'string') { out.push(v); }
+    }
+    return out;
+}
+
+function _patternNames(p, out) {
+    if (!p) { return out; }
+    if (p.type === 'Identifier') { out.push(p.name); }
+    else if (p.type === 'ObjectPattern') { for (const q of p.properties) { _patternNames(q.type === 'RestElement' ? q.argument : q.value, out); } }
+    else if (p.type === 'ArrayPattern') { for (const e of p.elements) { _patternNames(e, out); } }
+    else if (p.type === 'RestElement') { _patternNames(p.argument, out); }
+    else if (p.type === 'AssignmentPattern') { _patternNames(p.left, out); }
+    return out;
+}
+
+const _FUNCTION = { FunctionDeclaration: 1, FunctionExpression: 1, ArrowFunctionExpression: 1 };
+
+/** `var` names declared in a function body (not crossing a nested function). */
+function _varNames(n, out) {
+    for (const c of _children(n)) {
+        if (_FUNCTION[c.type]) { continue; }
+        if (c.type === 'VariableDeclaration' && c.kind === 'var') {
+            for (const d of c.declarations) { _patternNames(d.id, out); }
+        }
+        _varNames(c, out);
+    }
+    return out;
+}
+
+/** Block-scoped names declared directly in a statement list (let/const/class/function). */
+function _lexicalNames(body, out) {
+    for (const s of body) {
+        const d = (s.type === 'ExportNamedDeclaration' || s.type === 'ExportDefaultDeclaration') ? s.declaration : s;
+        if (!d) { continue; }
+        if (d.type === 'VariableDeclaration' && d.kind !== 'var') { for (const x of d.declarations) { _patternNames(x.id, out); } }
+        else if ((d.type === 'ClassDeclaration' || d.type === 'FunctionDeclaration') && d.id) { out.push(d.id.name); }
+    }
+    return out;
+}
+
+/** The names a node introduces into the scope it opens (null when it opens none). */
+function _scopeNames(n, isModule) {
+    if (_FUNCTION[n.type]) {
+        const names = [];
+        for (const p of n.params) { _patternNames(p, names); }
+        if (n.type === 'FunctionExpression' && n.id) { names.push(n.id.name); }
+        if (n.body.type === 'BlockStatement') { _varNames(n.body, names); _lexicalNames(n.body.body, names); }
+        return names;
+    }
+    if (n.type === 'BlockStatement' || n.type === 'StaticBlock') { return isModule ? null : _lexicalNames(n.body, []); }
+    if (n.type === 'SwitchStatement') { return _lexicalNames(n.cases.flatMap(function (c) { return c.consequent; }), []); }
+    if (n.type === 'ForStatement' || n.type === 'ForInStatement' || n.type === 'ForOfStatement') {
+        const init = n.type === 'ForStatement' ? n.init : n.left;
+        if (!init || init.type !== 'VariableDeclaration' || init.kind === 'var') { return []; }
+        return init.declarations.reduce(function (acc, d) { return _patternNames(d.id, acc); }, []);
+    }
+    if (n.type === 'CatchClause') { return n.param ? _patternNames(n.param, []) : []; }
+    if (n.type === 'ClassExpression' && n.id) { return [n.id.name]; }
+    return null;
+}
+
+/**
+ * Every Identifier node that resolves to the MODULE-scope binding `name` (declarations and references).
+ * Positions that are not references (non-computed property keys and member properties, labels, an import's
+ * imported name, an export's exported name when it differs from the local) are skipped.
+ */
+function _moduleBindingIds(ast, name) {
+    const hits = [];
+    function visit(n, shadowed, parent, key) {
+        if (n.type === 'Identifier') {
+            if (n.name !== name || shadowed) { return; }
+            if (parent) {
+                if (parent.type === 'MemberExpression' && key === 'property' && !parent.computed) { return; }
+                if ((parent.type === 'Property' || parent.type === 'MethodDefinition' || parent.type === 'PropertyDefinition') &&
+                    key === 'key' && !parent.computed && !parent.shorthand) { return; }
+                if ((parent.type === 'LabeledStatement' || parent.type === 'BreakStatement' || parent.type === 'ContinueStatement') && key === 'label') { return; }
+                // An import's imported name and an export's exported name are names, not references: the local
+                // is the binding (acorn hands the SAME node to both keys of a shorthand specifier).
+                if (parent.type === 'ImportSpecifier' && key === 'imported') { return; }
+                if (parent.type === 'ExportSpecifier' && key === 'exported') { return; }
+            }
+            hits.push(n);
+            return;
+        }
+        const names = n === ast ? null : _scopeNames(n, false);
+        const sh = shadowed || !!(names && names.indexOf(name) !== -1);
+        for (const k of Object.keys(n)) {
+            if (k === 'type' || k === 'start' || k === 'end' || k === 'loc') { continue; }
+            const v = n[k];
+            if (Array.isArray(v)) { for (const c of v) { if (c && typeof c.type === 'string') { visit(c, _childShadow(n, k, c, sh, shadowed), n, k); } } }
+            else if (v && typeof v.type === 'string') { visit(v, _childShadow(n, k, v, sh, shadowed), n, k); }
+        }
+    }
+    // A function DECLARATION's id belongs to the enclosing scope, not the one the function opens.
+    function _childShadow(n, k, c, sh, outer) {
+        if (n.type === 'FunctionDeclaration' && k === 'id') { return outer; }
+        return sh;
+    }
+    visit(ast, false, null, null);
+    return hits;
+}
+
+/** The module-top binding of `name`: its declaration node, or null. */
+function _topDeclaration(ast, name) {
+    for (const s of ast.body) {
+        const d = (s.type === 'ExportNamedDeclaration' || s.type === 'ExportDefaultDeclaration') ? s.declaration : s;
+        if (!d) { continue; }
+        if ((d.type === 'ClassDeclaration' || d.type === 'FunctionDeclaration') && d.id && d.id.name === name) { return d; }
+        if (d.type === 'VariableDeclaration' && d.declarations.some(function (x) { return _patternNames(x.id, []).indexOf(name) !== -1; })) { return d; }
+    }
+    return null;
+}
+
+/** The `palette.displayName` string Literal of the module's `registerKind(<from>, { … })` row, or null. */
+function _paletteName(ast, from) {
+    let found = null;
+    (function visit(n) {
+        if (found) { return; }
+        if (n.type === 'CallExpression' && n.callee.type === 'Identifier' && n.callee.name === 'registerKind' &&
+            n.arguments[0] && n.arguments[0].type === 'Identifier' && n.arguments[0].name === from &&
+            n.arguments[1] && n.arguments[1].type === 'ObjectExpression') {
+            const pal = n.arguments[1].properties.find(function (p) { return p.type === 'Property' && !p.computed && p.key.name === 'palette'; });
+            if (pal && pal.value.type === 'ObjectExpression') {
+                const dn = pal.value.properties.find(function (p) { return p.type === 'Property' && !p.computed && p.key.name === 'displayName'; });
+                if (dn && dn.value.type === 'Literal' && typeof dn.value.value === 'string') { found = dn.value; }
+            }
+            return;
+        }
+        for (const c of _children(n)) { visit(c); }
+    })(ast);
+    return found;
+}
+
+/** The lib-identity (or project) path a relative specifier names from `fromPath`. */
+function _resolve(fromPath, spec) {
+    const segs = fromPath.split('/');
+    segs.pop();
+    for (const s of spec.split('/')) {
+        if (s === '.' || s === '') { continue; }
+        if (s === '..') { segs.pop(); } else { segs.push(s); }
+    }
+    return segs.join('/');
+}
+
+function _quoteLike(original, value) {
+    const q = original[0] === '"' ? '"' : '\'';
+    return q + value.replace(/\\/g, '\\\\').split(q).join('\\' + q) + q;
+}
+
+/**
+ * @param {string} text — the source part file
+ * @param {{from: string, to: string, libPath: string, files: Object<string, string>}} opts
+ * @returns {{text: string, imports: Array<{from: string, to: string}>}}
+ */
+export function forkPartText(text, opts) {
+    if (typeof text !== 'string' || !text) { _fail('forkPartText(text, opts): text is the part file (got ' + typeof text + ').'); }
+    const o = opts || {};
+    const from = o.from, to = o.to, libPath = o.libPath, files = o.files;
+    if (typeof from !== 'string' || !from) { _fail('forkPartText: `from` is the class name the part registers.'); }
+    if (typeof libPath !== 'string' || !libPath) { _fail('forkPartText(' + from + '): `libPath` names the source file.'); }
+    if (!files || typeof files !== 'object') { _fail('forkPartText(' + from + '): `files` is the project\'s file map ({} when none).'); }
+    if (typeof to !== 'string' || !isIdentifierName(to)) {
+        _fail('forkPartText(' + from + '): the new class name ' + JSON.stringify(to) + ' is not an identifier (or is a reserved word) ' +
+            '— the class name IS the kind name.');
+    }
+    if (to === from) { _fail('forkPartText(' + from + '): the new class name equals the part\'s own — a fork is a NEW kind; name it.'); }
+    if (kindOf(to)) {
+        _fail('forkPartText(' + from + '): "' + to + '" is already a registered kind (' + kindOf(to).from + ') — one name has one owner; ' +
+            'choose another name.');
+    }
+    const target = 'parts/' + to + '.js';
+    if (Object.prototype.hasOwnProperty.call(files, target)) {
+        _fail('forkPartText(' + from + '): ' + target + ' is already a project file — a fork never overwrites one.');
+    }
+    if (Object.prototype.hasOwnProperty.call(FORK_REFUSED, from)) {
+        _fail('forkPartText(' + from + '): ' + from + ' is not forkable — ' + FORK_REFUSED[from] + '.');
+    }
+    const pkg = libPath.indexOf(PARTS_DIR) === 0;
+    let ast;
+    try { ast = parseModule(text); }
+    catch (err) { _fail('forkPartText(' + from + '): ' + libPath + ' does not parse (' + err.message + ').'); }
+    if (!_topDeclaration(ast, from)) {
+        _fail('forkPartText(' + from + '): ' + libPath + ' declares no module-scope ' + from + ' — the file a kind\'s `from` names declares its class.');
+    }
+
+    const patches = [];
+    const imports = [];
+    for (const s of ast.body) {
+        const src = (s.type === 'ImportDeclaration' || ((s.type === 'ExportNamedDeclaration' || s.type === 'ExportAllDeclaration') && s.source))
+            ? s.source : null;
+        if (!src) { continue; }
+        const spec = src.value;
+        if (!(spec.startsWith('./') || spec.startsWith('../'))) { imports.push({ from: spec, to: spec }); continue; }
+        if (!pkg) { imports.push({ from: spec, to: spec }); continue; }   // a fork of a fork: project files beside it
+        const lp = _resolve(libPath, spec);
+        let out;
+        if (lp === KINDS_LIB) {
+            const names = (s.specifiers || []).map(function (x) {
+                return x.type === 'ImportSpecifier' ? (x.imported.name || x.imported.value) : '*';
+            });
+            const outside = names.filter(function (n) { return KINDS_EXPORTS.indexOf(n) === -1; });
+            if (outside.length) {
+                _fail('forkPartText(' + from + '): ' + libPath + ' imports ' + outside.join(', ') + ' from "' + spec + '" — the kinds ' +
+                    'door (@descix/frqtl-web/kinds) publishes ' + KINDS_EXPORTS.join(', ') + ' only.');
+            }
+            out = specifierOfLibPath('frqtl/objects/kinds-entry.js');
+        } else {
+            out = specifierOfLibPath(lp);
+        }
+        if (!out) {
+            _fail('forkPartText(' + from + '): ' + libPath + ' imports "' + spec + '" (' + lp + '), which no specifier row names — a ' +
+                'fork imports every non-part module from the package (lib/shim/project/specifiers.js); it never copies one.');
+        }
+        patches.push({ start: src.start, end: src.end, text: _quoteLike(text.slice(src.start, src.end), out) });
+        imports.push({ from: spec, to: out });
+    }
+    for (const id of _moduleBindingIds(ast, from)) { patches.push({ start: id.start, end: id.end, text: to }); }
+    const dn = _paletteName(ast, from);
+    if (dn) { patches.push({ start: dn.start, end: dn.end, text: _quoteLike(text.slice(dn.start, dn.end), to) }); }
+
+    patches.sort(function (a, b) { return b.start - a.start; });
+    for (let i = 1; i < patches.length; i++) {
+        if (patches[i].end > patches[i - 1].start) { _fail('forkPartText(' + from + '): overlapping rewrites — a bug in the transform.'); }
+    }
+    let out = text;
+    for (const p of patches) { out = out.slice(0, p.start) + p.text + out.slice(p.end); }
+    return { text: out, imports: imports };
+}