@standardagents/code-web 0.14.1-issue.663.fd4c3f → 0.14.4-branch.9e48e914.ee06ef

package/dist/plugins/samples.json

@@ -0,0 +1,81 @@
+{
+  "schema": 2,
+  "transpiler": "@bytecodealliance/jco-transpile@0.15.0",
+  "world": {
+    "glue": {
+      "file": "ui.js",
+      "sha256": "24c4ba57a14d27d8fda334210c4b5225f1b196ed43f8680442954f07080294ba"
+    },
+    "jspi": {
+      "file": "ui-jspi.js",
+      "sha256": "24e6e96752a139da58b703f6b2ae7551ae011783ed6ca895cf343e1a355da8e9"
+    },
+    "shims": [
+      {
+        "file": "ui.core2.wasm",
+        "sha256": "f3b18532f5fa5f5e31522891929d243dd383df225120106933cce6b7b31960c0"
+      },
+      {
+        "file": "ui.core3.wasm",
+        "sha256": "7ec25df2026c03fdd7c51abe4522e357d5888c0b2ba4b45cf8bf502275da1c60"
+      }
+    ]
+  },
+  "plugins": [
+    {
+      "id": "clock-cells",
+      "dir": "clock-cells",
+      "manifest": {
+        "apiVersion": 2,
+        "kind": "ui",
+        "id": "clock-cells",
+        "version": "0.1.0",
+        "module": "clock_cells.wasm",
+        "surfaces": [
+          {
+            "id": "card",
+            "anchor": "sidebar.card",
+            "model": "cells",
+            "height": 2
+          }
+        ],
+        "grants": {}
+      },
+      "component": {
+        "file": "clock_cells.wasm",
+        "sha256": "80d8a92f866f3bd906dfdde535e5b6489613ebffa4b04b0029d71182f2af28b9"
+      },
+      "core": {
+        "file": "clock_cells.core.wasm",
+        "sha256": "df640416b7ff87c0bd7dc9982f29baa6fdf8c856e13f28484e13727cfd3823ac"
+      }
+    },
+    {
+      "id": "plasma-pixels",
+      "dir": "plasma-pixels",
+      "manifest": {
+        "apiVersion": 2,
+        "kind": "ui",
+        "id": "plasma-pixels",
+        "version": "0.1.0",
+        "module": "plasma_pixels.wasm",
+        "surfaces": [
+          {
+            "id": "stage",
+            "anchor": "stage",
+            "model": "pixels"
+          }
+        ],
+        "grants": {}
+      },
+      "component": {
+        "file": "plasma_pixels.wasm",
+        "sha256": "cc80f9e6fdeb7433cf3f1ab7787f7192082a2a86a38d8aa535f7d6c934c2819d"
+      },
+      "core": {
+        "file": "plasma_pixels.core.wasm",
+        "sha256": "0cf0a23eceb1acc34db76b6e20f773229c52e0fc453b4324ea302347c899e6d0"
+      }
+    }
+  ]
+}

package/dist/plugins/worker.js

@@ -0,0 +1,411 @@
+// One plugin's Worker (docs/plugin-runtime.md, "The browser runtime").
+//
+// The viewer starts one module Worker per plugin from its own verified
+// bundle path and sends it plain messages: `{ m: <json>, b: [buffers] }`.
+// The Worker gets the plugin's world core module (a sample's from the
+// bundle, checked against the index; an account package's by transpiling
+// its verified component in the viewer, cached per component hash),
+// instantiates it through the viewer's own reference glue (host/world.js)
+// with the host imports in runtime.js, and calls `activate`, `frame()` and
+// `event()` only when the viewer asks. It never wakes on its own: an idle
+// plugin costs nothing here.
+//
+// The same script, started by a plugin Worker with a `transpile` message,
+// is the transpile Worker: it loads jco's transpiler, extracts the world
+// core module, answers, and is terminated. It runs under the Worker policy
+// the site gives this path, and only the plugin Worker that needs a
+// transpile pays for loading jco.
+//
+// Calls into the plugin run one at a time, in the order the viewer sent
+// them. Under JSPI an account call suspends the plugin until the viewer
+// answers; what arrives meanwhile waits its turn, except the answers
+// themselves, released buffers and view state.
+//
+// The viewer owns the budgets: this Worker reports how long each `frame()`
+// took, less the time it waited for the account, and the viewer terminates
+// a Worker that overruns or hangs.
+import { Mirror, PluginHost, witEvent } from './runtime.js'
+import { instantiatePlugin } from './host/world.js'
+import { extractMain } from './host/transpile.js'
+
+const CACHE = 'standard-plugin-core-v1'
+
+let epoch = 0
+let host = null
+let plugin = null
+let memory = () => null
+let memoryLimit = 64 * 1024 * 1024
+let dead = false
+/** Work for the plugin, in order; `running` while a call is suspended. */
+const queue = []
+let running = false
+/** A call into the plugin is on the stack or suspended. */
+let calling = false
+/** What arrived before the plugin was instantiated. */
+let early = []
+/** Account calls in flight, by id, and the time spent waiting on them. */
+const pending = new Map()
+let nextCall = 1
+let suspendedSince = null
+let suspendedMs = 0
+
+function post(message, buffer) {
+  const data = { m: JSON.stringify({ ...message, epoch }) }
+  if (buffer) {
+    data.b = [buffer]
+    self.postMessage(data, [buffer])
+  } else {
+    self.postMessage(data)
+  }
+}
+
+function describe(error) {
+  return error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+}
+
+/** A trap, or a call that grew memory past the limit, ends this instance. */
+function trapped(error) {
+  if (dead) return
+  dead = true
+  queue.length = 0
+  post({ t: 'trap', error: describe(error) })
+}
+
+function checkMemory() {
+  const current = memory()
+  if (current && current.buffer.byteLength > memoryLimit) {
+    trapped(new Error(`linear memory grew to ${current.buffer.byteLength} bytes, over the ${memoryLimit} limit`))
+    return false
+  }
+  return true
+}
+
+async function sha256(bytes) {
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, '0')).join('')
+}
+
+/** A file of this bundle, bound to the SHA-256 the index names. The site's
+ *  verified route checked the whole bundle; this binds each file to the
+ *  index the viewer read. A non-secure development origin has no WebCrypto
+ *  and relies on the bundle check alone. */
+async function bundleFile(url, expected) {
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`${url}: HTTP ${response.status}`)
+  const bytes = new Uint8Array(await response.arrayBuffer())
+  if (globalThis.crypto?.subtle) {
+    const actual = await sha256(bytes)
+    if (actual !== expected) throw new Error(`${url}: SHA-256 ${actual} does not match the index`)
+  }
+  return bytes
+}
+
+// ── the account, through the viewer ─────────────────────────────────────────
+
+function ask(call) {
+  const id = nextCall++
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject })
+    if (calling && pending.size === 1 && suspendedSince === null) {
+      suspendedSince = performance.now()
+      post({ t: 'suspend', on: true })
+    }
+    post({ t: 'account', id, call })
+  })
+}
+
+function answered(id, reply) {
+  const waiter = pending.get(id)
+  if (!waiter) return
+  pending.delete(id)
+  if (pending.size === 0 && suspendedSince !== null) {
+    suspendedMs += performance.now() - suspendedSince
+    suspendedSince = null
+    post({ t: 'suspend', on: false })
+  }
+  waiter.resolve(reply)
+}
+
+// ── the world core module ───────────────────────────────────────────────────
+
+/** Transpiles in a Worker of its own, so jco's memory goes with it. */
+function transpileElsewhere(component) {
+  return new Promise((resolve, reject) => {
+    const worker = new Worker(import.meta.url, { type: 'module' })
+    worker.onmessage = (event) => {
+      worker.terminate()
+      const message = JSON.parse(event.data.m)
+      if (message.t === 'transpiled') resolve({ bytes: new Uint8Array(event.data.b[0]), ms: message.ms })
+      else reject(new Error(message.error))
+    }
+    worker.onerror = (event) => {
+      worker.terminate()
+      reject(new Error(event.message || 'the transpile Worker failed'))
+    }
+    const copy = component.slice().buffer
+    worker.postMessage({ m: JSON.stringify({ t: 'transpile' }), b: [copy] }, [copy])
+  })
+}
+
+async function transpileHere(component) {
+  const started = performance.now()
+  const jco = await import(new URL('jco/js-component-bindgen-component.js', import.meta.url).href)
+  await jco.$init
+  const loadedAt = performance.now()
+  const bytes = await extractMain(component, jco.generate)
+  return { bytes, ms: { load: loadedAt - started, transpile: performance.now() - loadedAt } }
+}
+
+function cacheKey(base, entry, world) {
+  return new Request(new URL(`plugins/cache/${entry.component.sha256}-${world.glue.sha256.slice(0, 16)}.wasm`, base))
+}
+
+async function cached(key) {
+  try {
+    if (!globalThis.caches) return null
+    const response = await (await caches.open(CACHE)).match(key)
+    if (!response) return null
+    const bytes = new Uint8Array(await response.arrayBuffer())
+    const expected = response.headers.get('x-core-sha256')
+    if (globalThis.crypto?.subtle && (!expected || (await sha256(bytes)) !== expected)) return null
+    return bytes
+  } catch {
+    return null
+  }
+}
+
+async function remember(key, bytes) {
+  try {
+    if (!globalThis.caches) return
+    const headers = { 'content-type': 'application/wasm' }
+    if (globalThis.crypto?.subtle) headers['x-core-sha256'] = await sha256(bytes)
+    await (await caches.open(CACHE)).put(key, new Response(bytes, { headers }))
+  } catch {
+    // A full or unavailable cache only costs the next start a transpile.
+  }
+}
+
+/** The plugin's world core module and how it was obtained. */
+async function mainModule(init, component) {
+  const entry = init.plugin
+  if (!component) {
+    const dir = new URL(`plugins/${entry.dir}/`, init.base)
+    return { bytes: await bundleFile(new URL(entry.core.file, dir).href, entry.core.sha256), source: 'bundle' }
+  }
+  // The viewer checked the package against its hash and hashed the
+  // component it extracted; the cache is keyed by that and by the glue.
+  const key = cacheKey(init.base, entry, init.world)
+  const hit = await cached(key)
+  if (hit) return { bytes: hit, source: 'cache' }
+  const { bytes, ms } = typeof Worker === 'function' ? await transpileElsewhere(component) : await transpileHere(component)
+  await remember(key, bytes)
+  return { bytes, source: 'transpiled', ms }
+}
+
+async function load(init, component) {
+  const started = performance.now()
+  memoryLimit = init.memoryLimit
+  const jspi = init.account?.mode === 'jspi'
+  const world = init.world
+  const glueFile = jspi ? world.jspi : world.glue
+  const [glue, shims, main] = await Promise.all([
+    import(new URL(`plugins/host/${glueFile.file}`, init.base).href),
+    Promise.all(world.shims.map(async shim => [shim.file, await WebAssembly.compile(
+      await bundleFile(new URL(`plugins/host/${shim.file}`, init.base).href, shim.sha256))])),
+    mainModule(init, component),
+  ])
+  const account = init.account
+    ? { mode: init.account.mode, ask, mirror: new Mirror(init.account.mirror ?? {}) }
+    : null
+  host = new PluginHost({
+    manifest: init.plugin.manifest,
+    grants: init.grants ?? undefined,
+    config: init.config ?? '{}',
+    view: init.view,
+    shared: init.shared,
+    post,
+    memory: () => memory(),
+    account,
+    deliver: event => enqueue({ t: 'event', event, gesture: false }),
+  })
+  if (init.accountState) host.accountState = init.accountState
+  const linked = instantiatePlugin({
+    glue,
+    shims: Object.fromEntries(shims),
+    main: await WebAssembly.compile(main.bytes),
+    imports: host.imports(),
+    // The surface's `attach` takes the region as a list<u8>; the canonical
+    // ABI hands the core import its address and length in linear memory,
+    // which the host records to copy committed slots out of later. The
+    // glue lifts only a copy of the bytes.
+    wrap: (module, name, fn) => (module === 'cm32p2|standard:plugin/surface@2' && name === 'attach'
+      ? (...args) => {
+          host.attaching = { ptr: args[2] >>> 0, len: args[3] >>> 0 }
+          return fn(...args)
+        }
+      : fn),
+  })
+  memory = linked.memory
+  plugin = linked.instance
+  const timing = { ms: performance.now() - started, source: main.source, transpile: main.ms ?? null }
+  enqueue({ t: 'activate', timing })
+  const waiting = early
+  early = []
+  for (const { message, buffers } of waiting) handle(message, buffers)
+}
+
+// ── calls into the plugin ───────────────────────────────────────────────────
+
+function enqueue(message, buffers = []) {
+  queue.push({ message, buffers })
+  drain()
+}
+
+/** Runs queued work until the queue is empty or a call suspends. */
+function drain() {
+  while (!running && !dead && plugin && queue.length) {
+    const { message, buffers } = queue.shift()
+    let result
+    calling = true
+    try {
+      result = begin(message, buffers)
+    } catch (error) {
+      calling = false
+      trapped(error)
+      return
+    }
+    if (result instanceof Promise) {
+      running = true
+      result.then((value) => {
+        running = false
+        calling = false
+        finish(message, value)
+        drain()
+      }, (error) => {
+        running = false
+        calling = false
+        trapped(error)
+      })
+      return
+    }
+    calling = false
+    finish(message, result)
+  }
+}
+
+/** Starts one piece of work; a call into the plugin may return a promise
+ *  (JSPI). */
+function begin(message, buffers) {
+  suspendedMs = 0
+  message.started = performance.now()
+  switch (message.t) {
+    case 'activate':
+      return plugin.activate(host.config)
+    case 'resize':
+      host.resize(message.surface, message.geometry, message.gen, buffers, message.model)
+      return plugin.event(witEvent({ tag: 'resize', surface: message.surface, geometry: message.geometry }))
+    case 'visibility':
+      return plugin.event(witEvent({ tag: 'visibility', surface: message.surface, visible: message.visible }))
+    case 'event':
+      // A key, paste, press or command lets the plugin open a surface
+      // while it handles it, and only then.
+      host.gesture = Boolean(message.gesture)
+      if (host.gesture) host.noteInput()
+      return plugin.event(witEvent(message.event))
+    case 'frame':
+      return plugin.frame(BigInt(message.now), message.interval, message.power)
+    case 'deactivate':
+      return plugin.deactivate()
+    default:
+      return undefined
+  }
+}
+
+function finish(message, result) {
+  host.gesture = false
+  if (dead || !checkMemory()) return
+  switch (message.t) {
+    case 'activate':
+      post({ t: 'ready', jspi: host.waits, timing: message.timing })
+      break
+    case 'frame': {
+      const elapsed = performance.now() - message.started - suspendedMs
+      post({ t: 'frame-done', next: result === undefined ? null : Number(result), elapsed })
+      break
+    }
+    case 'deactivate':
+      dead = true
+      self.close()
+      break
+    default:
+      break
+  }
+}
+
+// ── the viewer's messages ───────────────────────────────────────────────────
+
+function handle(message, buffers) {
+  switch (message.t) {
+    case 'account-reply':
+      answered(message.id, message.reply)
+      break
+    case 'release':
+      if (!dead && host) host.release(message.surface, message.gen, message.slot, buffers[0])
+      break
+    case 'view':
+      if (host) host.view = message.view
+      break
+    case 'mirror':
+      host?.account?.mirror?.apply(message.values ?? {})
+      break
+    case 'account-state':
+      if (!host) break
+      host.accountState = message.state
+      if (host.accountWatched) enqueue({ t: 'event', event: { tag: 'account-changed' }, gesture: false })
+      break
+    case 'deliver':
+      enqueue({ t: 'event', event: message.event, gesture: false })
+      break
+    default:
+      enqueue(message, buffers)
+  }
+}
+
+async function transpileRole(component) {
+  try {
+    const { bytes, ms } = await transpileHere(component)
+    const buffer = bytes.slice().buffer
+    self.postMessage({ m: JSON.stringify({ t: 'transpiled', ms }), b: [buffer] }, [buffer])
+  } catch (error) {
+    self.postMessage({ m: JSON.stringify({ t: 'failed', error: describe(error) }) })
+  }
+}
+
+self.onmessage = (event) => {
+  const message = JSON.parse(event.data.m)
+  const buffers = event.data.b ?? []
+  if (message.t === 'transpile') {
+    transpileRole(new Uint8Array(buffers[0]))
+    return
+  }
+  if (message.t === 'init') {
+    epoch = message.epoch
+    // A Worker has no page address: resolve a relative bundle base against
+    // this script's own location, so callers may pass either form.
+    message.base = new URL(message.base, self.location.href).href
+    const component = buffers[0] ? new Uint8Array(buffers[0]) : null
+    load(message, component).catch((error) => {
+      dead = true
+      post({ t: 'failed', error: describe(error) })
+    })
+    return
+  }
+  // Until the plugin exists only queued work accumulates; view state and
+  // releases for it arrive only after its surfaces were sized.
+  if (!host && message.t !== 'account-reply') {
+    early.push({ message, buffers })
+    return
+  }
+  handle(message, buffers)
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/code-web",
-  "version": "0.14.1-issue.663.fd4c3f",
+  "version": "0.14.4-branch.9e48e914.ee06ef",
   "type": "module",
   "description": "The Standard viewer runtime for the browser: the TUI compiled to wasm, its JS glue, and its fonts",
   "license": "UNLICENSED",
@@ -27,6 +27,7 @@
     "./standard_web_bg.wasm": "./dist/pkg/standard_web_bg.wasm",
     "./fonts/*": "./dist/fonts/*",
     "./licenses/*": "./dist/licenses/*",
+    "./plugins/*": "./dist/plugins/*",
     "./build.json": "./dist/build.json",
     "./manifest.json": "./dist/manifest.json",
     "./manifest.sig": "./dist/manifest.sig",
@@ -36,6 +37,7 @@
     "dist/pkg",
     "dist/fonts",
     "dist/licenses",
+    "dist/plugins",
     "dist/build.json",
     "dist/manifest.json",
     "dist/manifest.sig",
@@ -45,6 +47,10 @@
     "fonts": "node scripts/fetch-fonts.mjs",
     "build": "node scripts/build.mjs",
     "check": "node scripts/build.mjs --check",
-    "serve": "node scripts/serve.mjs"
+    "serve": "node scripts/serve.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@bytecodealliance/jco-transpile": "0.15.0"
   }
 }