lecodes-cli 2.2.9 → 2.2.10

package/src/plugin/emitSwift.ts

@@ -6,8 +6,8 @@
 //   - `<Name>Plugin`: the PROTOCOL the plugin implements — one method per call, a typed `Reply`;
 //   - `<Name>Channel.register(in:_:)` + 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.swift (Reply, PluginFile) and on the wire's two ends
-// (WireIn, WireOut). The wire carries VALUES, and the codecs read a struct straight out of the
+// It stands on the host SDK's PluginChannel.swift (Reply, PluginFile), its gl facade's Entity / Scene3D
+// (scene/GL.swift) and on the wire's two ends (WireIn, WireOut). The wire carries VALUES, and the codecs read a struct straight out of the
 // runtime's value and write one straight into it — no tree of Foundation's objects in between. A
 // Uint8Array is a `Data`, a File the handle of a host buffer; a `Json` member alone is Foundation's
 // objects, because JSON is what a half does with it.
@@ -46,6 +46,8 @@ export const swiftType = (t: L): string => {
     case "string": return "String"
     case "json": return "Any"
     case "file": return "PluginFile"
+    case "entity": return "Entity"
+    case "scene3d": return "Scene3D"
     case "bytes": return "Data"
     case "void": return "Void"
     case "enum": case "struct": case "union": return t.name
@@ -68,6 +70,8 @@ const decode = (t: L, e: string, depth = 0): string[] => {
     case "json": return [`${e}.json`]
     case "bytes": return [`${e}.bytes`]
     case "file": return [`${e}.file`]
+    case "entity": return [`${e}.entity`]
+    case "scene3d": return [`${e}.scene3D`]
     case "enum": case "struct": case "union": return [`${t.name}(wire: ${e})`]
     // Closures are ARGUMENTS, never trailing: a trailing one does not parse inside a `guard` condition.
     case "list": return block(`${e}.list({ ${v} in`, decode(t.of, v, depth + 1), `})`)
@@ -100,7 +104,8 @@ const encode = (t: L, e: string, w: string, depth = 0): string[] => {
     case "json": return [`${w}.json(${e})`]
     case "bytes": return [`${w}.bytes(${e})`]
     case "enum": return [`${w}.string(${e}.rawValue)`]
-    case "file": case "struct": case "union": return [`${e}.write(to: ${w})`]
+    case "file": case "entity": case "struct": case "union": return [`${e}.write(to: ${w})`]
+    case "scene3d": throw new EmitError("a Scene3D crosses from the app to the host only")
     case "list": return [`${w}.beginArray(${e}.count)`, ...block(`for ${v} in ${e} {`, encode(t.of, v, w, depth + 1), `}`), `${w}.end()`]
     case "map": return [`${w}.beginObject(${e}.count)`, `for (k${depth}, ${v}) in ${e} {`, ...indent([`${w}.name(k${depth})`, ...encode(t.of, v, w, depth + 1)]), `}`, `${w}.end()`]
     case "tuple": return [`${w}.beginArray(${t.of.length})`, ...t.of.flatMap((m, i) => encode(m, `${e}.${i}`, w, depth + 1)), `${w}.end()`]
@@ -242,7 +247,11 @@ const emitChannel = (ch: LChannel): string => {
   // ---- the protocol ----
   const signatures = ch.methods.map(m => {
     const args = [...m.args.map(a => `_ ${ident(a.name)}: ${swiftType(a.type)}`), `_ reply: Reply<${swiftType(m.result)}, ${code}>`]
-    const tags = [m.doc, m.rejects.length ? `Rejects with ${m.rejects.map(r => `.${r}`).join(" / ")}.` : ""].filter(Boolean).join("\n")
+    const tags = [
+      m.doc,
+      m.permissions.length ? `Needs the ${m.permissions.join(" and ")} permission${m.permissions.length > 1 ? "s" : ""}: asked by the glue before the call, .denied when refused.` : "",
+      m.rejects.length ? `Rejects with ${m.rejects.map(r => `.${r}`).join(" / ")}.` : "",
+    ].filter(Boolean).join("\n")
     return `${doc(tags, "    ")}    func ${ident(m.name)}(${args.join(", ")})`
   })
   out.push([
@@ -258,6 +267,7 @@ const emitChannel = (ch: LChannel): string => {
   ].join(""))
 
   // ---- registration ----
+  const gated = ch.methods.some(m => m.permissions.length > 0)
   out.push([
     `public enum ${iface}Channel {\n`,
     `    /// What the halves register under.\n    public static let name = ${JSON.stringify(ch.name)}\n`,
@@ -265,7 +275,7 @@ const emitChannel = (ch: LChannel): string => {
     `    /// Register the ${ch.kind}: \`make\` builds ${isView ? "one instance" : "one session"} from its params. ${isView ? "" : "It must be cheap — no prompt,\n    /// no I/O: that belongs to the first call that needs it."}\n`.replace(/ \n/, "\n"),
     `    public static func register(in engine: LeCodesEngine, _ make: @escaping (${ch.params}, ${iface}Events) -> ${iface}Plugin) {\n`,
     `        engine.register${isView ? "View" : "Service"}(name, version: Int32(version)) { params, channel in\n`,
-    `            ${iface}Glue(make(WireIn.of(params, { ${ch.params}(wire: $0) }) ?? ${ch.params}(), ${iface}Events(channel: channel)))\n`,
+    `            ${iface}Glue(make(WireIn.of(params, { ${ch.params}(wire: $0) }) ?? ${ch.params}(), ${iface}Events(channel: channel))${gated ? ", engine.permissions" : ""})\n`,
     `        }\n    }\n}\n`,
   ].join(""))
 
@@ -294,14 +304,29 @@ const emitChannel = (ch: LChannel): string => {
         // Nothing is written for nil: the app's promise resolves with `undefined`.
         ? block(`${head} { v, w in`, block(`if let v1 = v {`, encode(m.result.of, "v1", "w", 2), `}`), `}`)
         : block(`${head} { v, w in`, encode(m.result, "v", "w", 1), `}`)
-    lines.push(...wrap(`plugin.${ident(m.name)}(${m.args.map((_, i) => `a${i}, `).join("")}`, reply, `)`))
+    if (m.permissions.length) {
+      // The gate: the host's permission service, then the plugin — or `.denied` without it.
+      lines.push(...wrap(`let reply = `, reply, ``))
+      lines.push(
+        `permissions.ensure([${m.permissions.map(k => `.${k}`).join(", ")}]) { [plugin] granted in`,
+        `    guard granted else { return reply.reject(.denied) }`,
+        `    plugin.${ident(m.name)}(${m.args.map((_, i) => `a${i}, `).join("")}reply)`,
+        `}`,
+      )
+    } else {
+      lines.push(...wrap(`plugin.${ident(m.name)}(${m.args.map((_, i) => `a${i}, `).join("")}`, reply, `)`))
+    }
     return `        case ${JSON.stringify(m.name)}:\n${text(lines, "            ")}`
   })
   out.push([
     `/// Reads a call off the wire and hands it to the plugin; a malformed call never reaches it.\n`,
     `final class ${iface}Glue: ${isView ? "WireNativeViewInstance" : "WireServiceInstance"} {\n`,
-    `    private let plugin: ${iface}Plugin\n\n`,
-    `    init(_ plugin: ${iface}Plugin) { self.plugin = plugin }\n\n`,
+    `    private let plugin: ${iface}Plugin\n`,
+    gated ? `    /// The host's permission service: what a method tagged \`@permission\` is gated by.\n    private let permissions: Permissions\n` : "",
+    `\n`,
+    gated
+      ? `    init(_ plugin: ${iface}Plugin, _ permissions: Permissions) {\n        self.plugin = plugin\n        self.permissions = permissions\n    }\n\n`
+      : `    init(_ plugin: ${iface}Plugin) { self.plugin = plugin }\n\n`,
     isView ? `    var view: UIView { plugin.view }\n\n` : "",
     `    func call(_ method: String, wire args: WireIn, _ settle: ChannelSettle) {\n        switch method {\n`,
     cases.length ? cases.join("\n") + "\n" : "",

package/src/plugin/emitWeb.ts

@@ -16,7 +16,7 @@
 // take the same half. What the host is asked for is a SHAPE (`PluginHost`), declared in the file.
 
 import { EmitError } from "./emitSdk"
-import { waysOf, type L, type LChannel, type LDecl, type LField, type Lowered, type Ways } from "./lower"
+import { reachesKind, waysOf, type L, type LChannel, type LDecl, type LField, type Lowered, type Ways } from "./lower"
 
 const str = (value: string): string => JSON.stringify(value)
 const key = (name: string): string => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : str(name)
@@ -37,6 +37,8 @@ export const webType = (t: L): string => {
     case "string": return "string"
     case "json": return "Json"
     case "file": return "PluginFile"
+    case "entity": return "Entity"
+    case "scene3d": return "Scene3D"
     case "bytes": return "Uint8Array"
     case "void": return "void"
     case "enum": case "struct": case "union": return t.name
@@ -62,6 +64,7 @@ const decode = (t: L, e: string, depth = 0): string => {
     case "json": return `wire.json(${e})`
     case "bytes": return `wire.bytes(${e})`
     case "file": return `readFile(${e})`
+    case "entity": case "scene3d": return `readId(${e})`
     case "enum": case "struct": case "union": return `read${t.name}(${e})`
     case "list": return `wire.list(${e}, (${v}) => ${decode(t.of, v, depth + 1)})`
     case "map": return `wire.map(${e}, (${v}) => ${decode(t.of, v, depth + 1)})`
@@ -289,6 +292,9 @@ export const emitWeb = (lowered: Lowered, opts: WebEmitOptions): string => {
   const uses = (name: string): boolean => new RegExp(`\\b${name}\\b`).test(body)
   const views = lowered.channels.some(c => c.kind === "view")
   const services = lowered.channels.some(c => c.kind === "service")
+  // A contract that hands the half the app's 3D nodes / scenes is one whose half drives them: through
+  // the host's gl facade, which the host then must have.
+  const drives3d = reachesKind(lowered, "entity") || reachesKind(lowered, "scene3d")
 
   return [
     `// GENERATED by \`lecodes plugin gen\` from contract.d.ts — do not edit.\n`,
@@ -302,7 +308,9 @@ export const emitWeb = (lowered: Lowered, opts: WebEmitOptions): string => {
     services ? `  registerService(name: string, factory: (params: unknown, channel: PluginChannel) => {\n    call?(method: string, args: unknown[]): unknown, close?(): void,\n  }, version: number): void\n` : "",
     uses("writeFile") ? `  /** Store bytes in the host's buffer table: the handle a File crosses as. */\n  putBuffer(bytes: ArrayBuffer): number\n` : "",
     uses("readFile") ? `  /** The bytes of a buffer of the host's table — what the handle of a File the app sent names. */\n  getBuffer(systemId: number): ArrayBuffer | Uint8Array | null | undefined\n` : "",
+    drives3d ? `  /** The 3D engine as the half drives it: the app's entities and scenes by their ids. */\n  gl: PluginGL\n` : "",
     `}\n\n`,
+    drives3d ? PLUGIN_GL : "",
     uses("PluginFile") ? [
       `/** A \`File\` of the contract. One a half hands to the app: its bytes go into the host's buffer\n *  table, the app gets the handle (a texture source, an upload, a share). One the app hands to a\n *  half: the bytes of the buffer its handle names. */\n`,
       `export interface PluginFile { data: ArrayBuffer | Uint8Array, name: string }\n\n`,
@@ -313,8 +321,11 @@ export const emitWeb = (lowered: Lowered, opts: WebEmitOptions): string => {
       `  return { systemId: host.putBuffer(bytes), name: file.name, size: bytes.byteLength }\n}\n\n`,
     ].join("") : "",
     uses("Json") ? `/** A value the generator passes through untyped. */\nexport type Json = null | boolean | number | string | Json[] | { [key: string]: Json }\n\n` : "",
+    reachesKind(lowered, "entity") ? `/** A 3D node of the app (\`Entity\` of the contract): its id, what the host's gl facade (\`host.gl\`) takes. */\nexport type Entity = number\n\n` : "",
+    reachesKind(lowered, "scene3d") ? `/** A 3D scene of the app (\`Scene3D\` of the contract): its id, what the host's gl facade (\`host.gl\`) takes. */\nexport type Scene3D = number\n\n` : "",
     uses("wire") || uses("readFile") ? WIRE : "",
     uses("readFile") ? READ_FILE : "",
+    uses("readId") ? READ_ID : "",
     body.replaceAll("__BUFFERS__", uses("readFile") ? `  buffers = (systemId) => host.getBuffer(systemId)\n` : ""),
   ].join("")
 }
@@ -334,6 +345,51 @@ const readFile = (v: unknown): PluginFile | undefined => {
 
 `
 
+/** The host's gl facade as a half sees it — a SHAPE of the web hosts' own (lecodes-web-shared's
+ *  GLFacade), the twin of `engine.gl` in Swift and Kotlin. */
+const PLUGIN_GL = `/** The host's gl facade (\`host.gl\`): what a half drives the 3D engine through — the app's entities
+ *  and scenes by their ids, a scene's projection and background, a hook before each frame, a
+ *  readback. Never creates or frees an entity or a scene. Every call is a no-op on a page without
+ *  the 3D engine. */
+export interface PluginGL {
+  /** The entity's world matrix (16 numbers, column-major). */
+  setMatrix(entity: number, m16: ArrayLike<number>): void
+  setVisible(entity: number, visible: boolean): void
+  /** The pose of the scene's camera (its world matrix). */
+  setCameraMatrix(scene: number, m16: ArrayLike<number>): void
+  /** A projection the half computes (column-major, OpenGL clip conventions), with the near / far it
+   *  was built with, in place of the scene's fov projection. */
+  setProjection(scene: number, m16: ArrayLike<number>, near: number, far: number): void
+  /** Back to the scene's own (fov) projection. */
+  clearProjection(scene: number): void
+  /** The scene's background: a playing video behind the scene, through \`uv\` — the affine map from
+   *  the viewport's normalized coordinates (0,0 top-left) to the video's, row-major
+   *  [a, b, tx, c, d, ty] (identity by default). null = none. */
+  setBackground(scene: number, video: HTMLVideoElement | null, uv?: ArrayLike<number>): void
+  /** The web has no external textures: a video is handed to setBackground as it is. Always null. */
+  createExternalTexture(): null
+  /** \`body\` before each frame (the page's animation frame), until the returned function is called —
+   *  or the world swap. */
+  onFrame(body: () => void): () => void
+  /** The composite of the scene's next frame — the 3D picture, not the UI over it: RGBA8, top row
+   *  first, width, height; null (0 × 0) when the scene is not the one presented. */
+  readPixels(scene: number, then: (rgba: Uint8Array | null, width: number, height: number) => void): void
+  /** The scene's view: the size of the canvas it draws on in CSS px (the space its touches arrive in;
+   *  not the window's — a player inside a device frame is smaller than its page; 0 × 0 while no scene
+   *  is on show) and the display's turn (\`screen.orientation.angle\`: 0, 90 = turned
+   *  counter-clockwise, 180, 270). Read it each frame (\`onFrame\`) and follow a change. */
+  viewport(scene: number): { width: number, height: number, rotation: 0 | 90 | 180 | 270 }
+}
+
+`
+
+/** The reader of an Entity / a Scene3D the app sent: the id of its 3D node / scene. */
+const READ_ID = `/** An Entity / a Scene3D the app sent: its id, a whole number in u32's range. */
+const readId = (v: unknown): number | undefined =>
+  typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= 4294967295 ? v : undefined
+
+`
+
 /** The readers of the wire's values: undefined = absent, null, or not that type. */
 const WIRE = `// The readers of the wire's values: undefined = absent, null, or not that type. On the web the wire
 // carries the app's OWN values (the host is JavaScript like the app). What is read of the contract is

package/src/plugin/generate.ts

@@ -16,7 +16,8 @@ import { EmitError, emitSdk } from "./emitSdk"
 import { emitSwift } from "./emitSwift"
 import { emitWeb } from "./emitWeb"
 import { lower } from "./lower"
-import { ManifestError, readManifestIfAny, type PluginManifest } from "./manifest"
+import { MANIFEST_FILE, ManifestError, readManifestIfAny, type PluginManifest } from "./manifest"
+import { missingDeclarations, usesPermissions, type PermissionKind } from "./permissions"
 import { DEFAULT_SDK_PATH, PACKAGE_FILE, PackageError, emitPackageSwift } from "./emitPackage"
 
 // A path as the report shows it: relative to `from`, with `/` on every platform (a report is
@@ -60,6 +61,7 @@ export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contra
   // The manifest is held to the folders the plugin has: a half the manifest does not name is built
   // into no host.
   const manifest = readManifestIfAny(plugin.dir, plugin.id)
+  checkPermissions(plugin, contract, manifest)
   const handWritten = existsSync(join(plugin.dir, "sdk", `${plugin.id}.ts`))
   const single = contract.channels.length === 1
   const files: Generated[] = contract.channels.map(channel => ({
@@ -86,6 +88,25 @@ export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contra
   return { contract, manifest, files }
 }
 
+/** The declarations the contract's `@permission` kinds need, held against the plugin's manifests:
+ *  the usage strings of ios.infoPlist (a missing one crashes the app at the prompt) and the
+ *  `<uses-permission>` elements of android/src/main/AndroidManifest.xml (a missing one is a
+ *  silent refusal). Checked where the plugin has the half; a plugin without a manifest (a project's
+ *  own, the shell declares for it) is not held. */
+const checkPermissions = (plugin: PluginDir, contract: Contract, manifest: PluginManifest | null): void => {
+  if (!manifest) return
+  const kinds: PermissionKind[] = []
+  for (const ch of contract.channels) for (const m of ch.methods) for (const k of m.permissions) if (!kinds.includes(k)) kinds.push(k)
+  if (kinds.length === 0) return
+  const androidManifest = join(plugin.dir, "android", "src", "main", "AndroidManifest.xml")
+  const androidNames = manifest.android ? (existsSync(androidManifest) ? usesPermissions(readFileSync(androidManifest, "utf8")) : []) : null
+  const missing = missingDeclarations(kinds, manifest.ios ? manifest.ios.infoPlist ?? {} : null, androidNames)
+  const problems: string[] = []
+  if (missing.infoPlist.length) problems.push(`ios.infoPlist: the contract's @permission needs ${missing.infoPlist.join(", ")} — the usage string the dialog shows`)
+  if (missing.android.length) problems.push(`android/src/main/AndroidManifest.xml: the contract's @permission needs <uses-permission android:name="…"/> for ${missing.android.join(", ")}`)
+  if (problems.length) throw new ManifestError(join(plugin.dir, MANIFEST_FILE), problems)
+}
+
 /** The imports of a web half that name a LeCodes package (`lecodes-sdk`, `lecodes-web-shared`, …), as
  *  `file:line: the import`. A half that imports its host runs on that host only. */
 export const hostImports = (web: string): string[] => {

package/src/plugin/lower.ts

@@ -10,8 +10,9 @@
 
 import type { Channel, Contract, Decl, Field, Type } from "./contract"
 import { EmitError } from "./emitSdk"
+import type { PermissionKind } from "./permissions"
 
-export type Scalar = "i32" | "f64" | "boolean" | "string" | "json" | "file" | "bytes" | "void"
+export type Scalar = "i32" | "f64" | "boolean" | "string" | "json" | "file" | "bytes" | "entity" | "scene3d" | "void"
 
 export type L =
   | { kind: Scalar }
@@ -36,7 +37,7 @@ export type LDecl =
 /** `omit`: the argument may be left out (`name?:`); a nullable one (`T | null`) is always named. */
 export type LArg = { name: string, type: L, omit: boolean }
 
-export type LMethod = { name: string, args: LArg[], result: L, since: number, rejects: string[], doc: string }
+export type LMethod = { name: string, args: LArg[], result: L, since: number, rejects: string[], permissions: PermissionKind[], doc: string }
 
 export type LEvent = {
   name: string
@@ -70,7 +71,7 @@ const upper = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
  *  tells them apart: by what the value at hand IS, before it reads it. */
 export const wireClass = (t: L): string => {
   switch (t.kind) {
-    case "i32": case "f64": return "number"
+    case "i32": case "f64": case "entity": case "scene3d": return "number"
     case "string": case "enum": return "string"
     case "boolean": return "boolean"
     case "struct": case "map": return "object"
@@ -116,7 +117,7 @@ export const lower = (contract: Contract): Lowered => {
         const members = t.of.map((m, i) => type(m, `${name}${upper(memberLabel(m, i))}`, where))
         const seen = new Map<string, L>()
         for (const m of members) {
-          if (m.kind === "json" || m.kind === "file" || m.kind === "bytes" || m.kind === "optional" || m.kind === "union") {
+          if (m.kind === "json" || m.kind === "file" || m.kind === "bytes" || m.kind === "entity" || m.kind === "scene3d" || m.kind === "optional" || m.kind === "union") {
             throw new EmitError(`${where}: a union holds scalars, enums, structs, lists — not ${m.kind === "optional" ? "a nullable member" : m.kind}`)
           }
           const c = wireClass(m)
@@ -171,7 +172,7 @@ export const lower = (contract: Contract): Lowered => {
           return { name: a.name, type: a.optional && t.kind !== "optional" ? { kind: "optional", of: t } : t, omit: a.optional }
         }),
         result: m.result.kind === "void" ? { kind: "void" } : type(m.result, `${iface}${upper(m.name)}Result`, `${where}()`),
-        since: m.since, rejects: m.rejects, doc: m.doc,
+        since: m.since, rejects: m.rejects, permissions: m.permissions, doc: m.doc,
       }
     })
 
@@ -190,9 +191,44 @@ export const lower = (contract: Contract): Lowered => {
 
   // Only what a channel reaches is declared: a struct of the contract nothing names is not a type
   // a half ever sees.
-  return { decls: [...decls.values()], channels }
+  const lowered: Lowered = { decls: [...decls.values()], channels }
+  // A Scene3D crosses from the app to the host only: a half is handed the scene it drives, it never
+  // names one back (the SDK has no scene to resolve an id to).
+  const sends = (t: L): boolean => usesKind(lowered, t, "scene3d")
+  for (const ch of channels) {
+    for (const m of ch.methods) if (sends(m.result)) throw new EmitError(`${ch.iface}.${m.name}(): a Scene3D crosses from the app to the host only — a result cannot hold one`)
+    for (const e of ch.events) {
+      if (sends(e.payload) || e.inline?.some(f => sends(f.type))) throw new EmitError(`${ch.iface} event ${e.name}: a Scene3D crosses from the app to the host only — an event cannot hold one`)
+    }
+  }
+  return lowered
 }
 
+/** Does a value of type `t` hold a `kind` anywhere (through the declarations it names)? */
+export const usesKind = (lowered: Lowered, t: L, kind: Scalar, seen = new Set<string>()): boolean => {
+  switch (t.kind) {
+    case "list": case "map": case "optional": return usesKind(lowered, t.of, kind, seen)
+    case "tuple": return t.of.some(m => usesKind(lowered, m, kind, seen))
+    case "struct": case "union": {
+      if (seen.has(t.name)) return false
+      seen.add(t.name)
+      const d = lowered.decls.find(x => x.name === t.name)
+      if (d?.kind === "struct") return d.fields.some(f => usesKind(lowered, f.type, kind, seen))
+      if (d?.kind === "union") return d.members.some(m => usesKind(lowered, m, kind, seen))
+      return false
+    }
+    case "enum": return false
+    default: return t.kind === kind
+  }
+}
+
+/** Does the contract reach a `kind` at all (an argument, a param, a result, an event)? */
+export const reachesKind = (lowered: Lowered, kind: Scalar): boolean =>
+  lowered.channels.some(ch =>
+    usesKind(lowered, { kind: "struct", name: ch.params }, kind) ||
+    ch.methods.some(m => usesKind(lowered, m.result, kind) || m.args.some(a => usesKind(lowered, a.type, kind))) ||
+    ch.events.some(e => usesKind(lowered, e.payload, kind) || !!e.inline?.some(f => usesKind(lowered, f.type, kind))))
+
 /** Which way a declaration crosses: the app SENDS it (an argument, a param) → it is read here; the
  *  plugin sends it (a result, an event) → it is written here. Only the codec a way needs is
  *  emitted by a native emitter — a struct that carries a File is written, never read. */

package/src/plugin/permissions.ts

@@ -0,0 +1,52 @@
+// `@permission <kind…>` on a method of a contract: the OS permissions the call needs. The generated
+// native glue asks the host's one permission service (`engine.permissions`) before the call and
+// rejects with `denied` when one was refused — the plugin's code never sees a dialog; the web half
+// asks nothing (the browser's API prompts itself). A kind's needs on each platform are known here,
+// so `lecodes plugin gen` can hold the plugin's manifests to them: the Info.plist usage strings the
+// manifest declares (ios.infoPlist) and the `<uses-permission>` elements of the Android manifest.
+//
+// The kinds are the SDK's (`permissions.query / request` in lecodes-sdk: sdk/src/runtime/permissions.ts).
+
+export const PERMISSION_KINDS = ["camera", "microphone", "location", "speech"] as const
+export type PermissionKind = (typeof PERMISSION_KINDS)[number]
+
+export const isPermissionKind = (s: string): s is PermissionKind => (PERMISSION_KINDS as readonly string[]).includes(s)
+
+/** What a kind needs declared: Info.plist keys (every one), Android permissions (every group has
+ *  one of its names in the manifest — location takes FINE or COARSE). */
+export const PERMISSION_NEEDS: Record<PermissionKind, { infoPlist: string[], android: string[][] }> = {
+  camera: { infoPlist: ["NSCameraUsageDescription"], android: [["android.permission.CAMERA"]] },
+  microphone: { infoPlist: ["NSMicrophoneUsageDescription"], android: [["android.permission.RECORD_AUDIO"]] },
+  location: {
+    infoPlist: ["NSLocationWhenInUseUsageDescription"],
+    android: [["android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION"]],
+  },
+  // Speech recognition: its own purpose string on iOS, the microphone's permission on Android. A
+  // method that recognizes live speech tags `microphone` beside it (the audio is the microphone's).
+  speech: { infoPlist: ["NSSpeechRecognitionUsageDescription"], android: [["android.permission.RECORD_AUDIO"]] },
+}
+
+/** The `android:name`s of the `<uses-permission>` elements of an AndroidManifest.xml. */
+export const usesPermissions = (xml: string): string[] =>
+  [...xml.matchAll(/<uses-permission(?:-sdk-23)?\b[^>]*\bandroid:name\s*=\s*"([^"]+)"/g)].map(m => m[1]!)
+
+/** The declarations the kinds need and the manifests lack: `infoPlist` keys missing from the iOS
+ *  manifest's ios.infoPlist (null = no iOS half), `android` permission groups with no name in the
+ *  Android manifest (null = no Android half). Each entry names the kind that needs it. */
+export const missingDeclarations = (
+  kinds: PermissionKind[],
+  infoPlist: Record<string, string> | null,
+  androidNames: string[] | null,
+): { infoPlist: string[], android: string[] } => {
+  const out = { infoPlist: [] as string[], android: [] as string[] }
+  for (const kind of kinds) {
+    const needs = PERMISSION_NEEDS[kind]
+    if (infoPlist) for (const key of needs.infoPlist) {
+      if (!(key in infoPlist)) out.infoPlist.push(`${key} (${kind})`)
+    }
+    if (androidNames) for (const group of needs.android) {
+      if (!group.some(name => androidNames.includes(name))) out.android.push(`${group.join(" or ")} (${kind})`)
+    }
+  }
+  return { infoPlist: [...new Set(out.infoPlist)], android: [...new Set(out.android)] }
+}