lecodes-cli 2.2.8 → 2.2.10

package/src/compile/screenEntry.ts

@@ -1,123 +1,123 @@
-import { existsSync, readFileSync, statSync } from "node:fs"
-import { isAbsolute, join, relative, resolve } from "node:path"
-import { screenFrame } from "../project/designMeta"
-import { CliError } from "../cli"
-import { toKey } from "../project/paths"
-import type { CompileEntry } from "./projectCompile"
-
-/*
- * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
- * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
- * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
- * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
- * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
- * (--png/--clip/--script/--device/…) against the project's real imports and assets.
- *
- * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
- */
-
-/** Extensions a screen module may carry (so `render design/screens/login` works too). */
-const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
-
-/** Where the generated entry lives — the project root, so its import specifier is the screen's
- *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
-const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
-
-/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
-const DEFAULT_DESIGN_DIR = "design"
-
-export type ScreenTarget = {
-  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
-  entry: CompileEntry
-  /** Path of that entry, for `entryOverride`. */
-  entryPath: string
-  /** The board frame from the design folder's meta.json, when this IS a design screen. */
-  frame?: [number, number]
-  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
-  label: string
-}
-
-/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
-
-/** Whether the argument names a path at all (vs a bare screen id). */
-const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
-
-/** Find the screen file: a path (with or without extension), or a bare id resolved against the
- *  design folder's screens/ (`lecodes render login`, honoring --dir). */
-const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
-  const candidates = [resolve(process.cwd(), file)]
-  if (!hasSeparator(file)) {
-    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
-  }
-  for (const base of candidates) {
-    if (existsSync(base) && statSync(base).isFile()) return base
-    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
-  }
-  throw new CliError(
-    `No screen file at "${file}".` +
-    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
-}
-
-/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
- *  or null when it isn't laid out as a design screen. */
-const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
-  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
-  if (!m) return null
-  const dir = join(root, m[1])
-  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
-}
-
-/**
- * Resolve `<file>` into the virtual entry that opens its default export.
- * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
- */
-const resolveScreenTarget = (
-  root: string, file: string, opts: { state?: string, dir?: string } = {},
-): ScreenTarget => {
-  const abs = findScreenFile(root, file, opts.dir)
-  const rel = relative(root, abs)
-  if (rel.startsWith("..") || isAbsolute(rel)) {
-    throw new CliError(
-      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
-      `imports and asset() files resolve from the same tree.`)
-  }
-  const key = toKey(rel)
-
-  // A file with no default export compiles to an empty render; say so here instead.
-  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
-    throw new CliError(
-      `${key.slice(1)} has no default export. A screen file ends with ` +
-      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
-  }
-
-  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
-  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
-  // as-is, and either way the screen is opened so the runtime has something to render.
-  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
-  const spec = "." + key.replace(/\.[^./]+$/, "")
-  const design = designDirOf(root, key)
-  return {
-    entryPath: SCREEN_ENTRY_PATH,
-    entry: {
-      path: SCREEN_ENTRY_PATH,
-      type: "text",
-      text: `import screen from ${JSON.stringify(spec)}\n`
-        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
-        + `__screen.open()\n`,
-    },
-    frame: design ? screenFrame(design.dir, design.id) : undefined,
-    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
-  }
-}
-
-/** The screen target named on the command line (`render <file>`), or undefined when no screen was
- *  named. Rejects the flag combinations that would fight over the entrypoint. */
-export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
-export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
-  if (a.file === undefined) {
-    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
-    return undefined
-  }
-  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
-  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
-}
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { isAbsolute, join, relative, resolve } from "node:path"
+import { screenFrame } from "../project/designMeta"
+import { CliError } from "../cli"
+import { toKey } from "../project/paths"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
+ * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
+ * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
+ * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
+ * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
+ * (--png/--clip/--script/--device/…) against the project's real imports and assets.
+ *
+ * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
+ */
+
+/** Extensions a screen module may carry (so `render design/screens/login` works too). */
+const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+
+/** Where the generated entry lives — the project root, so its import specifier is the screen's
+ *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
+const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
+
+/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
+const DEFAULT_DESIGN_DIR = "design"
+
+export type ScreenTarget = {
+  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
+  entry: CompileEntry
+  /** Path of that entry, for `entryOverride`. */
+  entryPath: string
+  /** The board frame from the design folder's meta.json, when this IS a design screen. */
+  frame?: [number, number]
+  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
+  label: string
+}
+
+/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
+
+/** Whether the argument names a path at all (vs a bare screen id). */
+const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
+
+/** Find the screen file: a path (with or without extension), or a bare id resolved against the
+ *  design folder's screens/ (`lecodes render login`, honoring --dir). */
+const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
+  const candidates = [resolve(process.cwd(), file)]
+  if (!hasSeparator(file)) {
+    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
+  }
+  for (const base of candidates) {
+    if (existsSync(base) && statSync(base).isFile()) return base
+    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
+  }
+  throw new CliError(
+    `No screen file at "${file}".` +
+    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
+}
+
+/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
+ *  or null when it isn't laid out as a design screen. */
+const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
+  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
+  if (!m) return null
+  const dir = join(root, m[1])
+  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
+}
+
+/**
+ * Resolve `<file>` into the virtual entry that opens its default export.
+ * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
+ */
+const resolveScreenTarget = (
+  root: string, file: string, opts: { state?: string, dir?: string } = {},
+): ScreenTarget => {
+  const abs = findScreenFile(root, file, opts.dir)
+  const rel = relative(root, abs)
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new CliError(
+      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
+      `imports and asset() files resolve from the same tree.`)
+  }
+  const key = toKey(rel)
+
+  // A file with no default export compiles to an empty render; say so here instead.
+  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
+    throw new CliError(
+      `${key.slice(1)} has no default export. A screen file ends with ` +
+      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
+  }
+
+  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
+  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
+  // as-is, and either way the screen is opened so the runtime has something to render.
+  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
+  const spec = "." + key.replace(/\.[^./]+$/, "")
+  const design = designDirOf(root, key)
+  return {
+    entryPath: SCREEN_ENTRY_PATH,
+    entry: {
+      path: SCREEN_ENTRY_PATH,
+      type: "text",
+      text: `import screen from ${JSON.stringify(spec)}\n`
+        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
+        + `__screen.open()\n`,
+    },
+    frame: design ? screenFrame(design.dir, design.id) : undefined,
+    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
+  }
+}
+
+/** The screen target named on the command line (`render <file>`), or undefined when no screen was
+ *  named. Rejects the flag combinations that would fight over the entrypoint. */
+export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
+export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
+  if (a.file === undefined) {
+    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
+    return undefined
+  }
+  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
+  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
+}

package/src/declarations/lecodes-headless.d.ts

@@ -27,6 +27,8 @@ declare module "lecodes-headless/headless" {
     /** Canned `_creatorFetch.fetch` responses (URL pattern → { status?, json?, text? }); they beat
      *  every other fetch path, including waitNetwork. */
     fixtures?: Fixtures
+    /** Native views drawn as a placeholder: view name → the label drawn in its box. */
+    nativeViews?: Record<string, string>
   }
   export type FetchFixture = { status?: number, json?: unknown, text?: string }
   export type Fixtures = Record<string, FetchFixture>

package/src/dev/backendWorker.ts

@@ -17,9 +17,9 @@ import type { FromWorker, LogLevel, ToWorker } from "./localBackend"
  * a new process, so nothing of the old code (its timers, its module state) outlives it.
  *
  * The database is marcidb's embedded engine (the peer marcidb-embedded), opened here, in the
- * directory the parent names. The schema is synced on every load, the way the runner syncs a draft
- * slot: what the models no longer have is dropped; a change the engine can't migrate in place moves
- * the old database aside and starts an empty one.
+ * directory the parent names. The schema is synced on every load, more freely than the runner does
+ * (this is the developer's own machine): what the models no longer have is dropped; a change the
+ * engine can't migrate in place moves the old database aside and starts an empty one.
  */
 
 type Embedded = {

package/src/plugin/contract.ts

@@ -11,8 +11,11 @@
 // `ts` is passed in: the CLI has no TypeScript of its own and loads the plugin repo's.
 
 import type tsModule from "typescript"
+import { PERMISSION_KINDS, isPermissionKind, type PermissionKind } from "./permissions"
 
-export type Scalar = "i32" | "f64" | "boolean" | "string" | "bytes" | "file" | "json" | "void"
+/** `entity` / `scene3d`: the app's 3D Node / Scene, on the wire their u32 ids (`Entity` / `Scene3D` of
+ *  lecodes-sdk/plugin — a half drives them through the host's gl facade). */
+export type Scalar = "i32" | "f64" | "boolean" | "string" | "bytes" | "file" | "json" | "entity" | "scene3d" | "void"
 
 export type Type =
   | { kind: Scalar }
@@ -46,8 +49,10 @@ export type Method = {
   result: Type
   /** The contract version that added it (`@since`), 1 when untagged. */
   since: number
-  /** The codes the call can fail with (`@rejects`). */
+  /** The codes the call can fail with (`@rejects`; `denied` is added for a method with a permission). */
   rejects: string[]
+  /** The OS permissions the call needs (`@permission`): the native glue asks before the call. */
+  permissions: PermissionKind[]
   doc: string
   line: number
 }
@@ -91,12 +96,12 @@ export class ContractError extends Error {
 /** The module a contract imports its vocabulary from, and the names it may take. */
 export const CONTRACT_MODULE = "lecodes-sdk/plugin"
 const MARKERS: Record<string, Channel["kind"]> = { View: "view", Service: "service" }
-const VOCABULARY: Record<string, Scalar> = { i32: "i32", f64: "f64", File: "file", Json: "json" }
+const VOCABULARY: Record<string, Scalar> = { i32: "i32", f64: "f64", File: "file", Json: "json", Entity: "entity", Scene3D: "scene3d" }
 
 /** Names a contract may not declare: the generated code of every language would shadow a global. */
 const RESERVED = new Set([
-  "Array", "Boolean", "Date", "Error", "File", "Function", "Json", "Map", "Number", "Object", "Promise", "Record",
-  "Service", "Set", "String", "Symbol", "Uint8Array", "View",
+  "Array", "Boolean", "Date", "Entity", "Error", "File", "Function", "Json", "Map", "Number", "Object", "Promise", "Record",
+  "Scene3D", "Service", "Set", "String", "Symbol", "Uint8Array", "View",
   // What a native half's generated file names: the types of Swift and Kotlin, the host's support types.
   "Any", "Bool", "Data", "Double", "Int", "Int32", "List", "Pair", "Triple", "Unit", "Void",
   "NoCode", "PluginFile", "Reply", "Wire",
@@ -112,7 +117,7 @@ const KEYWORDS = new Set([
 /** Members of the wrapper's bases a method would replace. */
 const TAKEN = new Set(["call", "on", "off", "open", "close", "destroy", "style", "constructor"])
 
-const TAGS = new Set(["since", "rejects"])
+const TAGS = new Set(["since", "rejects", "permission"])
 
 export const readContract = (ts: typeof tsModule, file: string, text: string): Contract => {
   const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)
@@ -157,9 +162,10 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
     const docs = ts.getJSDocCommentsAndTags(n).filter(ts.isJSDoc)
     return docs.map(d => ts.getTextOfJSDocComment(d.comment) ?? "").filter(Boolean).join("\n").trim()
   }
-  const tagsOf = (n: tsModule.Node): { since: number, rejects: string[] } => {
+  const tagsOf = (n: tsModule.Node): { since: number, rejects: string[], permissions: PermissionKind[] } => {
     let since = 1
     const rejects: string[] = []
+    const permissions: PermissionKind[] = []
     for (const tag of ts.getJSDocTags(n)) {
       const name = tag.tagName.text
       const value = (ts.getTextOfJSDocComment(tag.comment) ?? "").trim()
@@ -167,6 +173,13 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
       if (name === "since") {
         if (!/^[1-9]\d*$/.test(value)) fail(tag, `@since takes a contract version: a whole number from 1 (got "${value}")`)
         else since = Number(value)
+      } else if (name === "permission") {
+        const kinds = value.split(/[\s,]+/).filter(Boolean)
+        if (kinds.length === 0) fail(tag, `@permission names the OS permissions the call needs: ${PERMISSION_KINDS.join(", ")}`)
+        for (const kind of kinds) {
+          if (!isPermissionKind(kind)) fail(tag, `@permission: "${kind}" is not a permission (one of ${PERMISSION_KINDS.join(", ")})`)
+          else if (!permissions.includes(kind)) permissions.push(kind)
+        }
       } else {
         const codes = value.split(/[\s,]+/).filter(Boolean)
         if (codes.length === 0) fail(tag, "@rejects lists the codes a call can fail with")
@@ -176,7 +189,7 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
         }
       }
     }
-    return { since, rejects }
+    return { since, rejects, permissions }
   }
 
   // ---- types ---------------------------------------------------------------------------------------
@@ -323,8 +336,9 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
       if (m.questionToken) fail(m, `${d.name.text}.${name}: an event is not optional`)
       if (events.some(e => e.name === name)) fail(m, `${d.name.text}: "${name}" is declared twice`)
       const payload = m.type.kind === ts.SyntaxKind.VoidKeyword ? VOID : readType(m.type, `${d.name.text}.${name}`)
-      const { since, rejects } = tagsOf(m)
+      const { since, rejects, permissions } = tagsOf(m)
       if (rejects.length) fail(m, `${d.name.text}.${name}: an event rejects nothing`)
+      if (permissions.length) fail(m, `${d.name.text}.${name}: an event needs no permission — the method that starts it does`)
       events.push({ name, payload, since, doc: docOf(m), line: lineOf(m) })
     }
     return events
@@ -358,7 +372,10 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
       if (!promised) fail(m, `${where}: a call crosses to the host and back — it returns Promise<…>`)
       else if (promised.kind !== ts.SyntaxKind.VoidKeyword) result = readType(promised, `${where}()`)
 
-      methods.push({ name, args, result, ...tagsOf(m), doc: docOf(m), line: lineOf(m) })
+      const tags = tagsOf(m)
+      // A gated call fails with `denied` before the plugin's code: the code is the tag's, not the author's to list.
+      if (tags.permissions.length && !tags.rejects.includes("denied")) tags.rejects.unshift("denied")
+      methods.push({ name, args, result, ...tags, doc: docOf(m), line: lineOf(m) })
     }
     return methods
   }
@@ -399,8 +416,8 @@ export const readContract = (ts: typeof tsModule, file: string, text: string): C
     }
     const events = eventsDecl ? readEvents(eventsDecl) : []
     const methods = readMethods(d)
-    const { since, rejects } = tagsOf(d)
-    if (since !== 1 || rejects.length) fail(d.name, `${iface}: @since and @rejects tag a method or an event, not the channel`)
+    const { since, rejects, permissions } = tagsOf(d)
+    if (since !== 1 || rejects.length || permissions.length) fail(d.name, `${iface}: @since, @rejects and @permission tag a method (or @since an event), not the channel`)
     channels.push({
       kind: marker.kind, name, iface,
       params: paramsDecl ? readFields(paramsDecl.members, paramsDecl.name.text) : [],

package/src/plugin/emitKotlin.ts

@@ -7,8 +7,8 @@
 //   - `<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
+// It stands on the host SDK's PluginChannel.kt (Reply, PluginFile, Wire), its gl facade's Entity /
+// Scene3D (scene/GL.kt) 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.
@@ -54,6 +54,8 @@ export const kotlinType = (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 "ByteArray"
     case "void": return "Unit"
     case "enum": case "struct": case "union": return t.name
@@ -78,6 +80,8 @@ const decode = (t: L, depth = 0): string[] => {
     case "json": return [`r.json()`]
     case "bytes": return [`r.bytes()`]
     case "file": return [`Wire.file(r)`]
+    case "entity": return [`Entity.read(r)`]
+    case "scene3d": return [`Scene3D.read(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), `}`)
@@ -105,7 +109,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}.wire)`]
-    case "file": case "struct": case "union": return [`${e}.write(${w})`]
+    case "file": case "entity": case "struct": case "union": return [`${e}.write(${w})`]
+    case "scene3d": throw new EmitError("a Scene3D crosses from the app to the host only")
     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()`]
@@ -242,7 +247,11 @@ const emitChannel = (ch: LChannel): string => {
   // ---- 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")
+    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(constName).join(" / ")}.` : "",
+    ].filter(Boolean).join("\n")
     return `${doc(tags, "    ")}    fun ${ident(m.name)}(${args.join(", ")})`
   })
   out.push([
@@ -258,6 +267,8 @@ const emitChannel = (ch: LChannel): string => {
   ].join(""))
 
   // ---- registration ----
+  const gated = ch.methods.some(m => m.permissions.length > 0)
+  const glueArgs = gated ? "plugin, engine.permissions, " : "plugin, "
   out.push([
     `object ${iface}Channel {\n`,
     `    /** What the halves register under. */\n    const val NAME = ${str(ch.name)}\n\n`,
@@ -269,8 +280,8 @@ const emitChannel = (ch: LChannel): string => {
     `        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`,
+      ? `            NativeViews.Instance(plugin.view, onCall = { call -> ${iface}Glue.call(${glueArgs}call.method, call.reader(), call) }, onDestroy = { plugin.destroy() })\n`
+      : `            Services.Instance(onCall = { call -> ${iface}Glue.call(${glueArgs}call.method, call.reader(), call) }, onClose = { plugin.close() })\n`,
     `        }\n    }\n}\n`,
   ].join(""))
 
@@ -295,13 +306,24 @@ const emitChannel = (ch: LChannel): string => {
         // 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, `)`))
+    if (m.permissions.length) {
+      // The gate: the host's permission service, then the plugin — or DENIED without it.
+      lines.push(...wrap(`val reply = `, reply, ``))
+      lines.push(
+        `permissions.ensure(listOf(${m.permissions.map(k => `Permissions.Kind.${k.toUpperCase()}`).join(", ")})) { granted ->`,
+        `    if (!granted) reply.reject(${code}.DENIED)`,
+        `    else 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 `            ${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`,
+    `    fun call(plugin: ${iface}Plugin, ${gated ? "permissions: Permissions, " : ""}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(""))
@@ -321,9 +343,12 @@ const IMPORTS: [string, string][] = [
   ["ChannelSettle", "io.letary.lecodes.services.ChannelSettle"],
   ["NativeViews", "io.letary.lecodes.services.NativeViews"],
   ["NoCode", "io.letary.lecodes.services.NoCode"],
+  ["Permissions", "io.letary.lecodes.services.Permissions"],
   ["PluginCode", "io.letary.lecodes.services.PluginCode"],
   ["PluginEmit", "io.letary.lecodes.services.PluginEmit"],
   ["PluginFile", "io.letary.lecodes.services.PluginFile"],
+  ["Entity", "io.letary.lecodes.scene.Entity"],
+  ["Scene3D", "io.letary.lecodes.scene.Scene3D"],
   ["Reply", "io.letary.lecodes.services.Reply"],
   ["Services", "io.letary.lecodes.services.Services"],
   ["Wire", "io.letary.lecodes.services.Wire"],

package/src/plugin/emitPackage.ts

@@ -0,0 +1,98 @@
+// A plugin repo's `Package.swift`, from the manifests: the plugins with an iOS half as ONE SwiftPM
+// package — a target per plugin (its sources `plugins/<id>/ios`, the packages its manifest names)
+// and a product per plugin. Each plugin is its own MODULE, so two plugins may declare a type of the
+// same name, and an Xcode project links a plugin as a product instead of compiling its folder.
+//
+// The targets depend on the LeCodes SDK as a package on disk: `LECODES_IOS_SDK_PATH`, else the path
+// the repo's package.json names (`lecodes.iosSdkPath`), else the sibling `../lecodes` (a checkout
+// of the published SDK package, or whatever stands there).
+//
+// A shell made by `lecodes app sync` does NOT use this package: it vendors the sources into targets
+// of its own (templates/ios.ts), pinned by plugins.lock.json.
+
+import type { PluginManifest } from "./manifest"
+import { pascal } from "./manifest"
+
+export class PackageError extends Error {}
+
+/** A package's identity from its URL (`https://github.com/stasel/WebRTC` → `WebRTC`): what SwiftPM
+ *  names it in `.product(name:package:)`. The same rule as the shell's (commands/app/shared.ts). */
+export const swiftPackageName = (url: string): string =>
+  (url.replace(/\/+$/, "").split("/").pop() ?? url).replace(/\.git$/, "")
+
+/** The Swift module of a plugin's iOS half: the manifest's, or `LeCodes` + the id in PascalCase. */
+export const iosModule = (id: string, manifest: PluginManifest): string => manifest.ios?.module ?? `LeCodes${pascal(id)}`
+
+export const PACKAGE_FILE = "Package.swift"
+
+/** Where the SDK package stands when neither the environment nor the repo says: a sibling checkout. */
+export const DEFAULT_SDK_PATH = "../lecodes"
+
+/** The text of the repo's Package.swift for `plugins` (every manifest; those without an iOS half are
+ *  left out); `sdkPath` is the repo's own SDK location (package.json `lecodes.iosSdkPath`). Throws
+ *  PackageError when two plugins pin one package at different versions. */
+export const emitPackageSwift = (plugins: { id: string, manifest: PluginManifest }[], sdkPath: string = DEFAULT_SDK_PATH): string => {
+  const ios = plugins.filter(p => p.manifest.ios !== null)
+  const packages = new Map<string, { url: string, exact?: string, from?: string, by: string }>()
+  for (const p of ios) {
+    for (const pkg of p.manifest.ios!.packages ?? []) {
+      const prior = packages.get(pkg.url)
+      if (prior && (prior.exact !== pkg.exact || prior.from !== pkg.from)) {
+        throw new PackageError(`"${p.id}" pins ${pkg.url} at ${pkg.exact ?? `from ${pkg.from}`} but "${prior.by}" pins ${prior.exact ?? `from ${prior.from}`} — one package resolves once`)
+      }
+      if (!prior) packages.set(pkg.url, { ...pkg, by: p.id })
+    }
+  }
+  const moduleOf = (p: { id: string, manifest: PluginManifest }) => iosModule(p.id, p.manifest)
+
+  const products = ios.map(p => `        .library(name: "${moduleOf(p)}", targets: ["${moduleOf(p)}"]),`)
+  const dependencies = [
+    `        .package(name: "lecodes", path: sdk),`,
+    ...[...packages.values()].map(pkg => `        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`),
+  ]
+  const targets = ios.map(p => {
+    const deps = [
+      `.product(name: "LeCodes", package: "lecodes")`,
+      ...(p.manifest.ios!.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
+    ]
+    return [
+      `        // ${p.id}`,
+      `        .target(`,
+      `            name: "${moduleOf(p)}",`,
+      `            dependencies: [${deps.join(", ")}],`,
+      `            path: "plugins/${p.id}/ios"`,
+      `        ),`,
+    ].join("\n")
+  })
+
+  return `// swift-tools-version:5.9
+// GENERATED by \`lecodes plugin gen\` from the plugins' manifests (lecodes-plugin.json) — do not edit.
+//
+// The plugins with an iOS half as ONE SwiftPM package: a target per plugin (its sources in
+// plugins/<id>/ios, the packages its manifest names) and a product per plugin. Each plugin is its
+// own module: an Xcode project links a plugin as a product instead of compiling its folder, and two
+// plugins may name a type alike.
+//
+// The SDK is the LeCodes package on disk: LECODES_IOS_SDK_PATH, else the path below (the repo's
+// package.json \`lecodes.iosSdkPath\`, or the sibling ../lecodes). A shell made by \`lecodes app sync\`
+// does not use this package: it vendors the sources into targets of its own, pinned by
+// plugins.lock.json.
+import PackageDescription
+
+let sdk = Context.environment["LECODES_IOS_SDK_PATH"] ?? ${JSON.stringify(sdkPath)}
+
+let package = Package(
+    name: "lecodes-plugins",
+    platforms: [.iOS(.v15)],
+    products: [
+${products.join("\n")}
+    ],
+    dependencies: [
+${dependencies.join("\n")}
+    ],
+    targets: [
+${targets.join("\n")}
+    ]
+)
+`
+}