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

package/dist/frqtl/scenes/sun.js

@@ -5,7 +5,7 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rung r8-sun).
  */
@@ -21,18 +21,21 @@
 
 import { CameraControls, SphereEmitter } from '@descix/frqtl-web/parts';
 
+export const parts = {
+  source: [SphereEmitter, {
+    preset: 'spherical', emissionBoxSide: 0, is2D: false,
+    chargeMode: 'random', fundamentalDimension: 2,
+    wavelength: 1, fundamentalWaveLength: 64, emitEveryTicks: 1
+  }],
+};
+
 export default function buildExperiment(exp) {
   // Rung 8 (Sun) — the sun.png panel regime: a 3D omni POINT source, virtual mass 16
   // (fullness 1) via wavelength:1, λ scale 16 via fundamentalWaveLength:64, emit every 1.
   // The sphere shape + god-rays + glow FX ride the renderState (three-only capabilities).
   // The sun's yellow is the NATURAL fullness->color (mass=capacity, fullness 1); no forced color.
-  var SRC = {
-    preset: 'spherical', emissionBoxSide: 0, is2D: false,
-    chargeMode: 'random', fundamentalDimension: 2,
-    wavelength: 1, fundamentalWaveLength: 64, emitEveryTicks: 1
-  };
-  exp.createScene(600, 400, 600, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
-  exp.addObject('SphereEmitter', SRC);
+  exp.createScene(600, 400, 600, SphereEmitter.worldCfg(parts.source[1]));   // THE WORLD: a 3D scene + universe, 600x400x600 — first, then parts
+  exp.declare(parts);
   if (typeof document !== 'undefined' && exp.runner) {
     if (exp.runner.controlHost) { CameraControls.attach(exp.runner, exp.runner.controlHost); }
   }

package/dist/frqtl/scenes/two-source.js

@@ -5,7 +5,7 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rungs r6a-two-source, r6b-two-fountains, r6c-plasma-fusion).
  */
@@ -16,22 +16,27 @@
 
 import { SphereEmitter } from '@descix/frqtl-web/parts';
 
+// The classic self-interference config called TWICE, centered ±32px from canvas
+// center (64px apart = 1×fundamentalWaveLength, i.e. λ_eff/4 since λ_eff = 4×fWL).
+// The world is init'd ONCE, then TWO parts are constructed on it — no flag, no
+// re-init, no stacking. The
+// lattice BETWEEN the two visible sources is EMERGENT density superposition (SU1).
+const W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
+const cx = Math.floor(W / 2), cy = Math.floor(H / 2);
+const CFG = {
+  is2D: true, preset: 'spherical',
+  emissionShell: 'surface', innerR: 16,
+  fundamentalDimension: 2, wavelength: 32,
+  chargeMode: 'random', fundamentalWaveLength: 64,
+  burstSize: 72, emitEveryTicks: 1
+};
+
+export const parts = {
+  left: [SphereEmitter, { ...CFG, center: [cx - 32, cy] }],
+  right: [SphereEmitter, { ...CFG, center: [cx + 32, cy] }],
+};
+
 export default function buildExperiment(exp) {
-  // The classic self-interference config called TWICE, centered ±32px from canvas
-  // center (64px apart = 1×fundamentalWaveLength, i.e. λ_eff/4 since λ_eff = 4×fWL).
-  // The world is init'd ONCE, then TWO parts are constructed on it — no flag, no
-  // re-init, no stacking. The
-  // lattice BETWEEN the two visible sources is EMERGENT density superposition (SU1).
-  var W = 600, H = 400;   // THE WORLD this scene states (its co-init call below)
-  var cx = Math.floor(W / 2), cy = Math.floor(H / 2);
-  var CFG = {
-    is2D: true, preset: 'spherical',
-    emissionShell: 'surface', innerR: 16,
-    fundamentalDimension: 2, wavelength: 32,
-    chargeMode: 'random', fundamentalWaveLength: 64,
-    burstSize: 72, emitEveryTicks: 1
-  };
   exp.createCanvas(W, H, SphereEmitter.worldCfg(CFG));   // THE WORLD: a 2D canvas + universe — first, then parts
-  exp.addObject('SphereEmitter', Object.assign({}, CFG, { center: [cx - 32, cy] }));
-  exp.addObject('SphereEmitter', Object.assign({}, CFG, { center: [cx + 32, cy] }));
+  exp.declare(parts);
 }

package/dist/frqtl/scenes/wave.js

@@ -5,22 +5,25 @@
  *
  * A sketch file: the WHOLE scene as one ES module, `export default function buildExperiment(exp)`. The world
  * (its co-init call, `exp.createCanvas` / `exp.createScene` — the one place its size is written),
- * the parts (`exp.addObject`) and the render intent are all here; the sugar
+ * the parts (`export const parts` + `exp.declare`, or `exp.addObject`) and the render intent are all here; the sugar
  * objects, renderer and engine are imports. Registered by lib/shim/registry/walkthrough.js
  * (rung r2-wave).
  */
 
 import { SphereEmitter } from '@descix/frqtl-web/parts';
 
+export const parts = {
+  source: [SphereEmitter, {
+    preset: 'particle-walk', is2D: true,
+    fundamentalDimension: 2, wavelength: 8
+  }],
+};
+
 export default function buildExperiment(exp) {
   // Rung 2 — Rung 1 + raise the leaf dimension to 2 (WAVELENGTH_DEMO_DIMENSION):
   // wavelength is a NO-OP at dim 0 (capacity=1 saturates mass), so raising the
   // fundamental gives the wavelength arg leverage. wavelength:8 -> mass 2 ->
   // transverse period grows from ~16px (Rung 1) to a visible ~128px snake.
-  var SRC = {
-    preset: 'particle-walk', is2D: true,
-    fundamentalDimension: 2, wavelength: 8
-  };
-  exp.createCanvas(600, 400, SphereEmitter.worldCfg(SRC));   // THE WORLD: a 2D canvas + universe — first, then parts
-  exp.addObject('SphereEmitter', SRC);
+  exp.createCanvas(600, 400, SphereEmitter.worldCfg(parts.source[1]));   // THE WORLD: a 2D canvas + universe — first, then parts
+  exp.declare(parts);
 }

package/dist/shim/bundle/manifest.js

@@ -44,7 +44,7 @@ export var BUNDLE_ONLY_KEYS = ['sdkVersion', 'preview', 'descix'];
  * @param {object} envelope   — a `lib/shim/storage/modules.js` Module envelope
  *   (MUST carry `source`; every other field is ferried verbatim).
  * @param {object} opts
- * @param {string} opts.sdkVersion — REQUIRED; the CDN pin (e.g. '0.6.0-p0.2').
+ * @param {string} opts.sdkVersion — REQUIRED; the CDN pin (e.g. '0.6.0-p1.1').
  * @param {string|null} [opts.preview] — preview filename ref, or null/omitted.
  * @returns {object} the manifest (JSON-serializable).
  */

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-p0.2';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
+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_MATH_SDK_VERSION = '0.3.2';  // sdk/egpt-math-sdk/package.json#version — bound by router.test.mjs; bumped with each npm publish
 
 /**
@@ -507,7 +507,7 @@ var _assertProfileParity = (function () {
  * // CDN mode (static hosting — the artifact host shell has no server, no page anchor):
  * const cdnRouter = engineRouter({ mode: 'cdn', engine: 'wasm' });
  * console.log(cdnRouter.resolve('compat/engine.js'));
- * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p0.2/dist/frqtl/compat/engine.js'
+ * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.6.0-p1.1/dist/frqtl/compat/engine.js'
  *
  * // CDN mode, self-hosted: a copy of dist/ served from the consumer's own origin:
  * const selfHosted = engineRouter({ mode: 'cdn', engine: 'wasm', base: 'https://example.org/vendor/frqtl-web/dist' });

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

@@ -185,8 +185,8 @@ var HOST_TOKENS = Object.freeze([
         why: 'chrome is a HOST-COMPOSITION decision (whether the experiment\'s own ' +
              'control chrome DOM renders), never a per-experiment physics/render ' +
              'parameter; forwarding it from an outer host URL into an embedded ' +
-             'iframe would reintroduce the hidden-experiment-chrome bug fixed in ' +
-             'WS gym-controls-as-sugar Bite 2 (the GYM must always show the ' +
+             'iframe would reintroduce the hidden-experiment-chrome bug (the GYM ' +
+             'must always show the ' +
              'experiment\'s own full chrome, never chrome=canvas — see the ' +
              '"WHEN should a host set chrome=canvas" doc above for the general ' +
              'criterion, not just the GYM\'s specific answer to it)'

package/dist/shim/project/index.js

@@ -4,16 +4,18 @@
  * 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                                 specifiers.js
+ *   linkProject, sketchProject, SKETCH_ENTRY         link.js
  *   projectIdentity                                  identity.js
  *
  * 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',
+    'linkProject', 'sketchProject', 'SKETCH_ENTRY', 'projectIdentity']);
 
-export { FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor } from './specifiers.js';
-export { linkProject } from './link.js';
+export { FRQTL_WEB_SPECIFIERS, libPathOf, importMapFor, pageImportMapFor } from './specifiers.js';
+export { linkProject, sketchProject, SKETCH_ENTRY } from './link.js';
 export { projectIdentity } from './identity.js';

package/dist/shim/project/link.js

@@ -4,7 +4,7 @@
  * 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.
  *
- *   linkProject(project) → Promise<{ buildExperiment, files }>   files: { path: Uint8Array } — the bytes linked
+ *   linkProject(project) → Promise<{ buildExperiment, files, urls, project }>   files: { path: Uint8Array } — the bytes linked
  *     project = { files: { 'sketch.js': text, 'parts/X.js': text, … }, entry, mint, bare? }
  *             | { url: '<served folder>/', entry, mint?, bare? }
  *       url    absolute, or relative to the document's base URL in a page ('./'); ends in "/"
@@ -18,8 +18,12 @@
  *              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, files, urls, project } — files is the project's BYTES by path (fetched, for a
+ *       served folder; the UTF-8 encoding of each text, for a file map), the input of projectIdentity
+ *       (identity.js); urls is each file's minted URL by path (a forked part registers its kind `from` that
+ *       URL — lib/shim/project/parts-module.js maps it back to the path); project is the linked project as
+ *       TEXT — { files: { path: text }, entry, mint, bare? } — what a facade holds and re-links
+ *       (RecipeContext.build(linked)). A served folder's project is its decoded files.
  *
  * In a project, a file imports another project file by a RELATIVE specifier, and the package by
  * `@descix/frqtl-web/...`; nothing else. Relative specifiers are rewritten to the minted URLs of the files
@@ -242,7 +246,8 @@ function _entryFunction(ns, entry) {
 
 /**
  * @param {object} project — see the file header
- * @returns {Promise<{buildExperiment: function, files: Object<string, string>}>}
+ * @returns {Promise<{buildExperiment: function, 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') {
@@ -334,7 +339,9 @@ 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: g.files, entry: entry, mint: mint };
+        if (project.bare !== undefined) { held.bare = project.bare; }
+        return { buildExperiment: _entryFunction(ns, entry), files: g.bytes, urls: Object.assign({}, urls), project: held };
     } finally {
         for (const m of minted) { if (typeof m.release === 'function') { m.release(); } }
     }

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