@geeqdev/geeq-sdk 0.0.1 → 0.1.1

package/example/src/style.css

@@ -0,0 +1,149 @@
+:root {
+  --bg: #f6f7f9;
+  --surface: #ffffff;
+  --surface-2: #f2f4f7;
+  --border: #e3e6ea;
+  --text: #16191d;
+  --muted: #6b7280;
+  --accent: #2f6df6;
+  --accent-text: #ffffff;
+  --danger: #b42318;
+  --danger-bg: #fef3f2;
+  --danger-border: #fecdca;
+  --ok: #067647;
+  --ok-bg: #ecfdf3;
+  --radius: 10px;
+  --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0e1116;
+    --surface: #161b22;
+    --surface-2: #1c222b;
+    --border: #2a313c;
+    --text: #e6edf3;
+    --muted: #9198a1;
+    --accent: #4d84ff;
+    --danger: #ff8080;
+    --danger-bg: #2a1616;
+    --danger-border: #5c2626;
+    --ok: #4ade80;
+    --ok-bg: #12251a;
+  }
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font: 15px/1.55 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+
+.wrap { max-width: 780px; margin: 0 auto; padding: 40px 20px 80px; }
+
+header h1 { font-size: 24px; margin: 0 0 6px; letter-spacing: -0.02em; }
+header p { margin: 0; color: var(--muted); }
+
+.engine {
+  display: inline-flex; align-items: center; gap: 7px;
+  margin-top: 14px; padding: 5px 11px;
+  border: 1px solid var(--border); border-radius: 999px;
+  background: var(--surface); font-size: 13px; color: var(--muted);
+}
+.dot { width: 7px; height: 7px; border-radius: 50%; background: var(--muted); }
+.dot.loading { background: #f59e0b; animation: pulse 1.1s ease-in-out infinite; }
+.dot.ready { background: var(--ok); }
+.dot.error { background: var(--danger); }
+@keyframes pulse { 0%,100% { opacity: 1 } 50% { opacity: 0.35 } }
+
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 20px;
+  margin-top: 20px;
+}
+.card h2 {
+  font-size: 13px; text-transform: uppercase; letter-spacing: 0.06em;
+  color: var(--muted); margin: 0 0 16px; font-weight: 600;
+}
+.card h2 .step {
+  display: inline-block; width: 19px; height: 19px; line-height: 19px;
+  text-align: center; border-radius: 50%;
+  background: var(--surface-2); border: 1px solid var(--border);
+  color: var(--text); margin-right: 8px; font-size: 11px;
+}
+
+/* A step waiting on an earlier one: the note sits on top of the card like a tab, and the
+   card stays readable but dimmed. The heading keeps full strength so the order reads. */
+.gate-note {
+  margin: 20px 0 0; padding: 8px 14px;
+  border: 1px solid var(--border); border-bottom: 0;
+  border-radius: var(--radius) var(--radius) 0 0;
+  background: var(--surface-2); color: var(--muted); font-size: 13px;
+}
+.gate.locked .card { margin-top: 0; border-top-left-radius: 0; border-top-right-radius: 0; }
+.gate.locked .card > :not(h2) { opacity: 0.45; }
+.gate.done .card h2 .step { background: var(--ok-bg); border-color: var(--ok); color: var(--ok); }
+
+.row { display: flex; gap: 10px; align-items: center; flex-wrap: wrap; }
+.row + .row { margin-top: 12px; }
+.grow { flex: 1 1 auto; }
+
+button {
+  font: inherit; font-weight: 500;
+  padding: 9px 15px; border-radius: 8px;
+  border: 1px solid var(--border); background: var(--surface-2); color: var(--text);
+  cursor: pointer; transition: filter .12s ease;
+}
+button:hover:not(:disabled) { filter: brightness(0.97); }
+button:disabled { opacity: 0.5; cursor: not-allowed; }
+button.primary { background: var(--accent); border-color: var(--accent); color: var(--accent-text); }
+button.small { padding: 5px 10px; font-size: 13px; }
+
+select, input[type="number"], textarea {
+  font: inherit; color: var(--text);
+  background: var(--surface-2); border: 1px solid var(--border);
+  border-radius: 8px; padding: 9px 11px;
+}
+textarea { width: 100%; font-family: var(--mono); font-size: 13.5px; resize: vertical; min-height: 78px; }
+label { font-size: 13px; color: var(--muted); }
+
+.phrase {
+  display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 8px; margin: 4px 0 14px;
+}
+.word {
+  display: flex; align-items: baseline; gap: 7px;
+  background: var(--surface-2); border: 1px solid var(--border);
+  border-radius: 7px; padding: 8px 11px; font-family: var(--mono); font-size: 13.5px;
+}
+.word .n { color: var(--muted); font-size: 11px; min-width: 15px; }
+
+.field { margin-top: 13px; }
+.field .k { font-size: 12px; color: var(--muted); margin-bottom: 4px; }
+.field .v {
+  font-family: var(--mono); font-size: 13px; word-break: break-all;
+  background: var(--surface-2); border: 1px solid var(--border);
+  border-radius: 7px; padding: 9px 11px;
+}
+
+.warn {
+  background: var(--danger-bg); border: 1px solid var(--danger-border);
+  color: var(--danger); border-radius: 8px; padding: 11px 13px;
+  font-size: 13.5px; margin-top: 14px;
+}
+.warn strong { font-weight: 600; }
+
+.hint { font-size: 13px; color: var(--muted); margin-top: 10px; }
+.valid { color: var(--ok); }
+.invalid { color: var(--danger); }
+.empty { color: var(--muted); font-size: 14px; padding: 6px 0; }
+
+footer { margin-top: 30px; font-size: 13px; color: var(--muted); text-align: center; }
+code { font-family: var(--mono); font-size: 0.92em; background: var(--surface-2);
+       padding: 1px 5px; border-radius: 4px; border: 1px solid var(--border); }

package/example/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "preserve",
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/example/vite.config.ts

@@ -0,0 +1,26 @@
+import { createRequire } from 'node:module'
+import { dirname } from 'node:path'
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+// `@geeqdev/geeq-sdk` is a `file:` dependency, so node_modules holds a symlink and
+// Vite serves it from its real path under `/@fs/`. The engine lives next to the
+// bundle there, outside this project's root, so dev needs explicit read access —
+// without it the .wasm request 403s and initGeeq() rejects with `init-failed`.
+const require = createRequire(import.meta.url)
+const sdkRoot = dirname(require.resolve('@geeqdev/geeq-sdk/package.json'))
+
+export default defineConfig({
+  plugins: [vue()],
+  optimizeDeps: {
+    // Required by @geeqdev/geeq-sdk. Vite's dependency pre-bundling rewrites the
+    // `new URL('...wasm', import.meta.url)` the SDK uses to locate its engine;
+    // excluding it keeps that pattern intact so the .wasm is emitted as an asset.
+    exclude: ['@geeqdev/geeq-sdk'],
+  },
+  server: {
+    fs: {
+      allow: ['.', sdkRoot],
+    },
+  },
+})

package/jest.config.js

@@ -0,0 +1,18 @@
+/** @type {import('jest').Config} */
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    // Jest runs as CommonJS. Swap the ESM browser engine for the vendored
+    // CommonJS build, which instantiates itself on import, and swap the shipped
+    // loaders for a no-op. scripts/smoke.mjs covers the real ones.
+    '^.*/wasm/browser/geeq_core$': '<rootDir>/src/wasm/nodejs/geeq_core',
+    '^.*/wasm-loader\\.browser$': '<rootDir>/tests/wasm-loader.jest.ts',
+  },
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', { tsconfig: { module: 'CommonJS', verbatimModuleSyntax: false } }],
+  },
+  testMatch: ['<rootDir>/tests/**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts'],
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geeqdev/geeq-sdk",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Geeq blockchain SDK for wallets, transfers and NFTs. Works in the browser and Node.js.",
   "keywords": [
     "geeq",
@@ -40,10 +40,6 @@
     "./geeq_core_bg.wasm": "./dist/browser/geeq_core_bg.wasm",
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

package/scripts/copy-wasm.mjs

@@ -0,0 +1,21 @@
+// Copies the engine next to each build output, so the `new URL('./geeq_core_bg.wasm',
+// import.meta.url)` in our own source resolves for both targets.
+import { copyFile, mkdir, stat } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+
+const source = join(root, 'src', 'wasm', 'browser', 'geeq_core_bg.wasm')
+
+const info = await stat(source)
+if (info.size === 0) {
+  throw new Error(`Refusing to ship an empty engine: ${source}`)
+}
+
+for (const target of ['dist/browser', 'dist/node']) {
+  const dir = join(root, target)
+  await mkdir(dir, { recursive: true })
+  await copyFile(source, join(dir, 'geeq_core_bg.wasm'))
+  console.log(`copied geeq_core_bg.wasm -> ${target} (${(info.size / 1024 / 1024).toFixed(2)} MB)`)
+}

package/scripts/smoke.mjs

@@ -0,0 +1,382 @@
+/**
+ * Packaging proof. Runs the real built bundles — not src/ — so it catches the
+ * failures unit tests structurally cannot: a broken exports map, a WASM the
+ * loader cannot find, or an import.meta.url that did not survive the build.
+ *
+ *   node scripts/smoke.mjs
+ */
+import { createHash } from 'node:crypto'
+import { createServer } from 'node:http'
+import { createRequire } from 'node:module'
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import assert from 'node:assert/strict'
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const require = createRequire(import.meta.url)
+let checks = 0
+const ok = (label) => {
+  checks += 1
+  console.log(`  ok  ${label}`)
+}
+
+/**
+ * The vendored Cap'n Proto schemas, compiled from src/capnp for this script. A plain
+ * .mjs cannot import TypeScript, so esbuild (tsup's engine) builds the ones the ledger
+ * needs, leaving capnp-ts external so they share the `Message` this script uses.
+ */
+async function loadSchemas() {
+  const { build } = await import('esbuild')
+  const { outputFiles } = await build({
+    stdin: {
+      contents: [
+        "export { ValLayLedger } from './valLayLedger.capnp'",
+        "export { NetActorStatus, NetActorType } from './netActorRec.capnp'",
+      ].join('\n'),
+      resolveDir: join(root, 'src/capnp'),
+      loader: 'ts',
+    },
+    bundle: true,
+    write: false,
+    format: 'cjs',
+    platform: 'node',
+    external: ['capnp-ts'],
+    logLevel: 'silent',
+  })
+  const module = { exports: {} }
+  new Function('require', 'module', 'exports', outputFiles[0].text)(require, module, module.exports)
+  return module.exports
+}
+
+/**
+ * A minimal validation layer ledger, built with the same Cap'n Proto schema the SDK
+ * bundles and decodes with — the check that the decoder survived the build, which no
+ * unit test can prove, because unit tests import source rather than the built package.
+ */
+async function buildLedger(accountId) {
+  const { Message } = require('capnp-ts')
+  const { ValLayLedger, NetActorStatus, NetActorType } = await loadSchemas()
+
+  const message = new Message()
+  const vll = message.initRoot(ValLayLedger)
+  vll.setChainNum(1)
+  vll.setBlockNum(41)
+
+  const actors = vll.initNetActorList().initNetActorRecs(1)
+  const actor = actors.get(0)
+  actor.setIpAddr('10.0.0.1')
+  actor.setPortNum(2082)
+  actor.setNodeNumSelf(3)
+  // A real ledger sets this 100-355 blocks ahead; the capnp zero would read as a node
+  // already rotating out of the active set.
+  actor.setBlockNumRemove(241)
+  actor.setNetActorType(NetActorType.NET_ACTOR_TYPE_ANON_NODE)
+  actor.setRecStatus(NetActorStatus.NET_ACTOR_STATUS_NODE)
+  actor.initAcctNumVal(32)
+  actor.getAcctNumVal().copyBuffer(new Uint8Array(32).fill(0xa0))
+
+  const params = vll.initParamAcctList().initParamAcctRecs(2)
+  const num = params.get(0).initParamType().initMetadataVarNum()
+  num.setCurrentValue(4)
+  const bytes = params.get(1).initParamType().initMetadataVarBytes()
+  bytes.setCurrentValue(64)
+
+  const accounts = vll.initCoinAcctRecs(1)
+  const account = accounts.get(0)
+  account.initAcctNumVal(32)
+  account.getAcctNumVal().copyBuffer(accountId)
+  account.getRecType().initAsset().setNonce(7)
+
+  return Buffer.from(message.toPackedArrayBuffer()).toString('base64')
+}
+
+async function exercise(sdk, label) {
+  console.log(`\n${label}`)
+
+  const keypair = await sdk.generateKeypair()
+  assert.equal(keypair.publicKey.length, 32, 'public key is 32 bytes')
+  assert.equal(keypair.privateKey.length, 32, 'private key is 32 bytes')
+  assert.equal(keypair.accountId.length, 32, 'account id is 32 bytes')
+  ok('generateKeypair')
+
+  const restored = await sdk.importKeypair(keypair.publicKey, keypair.privateKey)
+  assert.deepEqual(
+    Buffer.from(restored.accountId),
+    Buffer.from(keypair.accountId),
+    'imported keypair has the same account id',
+  )
+  ok('importKeypair round-trip')
+
+  const address = keypair.getAddress({ chainNumber: 1 })
+  assert.ok(typeof address === 'string' && address.length > 0, 'address is a non-empty string')
+  ok(`createWalletAddress -> ${address.slice(0, 16)}...`)
+
+  const decoded = await sdk.decodeWalletAddress(address)
+  assert.equal(decoded.chainNumber, 1)
+  assert.equal(decoded.recordType, 'coin-asset')
+  assert.deepEqual(Buffer.from(decoded.accountId), Buffer.from(keypair.accountId))
+  ok('decodeWalletAddress round-trip')
+
+  const message = new TextEncoder().encode('geeq packaging smoke test')
+  const signature = keypair.sign(message)
+  assert.equal(signature.length, 64)
+  assert.equal(sdk.verifySignature(keypair.publicKey, signature, message), true)
+  ok('sign / verify')
+
+  const mnemonic = 'legal winner thank year wave sausage worth useful legal winner thank yellow'
+  const a = await sdk.keypairFromMnemonic(mnemonic)
+  const b = await sdk.keypairFromMnemonic(mnemonic)
+  assert.deepEqual(Buffer.from(a.publicKey), Buffer.from(b.publicKey), 'mnemonic is deterministic')
+  ok('keypairFromMnemonic is deterministic')
+
+  // Chain state read through a scripted transport — no node, no network.
+  const ledger = await buildLedger(a.accountId)
+  // Counts calls so the smoke can assert that connecting is genuinely free.
+  const transport = Object.assign(
+    async (url) => {
+      transport.calls += 1
+      if (url.includes('/admin/simulation/chains')) {
+        return {
+          ok: true,
+          status: 200,
+          text: async () => JSON.stringify({ result: [{ id: 9, chainNumber: 1, name: 'smoke' }] }),
+        }
+      }
+      if (url.includes('/api/nodes')) {
+        return {
+          ok: true,
+          status: 200,
+          text: async () =>
+            JSON.stringify({ result: [{ ip: '10.0.0.1', type: 'active', status: 'ready' }] }),
+        }
+      }
+      return { ok: true, status: 200, text: async () => JSON.stringify({ result: ledger }) }
+    },
+    { calls: 0 },
+  )
+
+  const chain = await sdk.GeeqChain.connect({ penniesPerGeeq: 1_000_000_000n, endpoint: 'https://10.0.0.1:2082', transport })
+  assert.equal(transport.calls, 0, 'connecting reads nothing from the chain')
+  assert.equal(chain.node, undefined, 'the node number is not known before a ledger read')
+  ok('GeeqChain.connect performs no I/O')
+
+  const state = await chain.getChainState({ account: a })
+  assert.equal(chain.chainNumber, 1, 'chain number comes from the ledger')
+  assert.equal(chain.node.nodeNumber, 3, 'node number is nodeNumSelf for the matched host')
+  ok(`first ledger read -> chain ${chain.chainNumber}, node ${chain.node.nodeNumber}`)
+
+  assert.equal(state.blockNumber, 42, 'target block is the ledger block plus one')
+  assert.equal(state.nonce, 7, 'nonce comes from the coin-asset record')
+  ok('getChainState derives block and nonce')
+
+  const attestation = await chain.createAttestation({ keypair: a, content: Buffer.from('smoke') })
+  assert.ok(attestation.transaction.length > 0, 'attestation is built')
+  assert.equal(attestation.nodeUrl, 'https://10.0.0.1:2082', 'it knows where to be submitted')
+  assert.equal(chain.node.submitUrl, 'https://10.0.0.1:2082/api/blocks/process', 'submit route')
+  ok('createAttestation through the built bundle')
+  chain.dispose()
+
+  // Discovery: the directory names an active node, and no ledger is read to do it.
+  transport.calls = 0
+  const discovered = await sdk.GeeqChain.connect({
+    penniesPerGeeq: 1_000_000_000n,
+    discovery: 'https://simulator.example.com',
+    chainNumber: 1,
+    transport,
+  })
+  assert.equal(discovered.endpoint, 'https://10.0.0.1:2082', 'picked the active node')
+  assert.equal(transport.calls, 2, 'discovery reads exactly two directory routes')
+  ok('GeeqChain.connect via the node directory')
+  discovered.dispose()
+
+  // The explorer is asked in hex for a refHash given in base64.
+  const refHash = new Uint8Array(32).fill(0xab)
+  let asked = ''
+  const found = await sdk.getExplorerTransaction({
+    explorerUrl: 'https://blkexp.example.com',
+    refHash: sdk.toBase64(refHash),
+    transport: async (url) => {
+      asked = url
+      return { ok: true, status: 200, text: async () => JSON.stringify({ result: { refHash: sdk.toHex(refHash), status: 'valid' } }) }
+    },
+  })
+  assert.ok(asked.endsWith(`/api/transactions/byRefHash?refHash=${sdk.toHex(refHash)}`), 'asks in hex')
+  assert.equal(found.status, 'valid')
+  ok('getExplorerTransaction asks the explorer in hex')
+
+  for (const kp of [keypair, restored, a, b]) kp.dispose()
+}
+
+/**
+ * The smallest WebSocket server that speaks enough RFC 6455 to be a node's socket: text
+ * frames both ways, a close, and the `/ws/` path. Node has a WebSocket client but no
+ * server, and the point is a real handshake with the runtime's own client — no fakes.
+ */
+async function socketServer() {
+  const peers = []
+  const server = createServer()
+  server.on('upgrade', (request, wire) => {
+    if (request.url !== '/ws/') {
+      wire.end('HTTP/1.1 404 Not Found\r\n\r\n')
+      return
+    }
+    const accept = createHash('sha1')
+      .update(`${request.headers['sec-websocket-key']}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+      .digest('base64')
+    wire.write(
+      'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+        `Sec-WebSocket-Accept: ${accept}\r\n\r\n`,
+    )
+
+    const peer = {
+      frames: [],
+      waiters: [],
+      send(text) {
+        const body = Buffer.from(text)
+        const head =
+          body.length < 126
+            ? Buffer.from([0x81, body.length])
+            : Buffer.from([0x81, 126, body.length >> 8, body.length & 0xff])
+        wire.write(Buffer.concat([head, body]))
+      },
+      /** Resolves with the next text frame the client sends. */
+      next() {
+        return new Promise((resolve) => peer.waiters.push(resolve))
+      },
+    }
+    peers.push(peer)
+
+    let pending = Buffer.alloc(0)
+    wire.on('data', (chunk) => {
+      pending = Buffer.concat([pending, chunk])
+      for (;;) {
+        if (pending.length < 2) return
+        const opcode = pending[0] & 0x0f
+        let length = pending[1] & 0x7f
+        let offset = 2
+        if (length === 126) {
+          length = pending.readUInt16BE(2)
+          offset = 4
+        }
+        if (pending.length < offset + 4 + length) return
+        const mask = pending.subarray(offset, offset + 4)
+        const body = Buffer.from(pending.subarray(offset + 4, offset + 4 + length))
+        for (let i = 0; i < body.length; i += 1) body[i] ^= mask[i % 4]
+        pending = pending.subarray(offset + 4 + length)
+
+        if (opcode === 0x8) {
+          wire.end(Buffer.from([0x88, 0]))
+          return
+        }
+        if (opcode !== 0x1) continue
+        const text = body.toString('utf8')
+        const waiter = peer.waiters.shift()
+        if (waiter === undefined) peer.frames.push(text)
+        else waiter(text)
+      }
+    })
+    wire.on('error', () => {})
+  })
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve))
+  return { server, peers, port: server.address().port }
+}
+
+async function exerciseSocket(sdk, label) {
+  console.log(`\n${label} socket`)
+  if (typeof globalThis.WebSocket !== 'function') {
+    console.log('  --  skipped: this Node has no global WebSocket (Node 22 does)')
+    return
+  }
+
+  assert.equal(sdk.socketRoute('https://10.0.0.1:2082'), 'wss://10.0.0.1:2082/ws/')
+  ok('socketRoute derives wss://…/ws/ from the node origin')
+
+  const { server, peers, port } = await socketServer()
+  const socket = await sdk.GeeqSocket.connect({ url: `ws://127.0.0.1:${port}/ws/` })
+  assert.equal(socket.state, 'open')
+  ok("GeeqSocket.connect handshakes with the runtime's own WebSocket")
+
+  const sender = await sdk.keypairFromMnemonic(
+    'legal winner thank year wave sausage worth useful legal winner thank yellow',
+  )
+  const receiver = await sdk.generateKeypair()
+  const tx = await sdk.createCoinTransferTx({
+    keypair: sender,
+    to: receiver.accountId,
+    amount: 150n,
+    chainState: { chainNumber: 1, blockNumber: 42, nodeNumber: 3, nonce: 7 },
+  })
+
+  const peer = peers[0]
+  const subscribed = peer.next()
+  const tracked = await socket.track(tx)
+  const frame = JSON.parse(await subscribed)
+  assert.equal(frame.event, 'client')
+  assert.ok(frame.payload.publicKeys.includes(sdk.toBase64(sender.publicKey)), 'signer key')
+  assert.ok(frame.payload.publicKeys.includes(sdk.toBase64(sender.accountId)), 'signer id')
+  ok('track() subscribes the signer before it resolves')
+
+  peer.send('pong')
+  peer.send(
+    JSON.stringify({
+      event: 'uut_status',
+      payload: {
+        refHash: sdk.transactionIdOf(tx),
+        publicKeys: [sdk.toBase64(sender.publicKey)],
+        status: 'valid',
+        isValid: true,
+        blockNumber: 42,
+        vlbBlock: 43,
+        error: '',
+      },
+    }),
+  )
+  const outcome = await tracked.settled()
+  assert.equal(outcome.status, 'confirmed', 'a valid status confirms the tracked transfer')
+  ok('a uut_status for the transfer hash settles it confirmed')
+
+  socket.dispose()
+  sender.dispose()
+  receiver.dispose()
+  server.closeAllConnections()
+  await new Promise((resolve) => server.close(resolve))
+}
+
+// 1. Node ESM build — resolves the engine through import.meta.url.
+const esm = await import(join(root, 'dist/node/index.js'))
+await exercise(esm, 'dist/node/index.js  (ESM)')
+await exerciseSocket(esm, 'dist/node/index.js  (ESM)')
+
+// 2. Node CJS build — esbuild shims import.meta.url; this proves the shim works.
+const cjs = require(join(root, 'dist/node/index.cjs'))
+await exercise(cjs, 'dist/node/index.cjs (CJS)')
+await exerciseSocket(cjs, 'dist/node/index.cjs (CJS)')
+
+// 3. Browser bundle — cannot be executed here, so assert the contract a bundler relies on.
+console.log('\ndist/browser/index.js (static checks)')
+const browser = await readFile(join(root, 'dist/browser/index.js'), 'utf8')
+assert.ok(
+  browser.includes("new URL(\"./geeq_core_bg.wasm\", import.meta.url)"),
+  'browser bundle keeps the new URL(..., import.meta.url) pattern bundlers key on',
+)
+ok('engine URL pattern preserved for bundlers')
+assert.ok(!browser.includes('node:fs'), 'browser bundle pulls in no Node built-ins')
+ok('no Node built-ins in the browser bundle')
+
+for (const target of ['browser', 'node']) {
+  const wasm = await stat(join(root, `dist/${target}/geeq_core_bg.wasm`))
+  assert.ok(wasm.size > 1_000_000, `dist/${target} ships the engine`)
+  ok(`dist/${target}/geeq_core_bg.wasm (${(wasm.size / 1024 / 1024).toFixed(2)} MB)`)
+}
+
+// 4. The exports map must actually resolve for a consumer.
+const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
+for (const [condition, targets] of Object.entries(pkg.exports['.'])) {
+  for (const [kind, rel] of Object.entries(targets)) {
+    await stat(join(root, rel))
+    ok(`exports["."].${condition}.${kind} -> ${rel}`)
+  }
+}
+
+console.log(`\nAll ${checks} checks passed.`)