lecodes-sdk 2.0.7 → 2.0.9

package/package.json

@@ -42,9 +42,10 @@
     "@types/node": "^25.9.1",
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4",
-    "marcidb-embedded": "^0.13.0"
+    "marcidb-embedded": "^0.14.1",
+    "sharp": "^0.35.2"
   },
-  "version": "2.0.7",
+  "version": "2.0.9",
   "files": [
     "src",
     "dist",

package/prompts/3d-scene-files.md

@@ -66,10 +66,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -107,7 +107,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/prompts/3d-scene.md

@@ -114,6 +114,6 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>

package/prompts/dist/3d-app.md

@@ -775,8 +775,8 @@ const hud = UIWidget(
     scoreLabel = UIText('Score: 0').style({ color: 'white', fontSize: 24, fontWeight: 700 }),
 ).style({ top: 'max(safe-top, 16px)', right: 16 })
 
+scene.setContent([hud])
 scene.open()
-hud.attachTo(scene).show()
 </file>
 
 ## Scene files (.scene.ts)
@@ -847,10 +847,10 @@ export class Spinner extends Aspect<'spinner'> {
 // ===== UI OVER AN OPEN SCENE =====
 
 // Exactly one Presentable is visible at a time: UIScreen(...).open() REPLACES the scene. A HUD is
-// a UIWidget attached to the scene — it shows/hides and transitions together with it:
+// a UIWidget that is the scene's CONTENT — it shows and hides together with it:
 const hud = UIWidget(UIText('Score: 0').style({ color: 'white', fontSize: 24 }))
     .style({ top: 'max(safe-top, 16px)', left: 16 })
-hud.attachTo(scene).show()
+scene.setContent([hud])
 
 // ===== SCENE FILE MISTAKES — DO NOT DO THESE =====
 
@@ -888,7 +888,7 @@ const { scene, nodes } = await mainScene.open()
 
 let taps = 0
 const label = UIText('Tap the crate').style({ color: 'white', fontSize: 20, fontWeight: 700 })
-UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 }).attachTo(scene).show()
+scene.setContent([UIWidget(label).style({ top: 'max(safe-top, 16px)', left: 16 })])
 
 nodes.crate.addEventListener('click', () => { label.text = `Taps: ${++taps}` })
 </file>

package/src/bridges/gl.d.ts

@@ -95,6 +95,11 @@ declare global {
     /** Punctual light. `intensity` is luminous POWER in lumens; `falloff` is the metres of
      *  influence (filament's own default is 1 m, i.e. invisible, so it is always passed). */
     createPointLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, castShadows: boolean): void
+    /** Spot light: the point light's lumens and falloff in a cone along the entity's local -Z. `inner` / `outer` are
+     *  HALF-angles in radians (outer ≤ π/2); the cone does not change the brightness. Real time only (the bake skips it). */
+    createSpotLight?(entityId: u32, intensity: f64, color: u32, falloff: f64, inner: f32, outer: f32, castShadows: boolean): void
+    /** A spot light's cone, live — half-angles in radians, as createSpotLight. */
+    setLightCone?(entityId: u32, inner: f32, outer: f32): void
     /** The lightmap bake takes this point light as a RECTANGLE of `width` x `height` metres (an area light: a ceiling
      *  panel) in the light's local XZ plane, emitting along its local -Y with the same lumens; 0, 0 = a point again. */
     setLightBakeArea?(entityId: u32, width: f32, height: f32): void

package/src/bridges/tree.d.ts

@@ -112,10 +112,20 @@ declare global {
     isViewSupported(name: string): boolean
     viewVersion(name: string): i32
     viewCall(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-    // Show a widget root; `ownerKind` / `ownerId` bind it to a destination (widget.attachTo: it
-    // mounts inside that page and rides its transition) — TREE_DEST_NONE = a global overlay.
-    showWidget(id: TreeNodeId, ownerKind: u8, ownerId: f64): void
-    hideWidget(id: TreeNodeId): void
+    // ---- widgets (docs/plans/widgets-plan.md): a widget is a CHILD — of a screen root, of a
+    //      destination's content layer, of the app layer — never a root of its own; `insert` /
+    //      `remove` place it, `display` shows it, the runtime lays it out in the outermost presented
+    //      destination's box (the portal) and mounts it under that root for the host. ------------
+    // The content LAYER of a destination: a "layer" root (a pass-through root laid out at the frame,
+    // shown while the destination is presented) whose widget children are the surface's UI — a HUD
+    // over a scene, a card over a map. `kind` TREE_DEST_NONE (id 0) = the APP layer, above every
+    // destination, always shown. 0 takes the layer away.
+    setLayer(kind: u8, id: f64, layer: TreeNodeId): void
+    // The pose a widget child enters from and leaves to: a transition id (defineTransition) whose
+    // ALONE roles the runtime plays as tracks on the widget when its resolved `display` flips —
+    // `none → flex` from the enter pose to rest, `flex → none` from rest to the exit pose, `none`
+    // taking effect when the tracks land. TRANSITION_NONE = no pose (the flip is instant).
+    setWidgetPose(id: TreeNodeId, transition: i32): void
 
     // ---- pager (a "pager" node's children are its pages; TAB-MAJOR order, `lens` = per-tab stack
     //      lengths, `index` = the selected tab). A change of the current tab's stack plays a
@@ -251,11 +261,16 @@ export interface HostUI {
    *  call's arguments, valid for the call. Settle exactly one of the two callbacks through the
    *  dispatch bridge — `onComplete` with the result as ONE value, or with none. */
   viewCall?(viewId: i32, method: string, args: value, onComplete: (result?: value) => void, onReject: (message: string) => void): void
-  /** Show a widget root: `ownerKind` = TREE_DEST_* (0xFF = a global overlay), `ownerId` = the sceneId /
-   *  viewId of a scene / native owner (0 for a screen), `ownerNode` = the owner screen's root (a
-   *  screen destination or a pager page) — 0 otherwise. */
-  widgetOpen(node: nodeid, ownerKind: u8, ownerId: i32, ownerNode: nodeid): void
-  widgetClose(node: nodeid): void
+  /** A LAYER root is shown: a pass-through root the runtime lays out at the frame, above every
+   *  destination (the app layer) or over the presented surface (a scene's / a native view's / a
+   *  video's content layer). Its own box is never hit — only its children are — so a touch outside
+   *  them reaches what is under the layer; it is painted after the destination, layers in open
+   *  order. Its children are widgets (the runtime inserts them with insertNode, as under a screen
+   *  root): a widget child with an overlay layer (`overlayColor`, any color — "transparent" too)
+   *  intercepts every touch outside its own box within its root and reports it as the overlay tap. */
+  layerOpen(node: nodeid): void
+  /** The layer root is hidden (its view stays; releaseNode says when it is gone). */
+  layerClose(node: nodeid): void
   /** Load a font face for `fontFamily` (weight 100–900, style 0 normal / 2 italic) from `url`; settle
    *  one of the callbacks through the dispatch bridge. */
   registerFont(url: string, fontFamily: string, weight: i32, style: i32, onComplete: () => void, onReject: (err: string) => void): void
@@ -289,9 +304,6 @@ export interface HostUI {
    *  a child (covered by a push, a keepAlive page); a page that is released goes through
    *  removeNode right after. */
   pagerDropPage?(node: nodeid, page: nodeid): void
-  /** A pager page root (`page`) was mounted under the pager or released (an attachTo widget names the
-   *  page node as its owner). */
-  pagerPageMounted?(page: nodeid, mounted: boolean): void
   /** Optional: the host may PLAY a UI tween track itself — a platform animation interpolating on its
    *  own clock (Core Animation on iOS) instead of one style write per runtime frame. `samples` holds
    *  the track evaluated at even points of its length, easing included, `lanes` floats each: 1 for a

package/src/chisel.ts

@@ -129,7 +129,7 @@ export const chiselVocab: ChiselVocab = {
       "onSelect", "onChange", "onFocus", "onBlur", "onOverlayTap", "onDetent",
       "onEndReached", "onStartReached",
       "append", "insert", "remove", "setContent", "keepAlive", "url",
-      "attachTo", "detents", "dismissible", "transition", "setSourceRect",
+      "detents", "dismissible", "transition", "setSourceRect",
       "push", "pop", "popToRoot", "replace", "select",
       // UITabs / UIVirtualizedList / the native views (NativeView, CameraView, MapView, QRScanner)
       "badge", "setData", "update", "prepend", "removeByKey",

package/src/compile/libraryImports.ts

@@ -31,6 +31,15 @@ export const rewriteLibraryImports = (src: string, slugs: Set<string>): string =
     if (isRelativeOrAbsolute(spec)) return spec
     const slash = spec.indexOf("/")
     const slug = slash === -1 ? spec : spec.slice(0, slash)
+    // The SDK's plugin bases (`lecodes-sdk/plugin`: ServiceChannel, ViewChannel — what a plugin's
+    // generated wrapper extends): the one SDK module a PROJECT file may import, because a plugin of
+    // the project itself (`plugins/<id>/sdk/<id>.gen.ts`, written by `lecodes plugin gen`) lives in
+    // the project tree and not in the SDK. It is the SDK's own module under /__sdk, the same instance
+    // the vendored first-party wrappers reach by relative path. Anything else of the SDK is a global.
+    if (slug === "lecodes-sdk") {
+      if (spec === "lecodes-sdk/plugin" || spec.startsWith("lecodes-sdk/plugin/")) return `/__sdk${spec.slice("lecodes-sdk".length)}`
+      throw new Error(`import from "${spec}": the SDK needs no imports — its API is globals; only "lecodes-sdk/plugin" (a plugin wrapper's bases) is imported.`)
+    }
     if (slugs.has(slug)) {
       // `acme-ui` → `/__lib/acme-ui/index`; `acme-ui/theme` → `/__lib/acme-ui/theme`.
       const sub = slash === -1 ? "/index" : spec.slice(slash)

package/src/compile/serverTypes.ts

@@ -127,6 +127,8 @@ const wrongSideGlobals = (ts: TS, program: import("typescript").Program, checker
   return out
 }
 
+const FILE_TYPE_PATH = "/__lecodes/file.d.ts"
+
 export type DeriveResult = {
   /** endpoint id → parameter schemas (only endpoints the checker could see). */
   params: Record<string, ParamSchema[]>
@@ -152,6 +154,9 @@ export const deriveEndpointParams = async (entries: CompileEntry[], modules: Rec
     if (!/\.[tj]sx?$/.test(e.path)) continue
     files.set(normalizePath(e.path), e.text)
   }
+  // The one SDK type this program knows: a parameter typed `File` is an upload, and has to be told
+  // from "some object". A declaration of the type alone — as a value the name stays unknown here.
+  files.set(FILE_TYPE_PATH, "interface File { readonly __lecodesFile: true, readonly name: string, readonly size: number, readonly type: string }\n")
   // the server modules, and every other file of the project: the app's are read for the globals they use
   const roots = [...new Set([...Object.keys(modules).map(normalizePath).filter(p => files.has(p)), ...files.keys()])]
 
@@ -346,6 +351,7 @@ const lower = (ts: TS, checker: import("typescript").TypeChecker, type: import("
   }
   if (f & T.Union) return lowerMembers(ts, checker, (type as import("typescript").UnionType).types, where, stack)
   if (f & T.Intersection || f & T.Object) {
+    if (type.getProperty("__lecodesFile")) return { t: "file" }
     if (stack.has(type)) throw new Error(`${where}: recursive type ${checker.typeToString(type)}`)
     if (type.getCallSignatures().length || type.getConstructSignatures().length) throw new Error(`${where}: functions are not JSON`)
     stack.add(type)

package/src/g2/Scene2D.ts

@@ -6,6 +6,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE2D, ensureEmitter, registerDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { cx, cy, type Vec2Like } from "../math/vec"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import { Camera2D } from "./Camera2D"
@@ -188,6 +189,15 @@ export class Scene2D implements Presentable {
     registerDest(TREE_DEST_SCENE2D, this.id, this)
     return [TREE_DEST_SCENE2D, this.id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */

package/src/gl/Light.ts

@@ -1,4 +1,4 @@
-// Lights. A directional sun (the engine's primary light) and punctual point lights. Add one to a
+// Lights. A directional sun (the engine's primary light), punctual point lights and spot lights. Add one to a
 // scene like any node; `intensity` and `color` stay writable so a light can be animated.
 
 import { Color, type ColorInput } from "../core/color"
@@ -80,6 +80,24 @@ export type PointOptions = {
   bakeArea?: readonly [number, number]
 }
 
+export type SpotOptions = {
+  /**
+   * Luminous power in lumens, as a point light's. The cone does not change the brightness: widen it and the
+   * same lumens light a larger patch at the same level. On its axis a spot is 4x brighter than a point light of
+   * the same lumens (its light is not spread over the whole sphere). Default 1000.
+   */
+  intensity?: number
+  color?: ColorInput
+  /** Metres of influence along the cone, the performance knob as for a point light. Default 10. */
+  range?: number
+  /** The cone's full angle in degrees, up to 180: past it the light contributes nothing. Default 45. */
+  angle?: number
+  /** The full angle in degrees of the cone's fully lit core; the light fades from it out to `angle`. Default 0.75 x `angle`. */
+  innerAngle?: number
+  /** A spot's shadow is one 2D shadow map (a point light's is a cubemap); off by default. */
+  castShadows?: boolean
+}
+
 export class Light extends Node {
   private _intensity = 0
 
@@ -159,7 +177,65 @@ export class Light extends Node {
   /** Whether this host can create point lights at all. */
   static get supportsPoint(): boolean { return _creator.createPointLight !== undefined }
 
-  /** Live intensity (sun: lux, point: lumens) — animate a flash without rebuilding the light. */
+  /** @internal a spot's cone, full angles in degrees (the engine takes half-angles in radians). */
+  _angle = 0
+  _innerAngle = 0
+
+  /**
+   * A spot light — a flashlight, a headlight, a stage light. It shines along the node's forward (-Z): position
+   * it like any node and aim it with `lookAt`. Real time only: the lightmap bake takes no spot lights, so a spot
+   * lights the baked statics live too.
+   *
+   * Feature-detected like `Light.point`: on a host without it the node exists and lights nothing
+   * (`Light.supportsSpot`).
+   */
+  static spot(options: SpotOptions = {}): Light {
+    const light = new Light()
+    light._intensity = options.intensity ?? 1000
+    light._color = options.color ?? 0xffffff
+    light._baked = false
+    light._angle = options.angle ?? 45
+    light._innerAngle = options.innerAngle ?? light._angle * 0.75
+    const [ inner, outer ] = light._cone()
+    _creator.createSpotLight?.(
+      light.id,
+      light._intensity,
+      Color.toPackedRgb(light._color),
+      options.range ?? 10,
+      inner, outer,
+      options.castShadows ?? false,
+    )
+    // the statics of a lightmapped level are on Filament channel 1 alone (see Lightmap)
+    _creator.setLightChannel?.(light.id, 1, true)
+    return light
+  }
+
+  /** Whether this host can create spot lights. */
+  static get supportsSpot(): boolean { return _creator.createSpotLight !== undefined }
+
+  /** @internal the cone as the engine takes it: half-angles in radians, outer in (0, 90°], inner in [0, outer]. */
+  _cone(): [number, number] {
+    const rad = Math.PI / 360
+    const outer = Math.min(Math.max(this._angle, 0.1), 180) * rad
+    const inner = Math.min(Math.max(this._innerAngle, 0), this._angle) * rad
+    return [ Math.min(inner, outer), outer ]
+  }
+
+  /** A spot's full cone angle in degrees — live (a flashlight's focus). */
+  get angle(): number { return this._angle }
+  set angle(value: number) {
+    this._innerAngle *= this._angle > 0 ? value / this._angle : 0
+    this._angle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+  /** A spot's fully lit core, full angle in degrees — live. Setting `angle` scales it along. */
+  get innerAngle(): number { return this._innerAngle }
+  set innerAngle(value: number) {
+    this._innerAngle = value
+    _creator.setLightCone?.(this.id, ...this._cone())
+  }
+
+  /** Live intensity (sun: lux, point / spot: lumens) — animate a flash without rebuilding the light. */
   get intensity(): number { return this._intensity }
   set intensity(value: number) {
     this._intensity = value

package/src/gl/Material.ts

@@ -187,6 +187,9 @@ export class Material {
     } else if ("_h" in (shader as any)) {
       this.shader = shader as FetchResponse
       this._h = _creator.createMaterial((shader as any)._h.id)   // owned: dropped and unused → freed
+      // 0xFFFFFFFF = the engine refused the package: no shader in it for the running backend (a
+      // phone on Vulkan handed the mobile `_opengl` artifact — the host's log names what is missing).
+      if (this._h.id === 0xFFFFFFFF) throw new Error("Material: the engine refused the shader (no variant for its backend — see the host log)")
     } else {
       this.shader = "unknown"
       this._h = shader as Handle           // an instance the runtime already wrapped for us

package/src/gl/Scene.ts

@@ -10,6 +10,7 @@ import { _installAspectFrames, _installTimeScale, _attachSystem, _detachSystem,
 import { _bumpNavEpoch, _navEpoch, _setCurrent, Presentable, type DestTuple, type DismissOptions, type PresentOptions } from "../ui/presentable"
 import { _transitionId, TRANSITION_NONE } from "../ui/transitions"
 import { TREE_DEST_SCENE3D, TREE_FLAG_BACK, ensureEmitter, registerDest, unregisterDest } from "../ui/tree"
+import { _setSurfaceContent, type LayerElement, type UIWidgetContent } from "../ui/UILayer"
 import { device } from "../runtime/device"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
@@ -478,10 +479,19 @@ export class Scene implements Presentable {
 
   /** @internal The destination tuple (ui/presentable.ts). */
   _dest(): DestTuple {
-    // Addressed by the router / an attached widget: make sure the (kind, id) resolves back to us.
+    // Addressed by the router / its content layer: make sure the (kind, id) resolves back to us.
     registerDest(TREE_DEST_SCENE3D, this._id, this)
     return [TREE_DEST_SCENE3D, this._id, "", ""]
   }
+  /** @internal The scene's content layer (ui/UILayer.ts), made by the first setContent. */
+  _contentLayer?: LayerElement
+  /** The UI over the scene — widgets (a HUD, a dialog), laid out over the scene while it is
+   *  presented; touches outside a widget's box reach the scene. `scene.setContent([hud])`. */
+  setContent(content: UIWidgetContent): this {
+    ensureEmitter()
+    _setSurfaceContent(this, content)
+    return this
+  }
   /** @internal presentation lifecycle from the runtime */
   _emitOpen(): void { for (const cb of this.ol.slice()) cb() }
   /** @internal */

package/src/inject.ts

@@ -44,6 +44,7 @@ export { Net, NetPlayer, Replicated, NetEntity, type NetMessage, type NetRole, t
 // only ever imports its server functions (docs/backend-plan.md §4).
 export { __rpc, __channel, __serverOnly, RpcError } from "./runtime/rpc"
 export type { ChannelSubscription } from "./server/channel"
+export type { StoredFile, StoredImage } from "./server/files/models"
 export { AudioPlayer, VideoPlayer } from "./runtime/media"
 // Game audio (docs/audio-plan.md): decoded clips, a voice pool, buses with effects; 3D through the
 // AudioSource / AudioZone aspects (gl/) and scene.audio.
@@ -101,6 +102,7 @@ export {
   UITabs, type UITabDef,
   defineTabs, type TabDef, type TabsHandle,
   UIWidget, type UIWidgetStyle,
+  UIOverlay, type UIWidgetContent,
   UIModal, type UIModalStyle,
   UIBottomSheet, type UIBottomSheetStyle,
   UIPopover, type UIPopoverStyle,

package/src/runtime/rpc.ts

@@ -9,6 +9,8 @@
  *
  * Wire (implemented by the runner):
  *   POST <serverUrl>/api/<id>   body {"args":[…]}, `authorization: Bearer <session>` when known
+ *                               — with a `File` among the arguments: multipart, the field `args` is
+ *                               that JSON with `{"$file": <i>}` where the file stood, `file<i>` the files
  *   → 200 {"ok":true,"result":…,"session"?:"…"} | {"ok":false,"status":n,"message":"…","session"?:"…"}
  *   WS   <serverUrl>/ws  the channel socket — its frames are ./wire.ts
  *
@@ -17,7 +19,7 @@
  * User code never sees it — "am I logged in" is an endpoint (`me()`), see the plan.
  */
 
-import { fetch } from "./fetch"
+import { fetch, File, FormData } from "./fetch"
 import { localStorage } from "./storage"
 import { WebSocket } from "./net"
 import type { ChannelGroup, ClientFrame, ServerFrame } from "./wire"
@@ -64,12 +66,22 @@ export const __rpc = (serverUrl: string, id: string) => {
     // an optional argument left out is `undefined` in its place — JSON has no such value (it would
     // travel as null and fail the parameter's type), and it is the last ones
     while (args.length && args[args.length - 1] === undefined) args.pop()
-    const headers: Record<string, string> = { "content-type": "application/json" }
+    const headers: Record<string, string> = {}
     const session = getSession(serverUrl)
     if (session) headers.authorization = `Bearer ${session}`
+    // a File anywhere among the arguments leaves its place to a marker and travels beside them
+    const files: File[] = []
+    const json = JSON.stringify({ args }, (_key, value) => value instanceof File ? { $file: files.push(value) - 1 } : value)
+    let payload: string | FormData = json
+    if (files.length) {
+      const form = new FormData()
+      form.append("args", json)
+      files.forEach((file, i) => form.append(`file${i}`, file, file.name))
+      payload = form
+    } else headers["content-type"] = "application/json"
     let res
     try {
-      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
+      res = await fetch(`${serverUrl}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: payload })
     } catch (e) {
       throw new RpcError(0, `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})`)
     }

package/src/server/context.ts

@@ -15,6 +15,10 @@ export type RequestContext = {
   sessionToken?: string
   /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
   auth?: unknown
+  /** The files a multipart call carried, as the receiving process left them (./files/host.ts `Upload`). */
+  uploads?: unknown[]
+  /** What `/files/<id>/<name>` is appended to in a stored file's url: the backend's own base, as this request reached it. */
+  filesBase?: string
 }
 
 type Provider = () => RequestContext | undefined

package/src/server/db/defineDb.ts

@@ -8,9 +8,11 @@
  * never sees a connection string.
  */
 
-import type { Field, FieldDef, ScalarKind } from "./fields"
+import { t, type Field, type FieldDef, type ScalarKind } from "./fields"
 import { createAuthApi } from "../auth/api"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityFields, sessionFields } from "../auth/models"
+import { createFileLayer } from "../files/db"
+import { FILE_MODEL, fileFields, fileOwnerKey, type FileField } from "../files/models"
 import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta } from "./marci/query"
 import type { AuthBinding, Db, Fields, Model, Schema, ValidateRefs } from "./types"
 
@@ -63,7 +65,12 @@ const buildMeta = (models: Record<string, Model>): Record<string, ModelMeta> =>
   for (const [name, m] of Object.entries(models)) {
     if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) throw new Error(`defineDb: model name "${name}" must be PascalCase`)
     const fields: Record<string, FieldDef> = {}
-    for (const [key, f] of Object.entries(m.fields as Fields)) fields[key] = { ...(f as Field<any, any>).def }
+    for (const [key, f] of Object.entries(m.fields as Fields)) {
+      const def = (f as Field<any, any>).def
+      if (def.kind === "struct" && Object.values(def.fields!).some(inner => (inner as Field<any, any>).def.kind === "file"))
+        throw new Error(`defineDb: ${name}.${key} — a file belongs to a model's row: put the t.file() field on ${name} itself, not inside a struct`)
+      fields[key] = { ...def }
+    }
     if (fields.id && !fields.id.isId) fields.id.isId = true
     const idKeys = Object.keys(fields).filter(k => fields[k].isId)
     const uuidId = idKeys.length === 1 && idKeys[0] === "id" && fields.id.scalar === "uuid"
@@ -133,6 +140,7 @@ const emitField = (owner: string, key: string, d: FieldDef, extra: string[]): st
     case "one": type = d.model!; break
     case "many": type = `${d.model}[]`; attrs.push(`@bind(${d.model}.${d.back})`); break
     case "list": type = `${d.model}[]`; attrs.push("@list"); break
+    case "file": throw new Error(`${owner}.${key}: a file field is emitted as the relation it stands for`)
   }
   if (d.array && d.kind !== "many" && d.kind !== "list") type += "[]"
   if (d.optional) type += "?"
@@ -164,12 +172,14 @@ export const toMarci = (metas: Record<string, ModelMeta>): string => {
  * model — `key` / `body` scalars, `one` / `many` relations with their target. Structs are pseudo-models
  * (`User.info`) so an empty nested select fills with the struct's own scalars, as marcidb does.
  */
-const modelsMeta = (metas: Record<string, ModelMeta>): ModelsMeta => {
+const modelsMeta = (metas: Record<string, ModelMeta>, isFile: (model: string, key: string) => boolean): ModelsMeta => {
   const out: Record<string, FieldDesc[]> = {}
   const describe = (name: string, fields: Record<string, FieldDef>, implicitId: boolean) => {
     const descs: FieldDesc[] = implicitId ? [{ n: "id", k: "key" }] : []
     for (const [key, d] of Object.entries(fields)) {
-      if (isRel(d)) descs.push({ n: key, k: d.kind === "one" ? "one" : "many", m: d.model! })
+      // a file reads like a scalar: a query without a selection returns it (../files/db.ts makes it the relation select)
+      if (isFile(name, key)) descs.push({ n: key, k: "body" })
+      else if (isRel(d)) descs.push({ n: key, k: d.kind === "one" ? "one" : "many", m: d.model! })
       else if (d.kind === "struct") {
         const sub = `${name}.${key}`
         const inner: Record<string, FieldDef> = {}
@@ -204,21 +214,51 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
   for (const name of [AUTH_SESSION_MODEL, AUTH_IDENTITY_MODEL]) {
     if (name in own) throw new Error(`defineDb: "${name}" is the platform's own model (it comes with .withAuth) — name yours differently`)
   }
+  if (FILE_MODEL in own) throw new Error(`defineDb: "${FILE_MODEL}" is the platform's own model (it comes with a t.file() field) — name yours differently`)
+  // the schema's file fields: each is, in the database, the reverse side of a reference on the platform's File
+  const fileList: FileField[] = []
+  for (const [name, m] of Object.entries(own)) {
+    for (const [key, f] of Object.entries(m.fields as Fields)) {
+      const def = (f as Field<any, any>).def
+      if (def.kind === "file") fileList.push({ model: name, key, array: def.array, owner: fileOwnerKey(name, key), ...(def.image ? { image: def.image } : {}) })
+    }
+  }
   // What is wrong with the project's own models is said HERE, at the definition, not at the first use:
   // checked against a stand-in for the one platform model they may point at.
   buildMeta({ ...own, [AUTH_SESSION_MODEL]: model({}) })
 
   let authModel: string | null = null
-  let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null } | null = null
+  let sealed: { models: Record<string, Model>, schema: string, collections: Record<string, unknown>, auth: AuthBinding | null, files: FileField[] } | null = null
 
   const transport = () => {
     const t = options.transport ?? seam.__lecodesDbTransport
     if (!t) throw new Error("db: no transport — the host must call setDbTransport() before user code runs")
     return t
   }
+  // A db with file fields runs every operation through the file layer: a write of a file field is the
+  // row's operation and the ones on File after it, in one transaction.
+  let files: ReturnType<typeof createFileLayer> | null = null
+  const exec = async (op: MarciOp): Promise<any> => {
+    if (!files) return transport().exec(op)
+    const plan = await files.plan(op, 0)
+    if (!plan.after.length) return files.result(plan.op, await transport().exec(plan.op))
+    return (await transport().batch([plan.op, ...plan.after]))[0]
+  }
+  const batch = async (ops: MarciOp[]): Promise<any[]> => {
+    if (!files) return transport().batch(ops)
+    // the project's operations keep their places (its `ref`s count them); what follows them goes after
+    const plans: Awaited<ReturnType<typeof files.plan>>[] = []
+    for (let index = 0; index < ops.length; index++) plans.push(await files.plan(ops[index], index))
+    const results = await transport().batch([...plans.map(p => p.op), ...plans.flatMap(p => p.after)])
+    return plans.map((p, index) => files!.result(p.op, results[index]))
+  }
   const seal = () => {
     if (sealed) return sealed
     const models: Record<string, Model> = { ...own }
+    if (fileList.length) {
+      for (const f of fileList) models[f.model] = model({ ...(models[f.model].fields as Fields), [f.key]: t.many(FILE_MODEL, f.owner) })
+      models[FILE_MODEL] = model(fileFields(fileList))
+    }
     if (authModel) {
       models[AUTH_SESSION_MODEL] = model(sessionFields(authModel))
       models[AUTH_IDENTITY_MODEL] = model(identityFields(authModel))
@@ -246,10 +286,21 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       for (const [key, value] of missing) out[key] = [...value]
       return out
     }
+    const isFile = (name: string, key: string) => fileList.some(f => f.model === name && f.key === key)
+    const meta = modelsMeta(metas, isFile)
+    if (fileList.length) {
+      const relations: Record<string, Record<string, string>> = {}
+      const scalars: Record<string, string[]> = {}
+      for (const [name, descs] of Object.entries(meta)) {
+        relations[name] = Object.fromEntries(descs.filter(d => d.m).map(d => [d.n, d.m!]))
+        scalars[name] = descs.filter(d => d.k === "key" || d.k === "body").map(d => d.n)
+      }
+      files = createFileLayer(fileList, relations, scalars)
+    }
     // marcidb's own query builder over our metadata; the transport is the only host-specific piece
     const { collection } = createQueryLayer({
-      models: modelsMeta(metas),
-      run: op => transport().exec(op),
+      models: meta,
+      run: exec,
       // a single uuid key is generated client-side so `insert` needs no id (the .marci says @format(uuid))
       prepareInsert: (name, raw) => {
         const data = withDefaults(name, raw)
@@ -262,12 +313,13 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       models, schema: toMarci(metas), collections,
       // the platform's models are reached by role, never as `db.session` / `db.identity`
       auth: authModel ? { model: authModel, user: collection(authModel), session: collection(AUTH_SESSION_MODEL), identity: collection(AUTH_IDENTITY_MODEL) } : null,
+      files: fileList,
     }
     return sealed
   }
 
   const db: Record<string, unknown> = {
-    $transaction: async (ops: unknown[]) => { seal(); return transport().batch(ops.map(opOf)) },
+    $transaction: async (ops: unknown[]) => { seal(); return batch(ops.map(opOf)) },
     withAuth: ({ model: name }: { model: string }) => {
       if (sealed) throw new Error("defineDb(...).withAuth(): this db has already been used — sign-in is part of the definition, write it on defineDb(...) itself")
       if (authModel) throw new Error("defineDb(...).withAuth(): called twice on one db")
@@ -276,7 +328,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       for (const [key, f] of Object.entries(user.fields as Fields)) {
         const d = (f as Field<any, any>).def
         if (d.isId || key === "id") throw new Error(`defineDb(...).withAuth(): ${name} must keep the built-in id (it declares "${key}" as its key) — sessions and sign-in methods point at it`)
-        if (d.kind === "many" || d.kind === "list" || d.optional || d.hasDefault) continue
+        if (d.kind === "many" || d.kind === "list" || d.optional || d.hasDefault || (d.kind === "file" && d.array)) continue
         throw new Error(`defineDb(...).withAuth(): ${name}.${key} needs .optional() or .default(...) — the platform creates the row the first time someone signs in`)
       }
       authModel = name
@@ -288,6 +340,7 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
     $schema: { get: () => seal().schema },
     $models: { get: () => seal().models },
     $auth: { get: () => seal().auth },
+    $files: { get: () => seal().files },
   })
   for (const name of Object.keys(own)) {
     Object.defineProperty(db, uncap(name), { enumerable: true, get: () => seal().collections[name] })