@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/lib/ids.ts

@@ -0,0 +1,93 @@
+import { isPrincipal, principal, type Principal } from "@meantjs/schema"
+import { principalBytesFromText } from "@meantjs/schema/codec"
+
+/**
+ * Why a text is not a canister id the studio can open. The codes are the
+ * id-related members of the interface loader's error codes, so the server
+ * function returns them as they are.
+ */
+export type CanisterIdProblem =
+  "invalid_canister_id" | "not_a_canister" | "management_canister"
+
+export type CanisterIdCheck =
+  | { readonly ok: true; readonly id: Principal }
+  | {
+      readonly ok: false
+      readonly code: CanisterIdProblem
+      readonly message: string
+    }
+
+/** The management canister: no interface of its own, and no calls from here. */
+export const MANAGEMENT_CANISTER_ID = "aaaaa-aa"
+
+// The longest canonical principal text (29 bytes) is 63 characters. Anything
+// longer is refused before it is parsed at all.
+const MAX_PRINCIPAL_TEXT = 63
+
+// Canister ids are opaque principals: 10 bytes, the last one 0x01. Users'
+// self-authenticating principals end in 0x02, and the anonymous principal is
+// the single byte 0x04.
+const CANISTER_ID_BYTES = 10
+const OPAQUE_ID_SUFFIX = 0x01
+
+/**
+ * Checks that `text` is a canister id the studio may read and call: canonical
+ * principal text whose bytes are an opaque 10-byte id, and not the management
+ * canister. The text is taken as it is: trim user input first, but never
+ * repair it (upper case, a missing dash), as `principal()` refuses to.
+ *
+ * Shared by the browser (the jump box, route params) and the server function
+ * that reads an interface, so both refuse the same ids with the same codes.
+ */
+export function checkCanisterId(text: string): CanisterIdCheck {
+  if (text === MANAGEMENT_CANISTER_ID) {
+    return {
+      ok: false,
+      code: "management_canister",
+      message:
+        "aaaaa-aa is the management canister: it publishes no interface, and the studio does not call it.",
+    }
+  }
+  if (text.length > MAX_PRINCIPAL_TEXT || !isPrincipal(text)) {
+    return {
+      ok: false,
+      code: "invalid_canister_id",
+      message: principalProblem(text) ?? "Not canonical principal text.",
+    }
+  }
+  const bytes = principalBytesFromText(text)
+  if (
+    bytes === undefined ||
+    bytes.length !== CANISTER_ID_BYTES ||
+    bytes[CANISTER_ID_BYTES - 1] !== OPAQUE_ID_SUFFIX
+  ) {
+    return {
+      ok: false,
+      code: "not_a_canister",
+      message:
+        "This principal is not a canister id: a canister id is 10 bytes ending in 0x01, and this looks like a user or the anonymous principal.",
+    }
+  }
+  return { ok: true, id: text }
+}
+
+/** Whether `text` is a canister id `checkCanisterId` accepts. */
+export function isCanisterId(text: string): boolean {
+  return checkCanisterId(text).ok
+}
+
+/**
+ * Why `text` is not canonical principal text (the message `principal()`
+ * throws), or `undefined` when it is.
+ */
+export function principalProblem(text: string): string | undefined {
+  if (text.length > MAX_PRINCIPAL_TEXT) {
+    return `Principal text is at most ${MAX_PRINCIPAL_TEXT} characters.`
+  }
+  try {
+    principal(text)
+    return undefined
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error)
+  }
+}

package/examples/canister-studio/src/lib/reactor.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest"
+import { createAppClient, toVars } from "./reactor.ts"
+
+describe("toVars", () => {
+  it("follows the builders' convention: nothing, the value, or the tuple", () => {
+    expect(toVars([])).toBeUndefined()
+    expect(toVars([5n])).toBe(5n)
+    const record = { owner: "aaaaa-aa" }
+    expect(toVars([record])).toBe(record)
+    expect(toVars([null])).toBeNull()
+    const values = [1, "two"] as const
+    const vars = toVars(values)
+    expect(vars).toEqual([1, "two"])
+    expect(vars).not.toBe(values)
+  })
+})
+
+describe("createAppClient", () => {
+  it("makes a mainnet client that keeps reads fresh for a minute", () => {
+    const client = createAppClient()
+    try {
+      expect(client.network).toBe("ic")
+      // On a server the client is anonymous and never builds the auth.
+      expect(client.authState().status).toBe("anonymous")
+      const defaults = client.queryClient.getQueryDefaults([
+        "ic-reactor",
+        "ic",
+        "2vxsx-fae",
+        "ryjl3-tyaaa-aaaaa-aaaba-cai",
+        "icrc1_fee",
+        "4449444c0000",
+      ])
+      expect(defaults.staleTime).toBe(60_000)
+      // The client's own defaults (read retry, serializers) are untouched.
+      const own = client.queryClient.getDefaultOptions()
+      expect(own.dehydrate?.serializeData).toBeTypeOf("function")
+      expect(own.hydrate?.deserializeData).toBeTypeOf("function")
+    } finally {
+      client.dispose()
+    }
+  })
+
+  it("makes a new client per call", () => {
+    const a = createAppClient()
+    const b = createAppClient()
+    try {
+      expect(a).not.toBe(b)
+      expect(a.queryClient).not.toBe(b.queryClient)
+    } finally {
+      a.dispose()
+      b.dispose()
+    }
+  })
+})

package/examples/canister-studio/src/lib/reactor.ts

@@ -0,0 +1,55 @@
+import { createClient, type Client } from "@ic-reactor/core"
+import { AuthClient } from "@icp-sdk/auth/client"
+
+/**
+ * A canister whose interface is known only at run time (a live canister's
+ * `candid:service`, a pasted .did): any method name, one `vars` value in, the
+ * decoded reply out. `client.queryOptions(c, method, vars)` and
+ * `client.mutationOptions(c, method)` accept a `Canister<DynActor>` with a
+ * plain `string` method.
+ */
+export type DynActor = Record<string, (arg: unknown) => Promise<unknown>>
+
+/**
+ * How long a read stays fresh. Reads the server rendered are not read again
+ * while the page hydrates, and revisits within a minute cost no request.
+ */
+const READ_STALE_TIME = 60_000
+
+/**
+ * The app's one ic-reactor client. `getRouter()` calls this once per request
+ * on the server and once per tab in the browser, which is exactly the
+ * lifetime a client needs: never call it anywhere else (never per render).
+ *
+ * - `network: "ic"`: mainnet, and the key segment `"ic"` on both sides, so
+ *   the keys the server dehydrates are the keys the browser asks for.
+ * - `auth`: Internet Identity. ic-reactor builds it only in a browser, on
+ *   first use; on a server the client is anonymous (2vxsx-fae) and refuses
+ *   every write before sending it.
+ * - The stale time goes through `setQueryDefaults(["ic-reactor"], …)`, never
+ *   `setDefaultOptions`, which would replace the client's own defaults (its
+ *   read retry policy and the serializers that carry bigint and bytes through
+ *   dehydration).
+ */
+export function createAppClient(): Client {
+  const client = createClient({
+    network: "ic",
+    auth: (network) => new AuthClient(network),
+  })
+  client.queryClient.setQueryDefaults(["ic-reactor"], {
+    staleTime: READ_STALE_TIME,
+  })
+  return client
+}
+
+/**
+ * Argument values as the one `vars` value ic-reactor's builders take
+ * (`queryOptions`, `queryKey`, `mutate`): nothing for no arguments, the value
+ * itself for one, the tuple for two or more. Never `[value]` for one
+ * argument: that encodes as a different (wrong) message.
+ */
+export function toVars(values: readonly unknown[]): unknown {
+  if (values.length === 0) return undefined
+  if (values.length === 1) return values[0]
+  return [...values]
+}

package/examples/canister-studio/src/lib/registry.test.ts

@@ -0,0 +1,74 @@
+import { serviceMethods } from "@meantjs/schema"
+import { describe, expect, it } from "vitest"
+import { checkCanisterId } from "./ids.ts"
+import { CURATED, REGISTRY, registryEntry } from "./registry.ts"
+
+describe("REGISTRY", () => {
+  it("holds the four typed canisters at their mainnet ids", () => {
+    expect(REGISTRY.map((e) => [e.id, e.module])).toEqual([
+      ["ryjl3-tyaaa-aaaaa-aaaba-cai", "icp_ledger"],
+      ["mxzaz-hqaaa-aaaar-qaada-cai", "icrc1"],
+      ["ss2fx-dyaaa-aaaar-qacoq-cai", "icrc1"],
+      ["mqygn-kiaaa-aaaar-qaadq-cai", "ckbtc_minter"],
+    ])
+  })
+
+  it("has valid canister ids and unique ids and slugs", () => {
+    for (const entry of REGISTRY)
+      expect(checkCanisterId(entry.id).ok).toBe(true)
+    expect(new Set(REGISTRY.map((e) => e.id)).size).toBe(REGISTRY.length)
+    expect(new Set(REGISTRY.map((e) => e.slug)).size).toBe(REGISTRY.length)
+  })
+
+  it("types every entry with its module's actor and .did text", () => {
+    for (const entry of REGISTRY) {
+      const methods = serviceMethods(entry.actor)
+      expect(methods.size).toBeGreaterThan(0)
+      expect(entry.did).toMatch(/service\s*:/)
+      if (entry.kind !== "ckbtc-minter") {
+        expect(methods.get("icrc1_transfer")?.mode).toBe("update")
+        expect(methods.get("icrc1_balance_of")?.mode).toBe("query")
+        expect(entry.decimals).toBeTypeOf("number")
+        expect(entry.symbol).toBeTypeOf("string")
+      }
+    }
+    const minter = registryEntry("mqygn-kiaaa-aaaar-qaadq-cai")
+    const methods = serviceMethods(minter!.actor)
+    expect(methods.get("get_minter_info")?.mode).toBe("query")
+    expect(methods.get("estimate_withdrawal_fee")?.mode).toBe("query")
+  })
+
+  it("names only update methods as idempotent updates", () => {
+    for (const entry of REGISTRY) {
+      const methods = serviceMethods(entry.actor)
+      for (const name of entry.idempotentUpdates ?? []) {
+        expect(methods.get(name)?.mode).toBe("update")
+      }
+    }
+    expect(
+      registryEntry("mqygn-kiaaa-aaaar-qaadq-cai")?.idempotentUpdates
+    ).toEqual(["get_btc_address"])
+  })
+
+  it("finds entries by id only", () => {
+    expect(registryEntry("ryjl3-tyaaa-aaaaa-aaaba-cai")?.slug).toBe(
+      "icp-ledger"
+    )
+    expect(registryEntry("icp-ledger")).toBeUndefined()
+    expect(registryEntry("__proto__")).toBeUndefined()
+  })
+})
+
+describe("CURATED", () => {
+  it("lists valid, unique canister ids outside the registry", () => {
+    const ids = CURATED.map((c) => c.id)
+    expect(new Set(ids).size).toBe(ids.length)
+    for (const entry of CURATED) {
+      expect(checkCanisterId(entry.id).ok).toBe(true)
+      expect(registryEntry(entry.id)).toBeUndefined()
+      expect(entry.name.length).toBeGreaterThan(0)
+      expect(entry.note.length).toBeGreaterThan(0)
+    }
+    expect(ids).toContain("um5iw-rqaaa-aaaaq-qaaba-cai")
+  })
+})

package/examples/canister-studio/src/lib/registry.ts

@@ -0,0 +1,238 @@
+import type { AnySchema } from "@meantjs/schema"
+import ckbtcMinterDid from "../../did/ckbtc_minter.did?raw"
+import icpLedgerDid from "../../did/icp_ledger.did?raw"
+import icrc1Did from "../../did/icrc1.did?raw"
+import { actor as ckbtcMinterActor } from "../canisters/ckbtc_minter.ts"
+import { actor as icpLedgerActor } from "../canisters/icp_ledger.ts"
+import { actor as icrc1Actor } from "../canisters/icrc1.ts"
+
+/**
+ * A canister the app knows at build time: its interface is a committed .did,
+ * generated into a typed module under src/canisters/, so it needs no live
+ * metadata read and its methods have generated TypeScript types.
+ */
+export interface RegistryEntry {
+  /** Canister id (principal text). */
+  id: string
+  /** URL-friendly name, unique in the registry. */
+  slug: string
+  name: string
+  /** The token's symbol, for a ledger (a hint; the ledger's own reply wins). */
+  symbol?: string
+  /** The token's decimals, for a ledger (a hint; the ledger's own reply wins). */
+  decimals?: number
+  description: string
+  kind: "icrc1-ledger" | "icp-ledger" | "ckbtc-minter"
+  /** Which generated module types it: `src/canisters/<module>.ts`. */
+  module: "icrc1" | "icp_ledger" | "ckbtc_minter"
+  /** That module's `actor`: what `client.canister()` takes. */
+  actor: AnySchema
+  /** The committed .did text the module was generated from. */
+  did: string
+  /**
+   * Update methods that change nothing and answer the same for the same
+   * caller and arguments, so the app may offer them as reads through
+   * `client.queryOptions(c, m, vars, { update: "idempotent" })`.
+   */
+  idempotentUpdates?: readonly string[]
+  /**
+   * Update methods this canister is known to run at most once per sender
+   * and argument within its window when the argument carries
+   * `created_at_time`, answering `Duplicate` (`TxDuplicate` for the ICP
+   * ledger's own `transfer`) to the same bytes again. Only these get the
+   * unconditional "re-send safely" wording: a field named `created_at_time`
+   * proves nothing on its own.
+   */
+  dedupedMethods?: readonly string[]
+  /** Shown on the home page with live stats. */
+  featured?: boolean
+}
+
+export const REGISTRY: readonly RegistryEntry[] = [
+  {
+    id: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+    slug: "icp-ledger",
+    name: "ICP ledger",
+    symbol: "ICP",
+    decimals: 8,
+    description:
+      "The ICP token's ledger: ICRC-1 and ICRC-2, plus its original account-identifier API.",
+    kind: "icp-ledger",
+    module: "icp_ledger",
+    actor: icpLedgerActor,
+    did: icpLedgerDid,
+    dedupedMethods: [
+      "transfer",
+      "icrc1_transfer",
+      "icrc2_approve",
+      "icrc2_transfer_from",
+    ],
+    featured: true,
+  },
+  {
+    id: "mxzaz-hqaaa-aaaar-qaada-cai",
+    slug: "ckbtc-ledger",
+    name: "ckBTC ledger",
+    symbol: "ckBTC",
+    decimals: 8,
+    description:
+      "The ICRC-1 ledger of ckBTC, bitcoin on the Internet Computer.",
+    kind: "icrc1-ledger",
+    module: "icrc1",
+    actor: icrc1Actor,
+    did: icrc1Did,
+    dedupedMethods: ["icrc1_transfer"],
+    featured: true,
+  },
+  {
+    id: "ss2fx-dyaaa-aaaar-qacoq-cai",
+    slug: "cketh-ledger",
+    name: "ckETH ledger",
+    symbol: "ckETH",
+    decimals: 18,
+    description: "The ICRC-1 ledger of ckETH, ether on the Internet Computer.",
+    kind: "icrc1-ledger",
+    module: "icrc1",
+    actor: icrc1Actor,
+    did: icrc1Did,
+    dedupedMethods: ["icrc1_transfer"],
+    featured: true,
+  },
+  {
+    id: "mqygn-kiaaa-aaaar-qaadq-cai",
+    slug: "ckbtc-minter",
+    name: "ckBTC minter",
+    description:
+      "Mints ckBTC for bitcoin deposits and sends bitcoin back for ckBTC.",
+    kind: "ckbtc-minter",
+    module: "ckbtc_minter",
+    actor: ckbtcMinterActor,
+    did: ckbtcMinterDid,
+    // The deposit address is derived from the owner and subaccount: asking
+    // twice gives the same address and changes nothing.
+    idempotentUpdates: ["get_btc_address"],
+    featured: true,
+  },
+]
+
+const BY_ID: ReadonlyMap<string, RegistryEntry> = new Map(
+  REGISTRY.map((entry) => [entry.id, entry])
+)
+
+/** The registry entry of a canister id, or `undefined` for any other canister. */
+export function registryEntry(id: string): RegistryEntry | undefined {
+  return BY_ID.get(id)
+}
+
+/**
+ * Mainnet canisters worth opening, each read live: their interfaces were
+ * read from mainnet and compiled without a diagnostic on 2026-10-12. All but
+ * the last publish certified `candid:service` metadata.
+ */
+export const CURATED: readonly { id: string; name: string; note: string }[] = [
+  {
+    id: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+    name: "NNS governance",
+    note: "Neurons and proposals: 33 methods over a 50 KB interface.",
+  },
+  {
+    id: "rdmx6-jaaaa-aaaaa-aaadq-cai",
+    name: "Internet Identity",
+    note: "The largest public interface here: 113 methods, 100 KB of Candid.",
+  },
+  {
+    id: "um5iw-rqaaa-aaaaq-qaaba-cai",
+    name: "Cycles ledger",
+    note: "An ICRC-1 and ICRC-2 ledger of cycles that also creates canisters.",
+  },
+  {
+    id: "rkp4c-7iaaa-aaaaa-aaaca-cai",
+    name: "Cycles minting canister",
+    note: "Turns ICP into cycles; reads the ICP/XDR conversion rate.",
+  },
+  {
+    id: "qhbym-qaaaa-aaaaa-aaafq-cai",
+    name: "ICP index",
+    note: "The ICP ledger's transactions by account: queries only.",
+  },
+  {
+    id: "qjdve-lqaaa-aaaaa-aaaeq-cai",
+    name: "ICP ledger archive",
+    note: "Old ICP ledger blocks behind two queries.",
+  },
+  {
+    id: "rwlgt-iiaaa-aaaaa-aaaaa-cai",
+    name: "NNS registry",
+    note: "Subnets, nodes and their records: 57 methods, mostly updates.",
+  },
+  {
+    id: "r7inp-6aaaa-aaaaa-aaabq-cai",
+    name: "NNS root",
+    note: "The controller of the NNS canisters.",
+  },
+  {
+    id: "qaa6y-5yaaa-aaaaa-aaafa-cai",
+    name: "SNS wasm",
+    note: "Deploys SNS DAOs and lists the deployed ones.",
+  },
+  {
+    id: "3r4gx-wqaaa-aaaaq-aaaia-cai",
+    name: "SNS aggregator",
+    note: "A small, query-heavy cache of SNS data.",
+  },
+  {
+    id: "sv3dd-oaaaa-aaaar-qacoa-cai",
+    name: "ckETH minter",
+    note: "Mints ckETH for ether deposits and withdraws ether for ckETH.",
+  },
+  {
+    id: "7hfb6-caaaa-aaaar-qadga-cai",
+    name: "EVM RPC",
+    note: "Ethereum JSON-RPC for canisters.",
+  },
+  {
+    id: "ghsi2-tqaaa-aaaan-aaaca-cai",
+    name: "Bitcoin canister",
+    note: "Bitcoin UTXOs, balances and fee percentiles.",
+  },
+  {
+    id: "uf6dk-hyaaa-aaaaq-qaaaq-cai",
+    name: "Exchange rate canister",
+    note: "A single method: an update that charges cycles for a rate.",
+  },
+  {
+    id: "2jvtu-yqaaa-aaaaq-aaama-cai",
+    name: "OpenChat SNS governance",
+    note: "Has a composite query, which has no certified path.",
+  },
+  {
+    id: "mwrha-maaaa-aaaab-qabqq-cai",
+    name: "Motoko playground",
+    note: "Has a oneway method: sent, with no reply and no outcome.",
+  },
+  {
+    id: "lj532-6iaaa-aaaah-qcc7a-cai",
+    name: "CAP router",
+    note: "No metadata: its interface comes from an uncertified query, and is labelled so.",
+  },
+]
+
+/**
+ * Every canister the studio knows by name, registry first, then the curated
+ * list without the registry's: suggestions for canister id inputs.
+ */
+export const KNOWN_CANISTERS: readonly { id: string; name: string }[] = [
+  ...REGISTRY.map(({ id, name }) => ({ id, name })),
+  ...CURATED.filter(({ id }) => registryEntry(id) === undefined).map(
+    ({ id, name }) => ({ id, name })
+  ),
+]
+
+const KNOWN_NAMES: ReadonlyMap<string, string> = new Map(
+  KNOWN_CANISTERS.map(({ id, name }) => [id, name])
+)
+
+/** The name of a canister the studio knows, or `undefined`. */
+export function knownCanisterName(id: string): string | undefined {
+  return KNOWN_NAMES.get(id)
+}

package/examples/canister-studio/src/lib/schema.ts

@@ -0,0 +1,148 @@
+// Schema reading helpers shared by the forms and the value viewers, over
+// @meantjs/schema's public API only.
+import {
+  resolveSchema,
+  type AnyFieldSchema,
+  type ResolvedNode,
+} from "@meantjs/schema"
+
+export type RecordNode = Extract<ResolvedNode, { kind: "record" }>
+export type TupleNode = Extract<ResolvedNode, { kind: "tuple" }>
+export type VariantNode = Extract<ResolvedNode, { kind: "variant" }>
+
+// Generated modules build a fresh node on every `rec` body() call: memoizing
+// gives one node per declaration and a stable identity, which the forms'
+// cycle cut of defaults needs. Loaded schemas are already one node per type.
+const resolved = new WeakMap<object, ResolvedNode>()
+
+/** The schema with every `rec` followed: what `.kind` can be read on. */
+export function resolve(schema: AnyFieldSchema): ResolvedNode {
+  let node = resolved.get(schema)
+  if (node === undefined) {
+    node = resolveSchema(schema)
+    resolved.set(schema, node)
+  }
+  return node
+}
+
+// The erased node types carry `any` children (RecordSchema<any>.fields is
+// `any`): these accessors name their real shape once.
+
+/** A record's fields in schema order (Candid label-id order). */
+export function fieldsOf(
+  node: RecordNode
+): readonly (readonly [string, AnyFieldSchema])[] {
+  return Object.entries(node.fields as Record<string, AnyFieldSchema>)
+}
+
+/** A tuple's element schemas. */
+export function elementsOf(node: TupleNode): readonly AnyFieldSchema[] {
+  return node.elements as readonly AnyFieldSchema[]
+}
+
+/** A variant's arms in schema order. */
+export function armsOf(
+  node: VariantNode
+): readonly (readonly [string, AnyFieldSchema])[] {
+  return Object.entries(node.arms as Record<string, AnyFieldSchema>)
+}
+
+/** The arm schema of `tag`, read as an own property ("toString" is a valid tag). */
+export function armOf(
+  node: VariantNode,
+  tag: string
+): AnyFieldSchema | undefined {
+  return getOwn(node.arms as Record<string, AnyFieldSchema>, tag)
+}
+
+/** Whether a variant arm carries no payload (its type is `null`). */
+export function isTagOnly(arm: AnyFieldSchema): boolean {
+  const node = resolve(arm)
+  return node.kind === "primitive" && node.primitive === "null"
+}
+
+/**
+ * Fields for people: required (non-opt) fields first, then the optional
+ * ones, each group in schema order. Candid orders fields by label id, which
+ * reads as random.
+ */
+export function orderFields<F extends readonly [string, AnyFieldSchema]>(
+  fields: readonly F[]
+): F[] {
+  const required = fields.filter(([, s]) => resolve(s).kind !== "opt")
+  const optional = fields.filter(([, s]) => resolve(s).kind === "opt")
+  return [...required, ...optional]
+}
+
+/**
+ * `obj[key] = v` with key "__proto__" sets the prototype instead of an own
+ * property, and validate() then reports missing_field. Candid allows any
+ * label, so every keyed write of a value or a draft goes through this.
+ */
+export function setOwn<T>(obj: Record<string, T>, key: string, value: T): void {
+  Object.defineProperty(obj, key, {
+    value,
+    enumerable: true,
+    writable: true,
+    configurable: true,
+  })
+}
+
+/** Own-property read: `fields["toString"]` must not find Object.prototype's. */
+export function getOwn<T>(
+  obj: Readonly<Record<string, T>>,
+  key: string
+): T | undefined {
+  return Object.hasOwn(obj, key) ? obj[key] : undefined
+}
+
+/** A copy of `obj` with `key` set, safe for any key. */
+export function withOwn<T>(
+  obj: Readonly<Record<string, T>>,
+  key: string,
+  value: T
+): Record<string, T> {
+  const out: Record<string, T> = {}
+  for (const k of Object.keys(obj)) setOwn(out, k, obj[k] as T)
+  setOwn(out, key, value)
+  return out
+}
+
+/**
+ * Whether a value is a `Uint8Array`, from this realm or another (a jsdom
+ * test's TextEncoder, an iframe): how `@meantjs/schema`'s codec recognizes a
+ * blob.
+ */
+export function isBytes(value: unknown): value is Uint8Array {
+  return (
+    ArrayBuffer.isView(value) &&
+    Object.prototype.toString.call(value) === "[object Uint8Array]"
+  )
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** A child's path in the codec's grammar: `$.to.owner`, `$["a b"]`, `$[3]`. */
+export function childPath(path: string, seg: string | number): string {
+  if (typeof seg === "number") return `${path}[${seg}]`
+  return IDENT.test(seg) ? `${path}.${seg}` : `${path}[${JSON.stringify(seg)}]`
+}
+
+/**
+ * The numeric id of a key `_N_`, the schema's spelling of an unnamed Candid
+ * label (a copy of `@meantjs/schema`'s internal `numericKeyId`).
+ */
+export function numericLabelId(key: string): number | undefined {
+  const match = /^_([0-9]+)_$/.exec(key)
+  const digits = match?.[1]
+  if (digits === undefined) return undefined
+  if (digits.length > 1 && digits.startsWith("0")) return undefined
+  const id = Number(digits)
+  return Number.isSafeInteger(id) && id < 4_294_967_296 ? id : undefined
+}
+
+/** A field or arm label for people: the name, or `#N` for an unnamed label. */
+export function displayLabel(key: string): string {
+  const id = numericLabelId(key)
+  return id === undefined ? key : `#${id}`
+}