lecodes-cli 2.2.9 → 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/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("")