lecodes-cli 2.2.8 → 2.2.10

package/src/plugin/emitSdk.ts

@@ -12,8 +12,9 @@
 //
 // 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).
+// VALUES: what an app passes and gets is what crosses, a Uint8Array included — only a File, an
+// Entity and a Scene3D are something else on it (the handle of a host buffer; the id of a 3D node,
+// of a 3D scene).
 
 import { CONTRACT_MODULE, type Channel, type Contract, type Decl, type Field, type Type } from "./contract"
 
@@ -53,6 +54,8 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
       case "bytes": return "Uint8Array"
       case "file": usedSdkTypes.add("File"); return "File"
       case "json": usedSdkTypes.add("Json"); return "Json"
+      case "entity": usedSdkTypes.add("Entity"); return "Entity"
+      case "scene3d": usedSdkTypes.add("Scene3D"); return "Scene3D"
       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(", ")} }` : "{}"
@@ -67,12 +70,12 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
   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? */
+  // A `File` crosses as the handle of a host buffer, an `Entity` / a `Scene3D` as the id of the app's
+  // 3D node / scene. Everything else — a Uint8Array too — is on the wire what it is for the app.
+  /** Does a value of this type hold a `File`, an `Entity` or a `Scene3D` anywhere? */
   const carriesBuffer = (t: Type, seen = new Set<string>()): boolean => {
     switch (t.kind) {
-      case "file": return true
+      case "file": case "entity": case "scene3d": return true
       case "ref": {
         if (seen.has(t.name)) return false
         seen.add(t.name)
@@ -92,6 +95,8 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
     if (!carriesBuffer(t)) return undefined
     switch (t.kind) {
       case "file": usedSdk.add("_toFile"); return `_toFile(${v})`
+      case "entity": usedSdk.add("_toEntity"); return `_toEntity(${v})`
+      case "scene3d": throw new EmitError(`${where}: a Scene3D crosses from the app to the host only`)
       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)}]))`
@@ -123,6 +128,8 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
     if (!carriesBuffer(t)) return undefined
     switch (t.kind) {
       case "file": usedSdk.add("_fromFile"); return `_fromFile(${v})`
+      case "entity": usedSdk.add("_fromEntity"); return `_fromEntity(${v})`
+      case "scene3d": usedSdk.add("_fromScene3D"); return `_fromScene3D(${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)}]))`
@@ -160,8 +167,11 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
   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}"`)},`)
+  // (an object literal in parentheses: an arrow's body that opens a brace is a block)
+  const readers = channel.events.filter(e => carriesBuffer(e.payload)).map(e => {
+    const read = decode(e.payload, "w", `${iface}: the event "${e.name}"`)!
+    return `  ${/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(e.name) ? e.name : JSON.stringify(e.name)}: (w: any) => ${read.startsWith("{") ? `(${read})` : read},`
+  })
   if (readers.length) usedSdkTypes.add("EventReaders")
 
   const wire: string[] = []
@@ -183,6 +193,7 @@ export const emitSdk = (contract: Contract, channel: Channel, opts: SdkEmitOptio
       : 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.permissions.length ? [`Needs the ${m.permissions.map(k => `"${k}"`).join(" and ")} permission${m.permissions.length > 1 ? "s" : ""}: the host asks before the call, "denied" when refused.`] : []),
       ...(m.rejects.length ? [`Rejects with ${m.rejects.map(r => `"${r}"`).join(" / ")}.`] : []),
     ]
     const doc = docBlock(m.doc, tags)
@@ -212,10 +223,13 @@ export type Method = ${methodNames}
   ].join("")
 
   const paramsArg = `params: ${paramsType ?? "{}"} = {}`
+  // Params that hold a File, an Entity or a Scene3D cross as their handles / ids, as an argument does:
+  // the channel serializes them as they are handed over.
+  const sentParams = paramsType ? encode({ kind: "ref", name: paramsType }, "params", `${iface}: its params`) : undefined
   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" : ""}) }`),
+    indent(`constructor(${paramsArg}) { super(${JSON.stringify(iface)}, NAME, ${sentParams ?? "params"}${readers.length ? ", READERS" : ""}) }`),
     members.length ? "\n\n" + indent(members.join("\n")) : "",
     `\n}`,
   ].join("")

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

@@ -2,7 +2,8 @@
 // with a `contract.d.ts`; the path is one plugin, or a repo that keeps them in `plugins/<id>/`.
 // Generated files are written beside the hand-written ones of the place they travel to
 // (`sdk/<id>.gen.ts`, `ios/<Name>.gen.swift`, `android/…/<Name>.gen.kt`, `web/<id>.gen.ts`) and are
-// committed — `check` is what CI runs.
+// committed — `check` is what CI runs. A REPO of plugins also gets its `Package.swift` (the iOS
+// halves as one SwiftPM package, emitPackage.ts) from the manifests.
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
 import { createRequire } from "node:module"
@@ -15,7 +16,9 @@ import { EmitError, emitSdk } from "./emitSdk"
 import { emitSwift } from "./emitSwift"
 import { emitWeb } from "./emitWeb"
 import { lower } from "./lower"
-import { ManifestError, readManifestIfAny } 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
 // compared and pasted; `\` is Windows' own).
@@ -52,12 +55,13 @@ export const loadTypescript = (dir: string): typeof tsModule => {
 export type Generated = { file: string, text: string }
 
 /** Everything one plugin's contract generates, as `path → text`. Throws ContractError / EmitError. */
-export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contract: Contract, files: Generated[] } => {
+export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contract: Contract, manifest: PluginManifest | null, files: Generated[] } => {
   const file = join(plugin.dir, CONTRACT_FILE)
   const contract = readContract(ts, file, readFileSync(file, "utf8"))
   // The manifest is held to the folders the plugin has: a half the manifest does not name is built
   // into no host.
-  readManifestIfAny(plugin.dir, plugin.id)
+  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 => ({
@@ -81,7 +85,26 @@ export const generatePlugin = (ts: typeof tsModule, plugin: PluginDir): { contra
     const foreign = hostImports(join(plugin.dir, "web"))
     if (foreign.length) throw new EmitError(`web/ imports the host — a web half depends on its generated file, the document it is handed and the browser:\n${foreign.map(f => `  ${f}`).join("\n")}`)
   }
-  return { contract, files }
+  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
@@ -121,8 +144,26 @@ export const kotlinPackage = (android: string): { dir: string, name: string } =>
   return { dir, name: relative(root, dir).split(/[\\/]/).join(".") }
 }
 
+/** The SDK package's path the repo names for its Package.swift: `lecodes.iosSdkPath` of the repo's
+ *  package.json (the first-party repo, a submodule of core, says `../apple/lecodes`); else the default. */
+export const repoSdkPath = (root: string): string => {
+  const file = join(root, "package.json")
+  if (!existsSync(file)) return DEFAULT_SDK_PATH
+  try {
+    const pkg = JSON.parse(readFileSync(file, "utf8")) as { lecodes?: { iosSdkPath?: unknown } }
+    const path = pkg.lecodes?.iosSdkPath
+    if (path !== undefined && typeof path !== "string") throw new PackageError(`package.json lecodes.iosSdkPath: a path, as a string`)
+    return path ?? DEFAULT_SDK_PATH
+  } catch (e) {
+    if (e instanceof PackageError) throw e
+    throw new PackageError(`package.json does not parse: ${e instanceof Error ? e.message : String(e)}`)
+  }
+}
+
 export type GenReport = {
   plugins: { id: string, contract: Contract, written: string[], stale: string[], fresh: string[] }[]
+  /** The repo's own files (its Package.swift), when the path is a repo of plugins. */
+  repo: { written: string[], stale: string[], fresh: string[] }
   /** Contracts that did not read or emit, as printable text. */
   failures: string[]
 }
@@ -134,21 +175,24 @@ export const generate = (path: string, opts: { check?: boolean } = {}): GenRepor
   if (plugins.length === 0) throw new CliError(`No plugin under ${resolve(path)}: a plugin is a directory with a ${CONTRACT_FILE} (one, or plugins/<id>/ of a repo).`)
   const ts = loadTypescript(plugins[0]!.dir)
   const root = resolve(path)
-  const report: GenReport = { plugins: [], failures: [] }
+  const report: GenReport = { plugins: [], repo: { written: [], stale: [], fresh: [] }, failures: [] }
+  const place = (f: Generated, entry: { written: string[], stale: string[], fresh: string[] }): void => {
+    const name = shown(root, f.file) || basename(f.file)
+    const current = existsSync(f.file) ? readFileSync(f.file, "utf8") : null
+    if (current === f.text) { entry.fresh.push(name); return }
+    if (opts.check) { entry.stale.push(name); return }
+    mkdirSync(join(f.file, ".."), { recursive: true })
+    writeFileSync(f.file, f.text)
+    entry.written.push(name)
+  }
+  const manifests: { id: string, manifest: PluginManifest }[] = []
 
   for (const plugin of plugins) {
     try {
-      const { contract, files } = generatePlugin(ts, plugin)
+      const { contract, manifest, files } = generatePlugin(ts, plugin)
+      if (manifest) manifests.push({ id: plugin.id, manifest })
       const entry = { id: plugin.id, contract, written: [] as string[], stale: [] as string[], fresh: [] as string[] }
-      for (const f of files) {
-        const name = shown(root, f.file) || basename(f.file)
-        const current = existsSync(f.file) ? readFileSync(f.file, "utf8") : null
-        if (current === f.text) { entry.fresh.push(name); continue }
-        if (opts.check) { entry.stale.push(name); continue }
-        mkdirSync(join(f.file, ".."), { recursive: true })
-        writeFileSync(f.file, f.text)
-        entry.written.push(name)
-      }
+      for (const f of files) place(f, entry)
       report.plugins.push(entry)
     } catch (e) {
       if (e instanceof ContractError) report.failures.push(e.problems.map(p => `${shown(root, e.file) || e.file}:${p.line}: ${p.message}`).join("\n"))
@@ -157,5 +201,17 @@ export const generate = (path: string, opts: { check?: boolean } = {}): GenRepor
       else throw e
     }
   }
+
+  // A repo of plugins (not one plugin): its Package.swift, from every manifest that read. Written
+  // only when every contract made it — a repo with a broken plugin keeps the package it has.
+  const isRepo = !existsSync(join(root, CONTRACT_FILE))
+  if (isRepo && report.failures.length === 0 && manifests.some(m => m.manifest.ios)) {
+    try {
+      place({ file: join(root, PACKAGE_FILE), text: emitPackageSwift(manifests, repoSdkPath(root)) }, report.repo)
+    } catch (e) {
+      if (e instanceof PackageError) report.failures.push(`${PACKAGE_FILE}: ${e.message}`)
+      else throw e
+    }
+  }
   return report
 }

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)] }
+}