feat(cadre): scaffold router navigation runtime wrapper (INT-09)

Author: hyperpolymath

affinescript-cadre/e2e/run.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+# End-to-end runtime test for the CadreRouter JS wrapper.
+
+set -uo pipefail
+cd "$(dirname "$0")"
+REPO="$(cd ../.. && pwd)"
+BIN="${AFFINESCRIPT_BIN:-$REPO/_build/default/bin/main.exe}"
+
+if [ ! -x "$BIN" ]; then
+  echo "SKIP: compiler not built ($BIN missing) — run dune build"
+  exit 0
+fi
+
+command -v node >/dev/null 2>&1 || { echo "SKIP: node not on PATH"; exit 0; }
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# Generate the Wasm router module
+"$BIN" router-bridge -o "$TMP/router.wasm"
+
+# Run the Node test
+node test.mjs "$TMP/router.wasm"

affinescript-cadre/e2e/test.mjs

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MPL-2.0
+// e2e test for the CadreRouter JS wrapper.
+
+import assert from 'node:assert/strict';
+import { CadreRouter } from '../src/CadreRouter.js';
+
+async function main() {
+  const wasmPath = process.argv[2] || './router.wasm';
+  const router = await CadreRouter.create(wasmPath, { base: import.meta.url });
+
+  // Initial State assertions
+  assert.equal(router.screenW, 1280, 'Initial screen width should be 1280');
+  assert.equal(router.screenH, 720, 'Initial screen height should be 720');
+  assert.equal(router.stackLen, 0, 'Initial stack should be empty');
+  assert.equal(router.stackTop, -1, 'Initial stack top should be -1');
+  assert.equal(router.popupTag, -1, 'Initial popup tag should be -1');
+
+  // Push a screen
+  router.push(4); // 4 = Game
+  assert.equal(router.stackLen, 1, 'Stack length should be 1 after push');
+  assert.equal(router.stackTop, 4, 'Stack top should be 4 (Game)');
+
+  // Push another screen
+  router.push(1); // 1 = CharacterSelect
+  assert.equal(router.stackLen, 2, 'Stack length should be 2 after push');
+  assert.equal(router.stackTop, 1, 'Stack top should be 1 (CharacterSelect)');
+
+  // Resize
+  router.resize(1920, 1080);
+  assert.equal(router.screenW, 1920, 'Width should be updated to 1920');
+  assert.equal(router.screenH, 1080, 'Height should be updated to 1080');
+
+  // Pop
+  router.pop();
+  assert.equal(router.stackLen, 1, 'Stack length should be 1 after pop');
+  assert.equal(router.stackTop, 4, 'Stack top should be 4 (Game) after pop');
+
+  // Popup
+  router.presentPopup(2); // 2 = Hacking
+  assert.equal(router.popupTag, 2, 'Popup tag should be 2 (Hacking)');
+  
+  router.dismissPopup();
+  assert.equal(router.popupTag, -1, 'Popup tag should be -1 after dismiss');
+
+  console.log('ALL ASSERTIONS PASS — CadreRouter ran end-to-end');
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

affinescript-cadre/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@hyperpolymath/affinescript-cadre",
+  "version": "0.1.0",
+  "description": "Router and Navigation runtime for AffineScript",
+  "type": "module",
+  "main": "src/CadreRouter.js",
+  "scripts": {
+    "test": "./e2e/run.sh"
+  },
+  "author": "Jonathan D.A. Jewell",
+  "license": "MPL-2.0"
+}

affinescript-cadre/src/CadreRouter.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MPL-2.0
+// Cadre Router runtime wrapping the affine-js loader and tea_router wasm.
+
+import { readBytes, buildImportObject } from '../../packages/affine-js/loader.js';
+
+export class CadreRouter {
+  constructor(instance) {
+    this.exports = instance.exports;
+  }
+
+  /**
+   * Initialize a new CadreRouter instance from a WASM module.
+   * @param {string | URL} wasmSource 
+   * @param {{ base?: string | URL }} options 
+   */
+  static async create(wasmSource, options = {}) {
+    const bytes = await readBytes(wasmSource, options);
+    // The router does not have imports, but we use buildImportObject for host parity
+    const importObject = buildImportObject({}, options);
+    const { instance } = await WebAssembly.instantiate(bytes, importObject);
+    const router = new CadreRouter(instance);
+    router.exports.affinescript_router_init();
+    return router;
+  }
+
+  // --- Actions ---
+
+  push(screenTag) {
+    this.exports.affinescript_router_push(screenTag);
+  }
+
+  pop() {
+    this.exports.affinescript_router_pop();
+  }
+
+  presentPopup(popupTag) {
+    this.exports.affinescript_router_present_popup(popupTag);
+  }
+
+  dismissPopup() {
+    this.exports.affinescript_router_dismiss_popup();
+  }
+
+  resize(w, h) {
+    this.exports.affinescript_router_resize(w, h);
+  }
+
+  // --- Getters ---
+
+  get screenW() {
+    return this.exports.affinescript_router_get_screen_w();
+  }
+
+  get screenH() {
+    return this.exports.affinescript_router_get_screen_h();
+  }
+
+  get stackLen() {
+    return this.exports.affinescript_router_get_stack_len();
+  }
+
+  get stackTop() {
+    return this.exports.affinescript_router_get_stack_top();
+  }
+
+  get popupTag() {
+    return this.exports.affinescript_router_get_popup_tag();
+  }
+}

docs/ECOSYSTEM.adoc

@@ -167,8 +167,8 @@ target.
 Linear-msg invariant; reuses the INT-02 loader. 9 Deno tests vs the
 canonical `affinescript tea-bridge` + a re-entrancy fixture.
 
-|`affinescript-cadre` |scaffold |Was imaginary until #175. Router/navigation
-satellite (internal `lib/tea_router.ml` contract exists).
+|`affinescript-cadre` |runtime |Cadre Router navigation satellite wrapper.
+Consumes `lib/tea_router.ml` generated WASM module.
 
 |`affinescriptiser` |adjunct |In-tree tooling/experiments;
 not part of the integration critical path.
@@ -269,7 +269,7 @@ the runtime is FIXED (PR #257, closed 2026-05-19); runtime VERIFIED
 end-to-end 2026-07-07 via `affinescript-dom/e2e/run.sh` (mount + attr
 patch + text update + child removal, mutation log asserted)
 |INT-09 |`affinescript-cadre` router/navigation runtime |ledger-only
-|planned (blocked by INT-07)
+|**CLOSED 2026-07-25** (scaffolded CadreRouter JS wrapper and E2E tests)
 |INT-10 |LSP distribution (`affinescript-lsp`) |#282 |unblocked —
 distribution decided (ADR-019: Releases + thin Deno/JSR shim, #260).
 Consumes the shim once #260 S2/S3 land