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

package/dist/shim/bundle/manifest.js

@@ -1,95 +0,0 @@
-/* Copyright 2023-2026 by Essam Abadir */
-
-/**
- * lib/shim/bundle/manifest.js — the bundle manifest as an ENVELOPE FERRY
- * (E1).
- *
- * ── The rule (E1): manifest = the Module envelope minus `source` ─────────────
- *
- * The bundle is a projection of the `lib/shim/storage/modules.js` Module
- * envelope. `experiment.js` = `module.source`. The manifest carries EVERYTHING
- * ELSE from the envelope, ferried VERBATIM (`{...envelope}` minus `source`) plus
- * a small set of bundle-only fields. Critically this module NEVER re-enumerates
- * the envelope's field list (`{name: mod.name, renderState: mod.renderState, …}`)
- * — that would be a schema mirror of modules.js. It spreads the whole envelope
- * and deletes the ONE key (`source`) the sibling `experiment.js` file owns. Any
- * field modules.js adds in future rides through automatically; `renderState`
- * rides through as an ordinary envelope field, opaque (never parsed here).
- *
- * ── Bundle-only fields ───────────────────────────────────────────────────────
- *
- *   sdkVersion : string  — the `@descix/frqtl-web@<pin>` the index.html imports.
- *                          A VALUE passed IN by the caller (the feature side
- *                          DERIVES it from the built SDK's package.json at export
- *                          time — truth-in-labeling; NEVER a literal in bundle
- *                          code). REQUIRED — FAIL-LOUD when absent.
- *   preview    : string|null — the preview image filename ref (e.g. 'preview.png'),
- *                          or null when no preview was captured.
- *   descix     : {}      — reserved inert publish block (DeSciX now-vs-later).
- *
- * Layer 2 (physics): none — pure metadata projection.
- */
-
-'use strict';
-
-/** The envelope key the sibling `experiment.js` file owns (never in the manifest). */
-export var SOURCE_KEY = 'source';
-
-/** Bundle-only manifest keys (NOT envelope fields — stripped on import). */
-export var BUNDLE_ONLY_KEYS = ['sdkVersion', 'preview', 'descix'];
-
-/**
- * Build the manifest object from a Module envelope + bundle-only inputs.
- *
- * @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|null} [opts.preview] — preview filename ref, or null/omitted.
- * @returns {object} the manifest (JSON-serializable).
- */
-export function buildManifest(envelope, opts) {
-    if (!envelope || typeof envelope !== 'object') {
-        throw new Error('[bundle/manifest] buildManifest(envelope): envelope must be an object.');
-    }
-    opts = opts || {};
-    if (typeof opts.sdkVersion !== 'string' || opts.sdkVersion.length === 0) {
-        throw new Error('[bundle/manifest] buildManifest: opts.sdkVersion is REQUIRED (a derived value, ' +
-            'never a literal) — the index.html CDN pin depends on it.');
-    }
-
-    // Ferry the WHOLE envelope minus `source` (no per-field re-enumeration).
-    var manifest = Object.assign({}, envelope);
-    delete manifest[SOURCE_KEY];
-
-    // Bundle-only fields.
-    manifest.sdkVersion = opts.sdkVersion;
-    manifest.preview = (opts.preview != null) ? opts.preview : null;
-    manifest.descix = {};   // reserved inert publish block
-
-    return manifest;
-}
-
-/**
- * Recover the Module envelope from a manifest + the `experiment.js` source.
- * Inverse of `buildManifest`: strips the bundle-only fields and re-attaches
- * `source`. The result is a full Module envelope (validatable by modules.js).
- *
- * @param {object} manifest — the parsed manifest.json object.
- * @param {string} source   — the `experiment.js` recipe source.
- * @returns {object} the reconstructed Module envelope.
- */
-export function manifestToEnvelope(manifest, source) {
-    if (!manifest || typeof manifest !== 'object') {
-        throw new Error('[bundle/manifest] manifestToEnvelope(manifest): manifest must be an object.');
-    }
-    if (typeof source !== 'string') {
-        throw new Error('[bundle/manifest] manifestToEnvelope: source (experiment.js) must be a string.');
-    }
-    var envelope = Object.assign({}, manifest);
-    for (var i = 0; i < BUNDLE_ONLY_KEYS.length; i++) {
-        delete envelope[BUNDLE_ONLY_KEYS[i]];
-    }
-    envelope[SOURCE_KEY] = source;
-    return envelope;
-}

package/dist/shim/storage/modules.js

@@ -1,249 +0,0 @@
-/* Copyright 2023-2026 by Essam Abadir */
-
-/**
- * lib/shim/storage/modules.js — Experiment module (.js text) storage helpers.
- *
- * Defines the Module envelope shape and CRUD helpers that operate on top of
- * any StorageProvider (lib/shim/storage/index.js) using the "files" namespace.
- *
- * ── Module envelope ────────────────────────────────────────────────────────
- *
- *   {
- *     id:            string               — unique identifier (newModuleId())
- *     name:          string               — human-readable module name
- *     language:      'javascript'
- *     source:        string               — the .js module text
- *     templateId:    string|null          — origin experiment id or null if blank
- *     kind:          'frqtl' | 'math'     — which SDK the recipe targets (v2+)
- *     createdAt:     string               — ISO-8601 creation timestamp
- *     updatedAt:     string               — ISO-8601 last-updated timestamp
- *     schemaVersion: number               — integer version (see MODULE_SCHEMA_VERSION,
- *                    the authority; currently 4)
- *     scripts:       string[]             — v4+. OPAQUE frqtl-relative setup-factory
- *                    delta the load path injects (engineRouter.resolve) BEFORE
- *                    eval, so a ferried recipe whose source calls a setup factory
- *                    (a walk-through rung) resolves that window global. `[]`/absent
- *                    for an ordinary saved project (DX-3, the rung-source ferry).
- *     renderState:   object|null          — v3+. Studio's Save realignment
- *                    (Studio Controls Realignment §2.6) capture bag —
- *                    everything the .js recipe itself does NOT round-trip:
- *                    renderer/seed (load-time), render capability
- *                    values + camera + backdrop visibility + bind-backed
- *                    page-level control values (runtime replay). Shape owned
- *                    by `lib/features/ide/save-state.js`'s
- *                    `normalizeSavedRenderState` — this module does NOT
- *                    re-validate its internal shape (an optional, best-effort
- *                    replay bag, never load-bearing for the recipe itself);
- *                    `null`/absent is the pre-S6 legacy state and stays
- *                    perfectly valid (R6 discipline extended to v3).
- *   }
- *
- * ── Schema migration ────────────────────────────────────────────────────────
- *
- *   v1 → v2: `kind` field added.  Legacy v1 envelopes (no `kind` field) are
- *   read without error and default to `kind:'frqtl'` (R6 binding: must never
- *   throw on legacy envelopes).  The `kind` field is the ONLY new field (AM-2).
- *
- *   v2 → v3: `renderState` field added (Studio Controls Realignment §2.6,
- *   S6). Legacy v1/v2 envelopes (no `renderState` field) are read without
- *   error and default to `renderState: null` (R6 extended) — a saved project
- *   from before S6 simply replays with NO render/camera/page-control
- *   state (byte-identical to its own pre-S6 behavior), never a throw.
- *
- * ── Namespace ──────────────────────────────────────────────────────────────
- *
- *   All helpers use the "files" namespace.  Keys are module ids.
- *
- * ── Usage ──────────────────────────────────────────────────────────────────
- *
- *   import { newModuleId, saveModule, loadModule,
- *            listModules, deleteModule } from 'lib/shim/storage/modules.js';
- *   import { getProvider } from 'lib/shim/storage';
- *
- *   const provider = getProvider();
- *
- *   const id = newModuleId();
- *   const mod = {
- *     id,
- *     name: 'My wave experiment',
- *     language: 'javascript',
- *     source: 'function buildExperiment(exp) { ... }',
- *     templateId: 'double-slit',
- *     kind: 'frqtl',          // or 'math' for EGPTMath recipes
- *     createdAt: new Date().toISOString(),
- *     updatedAt: new Date().toISOString(),
- *     schemaVersion: 2,
- *   };
- *   saveModule(provider, mod);
- *
- *   const loaded = loadModule(provider, id);
- *   const all    = listModules(provider);
- *   deleteModule(provider, id);
- */
-
-'use strict';
-
-import { makeNamespaceStore } from './make-namespace-store.js';
-
-/** @type {string} The storage namespace for all module records. */
-export var MODULES_NAMESPACE = 'files';
-
-/** @type {number} Current schema version.  Increment on breaking envelope changes. */
-export var MODULE_SCHEMA_VERSION = 4;
-
-// ── Envelope validation ────────────────────────────────────────────────────
-
-function _validateModule(mod) {
-  if (!mod || typeof mod !== 'object') {
-    throw new Error('[modules] module must be a non-null object');
-  }
-  if (typeof mod.id !== 'string' || mod.id.length === 0) {
-    throw new Error('[modules] module.id must be a non-empty string');
-  }
-  if (typeof mod.name !== 'string' || mod.name.length === 0) {
-    throw new Error('[modules] module.name must be a non-empty string');
-  }
-  if (typeof mod.source !== 'string') {
-    throw new Error('[modules] module.source must be a string');
-  }
-  if (mod.source.length === 0) {
-    throw new Error('[modules] module.source must not be empty');
-  }
-  if (mod.templateId !== null && typeof mod.templateId !== 'string') {
-    throw new Error('[modules] module.templateId must be a string or null');
-  }
-  if (mod.kind !== 'frqtl' && mod.kind !== 'math') {
-    throw new Error('[modules] module.kind must be "frqtl" or "math"');
-  }
-  if (typeof mod.schemaVersion !== 'number') {
-    throw new Error('[modules] module.schemaVersion must be a number');
-  }
-  // renderState (v3+) is OPTIONAL and best-effort (see envelope doc above) —
-  // the only shape check here is "object or null/undefined", never a deep
-  // validation of its internal fields (that tolerance lives in save-state.js's
-  // own normalizeSavedRenderState, applied at REPLAY time, not at save time).
-  if (mod.renderState !== undefined && mod.renderState !== null &&
-      (typeof mod.renderState !== 'object' || Array.isArray(mod.renderState))) {
-    throw new Error('[modules] module.renderState must be an object, null, or omitted');
-  }
-  // scripts (v4+) is OPTIONAL — an OPAQUE frqtl-relative setup-factory delta the
-  // load path injects (engineRouter.resolve) BEFORE eval, so a recipe whose source
-  // calls a setup factory (e.g. a ferried walk-through rung) resolves that global.
-  // Shape check only: an array of strings, or omitted. The loaders own the
-  // resolution + FAIL-LOUD injection, not this schema.
-  if (mod.scripts !== undefined && mod.scripts !== null) {
-    if (!Array.isArray(mod.scripts) || !mod.scripts.every(function (s) { return typeof s === 'string'; })) {
-      throw new Error('[modules] module.scripts must be an array of strings, null, or omitted');
-    }
-  }
-}
-
-// ── v1 → v2 migration ─────────────────────────────────────────────────────
-
-/**
- * Migrate a raw stored envelope to the current schema version.
- * Safe to call on already-current envelopes (idempotent).
- *
- * v1 → v2: default `kind` to `'frqtl'` when the field is absent.
- *   R6 (binding): this must NEVER throw on legacy v1 envelopes.
- *
- * v2 → v3: default `renderState` to `null` when the field is absent
- *   (Studio Controls Realignment §2.6, S6). R6 extended: never throw on
- *   a legacy v1/v2 envelope with no `renderState` field.
- *
- * v3 → v4: default `scripts` to `[]` when the field is absent (DX-3 —
- *   the rung-source ferry). R6 extended again: never throw on
- *   a legacy envelope with no `scripts` field (an ordinary saved project has none).
- *
- * @param {object} mod  Raw object from storage.
- * @returns {object}    Envelope at the current schema version.
- */
-function _migrate(mod) {
-  if (!mod || typeof mod !== 'object') { return mod; }
-  var patch = {};
-  if (mod.kind === undefined || mod.kind === null) { patch.kind = 'frqtl'; }
-  if (mod.renderState === undefined) { patch.renderState = null; }
-  if (mod.scripts === undefined) { patch.scripts = []; }
-  if (Object.keys(patch).length === 0) { return mod; }
-  return Object.assign({}, mod, patch);
-}
-
-// ── kind filter ────────────────────────────────────────────────────────────
-
-function _kindFilter(mod, opts) {
-  var kindFilter = (opts && opts.kind) ? opts.kind : null;
-  if (kindFilter !== null && mod.kind !== kindFilter) { return false; }
-  return true;
-}
-
-// ── Summary projection ─────────────────────────────────────────────────────
-
-function _summaryFields(mod) {
-  // Skip malformed records that are missing required summary fields.
-  if (typeof mod.name !== 'string') { return null; }
-  return {
-    id:         mod.id,
-    name:       mod.name,
-    kind:       mod.kind,
-    templateId: mod.templateId || null,
-    updatedAt:  mod.updatedAt  || '',
-  };
-}
-
-// ── Store instance ─────────────────────────────────────────────────────────
-
-var _store = makeNamespaceStore({
-  namespace:     MODULES_NAMESPACE,
-  schemaVersion: MODULE_SCHEMA_VERSION,
-  idPrefix:      'mod_',
-  validate:      _validateModule,
-  summaryFields: _summaryFields,
-  migrate:       _migrate,
-  listFilter:    _kindFilter,
-});
-
-// ── Public API (names and signatures unchanged) ────────────────────────────
-
-/**
- * Generate a new unique module id.
- * @returns {string}  e.g. "mod_lxyz0abc1234"
- */
-export var newModuleId = _store.newId;
-
-/**
- * Save (create or update) a module.
- * @param {import('./index.js').StorageProvider} provider
- * @param {object} mod
- * @throws {Error} on validation failure or provider write failure.
- */
-export var saveModule = _store.save;
-
-/**
- * Load a module by id.
- * Legacy v1 envelopes (no `kind` field) are migrated transparently (R6).
- * @param {import('./index.js').StorageProvider} provider
- * @param {string} id
- * @returns {object|null}
- */
-export var loadModule = _store.load;
-
-/**
- * List modules, returning summary objects suitable for a module picker.
- *
- * Returns an array of { id, name, kind, templateId, updatedAt } objects.
- * Sorted by updatedAt descending.
- * AM-2 (binding): filtering via opts.kind — pass to restrict, omit for all.
- *
- * @param {import('./index.js').StorageProvider} provider
- * @param {object}  [opts]
- * @param {'frqtl'|'math'|undefined} [opts.kind]
- * @returns {Array<{id: string, name: string, kind: string, templateId: string|null, updatedAt: string}>}
- */
-export var listModules = _store.list;
-
-/**
- * Delete a module by id.  No-op if absent.
- * @param {import('./index.js').StorageProvider} provider
- * @param {string} id
- */
-export var deleteModule = _store['delete'];

package/dist/shim/storage/projects.js

@@ -1,150 +0,0 @@
-/* Copyright 2023-2026 by Essam Abadir */
-
-/**
- * lib/shim/storage/projects.js — Project-envelope helpers.
- *
- * Defines the Project envelope shape and CRUD helpers that operate on top of
- * any StorageProvider (lib/shim/storage/index.js) using the "projects"
- * namespace.
- *
- * ── Project envelope ───────────────────────────────────────────────────────
- *
- *   {
- *     id:            string    — UUID-style unique identifier (newProjectId())
- *     name:          string    — human-readable project name
- *     templateId:    string|null — origin experiment id ("double-slit",
- *                                  "blackbody", etc.) or null if blank
- *     createdAt:     string    — ISO-8601 creation timestamp
- *     updatedAt:     string    — ISO-8601 last-updated timestamp
- *     schemaVersion: number    — integer version; currently 1
- *     design:        object    — opaque JSON authored by AuthorView
- *                                (do NOT interpret here — that is the
- *                                 AuthorView workstream's responsibility)
- *   }
- *
- * ── Namespace ──────────────────────────────────────────────────────────────
- *
- *   All helpers use the "projects" namespace.  Keys are project ids.
- *
- * ── Usage ──────────────────────────────────────────────────────────────────
- *
- *   import { newProjectId, saveProject, loadProject,
- *            listProjects, deleteProject } from 'lib/shim/storage/projects.js';
- *   import { getProvider } from 'lib/shim/storage';
- *
- *   const provider = getProvider();
- *
- *   const id = newProjectId();
- *   const project = {
- *     id,
- *     name: 'My first project',
- *     templateId: 'double-slit',
- *     createdAt: new Date().toISOString(),
- *     updatedAt: new Date().toISOString(),
- *     schemaVersion: 1,
- *     design: {},
- *   };
- *   saveProject(provider, project);
- *
- *   const loaded = loadProject(provider, id);
- *   const all    = listProjects(provider);
- *   deleteProject(provider, id);
- */
-
-'use strict';
-
-import { makeNamespaceStore } from './make-namespace-store.js';
-
-/** @type {string} The storage namespace for all project records. */
-export var PROJECTS_NAMESPACE = 'projects';
-
-/** @type {number} Current schema version.  Increment on breaking envelope changes. */
-export var PROJECT_SCHEMA_VERSION = 1;
-
-// ── Envelope validation ────────────────────────────────────────────────────
-
-function _validateProject(project) {
-  if (!project || typeof project !== 'object') {
-    throw new Error('[projects] project must be a non-null object');
-  }
-  if (typeof project.id !== 'string' || project.id.length === 0) {
-    throw new Error('[projects] project.id must be a non-empty string');
-  }
-  if (typeof project.name !== 'string' || project.name.length === 0) {
-    throw new Error('[projects] project.name must be a non-empty string');
-  }
-  if (project.templateId !== null && typeof project.templateId !== 'string') {
-    throw new Error('[projects] project.templateId must be a string or null');
-  }
-  if (typeof project.schemaVersion !== 'number') {
-    throw new Error('[projects] project.schemaVersion must be a number');
-  }
-  if (typeof project.design !== 'object' || project.design === null) {
-    throw new Error('[projects] project.design must be a non-null object');
-  }
-}
-
-// ── Summary projection ─────────────────────────────────────────────────────
-
-function _summaryFields(project) {
-  // Skip malformed records that are missing required summary fields.
-  if (typeof project.name !== 'string') { return null; }
-  return {
-    id:         project.id,
-    name:       project.name,
-    templateId: project.templateId || null,
-    updatedAt:  project.updatedAt  || '',
-  };
-}
-
-// ── Store instance ─────────────────────────────────────────────────────────
-
-var _store = makeNamespaceStore({
-  namespace:     PROJECTS_NAMESPACE,
-  schemaVersion: PROJECT_SCHEMA_VERSION,
-  idPrefix:      'proj_',
-  validate:      _validateProject,
-  summaryFields: _summaryFields,
-});
-
-// ── Public API (names and signatures unchanged) ────────────────────────────
-
-/**
- * Generate a new unique project id.
- * @returns {string}  e.g. "proj_lxyz0abc1234"
- */
-export var newProjectId = _store.newId;
-
-/**
- * Save (create or update) a project.
- * @param {import('./index.js').StorageProvider} provider
- * @param {object} project
- * @throws {Error} on validation failure or provider write failure.
- */
-export var saveProject = _store.save;
-
-/**
- * Load a project by id.
- * @param {import('./index.js').StorageProvider} provider
- * @param {string} id
- * @returns {object|null}
- */
-export var loadProject = _store.load;
-
-/**
- * List all projects, returning summary objects suitable for a project picker.
- *
- * Returns an array of { id, name, templateId, updatedAt } objects.
- * Sorted by updatedAt descending.
- *
- * @param {import('./index.js').StorageProvider} provider
- * @returns {Array<{id: string, name: string, templateId: string|null, updatedAt: string}>}
- */
-export var listProjects = _store.list;
-
-/**
- * Delete a project by id.  No-op if absent.
- * @param {import('./index.js').StorageProvider} provider
- * @param {string} id
- */
-export var deleteProject = _store['delete'];