lecodes-cli 1.0.0 → 2.0.0

package/src/plugin/emitKotlin.ts

@@ -0,0 +1,357 @@
+// The generator's emitter for `android/`: a contract's channel → `<Name>.gen.kt`, everything of the
+// Android half that is not the plugin's own work (docs/plans/plugins-plan.md in core) — the twin of
+// emitSwift.ts, over the same lowered model:
+//   - the contract's types as Kotlin (enum classes, data classes, sealed unions) with their wire codecs;
+//   - `<Name>Code`: the codes the channel rejects with;
+//   - `<Name>Events`: one function per event;
+//   - `<Name>Plugin`: the INTERFACE the plugin implements — one method per call, a typed `Reply`;
+//   - `<Name>Channel.register(engine, make)` + the glue that reads a call's arguments, refuses a
+//     malformed one and hands the call over.
+// It stands on the host SDK's PluginChannel.kt (Reply, PluginFile, Wire) and on the packed form's
+// two ends (PackedReader, PackedWriter). The wire carries VALUES, PACKED, and the codecs read a
+// class straight out of the buffer and write one straight into it — no tree of org.json's objects
+// in between. A Uint8Array is a ByteArray, a File the handle of a host buffer; a `Json` member alone
+// is org.json's objects, because JSON is what a half does with it.
+//
+// A READER IS A CURSOR (`r`): a codec takes the value at the cursor and moves past it, so what it
+// reads is what comes next, in the order it was written — an object's members are met one by one
+// and told apart by their keys, a union by what the value at hand is.
+
+import { EmitError } from "./emitSdk"
+import { block, indent, text, wrap, writerName } from "./lines"
+import { waysOf, wireClass, type L, type LChannel, type LDecl, type LField, type Lowered, type Ways } from "./lower"
+
+const KEYWORDS = new Set([
+  "as", "break", "class", "continue", "do", "else", "false", "for", "fun", "if", "in", "interface", "is", "null",
+  "object", "package", "return", "super", "this", "throw", "true", "try", "typealias", "typeof", "val", "var", "when",
+  "while",
+])
+
+const ident = (name: string): string => KEYWORDS.has(name) ? `\`${name}\`` : name
+
+/** A string of the contract as a Kotlin string: `$` would open a template. */
+const str = (value: string): string => JSON.stringify(value).replace(/\$/g, "\\$")
+
+/** A string of the contract as a Kotlin constant: `"not-asked"`, `"notAsked"` → `NOT_ASKED`. */
+const constName = (value: string): string => {
+  const words = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter(Boolean)
+  const name = words.map(w => w.toUpperCase()).join("_")
+  return /^[A-Z_]/.test(name) ? name : `_${name}`
+}
+
+const doc = (text: string, indent = ""): string => {
+  if (!text) return ""
+  const lines = text.split("\n").map(l => l.trim())
+  if (lines.length === 1) return `${indent}/** ${lines[0]} */\n`
+  return `${indent}/**\n${lines.map(l => `${indent} * ${l}`.trimEnd()).join("\n")}\n${indent} */\n`
+}
+
+export const kotlinType = (t: L): string => {
+  switch (t.kind) {
+    case "i32": return "Int"
+    case "f64": return "Double"
+    case "boolean": return "Boolean"
+    case "string": return "String"
+    case "json": return "Any"
+    case "file": return "PluginFile"
+    case "bytes": return "ByteArray"
+    case "void": return "Unit"
+    case "enum": case "struct": case "union": return t.name
+    case "list": return `List<${kotlinType(t.of)}>`
+    case "map": return `Map<String, ${kotlinType(t.of)}>`
+    case "optional": return `${kotlinType(t.of)}?`
+    case "tuple": return `${t.of.length === 2 ? "Pair" : "Triple"}<${t.of.map(kotlinType).join(", ")}>`
+  }
+}
+
+const TUPLE = ["first", "second", "third"]
+
+/** The expression of type `T?` that reads the value at the cursor of `r`, as lines: null = it is
+ *  not a T. */
+const decode = (t: L, depth = 0): string[] => {
+  const v = `v${depth}`
+  switch (t.kind) {
+    case "i32": return [`r.i32()`]
+    case "f64": return [`r.f64()`]
+    case "boolean": return [`r.bool()`]
+    case "string": return [`r.string()`]
+    case "json": return [`r.json()`]
+    case "bytes": return [`r.bytes()`]
+    case "file": return [`Wire.file(r)`]
+    case "enum": case "struct": case "union": return [`${t.name}.read(r)`]
+    case "list": return block(`r.list {`, decode(t.of, depth + 1), `}`)
+    case "map": return block(`r.map {`, decode(t.of, depth + 1), `}`)
+    case "optional": return decode(t.of, depth)
+    case "tuple": return [
+      `r.tuple(${t.of.length}) {`,
+      ...indent([
+        ...t.of.flatMap((m, i) => wrap(`val ${v}_${i} = `, decode(m, depth + 1), ` ?: return@tuple null`)),
+        `${t.of.length === 2 ? "Pair" : "Triple"}(${t.of.map((_, i) => `${v}_${i}`).join(", ")})`,
+      ]),
+      `}`,
+    ]
+    case "void": throw new EmitError("void has no value to read")
+  }
+}
+
+/** The statements that write the value `e` (a `T`) to the wire `w` (a PackedWriter), as lines. */
+const encode = (t: L, e: string, w: string, depth = 0): string[] => {
+  const v = `v${depth}`
+  switch (t.kind) {
+    case "i32": return [`${w}.i32(${e})`]
+    case "f64": return [`${w}.f64(${e})`]
+    case "boolean": return [`${w}.bool(${e})`]
+    case "string": return [`${w}.string(${e})`]
+    case "json": return [`${w}.json(${e})`]
+    case "bytes": return [`${w}.bytes(${e})`]
+    case "enum": return [`${w}.string(${e}.wire)`]
+    case "file": case "struct": case "union": return [`${e}.write(${w})`]
+    case "list": return [`${w}.beginArray()`, ...block(`for (${v} in ${e}) {`, encode(t.of, v, w, depth + 1), `}`), `${w}.end()`]
+    case "map": return [`${w}.beginObject()`, `for ((k${depth}, ${v}) in ${e}) {`, ...indent([`${w}.key(k${depth})`, ...encode(t.of, v, w, depth + 1)]), `}`, `${w}.end()`]
+    case "tuple": return [`${w}.beginArray()`, ...t.of.flatMap((m, i) => encode(m, `${e}.${TUPLE[i]}`, w, depth + 1)), `${w}.end()`]
+    case "optional": {
+      const some = encode(t.of, v, w, depth + 1)
+      const one = `${e}.let { ${v} -> if (${v} != null) ${some[0]} else ${w}.nil() }`
+      return some.length === 1 && one.length <= 100
+        ? [one]
+        : [`${e}.let { ${v} ->`, ...indent([`if (${v} != null) {`, ...indent(some), `} else {`, ...indent([`${w}.nil()`]), `}`]), `}`]
+    }
+    case "void": throw new EmitError("void has no value to write")
+  }
+}
+
+/** A value under its key: on the key's line when it is one plain statement. */
+const keyed = (key: string, value: string[]): string[] =>
+  value.length === 1 && !/^for /.test(value[0]!) && !value[0]!.includes(".let {") ? [`${key}; ${value[0]}`] : [key, ...value]
+
+/** The statements that write a class's members — an object — to the wire `w`, as lines. */
+const encodeFields = (fields: LField[], of: (f: LField) => string, w: string): string[] => [
+  `${w}.beginObject()`,
+  ...fields.flatMap(f => {
+    const key = `${w}.key(${str(f.name)})`
+    if (f.type.kind !== "optional") return keyed(key, encode(f.type, of(f), w))
+    // An optional member that is null is left out; a nullable one is written as a null.
+    if (f.omit) return block(`${of(f)}?.let { v ->`, keyed(key, encode(f.type.of, "v", w, 1)), `}`)
+    return keyed(key, encode(f.type, of(f), w))
+  }),
+  `${w}.end()`,
+]
+
+/** What PackedReader.kind() answers for a member of a union. */
+const readerKind = (t: L): string => {
+  switch (wireClass(t)) {
+    case "number": return "PackedReader.NUMBER"
+    case "string": return "PackedReader.TEXT"
+    case "boolean": return "PackedReader.BOOLEAN"
+    case "object": return "PackedReader.MAP"
+    case "array": return "PackedReader.LIST"
+    default: throw new EmitError(`a union cannot hold ${t.kind}`)
+  }
+}
+
+const unionCase = (m: L): string => {
+  switch (m.kind) {
+    case "f64": return "OfNumber"
+    case "i32": return "OfInteger"
+    case "boolean": return "OfBool"
+    case "string": return "OfString"
+    case "enum": case "struct": return `Of${m.name}`
+    default: return `Of${m.kind.charAt(0).toUpperCase()}${m.kind.slice(1)}`
+  }
+}
+
+const members = (fields: LField[], indent: string): string =>
+  fields.map(f => `${doc(f.doc, indent)}${indent}val ${ident(f.name)}: ${kotlinType(f.type)}${f.type.kind === "optional" ? " = null" : ""},`).join("\n")
+
+const emitDecl = (d: LDecl, ways: Ways): string => {
+  const read = ways.read.has(d.name)
+  const write = ways.write.has(d.name)
+  if (d.kind === "enum") {
+    const cases = d.values.map(v => `    ${constName(v)}(${str(v)})`)
+    return [
+      doc(d.doc),
+      `enum class ${d.name}(val wire: String) {\n${cases.join(",\n")};\n`,
+      read ? `\n    companion object {\n        internal fun read(r: PackedReader): ${d.name}? = r.string()?.let { s -> values().firstOrNull { it.wire == s } }\n    }\n` : "",
+      `}\n`,
+    ].join("")
+  }
+
+  if (d.kind === "union") {
+    const cases = d.members.map(m => `    data class ${unionCase(m)}(val value: ${kotlinType(m)}) : ${d.name}()`)
+    const reads = !read ? [] : d.members.flatMap(m => wrap(`${readerKind(m)} -> `, decode(m, 1), `?.let { ${unionCase(m)}(it) }`))
+    const writes = !write ? [] : d.members.flatMap(m => {
+      const lines = encode(m, "value", "w", 1)
+      return lines.length === 1 ? [`is ${unionCase(m)} -> ${lines[0]}`] : [`is ${unionCase(m)} -> {`, ...indent(lines), `}`]
+    })
+    return [
+      doc(d.doc),
+      `sealed class ${d.name} {\n${cases.join("\n")}\n`,
+      write ? `\n    internal fun write(w: PackedWriter) {\n        when (this) {\n${text(writes, "            ")}\n        }\n    }\n` : "",
+      read ? `\n    companion object {\n        internal fun read(r: PackedReader): ${d.name}? = when (r.kind()) {\n${text(reads, "            ")}\n            else -> null\n        }\n    }\n` : "",
+      `}\n`,
+    ].join("")
+  }
+
+  // The members are read into numbered locals and written from `this.`: a member's own name is
+  // never an identifier here, so none can shadow the wire.
+  const locals = !read ? [] : d.fields.map((f, i) => `            var m${i}: ${kotlinType(f.type.kind === "optional" ? f.type : { kind: "optional", of: f.type })} = null`)
+  const reads = !read ? [] : d.fields.flatMap((f, i) => {
+    const key = str(f.name)
+    if (f.type.kind !== "optional") return wrap(`${key} -> m${i} = `, decode(f.type), ` ?: return null`)
+    // An optional member that IS there must read: a wrong type is a malformed value, not an absent one.
+    return wrap(`${key} -> if (r.isNull()) r.skip() else m${i} = `, decode(f.type), ` ?: return null`)
+  })
+  const made = d.fields.map((f, i) => `${ident(f.name)} = m${i}${f.type.kind === "optional" ? "" : " ?: return null"}`)
+  const body = [
+    !write ? "" : `    internal fun write(w: PackedWriter) {\n${text(encodeFields(d.fields, f => `this.${ident(f.name)}`, "w"), "        ")}\n    }\n`,
+    !read ? "" : d.fields.length
+      ? `    companion object {\n        internal fun read(r: PackedReader): ${d.name}? {\n            val n = r.beginObject()\n            if (n < 0) return null\n${locals.join("\n")}\n            repeat(n) {\n                when (r.key()) {\n${text(reads, "                    ")}\n                    else -> r.skip()\n                }\n            }\n            return ${d.name}(${made.join(", ")})\n        }\n    }\n`
+      : `    companion object {\n        internal fun read(r: PackedReader): ${d.name}? {\n            if (r.isNull()) return ${d.name}()\n            if (r.beginObject() < 0) return null\n            return ${d.name}()\n        }\n    }\n`,
+  ].filter(Boolean).join("\n")
+  // A data class has a member or more: the empty struct is a plain class.
+  const head = d.fields.length ? `data class ${d.name}(\n${members(d.fields, "    ")}\n)` : `class ${d.name}`
+  return `${doc(d.doc)}${head}${body ? ` {\n${body}}` : ""}\n`
+}
+
+const emitChannel = (ch: LChannel): string => {
+  const isView = ch.kind === "view"
+  const iface = ch.iface
+  const code = ch.codes.length ? `${iface}Code` : "NoCode"
+  const out: string[] = []
+
+  if (ch.codes.length) {
+    out.push(`/** The codes the calls of "${ch.name}" reject with. */\nenum class ${iface}Code(override val code: String) : PluginCode {\n${ch.codes.map(c => `    ${constName(c)}(${str(c)})`).join(",\n")},\n}\n`)
+  }
+
+  // ---- events ----
+  const events = ch.events.map(e => {
+    const name = ident(e.name)
+    if (e.inline) {
+      const args = e.inline.map(f => `${ident(f.name)}: ${kotlinType(f.type)}${f.type.kind === "optional" ? " = null" : ""}`)
+      const w = writerName(e.inline.map(f => f.name))
+      return `${doc(e.doc, "    ")}    fun ${name}(${args.join(", ")}) {\n        val ${w} = PackedWriter()\n${text(encodeFields(e.inline, f => ident(f.name), w), "        ")}\n        this.channel.emit(${str(e.name)}, ${w}.bytes())\n    }`
+    }
+    if (e.payload.kind === "void") return `${doc(e.doc, "    ")}    fun ${name}() = channel.emit(${str(e.name)}, null)`
+    return `${doc(e.doc, "    ")}    fun ${name}(payload: ${kotlinType(e.payload)}) {\n        val w = PackedWriter()\n${text(encode(e.payload, "payload", "w"), "        ")}\n        channel.emit(${str(e.name)}, w.bytes())\n    }`
+  })
+  out.push([
+    `/** The events of "${ch.name}": what the plugin sends the app.${isView ? " From the main thread." : " Any thread."} */\n`,
+    `class ${iface}Events(private val channel: PluginEmit)${events.length ? ` {\n${events.join("\n\n")}\n}` : ""}\n`,
+  ].join(""))
+
+  // ---- the interface ----
+  const signatures = ch.methods.map(m => {
+    const args = [...m.args.map(a => `${ident(a.name)}: ${kotlinType(a.type)}`), `reply: Reply<${kotlinType(m.result)}, ${code}>`]
+    const tags = [m.doc, m.rejects.length ? `Rejects with ${m.rejects.map(constName).join(" / ")}.` : ""].filter(Boolean).join("\n")
+    return `${doc(tags, "    ")}    fun ${ident(m.name)}(${args.join(", ")})`
+  })
+  out.push([
+    `/**\n * ${(ch.doc || `The ${ch.kind} "${ch.name}".`).split("\n").map(l => l.trim()).join("\n * ")}\n *\n`,
+    ` * What the plugin implements. A call arrives on the main thread; its reply is settled exactly\n * once, now or later.\n */\n`,
+    `interface ${iface}Plugin {\n`,
+    isView ? `    /** The view the host mounts: fullscreen, or embedded among a screen's children. */\n    val view: android.view.View\n` : "",
+    signatures.length ? (isView ? "\n" : "") + signatures.join("\n\n") + "\n" : "",
+    isView
+      ? `\n    /** The instance goes (the world swapped): release the hardware. */\n    fun destroy() {}\n`
+      : `\n    /** The session closed (the app's close, the world's teardown): stop what it started. */\n    fun close() {}\n`,
+    `}\n`,
+  ].join(""))
+
+  // ---- registration ----
+  out.push([
+    `object ${iface}Channel {\n`,
+    `    /** What the halves register under. */\n    const val NAME = ${str(ch.name)}\n\n`,
+    `    /** The contract's version: the highest \`@since\` of its members. */\n    const val VERSION = ${ch.version}\n\n`,
+    isView
+      ? `    /** Register the view: \`make\` builds one instance from its params. */\n`
+      : `    /** Register the service: \`make\` builds one session from its params. It must be cheap — no\n     *  prompt, no I/O: that belongs to the first call that needs it. */\n`,
+    `    fun register(engine: LecodesEngine, make: (params: ${ch.params}, events: ${iface}Events) -> ${iface}Plugin) {\n`,
+    `        engine.register${isView ? "View" : "Service"}(NAME, VERSION) { params, channel ->\n`,
+    `            val plugin = make(${ch.params}.read(Wire.reader(params)) ?: ${ch.params}(), ${iface}Events { event, packed -> channel.emitPacked(event, packed) })\n`,
+    isView
+      ? `            NativeViews.Instance(plugin.view, onCall = { call -> ${iface}Glue.call(plugin, call.method, call.reader(), call) }, onDestroy = { plugin.destroy() })\n`
+      : `            Services.Instance(onCall = { call -> ${iface}Glue.call(plugin, call.method, call.reader(), call) }, onClose = { plugin.close() })\n`,
+    `        }\n    }\n}\n`,
+  ].join(""))
+
+  // ---- the glue ----
+  // The arguments are read into numbered locals, one after the other as they were written: an
+  // argument's own name is never an identifier here.
+  const cases = ch.methods.map(m => {
+    const lines: string[] = []
+    m.args.forEach((a, i) => {
+      const bad = `return settle.reject("bad arguments — ${iface}.${m.name}: ${a.name}")`
+      if (a.type.kind !== "optional") {
+        lines.push(...wrap(`val a${i} = (if (${i} < n) `, decode(a.type), ` else null) ?: ${bad}`))
+      } else {
+        // An argument the app left out, or a null: nothing is read, a null that is there is passed over.
+        lines.push(...wrap(`val a${i} = if (${i} < n && !r.isNull()) (`, decode(a.type), ` ?: ${bad}) else { if (${i} < n) r.skip(); null }`))
+      }
+    })
+    const head = `Reply<${kotlinType(m.result)}, ${code}>(settle)`
+    const reply = m.result.kind === "void"
+      ? [`Reply<Unit, ${code}>(settle, null)`]
+      : m.result.kind === "optional"
+        // Nothing is written for null: the app's promise resolves with `undefined`.
+        ? block(`${head} { v, w ->`, block(`if (v != null) {`, encode(m.result.of, "v", "w", 2), `}`), `}`)
+        : block(`${head} { v, w ->`, encode(m.result, "v", "w", 1), `}`)
+    lines.push(...wrap(`plugin.${ident(m.name)}(${m.args.map((_, i) => `a${i}, `).join("")}`, reply, `)`))
+    return `            ${str(m.name)} -> {\n${text(lines, "                ")}\n            }`
+  })
+  out.push([
+    `/** Reads a call off the wire and hands it to the plugin; a malformed call never reaches it. */\n`,
+    `internal object ${iface}Glue {\n`,
+    `    fun call(plugin: ${iface}Plugin, method: String, r: PackedReader, settle: ChannelSettle) {\n        val n = r.beginArray()   // the arguments, in their order\n        when (method) {\n`,
+    cases.length ? cases.join("\n") + "\n" : "",
+    `            else -> settle.reject("Unknown method: $method")\n        }\n    }\n}\n`,
+  ].join(""))
+
+  return out.join("\n")
+}
+
+export type KotlinEmitOptions = {
+  id: string
+  /** The package of the plugin's Kotlin: the generated file is a file of it. */
+  package: string
+}
+
+/** The host's names a generated file may use, by the import that brings each. */
+const IMPORTS: [string, string][] = [
+  ["LecodesEngine", "io.letary.lecodes.LecodesEngine"],
+  ["ChannelSettle", "io.letary.lecodes.services.ChannelSettle"],
+  ["NativeViews", "io.letary.lecodes.services.NativeViews"],
+  ["NoCode", "io.letary.lecodes.services.NoCode"],
+  ["PluginCode", "io.letary.lecodes.services.PluginCode"],
+  ["PluginEmit", "io.letary.lecodes.services.PluginEmit"],
+  ["PluginFile", "io.letary.lecodes.services.PluginFile"],
+  ["Reply", "io.letary.lecodes.services.Reply"],
+  ["Services", "io.letary.lecodes.services.Services"],
+  ["Wire", "io.letary.lecodes.services.Wire"],
+  ["PackedReader", "io.letary.lecodes.core.PackedReader"],
+  ["PackedWriter", "io.letary.lecodes.core.PackedWriter"],
+]
+
+/** One file per plugin: the types every channel of the contract reaches, then each channel. */
+export const emitKotlin = (lowered: Lowered, opts: KotlinEmitOptions): string => {
+  const header = lowered.channels.map(c => `the ${c.kind} "${c.name}", contract version ${c.version}`).join("; ")
+  const guarded = (what: string, body: () => string): string => {
+    try { return body() } catch (e) {
+      if (e instanceof EmitError) throw new EmitError(`${what}: ${e.message}`)
+      throw e
+    }
+  }
+  const ways = waysOf(lowered)
+  const body = [
+    `// ---- The contract's types ----\n\n`,
+    lowered.decls.map(d => guarded(d.name, () => emitDecl(d, ways))).join("\n"),
+    ...lowered.channels.map(ch => `\n// ---- ${ch.iface} ----\n\n${guarded(ch.iface, () => emitChannel(ch))}`),
+  ].join("")
+  const imports = IMPORTS.filter(([name]) => new RegExp(`\\b${name}\\b`).test(body)).map(([, path]) => `import ${path}`)
+  return [
+    `// GENERATED by \`lecodes plugin gen\` from contract.d.ts — do not edit.\n`,
+    `// ${opts.id}: ${header}.\n\n`,
+    `package ${opts.package}\n\n`,
+    `${imports.join("\n")}\n\n`,
+    body,
+  ].join("")
+}

package/src/plugin/emitSdk.ts

@@ -0,0 +1,259 @@
+// The generator's emitter for `sdk/`: a contract's channel → `<id>.gen.ts`, the wrapper an APP calls
+// (docs/plans/plugins-plan.md in core). TypeScript SOURCE: it is compiled with the app, so what an
+// app does not name is shaken out.
+//
+// Per channel the file holds
+//   - the WIRE, call by call: one function per method (`takePhoto(view)`), for a hand-written
+//     wrapper whose public API is not the wire's (the map queues its calls, Geolocation fans one
+//     watch out);
+//   - `<Name>Base`: the element / the client with the wire's methods as its own — the public shape
+//     when nothing is hand-written, the class a hand-written wrapper extends otherwise;
+//   - the public export (`<Name>`), ONLY when the plugin has no hand-written `sdk/<id>.ts`.
+//
+// The emitter knows the wire's FORMAT in one place each: `_call` (lecodes-sdk/plugin) and the
+// decoders below. A change of the wire is a change there, never in a plugin. The wire carries
+// VALUES: what an app passes and gets is what crosses, a Uint8Array included — only a File is
+// something else on it (the handle of a host buffer).
+
+import { CONTRACT_MODULE, type Channel, type Contract, type Decl, type Field, type Type } from "./contract"
+
+export class EmitError extends Error {}
+
+export type SdkEmitOptions = {
+  /** The plugin's id: the file is `<id>.gen.ts`. */
+  id: string
+  /** The plugin has a hand-written `sdk/<id>.ts`: it owns the public export. */
+  handWritten: boolean
+  /** The contract, as the generated file imports it. */
+  contractImport?: string
+}
+
+const indent = (text: string, by = "  "): string => text.split("\n").map(l => l ? by + l : l).join("\n")
+
+const docBlock = (doc: string, extra: string[] = []): string => {
+  const lines = [...(doc ? doc.split("\n").map(l => l.trim()) : []), ...extra]
+  if (lines.length === 0) return ""
+  if (lines.length === 1) return `/** ${lines[0]} */\n`
+  return `/** ${lines[0]}\n${lines.slice(1).map(l => ` *  ${l}`.trimEnd()).join("\n")} */\n`
+}
+
+export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptions): string => {
+  const decls = new Map<string, Decl>(contract.decls.map(d => [d.name, d]))
+  const usedTypes = new Set<string>()      // names of the contract this file imports
+  const usedSdk = new Set<string>()        // names of lecodes-sdk/plugin: values
+  const usedSdkTypes = new Set<string>()   // …and types
+
+  // ---- types as TypeScript --------------------------------------------------------------------------
+  const typeText = (t: Type): string => {
+    switch (t.kind) {
+      case "i32": case "f64": return "number"
+      case "boolean": return "boolean"
+      case "string": return "string"
+      case "void": return "void"
+      case "bytes": return "Uint8Array"
+      case "file": usedSdkTypes.add("File"); return "File"
+      case "json": usedSdkTypes.add("Json"); return "Json"
+      case "ref": usedTypes.add(t.name); return t.name
+      case "literals": return t.values.map(v => JSON.stringify(v)).join(" | ")
+      case "object": return t.fields.length ? `{ ${t.fields.map(fieldText).join(", ")} }` : "{}"
+      case "map": return `{ [key: string]: ${typeText(t.of)} }`
+      case "list": return `${wrapped(t.of)}[]`
+      case "tuple": return `[${t.of.map(typeText).join(", ")}]`
+      case "union": return t.of.map(typeText).join(" | ")
+      case "nullable": return `${typeText(t.of)} | null`
+    }
+  }
+  const wrapped = (t: Type): string => t.kind === "union" || t.kind === "nullable" || (t.kind === "literals" && t.values.length > 1) ? `(${typeText(t)})` : typeText(t)
+  const fieldText = (f: Field): string => `${f.name}${f.optional ? "?" : ""}: ${typeText(f.type)}`
+
+  // ---- what crosses as something else ---------------------------------------------------------------
+  // Only a `File`: it crosses as the handle of a host buffer. Everything else — a Uint8Array too — is
+  // on the wire what it is for the app.
+  /** Does a value of this type hold a `File` anywhere? */
+  const carriesBuffer = (t: Type, seen = new Set<string>()): boolean => {
+    switch (t.kind) {
+      case "file": return true
+      case "ref": {
+        if (seen.has(t.name)) return false
+        seen.add(t.name)
+        const d = decls.get(t.name)!
+        return d.kind === "alias" ? carriesBuffer(d.type, seen) : d.fields.some(f => carriesBuffer(f.type, seen))
+      }
+      case "object": return t.fields.some(f => carriesBuffer(f.type, seen))
+      case "map": case "list": case "nullable": return carriesBuffer(t.of, seen)
+      case "tuple": case "union": return t.of.some(m => carriesBuffer(m, seen))
+      default: return false
+    }
+  }
+
+  /** The expression that turns the wire's value `v` into the contract's; undefined = as is. */
+  const decoders = new Map<string, string>()   // struct / alias name → its decoder function
+  const decode = (t: Type, v: string, where: string): string | undefined => {
+    if (!carriesBuffer(t)) return undefined
+    switch (t.kind) {
+      case "file": usedSdk.add("_toFile"); return `_toFile(${v})`
+      case "nullable": return `${v} == null ? null : ${decode(t.of, v, where)}`
+      case "list": return `${v}.map((x: any) => ${decode(t.of, "x", where)})`
+      case "map": return `Object.fromEntries(Object.entries(${v}).map(([k, x]: [string, any]) => [k, ${decode(t.of, "x", where)}]))`
+      case "tuple": return `[${t.of.map((m, i) => decode(m, `${v}[${i}]`, where) ?? `${v}[${i}]`).join(", ")}]`
+      case "object": return `{ ...${v}, ${t.fields.filter(f => carriesBuffer(f.type)).map(f => `${f.name}: ${decodeField(f, v, where)}`).join(", ")} }`
+      case "union": throw new EmitError(`${where}: a File inside a union cannot be told apart on the wire — give it a member of its own`)
+      case "ref": {
+        const d = decls.get(t.name)!
+        if (!decoders.has(t.name)) {
+          decoders.set(t.name, "")   // a recursive type finds its own name
+          const body = d.kind === "alias" ? decode(d.type, "w", d.name)! : decode({ kind: "object", fields: d.fields }, "w", d.name)!
+          usedTypes.add(t.name)
+          decoders.set(t.name, `const _to${t.name} = (w: any): ${t.name} => (${body})`)
+        }
+        return `_to${t.name}(${v})`
+      }
+      default: return undefined
+    }
+  }
+  const decodeField = (f: Field, v: string, where: string): string => {
+    const value = `${v}.${f.name}`
+    const d = decode(f.type, value, `${where}.${f.name}`)!
+    return f.optional ? `${value} === undefined ? undefined : ${f.type.kind === "nullable" ? `(${d})` : d}` : d
+  }
+
+  /** The other way — the expression that turns the app's value `v` into the wire's; undefined = as is. */
+  const encoders = new Map<string, string>()   // struct / alias name → its encoder function
+  const encode = (t: Type, v: string, where: string): string | undefined => {
+    if (!carriesBuffer(t)) return undefined
+    switch (t.kind) {
+      case "file": usedSdk.add("_fromFile"); return `_fromFile(${v})`
+      case "nullable": return `${v} == null ? null : ${encode(t.of, v, where)}`
+      case "list": return `${v}.map((x: any) => ${encode(t.of, "x", where)})`
+      case "map": return `Object.fromEntries(Object.entries(${v}).map(([k, x]: [string, any]) => [k, ${encode(t.of, "x", where)}]))`
+      case "tuple": return `[${t.of.map((m, i) => encode(m, `${v}[${i}]`, where) ?? `${v}[${i}]`).join(", ")}]`
+      case "object": return `{ ...${v}, ${t.fields.filter(f => carriesBuffer(f.type)).map(f => `${f.name}: ${encodeField(f, v, where)}`).join(", ")} }`
+      case "union": throw new EmitError(`${where}: a File inside a union cannot be told apart on the wire — give it a member of its own`)
+      case "ref": {
+        const d = decls.get(t.name)!
+        if (!encoders.has(t.name)) {
+          encoders.set(t.name, "")   // a recursive type finds its own name
+          const body = d.kind === "alias" ? encode(d.type, "v", d.name)! : encode({ kind: "object", fields: d.fields }, "v", d.name)!
+          usedTypes.add(t.name)
+          encoders.set(t.name, `const _from${t.name} = (v: ${t.name}): any => (${body})`)
+        }
+        return `_from${t.name}(${v})`
+      }
+      default: return undefined
+    }
+  }
+  const encodeField = (f: Field, v: string, where: string): string => {
+    const value = `${v}.${f.name}`
+    const e = encode(f.type, value, `${where}.${f.name}`)!
+    return f.optional ? `${value} === undefined ? undefined : ${f.type.kind === "nullable" ? `(${e})` : e}` : e
+  }
+
+  // ---- the channel ------------------------------------------------------------------------------------
+  const isView = channel.kind === "view"
+  const base = isView ? "ViewChannel" : "ServiceChannel"
+  usedSdk.add(base)
+  const iface = channel.iface
+  const target = isView ? "view" : "service"
+  const { eventsType, paramsType } = channel
+  if (eventsType) usedTypes.add(eventsType)
+  if (paramsType) usedTypes.add(paramsType)
+  const targetType = `${base}<${eventsType ?? "{}"}>`
+
+  // An event whose payload holds a File is read before the app's listener sees it.
+  const readers = channel.events.filter(e => carriesBuffer(e.payload))
+    .map(e => `  ${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e.name) ? e.name : JSON.stringify(e.name)}: (w: any) => ${decode(e.payload, "w", `${iface}: the event "${e.name}"`)},`)
+  if (readers.length) usedSdkTypes.add("EventReaders")
+
+  const wire: string[] = []
+  const members: string[] = []
+  for (const m of channel.methods) {
+    const where = `${iface}.${m.name}`
+    const args = m.args.map(a => `${a.name}${a.optional ? "?" : ""}: ${typeText(a.type)}`)
+    // A File the app hands over crosses as its handle; an optional argument left out stays out.
+    const names = m.args.map(a => {
+      const e = encode(a.type, a.name, `${where}(${a.name})`)
+      if (e === undefined) return a.name
+      return a.optional ? `${a.name} === undefined ? undefined : ${a.type.kind === "nullable" ? `(${e})` : e}` : e
+    })
+    const own = m.args.map(a => a.name)
+    const result = `Promise<${typeText(m.result)}>`
+    const call = `${target}._call(${JSON.stringify(m.name)}, [${names.join(", ")}]${m.since > 1 ? `, ${m.since}` : ""})`
+    // A half resolves "nothing" as an absent value: a nullable result is null for the app.
+    const decoded = m.result.kind === "void" ? undefined
+      : decode(m.result, "w", `${where}()`) ?? (m.result.kind === "nullable" ? "w ?? null" : undefined)
+    const tags = [
+      ...(m.since > 1 ? [`Contract version ${m.since}: an older half rejects the call — ask \`supports(${JSON.stringify(m.name)})\`.`] : []),
+      ...(m.rejects.length ? [`Rejects with ${m.rejects.map(r => `"${r}"`).join(" / ")}.`] : []),
+    ]
+    const doc = docBlock(m.doc, tags)
+    wire.push(`${doc}export const ${m.name} = (${[`${target}: ${targetType}`, ...args].join(", ")}): ${result} =>\n  ${call}${decoded ? `.then((w: any) => ${decoded})` : ""}`)
+    members.push(`${doc}${m.name}(${args.join(", ")}): ${result} { return ${m.name}(${["this", ...own].join(", ")}) }`)
+  }
+
+  // ---- which methods the host's half has ---------------------------------------------------------------
+  const later = channel.methods.filter(m => m.since > 1)
+  const methodNames = channel.methods.length ? channel.methods.map(m => JSON.stringify(m.name)).join(" | ") : "never"
+  const supports = [
+    `/** A method of the contract. */
+export type Method = ${methodNames}
+
+`,
+    later.length ? `const SINCE: { [method: string]: number } = { ${later.map(m => `${m.name}: ${m.since}`).join(", ")} }
+
+` : "",
+    `/** Whether this host has the ${channel.kind} "${channel.name}" — and, given a method, a half new enough for it
+ *  (a method added after the first version of the contract is tagged \`@since\`). */
+`,
+    `export const supports = (method?: Method): boolean =>
+  ${base}.supports(NAME${later.length ? `, method === undefined ? 1 : SINCE[method] ?? 1` : ""})`,
+    later.length ? "" : `   // every method is of version 1`,
+    `
+`,
+  ].join("")
+
+  const paramsArg = `params: ${paramsType ?? "{}"} = {}`
+  const klass = [
+    docBlock(channel.doc || `The ${channel.kind} "${channel.name}" with the wire's methods as its own.`),
+    `export class ${iface}Base extends ${targetType} {\n`,
+    indent(`constructor(${paramsArg}) { super(${JSON.stringify(iface)}, NAME, params${readers.length ? ", READERS" : ""}) }`),
+    members.length ? "\n\n" + indent(members.join("\n")) : "",
+    `\n}`,
+  ].join("")
+
+  const publicExport = opts.handWritten ? "" : isView ? [
+    `\nexport type ${iface} = ${iface}Base\n\n`,
+    `// PURE IIFE: an app that never names ${iface} carries none of this file.\n`,
+    `export const ${iface}: {\n  (params?: ${paramsType ?? "{}"}): ${iface}\n  /** Whether this host registered the view "${channel.name}". */\n  readonly isSupported: boolean\n  /** Whether the host's half has \`method\`: false on a host whose half is older than it. */\n  supports(method: Method): boolean\n} = /*#__PURE__*/ (() => {\n`,
+    `  const factory = (params?: ${paramsType ?? "{}"}): ${iface} => new ${iface}Base(params)\n`,
+    `  Object.defineProperty(factory, "isSupported", { get: (): boolean => supports() })\n`,
+    `  factory.supports = supports\n`,
+    `  return factory as any\n})()\n`,
+  ].join("") : [
+    `\nexport type ${iface} = ${iface}Base & {\n  /** Whether this host registered the service "${channel.name}". */\n  readonly isSupported: boolean\n  /** Whether the host's half has \`method\`: false on a host whose half is older than it. */\n  supports(method: Method): boolean\n}\n\n`,
+    `// PURE IIFE: an app that never names ${iface} carries none of this file. One session for the app's\n// life, opened by the first call.\n`,
+    `export const ${iface}: ${iface} = /*#__PURE__*/ (() => {\n`,
+    `  const service = new ${iface}Base()\n`,
+    `  Object.defineProperty(service, "isSupported", { get: (): boolean => supports() })\n`,
+    `  Object.defineProperty(service, "supports", { value: supports })\n`,
+    `  return service as any\n})()\n`,
+  ].join("")
+
+  // ---- the file ---------------------------------------------------------------------------------------
+  const sdkImports = [...[...usedSdk].sort(), ...[...usedSdkTypes].sort().map(n => `type ${n}`)]
+  const out = [
+    `// GENERATED by \`lecodes plugin gen\` from contract.d.ts — do not edit.\n`,
+    `// ${opts.id}: the ${channel.kind} "${channel.name}", contract version ${channel.version}.\n\n`,
+    `import { ${sdkImports.join(", ")} } from "${CONTRACT_MODULE}"\n`,
+    usedTypes.size ? `import type { ${[...usedTypes].sort().join(", ")} } from "${opts.contractImport ?? "../contract"}"\n` : "",
+    `\n/** What the halves register under. */\nexport const NAME = ${JSON.stringify(channel.name)}\n`,
+    `/** The contract's version: the highest \`@since\` of its members. */\nexport const VERSION = ${channel.version}\n`,
+    decoders.size ? `\n${[...decoders.values()].join("\n")}\n` : "",
+    encoders.size ? `\n${[...encoders.values()].join("\n")}\n` : "",
+    readers.length ? `\n/** The events whose payload holds a File: read before a listener sees it. */\nexport const READERS: EventReaders = {\n${readers.join("\n")}\n}\n` : "",
+    wire.length ? `\n// ---- the wire, call by call ${"-".repeat(70)}\n\n${wire.join("\n\n")}\n` : "",
+    `\n// ---- what the host's half has ${"-".repeat(68)}\n\n${supports}`,
+    `\n// ---- the ${isView ? "element" : "client"} ${"-".repeat(isView ? 82 : 83)}\n\n${klass}\n`,
+    publicExport,
+  ]
+  return out.join("")
+}