@descix/frqtl-node 0.7.0-p1 → 0.7.0-p3

package/CLAUDE.md

@@ -2,7 +2,7 @@
 
 A discrete cellular-automata physics engine (compiled Rust → WASM) for node: the same modules as
 `@descix/frqtl-web` (one source, built twice), plus the node engine door `bootNode` and the hosted eyes.
-`0.7.0-p1` (npm dist-tag `next`). Node ≥ 22.12. See it run: https://egpt-frqtl.descix.net
+`0.7.0-p3` (npm dist-tag `next`). Node ≥ 22.12. See it run: https://egpt-frqtl.descix.net
 
 ## Install
   npm install @descix/frqtl-node

package/README.md

@@ -4,7 +4,7 @@ FRQTL for node: a discrete cellular-automata physics engine (compiled Rust → W
 local per-pixel rules — a frame moves one pixel per tick, single occupancy, momentum — rather than force
 equations. Interference, blackbody spectra and atom-like binding emerge from the automaton.
 
-`0.7.0-p1` (npm dist-tag `next`). Node ≥ 22.12. See it run: https://egpt-frqtl.descix.net (the showcase scenes in
+`0.7.0-p3` (npm dist-tag `next`). Node ≥ 22.12. See it run: https://egpt-frqtl.descix.net (the showcase scenes in
 STUDIO and the GYM).
 
 ## Install

package/dist/dist-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/frqtl-node",
-  "version": "0.7.0-p1",
+  "version": "0.7.0-p3",
   "files": {
     "eyes/index.js": "b3563421030bb7fdd277eb697959fbe9107463cbb5478160edc7d887daa67be3",
     "fat/pkg-node/egpt_wasm.js": "5e6af1f6725c93c0e9ad7386f1785cbe639ce596a4caa19ca85729c1f2bea04d",
@@ -137,14 +137,15 @@
     "shim/controls/registry.js": "3df843d774968d18e012624f2aba2fb09b08ede9e21b6c1f6687d4f3e9b46d3e",
     "shim/engine/boot-phases.js": "c6e12e12824bcf6f1a289f46e41c898a5416c80c131594525145aae9a3eefbfa",
     "shim/engine/engine-stack-boot.js": "0abf57dcff2ca2bb025c787a17875d49d54d9218ac08c78cb9c678dbb6118d08",
-    "shim/engine/router.js": "59092b6bf0474bbd0d55300dd8d3574ce6ad03fb55a0a0af5e7cceb6d365ac9c",
+    "shim/engine/router.js": "dcb0289143fc86dc74be1f5921695f75c026741496ac19e902b905be3ccf409a",
     "shim/engine/site-assemble.mjs": "37c9915c34b102daa8fe6389f8d66a1e3379e074e87d2ad79b0cff7a81a2d4b6",
     "shim/engine/site-graph.js": "4d5e5f9ecc2cefcf30eab25203178c0bb13230e9ce7f34bb3b36178f6b79dcb9",
     "shim/experiment-frame/index.js": "5a0219aaa225d8f808c405b08623ce85ada37d83fb4f55f983db3303e431e47f",
     "shim/expr/ast-schema.js": "4f1133b887639bbd86fab976292323bf4a955cdc873ff7ca8e8a8eb3b416923f",
     "shim/field-descriptor/index.js": "050091a9cab0bd37b32b5d8a52fc9bca3b42a089c188d7e49a11cf88b5c069f7",
     "shim/frame-data/index.js": "df6957b0b4a8e0ee0035bc970647b90089b421ae7f05911cc047d48457164be6",
-    "shim/host/device.js": "281e7e7ec4d8164a5a9f6d8de64be7ca0781a262d23efa0b43b6cf1fdbfd797e",
+    "shim/host/device.js": "67bcc932f31ddd08ef7667344f5f8894badd4d9dfd3e767c72d9e1dd327f54bd",
+    "shim/host/host-auth.js": "dabf305a2329227f0592a588681e20dd78063a85919ee1685d2a9b01dfe5ebcf",
     "shim/host/host-view.js": "feec2f5fdc318e75cd01768c24891f85d2694a269696fcfffd9567d31983cf43",
     "shim/host/index.js": "fade4b171218965570aa2e67e841920ebb3d972ff15e1cfa0394fd3fa123d82c",
     "shim/index.js": "dd3708d4935e597d9ca46a23077064bd1f460bb1e86315372c9d147bdfb3f0d1",
@@ -186,7 +187,7 @@
     "shim/registry/roster-link.js": "7c079eec1350640c8399e16f2515e1cdfb5c6cd31f77c16dfda85ec782a538d0",
     "shim/registry/roster.js": "df0dcc70d4c2202913a1e3e8788e9f1907ad63e43150c85960ebdfe9864d53db",
     "shim/registry/scene-source.js": "913ef72fc7caeeafc2eb6a28a2dcced752579e63c83b48d51f5bf36f67c55a88",
-    "shim/registry/studio-landing.js": "115294cd43b96c8a4892dd74eb58bdee096baf520cc655e589300f9bc1dfb724",
+    "shim/registry/studio-landing.js": "db2d76a241935828495ed063e6220026a13b80df402672b9ed960c128871b16e",
     "shim/render-state/apply.js": "94a9e60cb1722c9a82aa00f2f161fd65e6f438147333856a786e42a4ad5b7064",
     "shim/render-state/index.js": "72a6a3dcd8037893cb8fbd7ef32b126770e7efaec70847f8e4f2915ddb690b43",
     "shim/render/capture-envelope.js": "74db53dbc8c87d1b52452bcb858b1cc5210593062fec0b98609cd59cab63777a",

package/dist/shim/engine/router.js

@@ -152,7 +152,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.7.0-p1';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
+var CDN_SDK_VERSION = '0.7.0-p3';  // sdk/frqtl-web/package.json#version (the ONE version owner) — bound by router.test.mjs
 var CDN_MATH_SDK_VERSION = '0.3.3-p2.1';  // sdk/egpt-math-sdk/package.json#version — bound by router.test.mjs; bumped with each npm publish
 
 /**
@@ -526,7 +526,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.7.0-p1/dist/frqtl/compat/engine.js'
+ * // 'https://cdn.jsdelivr.net/npm/@descix/frqtl-web@0.7.0-p3/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/device.js

@@ -11,7 +11,7 @@
  *                         page (an app framed by the DeSciX shell measures its own frame). A window without
  *                         matchMedia THROWS: every browser has it, so its absence is a caller passing the wrong object.
  *
- * Its three consumers ask it once each, at load:
+ * Its four consumers ask it once each, at load:
  *   - the host-view call site (lib/features/ide/studio/host-view-entry.js) asks the shell for NoChrome on a phone, CodeSite
  *     elsewhere;
  *   - STUDIO (lib/features/ide/AuthorView.jsx) opens with its side panels collapsed on a phone and puts its Hand tool
@@ -19,6 +19,8 @@
  *     surface (lib/features/ide/studio-try-it.js);
  *   - FraqtlIde (lib/features/ide/index.jsx) opens the STUDIO tab card with the controls of that surface
  *     (presets.js presetExplainerFor).
+ *   - the IDE header's Sign In control (lib/features/ide/sign-in.js) shows only on a phone, where the shell's
+ *     full-screen view hides the shell's own Sign In.
  * The static build compiles it into both: the stable host-view entry is bundled as its own self-contained module
  * (apps/ide/vite.config.js frqtl-host-view-entry), the IDE's rollup graph carries its own copy of the same source.
  *

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

@@ -0,0 +1,176 @@
+/* Copyright 2023-2026 by Essam Abadir */
+
+/**
+ * host-auth.js — the ONE follower of the DeSciX shell's session for an app DOCUMENT.
+ *
+ * Behind the DeSciX App Shell, `DeSciX.powch.on('auth', cb)` calls `cb` once at once with the current state and then
+ * on every change, with `{ signedIn: boolean, address: string|null }`; it returns the unsubscribe
+ * (@descix/app-sdk 0.8.0 APP_SHELL_API.md §"DeSciX.powch — identity and wallet"). `DeSciX.powch.login()` opens Powch;
+ * on success the SHELL routes itself, so the app never redirects. This module follows that session for a caller and
+ * records which host state it met on `document.documentElement.dataset.descixAuth` (a HOST_AUTH_STATES row). The
+ * control that shows it, and where, is the call site's policy (lib/features/ide/sign-in.js).
+ *
+ * Order of operations, from the published contract:
+ *   - `powch` is read only after `ready()` resolved `mode:'shell'` AND its `members` names `powch` (the SDK's member
+ *     getters console.error where the member is absent — the same rule lib/shim/host/host-view.js follows for `view`).
+ *   - `powch` is read off the bus at the point of use (the bus object is replaced when the shell reaches READY), so
+ *     `login` is looked up at the tap, never captured at load.
+ *
+ * A host with no session to follow is a STATE (no SDK, no shell, a shell without Powch), never an error. A host that
+ * breaks the published shape is a defect: it THROWS a TypeError naming the contract, and the record says
+ * `contract-violated`.
+ *
+ * Host-neutral ESM with no imports. It is NOT part of the stable host-view entry (that bundle carries host-view.js
+ * and device.js only).
+ */
+
+/** Where the bridge calls this module relies on are published. */
+export const HOST_AUTH_CONTRACT = '@descix/app-sdk 0.8.0 APP_SHELL_API.md §"DeSciX.powch — identity and wallet"';
+
+/** The closed table of host session states. `session` is true where the shell holds a session the app can show. */
+export const HOST_AUTH_STATES = Object.freeze([
+    { id: 'pending', session: false, means: 'awaiting DeSciX.ready()' },
+    { id: 'sdk-absent', session: false, means: 'window.DeSciX is undefined: no publisher-provided DeSciXAppSDK.js beside this page (dev, a plain static host)' },
+    { id: 'unmanaged', session: false, means: 'ready() resolved standalone or embedded-no-bridge: no readable shell above this page, nothing to sign into' },
+    { id: 'powch-unpublished', session: false, means: 'the shell resolved, but its members do not include powch' },
+    { id: 'signed-out', session: true, means: 'powch.on(auth) reported signedIn false' },
+    { id: 'signed-in', session: true, means: 'powch.on(auth) reported signedIn true' },
+    { id: 'contract-violated', session: false, means: 'the SDK or shell broke the published shape; the edge is in dataset.descixAuthDetail and a TypeError was thrown' },
+].map(Object.freeze));
+
+const STATE_IDS = new Set(HOST_AUTH_STATES.map((r) => r.id));
+
+function defaultRoot() {
+    return typeof document !== 'undefined' ? document.documentElement : null;
+}
+
+function record(root, id, detail) {
+    if (!STATE_IDS.has(id)) { throw new Error(`host-auth: '${id}' is not a HOST_AUTH_STATES row`); }
+    if (root) {
+        root.dataset.descixAuth = id;
+        if (detail === undefined) { delete root.dataset.descixAuthDetail; } else { root.dataset.descixAuthDetail = detail; }
+    }
+    return id;
+}
+
+function violation(root, edge) {
+    record(root, 'contract-violated', edge);
+    return new TypeError(`host-auth: ${edge} — the published contract is ${HOST_AUTH_CONTRACT}. (FAIL-LOUD.)`);
+}
+
+function liveMode(sdk) {
+    try { return sdk.mode; } catch (e) { return undefined; }
+}
+
+/** The auth payload, checked against the published shape. */
+function sessionOf(s) {
+    if (!s || typeof s !== 'object' || typeof s.signedIn !== 'boolean') {
+        return { edge: 'powch.on(auth) delivered ' + JSON.stringify(s) + ', not { signedIn: boolean, address: string|null }' };
+    }
+    if (!(s.address === null || typeof s.address === 'string')) {
+        return { edge: 'powch.on(auth) delivered address ' + JSON.stringify(s.address) + ', not a string or null' };
+    }
+    return { signedIn: s.signedIn, address: s.address };
+}
+
+/**
+ * Follow the shell's session. `onState(id, session)` runs on every state change (`session` is
+ * `{ signedIn, address }` for the two session rows, else null).
+ *
+ * @param {object} args
+ * @param {object|undefined} args.sdk   the app-side SDK object (`window.DeSciX`), or undefined
+ * @param {function(string, ?{signedIn: boolean, address: ?string}): void} args.onState
+ * @param {{dataset: object}} [args.root] where the record is written; defaults to `document.documentElement`
+ * @returns {{ stop: function(): void, settled: Promise<string> }}  `stop` unsubscribes (idempotent; safe before
+ *   ready() settles); `settled` resolves once the subscription is made (with the state the shell's immediate callback
+ *   reported, else 'pending', or the non-session row met), and REJECTS with the TypeError on a contract violation.
+ */
+export function followHostAuth({ sdk, onState, root } = {}) {
+    if (typeof onState !== 'function') { throw new TypeError('host-auth: followHostAuth needs an onState(id, session) function'); }
+    const target = root || defaultRoot();
+    let stopped = false;
+    let off = null;
+    const emit = (id, session = null, detail) => { if (!stopped) { onState(record(target, id, detail), session); } };
+    const stop = () => {
+        if (stopped) { return; }
+        stopped = true;
+        if (off) { const f = off; off = null; f(); }
+    };
+
+    if (sdk === undefined || sdk === null) {
+        emit('sdk-absent');
+        return { stop, settled: Promise.resolve('sdk-absent') };
+    }
+    if (typeof sdk.ready !== 'function') {
+        const err = violation(target, 'window.DeSciX is a ' + typeof sdk + ' without ready()');
+        return { stop, settled: Promise.reject(err) };
+    }
+
+    emit('pending');
+    const settled = (async () => {
+        let ready;
+        try {
+            ready = await sdk.ready();
+        } catch (e) {
+            if (liveMode(sdk) === 'embedded-no-bridge') { emit('unmanaged', null, 'ready() rejected: ' + (e && e.message)); return 'unmanaged'; }
+            throw violation(target, 'ready() rejected while the SDK reports mode ' + JSON.stringify(liveMode(sdk)) + ': ' + (e && e.message));
+        }
+        const mode = ready && ready.mode;
+        if (mode === 'standalone' || mode === 'embedded-no-bridge') { emit('unmanaged', null, 'ready() resolved ' + mode); return 'unmanaged'; }
+        if (mode !== 'shell') { throw violation(target, 'ready() resolved mode ' + JSON.stringify(mode)); }
+        if (!Array.isArray(ready.members)) { throw violation(target, 'ready() resolved shell without a members array'); }
+        if (!ready.members.includes('powch')) {
+            emit('powch-unpublished', null, 'members: ' + ready.members.join(','));
+            return 'powch-unpublished';
+        }
+        if (stopped) { return 'pending'; }
+        const powch = sdk.powch;
+        if (!powch) { throw violation(target, 'members names powch; the getter returned ' + String(powch)); }
+        if (typeof powch.on !== 'function') { throw violation(target, 'powch.on is ' + typeof powch.on); }
+
+        let fault = null;
+        let first = null;
+        const cb = (s) => {
+            const got = sessionOf(s);
+            if (got.edge) {
+                // The shell logs a throwing subscriber and keeps the others running (the published contract).
+                fault = violation(target, got.edge);
+                if (off) { const f = off; off = null; f(); }
+                if (!stopped) { onState('contract-violated', null); }
+                throw fault;
+            }
+            const id = got.signedIn ? 'signed-in' : 'signed-out';
+            if (first === null) { first = id; }
+            emit(id, got);
+        };
+        let unsubscribe;
+        try {
+            unsubscribe = powch.on('auth', cb);
+        } catch (e) {
+            if (fault) { throw fault; }
+            throw violation(target, 'powch.on(auth) threw: ' + (e && e.message));
+        }
+        if (typeof unsubscribe !== 'function') { throw violation(target, 'powch.on(auth) returned ' + typeof unsubscribe + ', not the unsubscribe function'); }
+        off = unsubscribe;
+        if (fault) { const f = off; off = null; f(); throw fault; }
+        if (stopped) { const f = off; off = null; f(); }
+        // The first state is whatever the shell's immediate callback reported; 'pending' until it arrives.
+        return first || 'pending';
+    })();
+    return { stop, settled };
+}
+
+/**
+ * Open Powch's sign-in through the shell. `powch` and its `login` are read HERE, at the tap.
+ * @param {object} sdk  the app-side SDK object (`window.DeSciX`)
+ * @returns {Promise<unknown>} what `powch.login()` returns
+ * @throws {TypeError} a shell without a powch.login function (the control is only shown on a session row)
+ */
+export function hostSignIn(sdk) {
+    const powch = sdk && sdk.powch;
+    if (!powch || typeof powch.login !== 'function') {
+        throw new TypeError('host-auth: hostSignIn found no DeSciX.powch.login function at the tap — the published ' +
+            'contract is ' + HOST_AUTH_CONTRACT + '. (FAIL-LOUD.)');
+    }
+    return powch.login();
+}

package/dist/shim/registry/studio-landing.js

@@ -8,10 +8,13 @@
  * its error copy.
  *
  *   STUDIO_LANDING_ATTR          the <html> attribute carrying the outcome id
- *   STUDIO_LANDING_OUTCOMES      the closed table: one row per branch of STUDIO's link resolution, `{ id, runs, means }`;
- *                                `runs` says whether the scene that landing opens starts on load (through STUDIO's Run
- *                                control's own path) — true only on `ok`, a deep link that named a scene; every other
- *                                landing opens its scene in Design, waiting for Run
+ *   STUDIO_LANDING_OUTCOMES      the closed table: one row per branch of STUDIO's link resolution, `{ id, runs, cards,
+ *                                means }`; `runs` says whether the scene that landing opens starts on load (through
+ *                                STUDIO's Run control's own path) — true only on `ok`, a deep link that named a scene;
+ *                                every other landing opens its scene in Design, waiting for Run. `cards` says whether
+ *                                the landing offers the showcase cards (and the try-it) of the roster scene it opens —
+ *                                true on `ok` and on `first-contact`, so a bare STUDIO open offers what that scene's
+ *                                deep link offers; a landing that opens no roster scene offers none
  *   recordStudioLanding(root, id) writes `id` on `root` (an Element, or null to only validate); an id outside the
  *                                table THROWS — that is a defect in the writer, never a landing
  *
@@ -32,31 +35,31 @@ export const STUDIO_LANDING_ATTR = 'data-frqtl-studio-landing';
 
 /** The closed table of STUDIO deep-link landings, in the order the resolver tests them (lib/features/ide/test/studio-landing-of.test.mjs holds it). */
 export const STUDIO_LANDING_OUTCOMES = Object.freeze([
-    { id: 'refused-key', runs: false,
+    { id: 'refused-key', runs: false, cards: false,
       means: 'the link carries a key STUDIO does not own, or a deleted key (deep-link.js deepLinkRefusalOf): the refusal is on the deep-link strip and the opening scene opens' },
-    { id: 'conflict', runs: false,
+    { id: 'conflict', runs: false, cards: false,
       means: 'the link names more than one scene source (two of walkthrough, project and scene), or a renderer beside a walkthrough or a project, which carry their own: nothing opens' },
-    { id: 'mode-without-walkthrough', runs: false,
+    { id: 'mode-without-walkthrough', runs: false, cards: false,
       means: 'the link names a mode and no walkthrough: nothing opens' },
-    { id: 'renderer-without-scene', runs: false,
+    { id: 'renderer-without-scene', runs: false, cards: false,
       means: 'the link names a renderer and no scene; a renderer is chosen only for a scene link: nothing opens' },
-    { id: 'unknown-walkthrough', runs: false,
+    { id: 'unknown-walkthrough', runs: false, cards: false,
       means: 'the linked walkthrough is not a scene of the loaded roster (walkthroughById(roster, id)): nothing opens' },
-    { id: 'unknown-mode', runs: false,
+    { id: 'unknown-mode', runs: false, cards: false,
       means: 'the linked mode is not one the linked scene declares (walkthroughModes): nothing opens' },
-    { id: 'scene-refused-origin', runs: false,
+    { id: 'scene-refused-origin', runs: false, cards: false,
       means: 'the linked scene URL is on neither the page\'s origin nor the roster\'s (roster-link.js sceneOriginRefusalOf): the strip names the rule and both origins; nothing opens' },
-    { id: 'scene-unreadable', runs: false,
+    { id: 'scene-unreadable', runs: false, cards: false,
       means: 'the linked scene URL is allowed but its read failed (a non-200, an empty body, or not a .js sketch): nothing opens' },
-    { id: 'project-unreadable', runs: false,
+    { id: 'project-unreadable', runs: false, cards: false,
       means: 'the linked saved project is present but its folder is refused by the load: nothing opens' },
-    { id: 'project-not-found', runs: false,
+    { id: 'project-not-found', runs: false, cards: false,
       means: 'no saved project of the linked name in this browser: nothing opens' },
-    { id: 'ok', runs: true,
+    { id: 'ok', runs: true, cards: true,
       means: 'the linked walkthrough (in the linked mode, else its default), saved project or scene resolved and was handed to STUDIO\'s selection path; the scene starts on load' },
-    { id: 'first-contact', runs: false,
-      means: 'no STUDIO deep link: the roster\'s first-contact scene (firstContactOf(roster)) opens' },
-    { id: 'first-contact-empty', runs: false,
+    { id: 'first-contact', runs: false, cards: true,
+      means: 'no STUDIO deep link: the roster\'s first-contact scene (firstContactOf(roster)) opens, offering its showcase cards and try-it as its deep link does' },
+    { id: 'first-contact-empty', runs: false, cards: false,
       means: 'no STUDIO deep link and the roster declares no first contact: the Empty Universe opens' },
 ].map(Object.freeze));
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @descix/frqtl-node
 
 > The FRQTL physics engine (compiled Rust → WASM) for node: the same modules as @descix/frqtl-web, plus
-> `bootNode` and the hosted eyes. 0.7.0-p1 on npm dist-tag `next`. Node ≥ 22.12.
+> `bootNode` and the hosted eyes. 0.7.0-p3 on npm dist-tag `next`. Node ≥ 22.12.
 
 - Install: `npm install @descix/frqtl-node`
 - `import { bootNode, Wall } from '@descix/frqtl-node'` (require() works too); `await bootNode()` → the engine handle.
@@ -11,5 +11,5 @@
 - See it run: https://egpt-frqtl.descix.net
 - `./host-view`: `declareHostView`, `HOST_VIEW_OUTCOMES`, `CONTRACT_VIOLATIONS`, `HOST_SDK_SCRIPT` — the same declarer as @descix/frqtl-web/host-view, pure, for a node test of a call site.
 - `./register`: `node --import @descix/frqtl-node/register scene.mjs` resolves a scene's `@descix/frqtl-web/...` imports to this package.
-- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.7.0-p1/CLAUDE.md
+- Full agent guide: https://cdn.jsdelivr.net/npm/@descix/frqtl-node@0.7.0-p3/CLAUDE.md
 - Acceptance is visual; no CLI ships. No account, credits or tokens are needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descix/frqtl-node",
-  "version": "0.7.0-p1",
+  "version": "0.7.0-p3",
   "description": "FRQTL for node \u2014 the discrete fractal physics engine (compiled Rust \u2192 WASM), its parts as ES modules, the node engine door (bootNode) and the hosted eyes.",
   "type": "module",
   "engines": {