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

package/dist/shim/engine/artifact-shell.js

@@ -164,7 +164,7 @@ export function renderArtifactShellHtml(opts) {
     return (
 '<!DOCTYPE html>\n' +
 '<!-- Copyright 2023-2026 by Essam Abadir -->\n' +
-'<!-- FRQTL — claude.ai Artifact host shell (ws-artifact-showcase Bite A2).\n' +
+'<!-- FRQTL — claude.ai Artifact host shell.\n' +
 '     Generated by lib/shim/engine/artifact-shell.js — DO NOT hand-edit.\n' +
 '     Paste this ENTIRE file into a claude.ai chat as an Artifact (type: HTML). -->\n' +
 '<html lang="en">\n' +

package/dist/shim/engine/router.js

@@ -148,7 +148,7 @@ var DIST_PROFILE = buildDistProfile('../..');
 // lib/shim/engine/test/router.test.mjs asserts them against the two
 // package.json#version fields so a forgotten bump fails `make verify`, not a
 // silent stale-CDN-URL bug.
-var CDN_SDK_VERSION = '0.6.0-p1.1';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
+var CDN_SDK_VERSION = '0.6.0';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
 var CDN_MATH_SDK_VERSION = '0.3.2';  // sdk/egpt-math-sdk/package.json#version — bound by router.test.mjs; bumped with each npm publish
 
 /**
@@ -382,7 +382,7 @@ function documentSiteBuild() {
 }
 
 // The static IDE bundle's entry document, beside its front page. The bundle ships THIS name and no
-// index.html: a site's index.html is the publisher's front page (host-view.js::HOST_FRONT_PAGE),
+// index.html: a site's index.html is the publisher's front page (lib/shim/host/host-view.js::HOST_FRONT_PAGE),
 // which the IDE brand links home to.
 var STATIC_APP_PAGE = 'app.html';
 
@@ -507,7 +507,7 @@ var _assertProfileParity = (function () {
  * // CDN mode (static hosting — the artifact host shell has no server, no page anchor):
  * const cdnRouter = engineRouter({ mode: 'cdn', engine: 'wasm' });
  * console.log(cdnRouter.resolve('compat/engine.js'));
- * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p1.1/dist/frqtl/compat/engine.js'
+ * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0/dist/frqtl/compat/engine.js'
  *
  * // CDN mode, self-hosted: a copy of dist/ served from the consumer's own origin:
  * const selfHosted = engineRouter({ mode: 'cdn', engine: 'wasm', base: 'https://example.org/vendor/frqtl-web/dist' });

package/dist/shim/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,14 +15,12 @@
 
 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,
          defaultWalkthroughModeId, effectiveRenderState } from './registry/walkthrough.js';
-export { loadSceneSource, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
+export { projectOf, scenePath, EMPTY_SCENE } from './registry/scene-source.js';
 // The host-side experiment-iframe guard (the false-200 trap). Exported from the
 // barrel so every host that frames an experiment page (lib/features/ide's GYM)
 // asserts against the SAME contract.

package/dist/shim/notebook/format.js

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

package/dist/shim/notebook/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/notebook/store.js

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

package/dist/shim/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',