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

package/dist/plugins/runtime.js

@@ -0,0 +1,1044 @@
+// The browser plugin host inside a plugin's Worker: the WIT imports of the
+// `ui-plugin` world (wit/standard-plugin/plugin.wit) implemented against the
+// same rules as the native host (crates/standard-plugin-host), and the copy
+// of committed surface slots into the buffers the viewer samples.
+//
+// Nothing here touches the DOM or the network; worker.js wires it to a
+// transpiled component and to the viewer's messages, and the tests drive it
+// directly.
+
+/** Bytes before slot 0 of a plugin's region: eight u32 header words. */
+export const HEADER_LEN = 32
+/** Bytes per cell in the cells model. */
+export const CELL_LEN = 16
+/** Bytes per pixel in the pixels model. */
+export const PIXEL_LEN = 4
+/** The largest surface either model addresses, in cells. */
+export const MAX_COLS = 1024
+export const MAX_ROWS = 512
+/** Bytes before each output slot's data: `seq`, `gen` (u32 each), padding. */
+export const SLOT_HEADER = 16
+/** Output slots per surface: the viewer holds one, the worker writes another. */
+export const RING_SLOTS = 3
+/** Unpublished commits' rectangles merged past this become a full copy. */
+export const MAX_MERGED_RECTS = 64
+
+const MODELS = { cells: 0, pixels: 1 }
+/** Anchors instanced per pane, per machine or per project. */
+const INSTANCED = ['pane.footer', 'pane.header', 'machine.after', 'project.after']
+/** Anchors shown only when opened. */
+const OPENS = ['stage', 'panel.popover']
+/** The xterm defaults of the 16 ANSI colours. */
+const XTERM_PALETTE = [
+  0x000000, 0xcd0000, 0x00cd00, 0xcdcd00, 0x0000ee, 0xcd00cd, 0x00cdcd, 0xe5e5e5,
+  0x7f7f7f, 0xff0000, 0x00ff00, 0xffff00, 0x5c5cff, 0xff00ff, 0x00ffff, 0xffffff,
+]
+
+/** A manifest's `model`: one model, or several in preference order. */
+export function modelsOf(decl) {
+  return Array.isArray(decl.model) ? decl.model : [decl.model]
+}
+
+// ── grants (crates/standard-plugin-host/src/grants.rs) ─────────────────────
+
+function covers(granted, needed) {
+  if (granted === needed) return true
+  const split = granted.indexOf(':')
+  const neededSplit = needed.indexOf(':')
+  if (split < 0 || neededSplit < 0) return false
+  if (granted.slice(0, split) !== needed.slice(0, neededSplit)) return false
+  const pattern = granted.slice(split + 1)
+  if (!pattern.endsWith('*')) return false
+  const prefix = pattern.slice(0, -1)
+  return prefix === '' || needed.slice(neededSplit + 1).startsWith(prefix)
+}
+
+/** The approved grants of one plugin. */
+export class Grants {
+  constructor(pluginId, granted) {
+    this.pluginId = pluginId
+    this.granted = [...new Set(granted)]
+  }
+
+  allows(needed) {
+    return this.granted.some(granted => covers(granted, needed))
+  }
+
+  /** The missing grant, or `null` when `needed` is covered. */
+  check(needed) {
+    return this.allows(needed) ? null : needed
+  }
+
+  /** Whether a `url.open:` grant covers `host` (lowercase). */
+  allowsUrlOpen(host) {
+    return this.granted.some(granted => granted.startsWith('url.open:')
+      && hostPatternCovers(granted.slice('url.open:'.length), host))
+  }
+
+  /** A key, prefix or event name inside `<id>.` needs no grant. */
+  isOwnNamespace(subject) {
+    return subject.startsWith(this.pluginId) && subject[this.pluginId.length] === '.'
+  }
+
+  checkNamespaced(kind, subject) {
+    return this.isOwnNamespace(subject) ? null : this.check(`${kind}:${subject}`)
+  }
+}
+
+/** Whether host pattern `pattern` (`url.open:<pattern>`) covers `host`
+ *  (`standard_plugin_manifest::grants`): the host, `*.<domain>` for the
+ *  domain and its subdomains, `*` for any. */
+function hostPatternCovers(pattern, host) {
+  if (pattern === '*') return true
+  if (pattern.startsWith('*.')) {
+    const domain = pattern.slice(2).toLowerCase()
+    return host === domain || host.endsWith(`.${domain}`)
+  }
+  return host === pattern.toLowerCase()
+}
+
+/** The longest URL `url.open` takes, and how long after input it may. */
+export const URL_MAX_BYTES = 2048
+export const URL_OPEN_WINDOW_MS = 1000
+
+/** The lowercase host of a URL `url.open` accepts, or `null`
+ *  (`standard_plugin_manifest::url::https_host`): plain `https://`, no
+ *  credentials, a host of letters, digits, dots and dashes, no whitespace
+ *  or control characters. */
+export function httpsHost(url) {
+  if (typeof url !== 'string' || new TextEncoder().encode(url).length > URL_MAX_BYTES) return null
+  // eslint-disable-next-line no-control-regex
+  if (/[\s\u0000-\u001f\u007f-\u009f]/u.test(url)) return null
+  if (url.slice(0, 8).toLowerCase() !== 'https://') return null
+  const authority = url.slice(8).split(/[/?#]/)[0]
+  if (authority.includes('@')) return null
+  let host = authority
+  const colon = authority.lastIndexOf(':')
+  if (colon >= 0) {
+    const port = authority.slice(colon + 1)
+    if (!/^[0-9]+$/.test(port)) return null
+    host = authority.slice(0, colon)
+  }
+  if (!/^[A-Za-z0-9.-]+$/.test(host)) return null
+  return host.toLowerCase()
+}
+
+/** The grants a manifest carries: `{ "<grant>": "<reason>" }` or a list. */
+export function manifestGrants(manifest) {
+  const grants = manifest?.grants ?? {}
+  return Array.isArray(grants) ? grants.map(String) : Object.keys(grants)
+}
+
+// ── layout (crates/standard-plugin-host/src/buffer.rs) ─────────────────────
+
+/** The geometry a surface gets: cells, clamped, with its pixel size. */
+export function geometry(cols, rows, cellPxW, cellPxH) {
+  cols = Math.min(cols >>> 0, MAX_COLS)
+  rows = Math.min(rows >>> 0, MAX_ROWS)
+  return { cols, rows, pxW: cols * cellPxW, pxH: rows * cellPxH, cellPxW, cellPxH }
+}
+
+export function geometryEmpty(g) {
+  return !g || g.cols === 0 || g.rows === 0
+}
+
+export function sameGeometry(a, b) {
+  return a.cols === b.cols && a.rows === b.rows && a.pxW === b.pxW && a.pxH === b.pxH
+    && a.cellPxW === b.cellPxW && a.cellPxH === b.cellPxH
+}
+
+/** `surface.region-layout` for a model and geometry. */
+export function regionLayout(model, g) {
+  const slotLen = model === 'cells' ? g.cols * g.rows * CELL_LEN : g.pxW * g.pxH * PIXEL_LEN
+  return { len: HEADER_LEN + 2 * slotLen, headerLen: HEADER_LEN, slotLen, model, geometry: g }
+}
+
+/** Whether a region header describes exactly this layout (seq aside). */
+export function headerMatches(layout, bytes) {
+  if (bytes.byteLength < HEADER_LEN) return false
+  const view = new DataView(bytes.buffer, bytes.byteOffset, HEADER_LEN)
+  const g = layout.geometry
+  const expected = [MODELS[layout.model], g.cols, g.rows, g.pxW, g.pxH, g.cellPxW, g.cellPxH]
+  return expected.every((word, index) => view.getUint32((index + 1) * 4, true) === word)
+}
+
+/** The model's addressable size: cells or pixels. */
+export function extent(model, g) {
+  return model === 'cells' ? [g.cols, g.rows] : [g.pxW, g.pxH]
+}
+
+/** The part of `[x, y, w, h]` inside `width` by `height`, or `null`. */
+export function clampRect(rect, width, height) {
+  const [x, y, w, h] = rect
+  const right = Math.min(x + w, width)
+  const bottom = Math.min(y + h, height)
+  return x < right && y < bottom ? [x, y, right - x, bottom - y] : null
+}
+
+/** Bytes per unit of a rectangle (a cell or a pixel). */
+function unitLen(model) {
+  return model === 'cells' ? CELL_LEN : PIXEL_LEN
+}
+
+/**
+ * Copies `rects` of one slot image from `source` (at `sourceOffset`) into
+ * `target` (at `targetOffset`). Both images have the same layout: `width`
+ * units per row, `unit` bytes per unit. Rows a rectangle spans whole are one
+ * copy.
+ */
+export function copyRects(source, sourceOffset, target, targetOffset, rects, width, unit) {
+  const stride = width * unit
+  let bytes = 0
+  for (const [x, y, w, h] of rects) {
+    if (x === 0 && w === width) {
+      const start = y * stride
+      const length = h * stride
+      target.set(source.subarray(sourceOffset + start, sourceOffset + start + length), targetOffset + start)
+      bytes += length
+      continue
+    }
+    const length = w * unit
+    for (let row = y; row < y + h; row++) {
+      const start = row * stride + x * unit
+      target.set(source.subarray(sourceOffset + start, sourceOffset + start + length), targetOffset + start)
+      bytes += length
+    }
+  }
+  return bytes
+}
+
+/** Rectangles accumulated across commits: a list, or everything. */
+export class Dirty {
+  constructor(full = false) {
+    this.full = full
+    this.rects = []
+  }
+
+  add(rects, full) {
+    if (this.full) return
+    if (full) {
+      this.full = true
+      this.rects = []
+      return
+    }
+    this.rects.push(...rects)
+    if (this.rects.length > MAX_MERGED_RECTS) {
+      this.full = true
+      this.rects = []
+    }
+  }
+
+  empty() {
+    return !this.full && this.rects.length === 0
+  }
+
+  /** The rectangles to copy, clamped; the whole image when full. */
+  resolve(width, height) {
+    if (this.full) return [[0, 0, width, height]]
+    return this.rects.map(rect => clampRect(rect, width, height)).filter(Boolean)
+  }
+
+  take() {
+    const taken = { full: this.full, rects: this.rects }
+    this.full = false
+    this.rects = []
+    return taken
+  }
+}
+
+// ── the viewer's buffers for one surface ────────────────────────────────────
+
+/**
+ * The output of one surface at one size: `RING_SLOTS` buffers of
+ * `SLOT_HEADER + slot-len` bytes each, the viewer's to sample. A slot is
+ * either the worker's (it may write it) or the viewer's (published, and
+ * never written until the viewer releases it), so the viewer never reads a
+ * slot being written. Each slot holds a whole image: before a slot is
+ * published, everything that changed since its content was written is
+ * copied into it from the plugin's committed slot.
+ *
+ * With `SharedArrayBuffer`s both sides keep references and only the
+ * ownership moves (in messages); with plain `ArrayBuffer`s the buffer itself
+ * is transferred each way.
+ */
+export class SurfaceOutput {
+  constructor({ model, geometry: g, gen, buffers, shared }) {
+    this.model = model
+    this.geometry = g
+    this.gen = gen
+    this.shared = shared
+    this.layout = regionLayout(model, g)
+    this.width = extent(model, g)[0]
+    this.height = extent(model, g)[1]
+    this.slots = buffers.map(buffer => ({ buffer, owned: true, missing: new Dirty(true) }))
+    this.seq = 0
+    /** What changed since the last publish: what the viewer must redraw.
+     *  The viewer has nothing at this size yet, so the first publish is
+     *  whole. */
+    this.unpublished = new Dirty(true)
+    /** A commit that found no free slot waits here for a release. */
+    this.deferred = null
+  }
+
+  /**
+   * Publishes one commit. `source()` returns the plugin's memory as bytes
+   * and the offset of its committed slot, read at copy time (linear memory
+   * may have grown since). Returns the message fields and the buffer to
+   * hand over, or `null` when every slot is the viewer's (the commit waits
+   * for a release and carries into the next publish).
+   */
+  publish(source, rects, full) {
+    for (const slot of this.slots) slot.missing.add(rects, full)
+    this.unpublished.add(rects, full)
+    const index = this.slots.findIndex(slot => slot.owned && slot.buffer)
+    if (index < 0) {
+      this.deferred = source
+      return null
+    }
+    this.deferred = null
+    return this.write(index, source)
+  }
+
+  write(index, source) {
+    const slot = this.slots[index]
+    const { bytes, offset } = source()
+    const data = new Uint8Array(slot.buffer, SLOT_HEADER, this.layout.slotLen)
+    const words = new Int32Array(slot.buffer, 0, 2)
+    // Invalid while written: a viewer that ever looked here would see a
+    // sequence number that matches no commit.
+    Atomics.store(words, 0, 0)
+    const rects = slot.missing.resolve(this.width, this.height)
+    const copied = copyRects(bytes, offset, data, 0, rects, this.width, unitLen(this.model))
+    slot.missing = new Dirty()
+    this.seq = (this.seq + 1) >>> 0 || 1
+    Atomics.store(words, 1, this.gen)
+    Atomics.store(words, 0, this.seq)
+    slot.owned = false
+    const changed = this.unpublished.take()
+    const buffer = slot.buffer
+    if (!this.shared) slot.buffer = null
+    return {
+      message: {
+        gen: this.gen,
+        slot: index,
+        seq: this.seq,
+        full: changed.full,
+        rects: changed.full ? [] : changed.rects.map(rect => clampRect(rect, this.width, this.height)).filter(Boolean),
+      },
+      buffer: this.shared ? null : buffer,
+      copied,
+    }
+  }
+
+  /** The viewer is done with `index`. Publishes a waiting commit, if any. */
+  release(index, buffer) {
+    const slot = this.slots[index]
+    if (!slot || slot.owned) return null
+    if (!this.shared) {
+      if (!buffer || buffer.byteLength !== SLOT_HEADER + this.layout.slotLen) return null
+      slot.buffer = buffer
+    }
+    slot.owned = true
+    if (!this.deferred) return null
+    const source = this.deferred
+    this.deferred = null
+    return this.write(index, source)
+  }
+}
+
+// ── the host imports ─────────────────────────────────────────────────────────
+
+function err(tag, val) {
+  return val === undefined ? { tag: 'err', val: { tag } } : { tag: 'err', val: { tag, val } }
+}
+
+const VALUE_MAX_BYTES = 256 * 1024
+
+/** `send`s and `call-async`s of one plugin in flight at once. */
+export const MAX_CALLS_IN_FLIGHT = 32
+
+/** A call the viewer puts to the account; `timeoutMs` absent is the default. */
+function callOf(method, payload, to, timeoutMs) {
+  const call = { op: 'call', method, payload, to: to ?? { tag: 'singleton' } }
+  if (timeoutMs !== undefined && timeoutMs !== null) call.timeoutMs = timeoutMs >>> 0
+  return call
+}
+
+/** What a call that needs the account answers in a browser without JSPI. */
+export const NEEDS_JSPI = 'unsupported: this browser cannot wait for the account (no JSPI); see docs/plugin-runtime.md'
+
+/** The event a failed fire-and-forget write reports (the mirror mode). */
+export const WRITE_FAILED_EVENT = 'system.plugin.write-failed'
+
+/** A viewer's `{ ok }` / `{ err: { tag, val? } }` reply as the WIT result. */
+export function witResult(reply) {
+  if (reply && reply.err) return { tag: 'err', val: reply.err }
+  return reply?.ok ?? undefined
+}
+
+/**
+ * What a plugin reads of the account when the browser cannot wait for it:
+ * the values under the prefixes it may read, the secrets its grants name,
+ * kept current by the viewer (`{ t: 'mirror' }`). `complete` lists the
+ * prefixes whose every key is here; a key under another prefix may exist
+ * unseen.
+ */
+export class Mirror {
+  constructor({ values = {}, complete = [], secrets = {} } = {}) {
+    this.values = new Map(Object.entries(values))
+    this.complete = [...complete]
+    this.secrets = new Map(Object.entries(secrets))
+  }
+
+  apply(values) {
+    for (const [key, value] of Object.entries(values)) {
+      if (value === null) this.values.delete(key)
+      else this.values.set(key, value)
+    }
+  }
+
+  covers(key) {
+    return this.complete.some(prefix => key.startsWith(prefix))
+  }
+}
+
+/**
+ * One plugin instance's host: grants, the account interfaces, the
+ * viewer's view state, and the surfaces. `post(message, buffer)` sends to
+ * the viewer; `memory()` returns the instance's linear memory once it
+ * exists.
+ *
+ * `grants` are the grants the plugin runs with (its manifest's, and for an
+ * account install only those the account approved); the manifest's when
+ * absent. `account` selects the account interfaces:
+ *
+ * - absent: in memory, as the native `InMemoryProvider` (the demo samples);
+ * - `{ mode: 'jspi', ask }`: every call goes to the account through the
+ *   viewer (`ask(call)` resolves with its `{ ok } | { err }`), and the
+ *   import suspends the plugin until it answers;
+ * - `{ mode: 'mirror', ask, mirror }`: reads answer from the mirror, writes
+ *   go out without waiting and a refusal arrives later as the
+ *   `system.plugin.write-failed` event, calls and claims are unsupported.
+ *
+ * `deliver(event)` queues an event for the plugin (the Worker calls it
+ * between exports).
+ */
+export class PluginHost {
+  constructor({ manifest, grants, config = '{}', view, shared, post, memory, account = null, deliver = () => {} }) {
+    this.id = manifest.id
+    this.grants = new Grants(manifest.id, grants ?? manifestGrants(manifest))
+    this.config = config
+    this.view = view
+    this.shared = shared
+    this.post = post
+    this.memory = memory
+    this.account = account
+    this.deliver = deliver
+    this.accountState = { machines: [], projects: [], panes: [] }
+    this.accountWatched = false
+    this.values = new Map()
+    this.secrets = new Map()
+    this.claims = new Set()
+    this.published = []
+    this.denials = 0
+    this.lastDenied = null
+    /** The region the next `attach` names: set by the core-import shim. */
+    this.attaching = null
+    /** The plugin is handling a user gesture: `surface.open` may run. */
+    this.gesture = false
+    /** When the viewer last delivered user input, until `url.open` used it. */
+    this.inputAt = null
+    /** `call-async` ids, unique for this instance's life. */
+    this.nextCallId = 1n
+    this.callsInFlight = 0
+    this.surfaces = new Map((manifest.surfaces ?? []).map(decl => [decl.id, this.newSurface(decl, null)]))
+  }
+
+  newSurface(decl, owner) {
+    const perMachine = decl.anchor === 'machine.after'
+    const perProject = decl.anchor === 'project.after'
+    return {
+      decl,
+      pane: perMachine || perProject ? null : owner,
+      machine: perMachine ? owner : null,
+      project: perProject ? owner : null,
+      requested: null,
+      // The viewer names the model it picked with every resize.
+      model: modelsOf(decl)[0],
+      geometry: geometry(0, 0, 0, 0),
+      region: null,
+      pendingRegion: null,
+      committed: false,
+      output: null,
+    }
+  }
+
+  /** A surface by id; a pane instance (`<surface>@<pane>`) of a footer or
+   *  header, a machine instance (`<surface>@<machine>`) of a machine row or
+   *  a project instance (`<surface>@<project>`) of a project row, is
+   *  created the first time the viewer sizes it. */
+  surface(id, create = false) {
+    const known = this.surfaces.get(id)
+    if (known || !create) return known
+    const at = id.indexOf('@')
+    const template = at > 0 ? this.surfaces.get(id.slice(0, at)) : null
+    if (!template || template.pane != null || template.machine != null || template.project != null
+      || !INSTANCED.includes(template.decl.anchor)) return undefined
+    const instance = this.newSurface(template.decl, id.slice(at + 1))
+    this.surfaces.set(id, instance)
+    return instance
+  }
+
+  denied(grant) {
+    this.denials += 1
+    this.lastDenied = grant
+    this.post({ t: 'denied', grant })
+    return err('grant-denied', grant)
+  }
+
+  check(grant) {
+    return this.grants.check(grant)
+  }
+
+  namespaced(kind, subject) {
+    return this.grants.checkNamespaced(kind, subject)
+  }
+
+  /** The viewer resized a surface: the ring for its new size. */
+  resize(id, g, gen, buffers, model) {
+    const surface = this.surface(id, true)
+    if (!surface) return
+    if (model && model !== surface.model) {
+      // Another model: the old region describes nothing the viewer reads.
+      surface.model = model
+      surface.region = null
+      surface.pendingRegion = null
+      surface.committed = false
+    }
+    surface.geometry = g
+    surface.output = geometryEmpty(g) ? null : new SurfaceOutput({
+      model: surface.model, geometry: g, gen, buffers, shared: this.shared,
+    })
+  }
+
+  /** The viewer is done with a slot it held. */
+  release(id, gen, slot, buffer) {
+    const surface = this.surfaces.get(id)
+    const output = surface?.output
+    if (!output || output.gen !== gen) return
+    this.send(id, output.release(slot, buffer))
+  }
+
+  send(id, published) {
+    if (!published) return
+    this.post({ t: 'commit', surface: id, ...published.message }, published.buffer)
+  }
+
+  layout(id) {
+    const surface = this.surfaces.get(id)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    return regionLayout(surface.model, surface.geometry)
+  }
+
+  attach(id, region) {
+    const pointer = this.attaching
+    this.attaching = null
+    const surface = this.surfaces.get(id)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    const layout = regionLayout(surface.model, surface.geometry)
+    if (geometryEmpty(surface.geometry)) return err('invalid', `surface ${JSON.stringify(id)} has no size yet`)
+    if (!pointer || pointer.len !== region.byteLength) return err('invalid', 'the region is not in linear memory')
+    if (region.byteLength < layout.len) {
+      return err('invalid', `region of ${region.byteLength} bytes is smaller than the ${layout.len} the layout needs`)
+    }
+    if (!headerMatches(layout, region)) return err('invalid', 'region header does not describe the current layout')
+    const bound = { base: pointer.ptr, len: pointer.len, layout }
+    if (surface.region) surface.pendingRegion = bound
+    else surface.region = bound
+    return undefined
+  }
+
+  commit(id, slot, dirty) {
+    const surface = this.surfaces.get(id)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    if (!surface.region && !surface.pendingRegion) return err('invalid', `surface ${JSON.stringify(id)} has no region attached`)
+    if (slot > 1) return err('invalid', 'slot must be 0 or 1')
+    let full = Boolean(surface.pendingRegion) || !surface.committed
+    const rects = dirty.map(rect => [rect.x, rect.y, rect.w, rect.h])
+    if (!full && rects.length === 0) return undefined
+    if (surface.pendingRegion) {
+      // The first commit after an attach is at the new region's size.
+      surface.region = surface.pendingRegion
+      surface.pendingRegion = null
+    }
+    surface.committed = true
+    const region = surface.region
+    const output = surface.output
+    // A region at another size than the viewer's buffers (a commit racing
+    // a resize) is never copied: the viewer keeps its last frame until the
+    // plugin commits at the new size.
+    if (!output || !sameGeometry(region.layout.geometry, output.geometry)) return undefined
+    const offset = region.base + HEADER_LEN + slot * region.layout.slotLen
+    const memory = this.memory
+    const source = () => ({ bytes: new Uint8Array(memory().buffer), offset })
+    if (offset + region.layout.slotLen > memory().buffer.byteLength) {
+      return err('invalid', 'the region lies outside linear memory')
+    }
+    this.send(id, output.publish(source, rects, full))
+    return undefined
+  }
+
+  /** `surface.open`: a stage or a popover, and only during a user gesture. */
+  open(id) {
+    const surface = this.surfaces.get(id)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    if (!OPENS.includes(surface.decl.anchor)) {
+      return err('invalid', `surface ${JSON.stringify(id)} is placed by the viewer; only a stage or a popover opens`)
+    }
+    if (!this.gesture) return err('invalid', 'surface.open needs a user gesture: a key, paste or press on one of the plugin\'s surfaces, or one of its commands')
+    this.post({ t: 'surface', surface: id, open: true })
+    return undefined
+  }
+
+  /** User input reached the plugin: it may open one URL now or shortly. */
+  noteInput() {
+    this.inputAt = performance.now()
+  }
+
+  /** `url.open`: an https URL on a granted host, on user input, once per
+   *  input. The viewer checks all of it again and opens the tab. */
+  openUrl(url) {
+    const host = httpsHost(url)
+    if (host == null) {
+      return err('invalid', 'url.open takes a plain https:// URL with a host and no whitespace')
+    }
+    if (!this.grants.allowsUrlOpen(host)) return this.denied(`url.open:${host}`)
+    const at = this.inputAt
+    if (at == null || (!this.gesture && performance.now() - at > URL_OPEN_WINDOW_MS)) {
+      return err('invalid', 'url.open needs user input: a key, paste or press on one of the plugin\'s surfaces, or one of its commands, within the last second')
+    }
+    this.inputAt = null
+    this.post({ t: 'open-url', url })
+    return undefined
+  }
+
+  /** `surface.request-size`: bounded here as natively; the viewer clamps it
+   *  where it places the surface and answers with a resize. */
+  requestSize(id, cols, rows) {
+    // An instance the viewer has not sized yet (a machine or project row at
+    // zero rows) takes a request too, as natively.
+    const surface = this.surface(id, true)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    const requested = [Math.min(cols >>> 0, MAX_COLS), Math.min(rows >>> 0, MAX_ROWS)]
+    if (surface.requested?.[0] !== requested[0] || surface.requested?.[1] !== requested[1]) {
+      surface.requested = requested
+      this.post({ t: 'request-size', surface: id, cols: requested[0], rows: requested[1] })
+    }
+    return undefined
+  }
+
+  close(id) {
+    if (!this.surfaces.get(id)) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    this.post({ t: 'surface', surface: id, open: false })
+    return undefined
+  }
+
+  detach(id) {
+    const surface = this.surfaces.get(id)
+    if (!surface) return err('invalid', `no surface ${JSON.stringify(id)} in the manifest`)
+    surface.region = null
+    surface.pendingRegion = null
+    surface.committed = false
+    return undefined
+  }
+
+  /** Sends one account call and answers its WIT result (JSPI mode). */
+  ask(call) {
+    return this.account.ask(call).then(witResult, error => err('unavailable', String(error?.message ?? error)))
+  }
+
+  /**
+   * A write without waiting (the mirror mode): the call goes out and a
+   * refusal reaches the plugin later as `system.plugin.write-failed`.
+   * `undo` puts back what the write changed locally.
+   */
+  tell(call, undo = () => {}) {
+    this.account.ask(call).then((reply) => {
+      if (!reply?.err) return
+      undo()
+      this.deliver({
+        tag: 'plugin-event',
+        name: WRITE_FAILED_EVENT,
+        payload: JSON.stringify({ call: call.op, key: call.key ?? call.name ?? call.prefix ?? call.pattern ?? null, error: reply.err }),
+      })
+    }, () => {})
+    return undefined
+  }
+
+  /**
+   * A `send` or `call-async`: goes to the account at once and hands its
+   * outcome (`{ tag: 'ok' | 'err', val }`) to `done` when it arrives. At
+   * most `MAX_CALLS_IN_FLIGHT` at once, as natively; `rate-limited` past
+   * that. Returns an error result, or `undefined` once sent.
+   */
+  startCall(call, done) {
+    if (this.callsInFlight >= MAX_CALLS_IN_FLIGHT) return err('rate-limited')
+    this.callsInFlight += 1
+    const settle = (outcome) => {
+      this.callsInFlight -= 1
+      done(outcome)
+    }
+    this.account.ask(call).then(
+      reply => settle(reply?.err ? { tag: 'err', val: reply.err } : { tag: 'ok', val: String(reply?.ok ?? 'null') }),
+      error => settle({ tag: 'err', val: { tag: 'unavailable', val: String(error?.message ?? error) } }),
+    )
+    return undefined
+  }
+
+  /** Whether calls go to the account (an installed plugin). */
+  get onAccount() {
+    return this.account !== null
+  }
+
+  get waits() {
+    return this.account?.mode === 'jspi'
+  }
+
+  /** A read from the mirror: the value, none, or `unavailable` when the
+   *  key may exist beyond what the mirror holds. */
+  mirrored(key) {
+    const mirror = this.account.mirror
+    if (mirror.values.has(key)) return mirror.values.get(key)
+    if (mirror.covers(key)) return undefined
+    this.account.ask({ op: 'values.fetch', key }).catch(() => {})
+    return err('unavailable', `${key} is not mirrored in this browser yet; ${NEEDS_JSPI}`)
+  }
+
+  /** A value write in the mirror mode: applied locally at once. */
+  mirrorWrite(call, key, value) {
+    const values = this.account.mirror.values
+    const before = values.has(key) ? values.get(key) : null
+    if (value === null) values.delete(key)
+    else values.set(key, value)
+    return this.tell(call, () => {
+      // Only if nothing newer arrived since.
+      if ((values.get(key) ?? null) !== value) return
+      if (before === null) values.delete(key)
+      else values.set(key, before)
+    })
+  }
+
+  /** The import object a `ui-plugin` component instantiates with. */
+  imports() {
+    const host = this
+    const denial = grant => (grant ? host.denied(grant) : null)
+    return {
+      'standard:plugin/types': {},
+      'standard:plugin/event-types': {},
+      'standard:plugin/values': {
+        get(key) {
+          const denied = denial(host.namespaced('values.read', key))
+          if (denied) return denied
+          if (!host.onAccount) return host.values.get(key)
+          if (host.waits) return host.ask({ op: 'values.get', key })
+          return host.mirrored(key)
+        },
+        set(key, value) {
+          const denied = denial(host.namespaced('values.write', key))
+          if (denied) return denied
+          if (value.length > VALUE_MAX_BYTES) return err('invalid', 'value over 256 KiB')
+          if (!host.onAccount) {
+            host.values.set(key, value)
+            return undefined
+          }
+          const call = { op: 'values.set', key, value }
+          return host.waits ? host.ask(call) : host.mirrorWrite(call, key, value)
+        },
+        delete(key) {
+          const denied = denial(host.namespaced('values.write', key))
+          if (denied) return denied
+          if (!host.onAccount) {
+            host.values.delete(key)
+            return undefined
+          }
+          const call = { op: 'values.delete', key }
+          return host.waits ? host.ask(call) : host.mirrorWrite(call, key, null)
+        },
+        keys(prefix) {
+          const denied = denial(host.namespaced('values.read', prefix))
+          if (denied) return denied
+          const listed = values => [...values.keys()].filter(key => key.startsWith(prefix)).sort()
+          if (!host.onAccount) return listed(host.values)
+          if (host.waits) return host.ask({ op: 'values.keys', prefix })
+          const mirror = host.account.mirror
+          if (!mirror.covers(prefix)) return err('unavailable', `keys under ${prefix} are not all mirrored; ${NEEDS_JSPI}`)
+          return listed(mirror.values)
+        },
+        watch(prefix) {
+          const denied = denial(host.namespaced('values.read', prefix))
+          if (denied) return denied
+          // The viewer's router passes on only watched keys; nothing waits.
+          if (host.onAccount) host.account.ask({ op: 'values.watch', prefix }).catch(() => {})
+          return undefined
+        },
+      },
+      'standard:plugin/live': {
+        publish(key, payload) {
+          const denied = denial(host.namespaced('live.publish', key))
+          if (denied) return denied
+          if (!host.onAccount) {
+            host.published.push(['live', key, payload])
+            return undefined
+          }
+          const call = { op: 'live.publish', key, payload }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+        delete(key) {
+          const denied = denial(host.namespaced('live.publish', key))
+          if (denied) return denied
+          if (!host.onAccount) {
+            host.published.push(['live-delete', key, ''])
+            return undefined
+          }
+          const call = { op: 'live.delete', key }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+        subscribe(prefix) {
+          const denied = denial(host.namespaced('live.subscribe', prefix))
+          if (denied || !host.onAccount) return denied ?? undefined
+          const call = { op: 'live.subscribe', prefix, on: true }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+        unsubscribe(prefix) {
+          const denied = denial(host.namespaced('live.subscribe', prefix))
+          if (denied || !host.onAccount) return denied ?? undefined
+          const call = { op: 'live.subscribe', prefix, on: false }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+      },
+      'standard:plugin/events': {
+        emit(name, payload, to) {
+          if (name.startsWith('system.')) return host.denied(`events.emit:${name}`)
+          const denied = denial(host.namespaced('events.emit', name))
+          if (denied) return denied
+          if (!host.onAccount) {
+            host.published.push(['event', name, payload])
+            return undefined
+          }
+          const call = { op: 'events.emit', name, payload, to: to ?? { tag: 'all' } }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+        on(pattern) {
+          const denied = denial(host.namespaced('events.on', pattern))
+          if (denied || !host.onAccount) return denied ?? undefined
+          const call = { op: 'events.listen', pattern, on: true }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+        off(pattern) {
+          const denied = denial(host.namespaced('events.on', pattern))
+          if (denied || !host.onAccount) return denied ?? undefined
+          const call = { op: 'events.listen', pattern, on: false }
+          return host.waits ? host.ask(call) : host.tell(call)
+        },
+      },
+      'standard:plugin/calls': {
+        call(method, payload, to, timeoutMs) {
+          const denied = denial(host.check(`call:${host.id}`))
+          if (denied) return denied
+          if (!host.onAccount) return err('unavailable', 'companion calls arrive with the account service')
+          if (!host.waits) return err('unavailable', NEEDS_JSPI)
+          return host.ask(callOf(method, payload, to, timeoutMs))
+        },
+        // Neither waits, with or without JSPI: the call goes out and the
+        // plugin carries on.
+        send(method, payload, to) {
+          const denied = denial(host.check(`call:${host.id}`))
+          if (denied) return denied
+          if (!host.onAccount) return err('unavailable', 'companion calls arrive with the account service')
+          return host.startCall(callOf(method, payload, to, undefined), () => {})
+        },
+        callAsync(method, payload, to, timeoutMs) {
+          const denied = denial(host.check(`call:${host.id}`))
+          if (denied) return denied
+          if (!host.onAccount) return err('unavailable', 'companion calls arrive with the account service')
+          const id = host.nextCallId
+          const started = host.startCall(callOf(method, payload, to, timeoutMs), (outcome) => {
+            host.deliver({ tag: 'call-result', id, outcome })
+          })
+          if (started) return started
+          host.nextCallId += 1n
+          return id
+        },
+      },
+      'standard:plugin/config': {
+        get() {
+          return host.config
+        },
+      },
+      'standard:plugin/secrets': {
+        get(name) {
+          const denied = denial(host.check(`secret:${name}`))
+          if (denied) return denied
+          if (!host.onAccount) return host.secrets.get(name)
+          if (host.waits) return host.ask({ op: 'secret.get', name })
+          const secrets = host.account.mirror.secrets
+          return secrets.has(name) ? (secrets.get(name) ?? undefined) : err('unavailable', NEEDS_JSPI)
+        },
+      },
+      // Claims live in the plugin's own namespace: no grant. In memory one
+      // instance holds every claim it takes, as the native in-memory host.
+      'standard:plugin/claims': {
+        claim(key, ttlMs) {
+          if (!host.onAccount) {
+            host.claims.add(key)
+            return true
+          }
+          if (!host.waits) return err('unavailable', NEEDS_JSPI)
+          return host.ask({ op: 'claim', key, ttlMs: ttlMs >>> 0 })
+        },
+        // The holder releases; releasing a claim this session does not
+        // hold does nothing. Without JSPI the release is sent and not awaited.
+        release(key) {
+          if (!host.onAccount) {
+            host.claims.delete(key)
+            return undefined
+          }
+          if (host.waits) host.ask({ op: 'claim.release', key })
+          else host.tell({ op: 'claim.release', key })
+          return undefined
+        },
+      },
+      // The plugin's own report; the viewer lists it in the Plugins view.
+      'standard:plugin/health': {
+        set(state, message) {
+          host.post({ t: 'health', state, message: String(message).slice(0, 200) })
+        },
+      },
+      'standard:plugin/account': {
+        state() {
+          const denied = denial(host.check('account.read'))
+          if (denied) return denied
+          const state = host.accountState
+          // `generation` is a u64: the glue lowers it from a BigInt.
+          return { ...state, panes: (state.panes ?? []).map(pane => ({ ...pane, generation: BigInt(pane.generation ?? 0) })) }
+        },
+        watch() {
+          const denied = denial(host.check('account.read'))
+          if (denied) return denied
+          host.accountWatched = true
+          return undefined
+        },
+      },
+      'standard:plugin/surface': {
+        layout: id => host.layout(id),
+        attach: (id, region) => host.attach(id, region),
+        commit: (id, slot, dirty) => host.commit(id, slot, dirty),
+        detach: id => host.detach(id),
+        open: id => host.open(id),
+        close: id => host.close(id),
+        requestSize: (id, cols, rows) => host.requestSize(id, cols, rows),
+      },
+      'standard:plugin/url': {
+        open: url => host.openUrl(url),
+      },
+      'standard:plugin/view': {
+        isDriving: () => Boolean(host.view.driving),
+        theme() {
+          const [fg, bg, recedeFg, recedeBg, accent] = host.view.theme
+          const palette = Array.isArray(host.view.palette) && host.view.palette.length === 16
+            ? host.view.palette
+            : XTERM_PALETTE
+          return { fg, bg, recedeFg, recedeBg, accent, palette }
+        },
+        surfaceMachine: id => host.surfaces.get(id)?.machine ?? undefined,
+        surfaceProject: id => host.surfaces.get(id)?.project ?? undefined,
+        surfaceTint(id) {
+          const surface = host.surfaces.get(id)
+          const tints = host.view.tints ?? {}
+          if (!surface) return undefined
+          if (surface.machine != null) return tints[surface.machine] ?? undefined
+          if (surface.project != null) return tints[surface.project] ?? undefined
+          if (surface.pane == null) return undefined
+          const pane = (host.accountState.panes ?? []).find(entry => entry.id === surface.pane)
+          if (!pane) return undefined
+          return (pane.project != null ? tints[pane.project] : undefined) ?? tints[pane.machine] ?? undefined
+        },
+        identityTint: id => (host.view.tints ?? {})[id] ?? undefined,
+        capabilities() {
+          const [cellPxW, cellPxH] = host.view.cellPx ?? [0, 0]
+          const pixelScale = Math.max(1, host.view.pixelScale >>> 0)
+          const scaled = size => (size === 0 ? 0 : Math.max(1, Math.floor(size / pixelScale)))
+          return {
+            graphics: Boolean(host.view.graphics),
+            cellPxW: scaled(cellPxW),
+            cellPxH: scaled(cellPxH),
+            fps: host.view.fps >>> 0,
+            pixelScale,
+          }
+        },
+        focusedPane: () => host.view.focusedPane ?? undefined,
+        machineId: () => host.view.machineId ?? undefined,
+        instanceId: () => String(host.view.instanceId ?? ''),
+        // The browser's own clock and zone, read when the plugin asks.
+        wallMs: () => BigInt(Date.now()),
+        utcOffsetMinutes: () => -new Date().getTimezoneOffset(),
+        timeZone: () => Intl.DateTimeFormat().resolvedOptions().timeZone || undefined,
+        surfacePane(id) {
+          const pane = host.surfaces.get(id)?.pane
+          if (pane == null) return undefined
+          const known = (host.accountState.panes ?? []).find(entry => entry.id === pane)
+          return { id: pane, generation: BigInt(known?.generation ?? 0) }
+        },
+        // The viewer's clock is its own; 0 means "the next paced frame".
+        requestFrame: () => host.post({ t: 'wake', at: 0 }),
+        wakeAt: at => host.post({ t: 'wake', at: Number(at) }),
+      },
+    }
+  }
+}
+
+/** The `event` export's value for a viewer event message. */
+export function witEvent(event) {
+  switch (event.tag) {
+    case 'resize': return { tag: 'resize', val: [event.surface, event.geometry] }
+    case 'visibility': return { tag: 'visibility', val: [event.surface, Boolean(event.visible)] }
+    case 'driving': return { tag: 'driving', val: Boolean(event.driving) }
+    case 'capabilities-changed': return { tag: 'capabilities-changed' }
+    case 'theme-changed': return { tag: 'theme-changed' }
+    case 'focus': return { tag: 'focus', val: [event.surface, Boolean(event.focused)] }
+    case 'command': return { tag: 'command', val: event.id }
+    // A `call-async` finished (the Worker's own delivery).
+    case 'call-result': return { tag: 'call-result', val: { id: BigInt(event.id), outcome: event.outcome } }
+    // The account's pushes, routed to this plugin only by the viewer.
+    case 'value-changed': return { tag: 'value-changed', val: [event.key, event.value ?? undefined] }
+    case 'live': return { tag: 'live', val: [event.key, event.value] }
+    case 'live-deleted': return { tag: 'live-deleted', val: event.key }
+    case 'plugin-event': return { tag: 'plugin-event', val: [event.name, event.payload] }
+    case 'account-changed': return { tag: 'account-changed' }
+    case 'key': return {
+      tag: 'key',
+      val: {
+        surface: event.surface,
+        code: event.code,
+        text: event.text ?? undefined,
+        modifiers: event.modifiers >>> 0,
+        phase: event.phase,
+      },
+    }
+    case 'paste': return { tag: 'paste', val: [event.surface, event.text] }
+    case 'pointer': return {
+      tag: 'pointer',
+      val: {
+        surface: event.surface,
+        x: event.x >>> 0,
+        y: event.y >>> 0,
+        col: event.col >>> 0,
+        row: event.row >>> 0,
+        button: event.button & 0xff,
+        kind: event.kind,
+        modifiers: event.modifiers >>> 0,
+      },
+    }
+    default: throw new Error(`unknown event ${event.tag}`)
+  }
+}