lecodes-cli 2.0.6 → 2.0.8

package/src/commands/app/templates/ios.ts

@@ -482,48 +482,19 @@ class SceneDelegate: UIResponder, UIWindowSceneDelegate {
 
 export const VIEW_CONTROLLER = `//
 //  ViewController.swift
-//  Generated by lecodes app init — yours to edit.
+//  Generated by lecodes app init — yours to edit; \`lecodes app sync\` never touches it.
 //
-//  Runs the bundled app.js (produced by \`lecodes app sync\`) offline: everything the
-//  script needs is provided by the SDK core (_creatorTree / the host bridges / console)
-//  plus the plugins registered below via LeCodesRuntime.
+//  The shell's controller: LeCodesAppViewController (LeCodesRuntime, CLI-owned) boots the engine
+//  with the bundled app.js — offline, the plugins of app.json registered, newer bundles taken over
+//  the air (app.json "update"). Override \`configure(_:)\` to register your own native code
+//  (\`engine.registerService\`, \`engine.registerView\`) before the bundle runs, or any UIViewController
+//  hook to put native UI around the app's root view.
 //
 
 import UIKit
 import LeCodesRuntime
 
-class ViewController: LeCodesViewController {
-
-    override func viewDidLoad() {
-        super.viewDidLoad()
-
-        let lang = Locale.preferredLanguages.first.map { String($0.prefix(2)) } ?? "en"
-        engine.setLanguage(lang)
-
-        // \`// preload:\` assets (images, fonts) resolve out of the app bundle.
-        engine.setFetchLocal { path in
-            let ns = path as NSString
-            let ext = ns.pathExtension
-            let name = ns.deletingPathExtension
-            guard let url = Bundle.main.url(forResource: name, withExtension: ext.isEmpty ? nil : ext) else {
-                return nil
-            }
-            return try? Data(contentsOf: url)
-        }
-
-        registerBundledPlugins(in: engine)
-
-        // OTA (native, no JS involved): start the check FIRST — even a bundle that crashes
-        // on boot can never block its own fix — then run the newest local bundle (a
-        // downloaded update, or the embedded app.js). New code applies on the next launch.
-        // Configured via app.json "update" (→ Info.plist LeCodesUpdateURL); offline: no-op.
-        LeCodesUpdater.checkForUpdate()
-        guard let code = LeCodesUpdater.activeBundle() else {
-            print("LeCodes: bundled app.js is missing — run \`lecodes app sync\`")
-            return
-        }
-        engine.run(code)
-    }
+class ViewController: LeCodesAppViewController {
 }
 `
 
@@ -702,19 +673,32 @@ export interface RuntimePlugin {
   packages?: IosPackage[]
 }
 
-/** The SDK binary products (all vend the same `LeCodesSDK` module): core = UI only,
- *  2d = + Creator2D, 3d = + CreatorGL/filament with Jolt physics (AR included), full = everything. */
+/** The SDK's engine variants — one tag of lecodes-ios-sdk per variant (`<version>` = full,
+ *  `<version>-3d`, `-2d`, `-core`): core = UI only, 2d = + the 2D engine, 3d = + Filament with Jolt
+ *  (AR included), full = everything. The Swift sources are the same; the engine binary differs. */
 export type SdkVariant = "core" | "2d" | "3d" | "full"
 
-/** LeCodesRuntime/Package.swift — the CLI-owned dependency graph: the SDK variant + one
- *  vendored target per installed plugin.
- *
- *  `sdkVersion` is always an exact release and is pinned with `.exact(…)`: the CLI also
- *  downloads that version's LeCodesSDKResources.bundle (filament assets) into App/Resources/,
- *  so letting SwiftPM drift to a newer release on its own would pair mismatched halves of one
- *  SDK. Moving the version is the CLI's job — `lecodes app update` (or app.json ios.sdk). */
-export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant, plugins: RuntimePlugin[]): string => {
-  const product = `LeCodesSDK-${variant}`
+/** The tag of lecodes-ios-sdk a shell pins for an SDK version + variant. */
+export const sdkTag = (sdkVersion: string, variant: SdkVariant): string => variant === "full" ? sdkVersion : `${sdkVersion}-${variant}`
+
+/** The SDK products a shell links: `LeCodes` always; the 3D variants also AR (ARKit behind the
+ *  scenes) and the binaural filters (`engine.useHrtf()`), as the viewer does. */
+export const sdkProducts = (variant: SdkVariant): string[] =>
+  variant === "full" || variant === "3d" ? ["LeCodes", "LeCodesAR", "LeCodesHRTF"] : ["LeCodes"]
+
+/** LeCodesRuntime/Package.swift — the CLI-owned dependency graph: the SDK (one tag per
+ *  variant, pinned with `.exact(…)`: the variant is the engine binary the tag's manifest names,
+ *  so SwiftPM must never drift on its own — moving the version is the CLI's job, `lecodes app
+ *  update` or app.json ios.sdk) + one vendored target per installed plugin. The SDK's assets
+ *  (the 3D variants' shader archives) ride inside the package. */
+export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant, plugins: RuntimePlugin[], sdkPath?: string): string => {
+  const sdkDep = (name: string) => `.product(name: "${name}", package: "lecodes-ios-sdk")`
+  // LECODES_IOS_SDK_PATH: the SDK-development loop — a package tree on disk (release-ios-sdk.sh
+  // --check assembles one per variant) in place of the published tag; `name:` keeps the products'
+  // package identity so nothing else in this manifest changes.
+  const sdkPackage = sdkPath
+    ? `.package(name: "lecodes-ios-sdk", path: "${sdkPath}"),   // LECODES_IOS_SDK_PATH — not a release`
+    : `.package(url: "https://github.com/letary/lecodes-ios-sdk.git", exact: "${sdkTag(sdkVersion, variant)}"),`
   // Third-party Swift packages (manifest ios.packages), one `.package(…)` per url. Two plugins
   // naming the same url must agree on the pin — SwiftPM has one resolution per package.
   const packages = new Map<string, IosPackage>()
@@ -731,7 +715,7 @@ export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant,
     `\n        .package(url: "${pkg.url}", ${pkg.exact ? `exact: "${pkg.exact}"` : `from: "${pkg.from}"`}),`).join("")
   const pluginTargets = plugins.map(p => {
     const deps = [
-      `.product(name: "${product}", package: "lecodes-ios-sdk")`,
+      sdkDep("LeCodes"),
       ...(p.packages ?? []).flatMap(pkg => pkg.products.map(name => `.product(name: "${name}", package: "${swiftPackageName(pkg.url)}")`)),
     ]
     return `
@@ -742,14 +726,14 @@ export const runtimePackageTemplate = (sdkVersion: string, variant: SdkVariant,
             path: "Sources/${p.module}"
         ),`
   }).join("")
-  const runtimeDeps = [`.product(name: "${product}", package: "lecodes-ios-sdk")`, ...plugins.map(p => `"${p.module}"`)]
+  const runtimeDeps = [...sdkProducts(variant).map(sdkDep), ...plugins.map(p => `"${p.module}"`)]
   return `// swift-tools-version:5.9
 //
 // GENERATED by lecodes — regenerated by \`lecodes app sync\`; do not edit.
-// Owns the app's native dependency graph: the LeCodesSDK variant (auto-picked from what
-// the compiled bundle uses, or forced via app.json ios.variant), the exact SDK release
-// (app.json ios.sdk — move it with \`lecodes app update\`) and one vendored target per
-// installed plugin (see plugins.lock.json).
+// Owns the app's native dependency graph: the SDK's tag (the release of app.json ios.sdk — move
+// it with \`lecodes app update\` — and the engine variant, auto-picked from what the compiled
+// bundle uses or forced via app.json ios.variant) and one vendored target per installed plugin
+// (see plugins.lock.json).
 
 import PackageDescription
 
@@ -760,7 +744,7 @@ let package = Package(
         .library(name: "LeCodesRuntime", targets: ["LeCodesRuntime"]),
     ],
     dependencies: [
-        .package(url: "https://github.com/letary/lecodes-ios-sdk.git", exact: "${sdkVersion}"),${packageDecls}
+        ${sdkPackage}${packageDecls}
     ],
     targets: [
         .target(
@@ -775,31 +759,43 @@ let package = Package(
 `
 }
 
-/** Sources/LeCodesRuntime/LeCodesRuntime.swift — SDK re-export + plugin registration +
- *  (server-backed projects, SDK ≥ 1.6.0) the baked project identity. Baking it here — in a
- *  CLI-owned file that runs BEFORE \`engine.run(code)\` — means every shell picks identity up
- *  from a plain \`lecodes app sync\`, with no edits to the user-owned ViewController. */
-export const runtimeSwiftTemplate = (plugins: RuntimePlugin[], projectUuid?: string): string => {
-  const imports = plugins.map(p => `import ${p.module}\n`).join("")
-  const identity = !projectUuid ? "" : `    // World identity: this shell IS the project — the engine attributes the boot world so
-    // identity-gated services (push registration) see the app's uuid from its first
-    // synchronous statement. Baked from .lecodes/manifest.json by \`lecodes app sync\`.
-    engine.bootProjectUuid = "${projectUuid}"
+/** Sources/LeCodesRuntime/LeCodesRuntime.swift — the SDK re-exported (app code needs only
+ *  \`import LeCodesRuntime\`) and the shell's controller: LeCodesAppViewController, a
+ *  LeCodesShellViewController (the SDK's — the boot: language, the OTA check, the newest local
+ *  bundle) whose \`configure\` registers every plugin of app.json, the AR kinds of a 3D variant and
+ *  (server-backed projects) the baked project identity — all BEFORE the bundle runs, in a
+ *  CLI-owned file: a plain \`lecodes app sync\` moves every shell, the user-owned ViewController
+ *  (a subclass of this one) is never edited. */
+export const runtimeSwiftTemplate = (plugins: RuntimePlugin[], projectUuid: string | undefined, variant: SdkVariant): string => {
+  const is3d = variant === "full" || variant === "3d"
+  const imports = [...(is3d ? ["import LeCodesAR\n", "import LeCodesHRTF\n"] : []), ...plugins.map(p => `import ${p.module}\n`)].join("")
+  const identity = !projectUuid ? "" : `        // World identity: this shell IS the project — the engine attributes the boot world so
+        // identity-gated services (push registration) see the app's uuid from its first
+        // synchronous statement. Baked from .lecodes/manifest.json by \`lecodes app sync\`.
+        engine.bootProjectUuid = "${projectUuid}"
 `
-  const calls = plugins.map(p => `    ${p.register}.register(in: engine)\n`).join("")
-  const body = identity + calls
+  const ar = !is3d ? "" : `        // The AR controller kinds of the 3D engine (ARKit), and the binaural audio filters.
+        for mode in ["default", "world", "arcore", "detached"] { engine.registerARController(mode) { ARKitController(.world) } }
+        engine.registerARController("markers") { ARKitController(.markers) }
+        engine.useHrtf()
+`
+  const calls = plugins.map(p => `        ${p.register}.register(in: engine)\n`).join("")
+  const body = identity + ar + calls
   return `//
 //  LeCodesRuntime.swift
 //  GENERATED by lecodes — regenerated by \`lecodes app sync\`; do not edit.
 //
-//  Re-exports the SDK (so app code needs only \`import LeCodesRuntime\`) and registers
-//  every plugin installed in app.json.
+//  Re-exports the SDK (so app code needs only \`import LeCodesRuntime\`) and gives the app its
+//  controller: the SDK's shell controller with this project's plugins, AR kinds and identity
+//  registered before the bundle runs. App/ViewController.swift subclasses it.
 //
 
-@_exported import LeCodesSDK
+@_exported import LeCodes
 ${imports}
-public func registerBundledPlugins(in engine: LeCodesEngine) {
-${body === "" ? "\n" : body}}
+open class LeCodesAppViewController: LeCodesShellViewController {
+    open override func configure(_ engine: LeCodesEngine) {
+${body === "" ? "        // no plugins installed (app.json \"plugins\")\n" : body}    }
+}
 `
 }
 
@@ -859,18 +855,19 @@ CLI-owned — regenerated on every sync, hand edits are overwritten:
   assets (videos, big models) back into streaming from the server instead.
 - \`App/Info.plist\` — template + the installed plugins' usage keys
 - \`App/App.entitlements\` — the capabilities the installed plugins declare (e.g. push)
-- \`LeCodesRuntime/\` — local Swift package: the LeCodesSDK dependency, vendored plugin
-  sources (Sources/<Module>/), and the registerBundledPlugins entry point
+- \`LeCodesRuntime/\` — local Swift package: the lecodes-ios-sdk dependency (one tag per engine
+  variant), vendored plugin sources (Sources/<Module>/), and LeCodesAppViewController — the SDK's
+  shell controller with this project's plugins registered (App/ViewController.swift subclasses it)
 - the version values inside \`App.xcodeproj/project.pbxproj\` (from app.json)
 - this README
 
 ## SDK variant
 
-Sync links the smallest SDK product that covers what the compiled bundle actually uses:
-\`core\` (UI only), \`2d\` (+ 2D engine with physics), \`3d\` (+ 3D/AR engine with physics,
-~17 MB heavier), or \`full\` (everything). Adding your first 3D scene or 2D game to the
-project switches it automatically on the next sync; set \`ios.variant\` in \`../app.json\`
-to pin one instead.
+Sync pins the SDK tag of the smallest engine variant that covers what the compiled bundle actually
+uses: \`core\` (UI only), \`2d\` (+ the 2D engine with physics), \`3d\` (+ the 3D/AR engine with
+physics, ~10 MB heavier), or \`full\` (everything) — \`<version>-core\`, \`-2d\`, \`-3d\`, and the
+bare \`<version>\` for full. Adding your first 3D scene or 2D game to the project switches it
+automatically on the next sync; set \`ios.variant\` in \`../app.json\` to pin one instead.
 
 ## Over-the-air updates
 

package/src/commands/compile.ts

@@ -143,7 +143,7 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
     const project = await getProject(apiUrl, token, manifest.uuid)
     // Local-asset compiles use URL-less resources as-is instead of degrading, so skip that warning
     // there (an unpushed resources.remote match still warns below).
-    ;({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !localAssets }))
+    ;({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !localAssets, localShaders: localAssets && (opts.localShaders ?? !shell) }))
     name = manifest.name
     publicUrl = bundle.publicUrl ?? apiUrl
     note(`Resolved ${entries.length} entries in ${((performance.now() - tResolve) / 1000).toFixed(1)} s`)

package/src/commands/init/templates.ts

@@ -118,6 +118,13 @@ assertion channel for game state that has no UI.
   \`{ status?, json?, text? }\`; \`*\` wildcards full-match, plain strings substring-match, first
   match wins). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
   with \`"fixtures": "fixtures.json"\` in its envelope.
+- A project with \`*.server.ts\` files: \`lecodes test\` runs its backend for the run, on a database
+  of its own that is EMPTY before every case (a flow signs up, it never finds yesterday's data). A
+  step waits for the server calls it started — no \`wait\` after a tap that saves.
+- A file dialog (\`openFilePicker\`) is answered by \`pick\`, on the step whose action opens it:
+  \`{ "tap": "attach", "pick": "cat.png" }\` — a file beside the flow file, a list of them, or a
+  file made for the run: \`{ "name": "me.png", "width": 400, "height": 300 }\`,
+  \`{ "name": "notes.txt", "text": "hello" }\`. Without \`pick\` the dialog is cancelled.
 - \`fill\` fills every empty input — use it before tapping a disabled-until-filled submit.
 - Visual state is a \`$class\` in the style (\`$pressed\`, \`$hovered\`, \`$focused\`, your own
   \`$selected\` set with \`el.class.selected = true\` or bound with \`.class({ selected: () => … })\`);

package/src/commands/render.ts

@@ -5,6 +5,7 @@ import { screenTargetFrom } from "../compile/screenEntry"
 import { findProjectRoot } from "../project/manifest"
 import { buildBundle } from "./compile"
 import { runBackend } from "../dev/projectBackend"
+import { resolvePicks } from "../hosts/flowPick"
 import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
@@ -156,11 +157,11 @@ const readScenarioFile = (path: string): ScenarioFile => {
   } catch (e) {
     throw new CliError(`Can't read scenario "${path}": ${e instanceof Error ? e.message : String(e)}`)
   }
-  if (Array.isArray(raw)) return { steps: raw } // a bare step array is a valid scenario file
+  if (Array.isArray(raw)) return { steps: resolvePicks(raw, dirname(resolve(path))) } // a bare step array is a valid scenario file
   if (typeof raw !== "object" || raw === null) throw new CliError(`Scenario "${path}" must be a JSON object with "steps" (or a bare step array).`)
   const file = raw as ScenarioFile
   if (file.steps === undefined) throw new CliError(`Scenario "${path}" has no "steps".`)
-  return file
+  return { ...file, steps: resolvePicks(file.steps, dirname(resolve(path))) }
 }
 
 /** `--clip <name|x,y,w,h>`: a node name (its layout rect) or an explicit logical-px rect. */
@@ -354,7 +355,18 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
   }, timeoutMs)
   killer.unref?.()
 
-  const { js, warnings, useLocalAssets, root } = await compileHeadlessBundle({ screen, entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
+  // The project's backend, when it has one (the database of `lecodes dev`). Beside a running
+  // `lecodes dev`, which holds that database, the picture is still made — without the backend.
+  const run = runBackend({ root: projectRoot, command: "lecodes render", log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } })
+  const backend: typeof run = {
+    ...run,
+    start: (entries, onWarning) => run.start(entries, onWarning).catch((e: Error) => {
+      if (!/is in use/.test(e.message)) throw e
+      warnErr(`${e.message} Rendering without the backend: every call to the server fails.`)
+      return undefined
+    }),
+  }
+  const { js, warnings, useLocalAssets, root, serverUrl } = await compileHeadlessBundle({ screen, entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"], backend })
   const renderer = await requireRenderer()
 
   // Flags override the scenario file's envelope; both fall back to the project default (a
@@ -385,6 +397,7 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
   const timing = {
     settleMs: flags.settle ?? scenario?.settle,
     waitNetwork: flags["wait-network"],
+    backend: serverUrl,
     localAssets: useLocalAssets,
     fixtures,
     timeMs: flags.time,
@@ -395,7 +408,7 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
 
   // Clean process exit: clear the timeout guard, flush the given output, then exit. Without this the
   // process could linger (e.g. on stdout pipe back-pressure) even though the render is done.
-  const done = (flush: (cb: () => void) => void, code = 0) => flush(() => { clearTimeout(killer); process.exit(code) })
+  const done = (flush: (cb: () => void) => void, code = 0) => flush(() => { clearTimeout(killer); void backend.close().finally(() => process.exit(code)) })
 
   // --script: drive the compiled app through the scenario steps against a live session.
   if (scenario) {

package/src/commands/test.ts

@@ -5,6 +5,7 @@ import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer
 import { desktopRenderFlags, fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
 import { buildBundle } from "./compile"
 import { runBackend } from "../dev/projectBackend"
+import { resolvePicks } from "../hosts/flowPick"
 import { findProjectRoot } from "../project/manifest"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
@@ -133,13 +134,13 @@ const readFlowFile = (abs: string, displayName: string): FlowCase => {
   } catch (e) {
     throw new CliError(`Can't read "${displayName}": ${e instanceof Error ? e.message : String(e)}`)
   }
-  if (Array.isArray(raw)) return { name: displayName, kind: "file", steps: raw }
+  if (Array.isArray(raw)) return { name: displayName, kind: "file", steps: resolvePicks(raw, dirname(abs)) }
   if (typeof raw !== "object" || raw === null || (raw as { steps?: unknown }).steps === undefined) {
     throw new CliError(`"${displayName}" must be a JSON object with "steps" (or a bare step array).`)
   }
   const file = raw as { name?: string, width?: number, height?: number, settle?: number, device?: string, safeArea?: string, fixtures?: Record<string, unknown> | string, steps: unknown }
   return {
-    name: file.name ?? displayName, kind: "file", steps: file.steps,
+    name: file.name ?? displayName, kind: "file", steps: resolvePicks(file.steps, dirname(abs)),
     fixtures: resolveFixtures(file.fixtures, dirname(abs)),
     width: file.width, height: file.height, settle: file.settle, device: file.device, safeArea: file.safeArea,
   }
@@ -170,7 +171,7 @@ export default defineCommand({
   name: "test",
   summary: "Run the flow tests (tests/*.flow.json + design-derived flows)",
   usage: "[name…]",
-  description: "Headless flow tests: tests/*.flow.json scenarios, plus flows derived from the design graph (design/meta.json activator edges — checks the built app against the designed navigation; needs named elements + screen roots). Failing steps dump the frame (JSON + PNG) under tests/.artifacts/<flow>/. On --desktop / --lite / --web a project with *.server.ts files gets its backend run for the tests, on a database of its own (.lecodes/test-db) that is emptied before every case. The headless renderer has no backend, and --sim does not wait for one: its frames are not tied to real time.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
+  description: "Headless flow tests: tests/*.flow.json scenarios, plus flows derived from the design graph (design/meta.json activator edges — checks the built app against the designed navigation; needs named elements + screen roots). Failing steps dump the frame (JSON + PNG) under tests/.artifacts/<flow>/. A project with *.server.ts files gets its backend run for the tests, on a database of its own (.lecodes/test-db) that is emptied before every case; a step waits for the calls it started.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
   flags: testFlags,
   examples: ["lecodes test", "lecodes test hero --logs", "lecodes test --flows --json", "lecodes test --desktop"],
   run: ({ args, flags }) => runTests(args, flags),
@@ -193,9 +194,10 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
   const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
   // The project's backend, when it has one: on a database of its own, emptied before every case.
-  const backend = desktop ? runBackend({ root: desktopRoot, command: "lecodes test", test: true, log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } }) : null
+  // (a browser run starts its own, in its session)
+  const backend = lite ? null : runBackend({ root: desktopRoot, command: "lecodes test", test: true, log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } })
   const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer, backend: backend! }) : null
-  const headless = desktop || lite ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
+  const headless = desktop || lite ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"], backend: backend! })
   const warnings = headless?.warnings ?? []
   const useLocalAssets = headless?.useLocalAssets ?? false
   const js = headless?.js ?? ""
@@ -257,9 +259,10 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
     if ((meta.edges ?? []).length > 0) {
       // Probe the app for its start screen — the BFS origin of every derived flow.
       note("Probing the start screen…")
-      const probe = await renderer!.createSession(js, { raster: false, localAssets: useLocalAssets, fixtures: flowFixtures })
+      const probe = await renderer!.createSession(js, { raster: false, localAssets: useLocalAssets, fixtures: flowFixtures, backend: headless!.serverUrl })
       entryScreen = probe.screenName()
       probe.dispose()
+      await backend?.reset()
       if (entryScreen === null) {
         warnErr("Design flows skipped: the app's start screen root has no `name`. Name each screen root with its design screen id (e.g. UIScreen(...).named(\"login\")).")
       } else {
@@ -408,6 +411,7 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
         height: flags.height || kase.height || projectViewport?.height || 844,
         settleMs: flags.settle ?? kase.settle,
         waitNetwork: flags["wait-network"],
+        backend: headless!.serverUrl,
         localAssets: useLocalAssets,
         fixtures: kase.fixtures,
         ...resolveSafeAreaChoice(flags["safe-area"] ?? kase.safeArea, flags.device ?? kase.device),

package/src/compile/collect.ts

@@ -16,7 +16,13 @@ import type { CompileEntry } from "./projectCompile"
  */
 export const collectEntries = (
   root: string, manifest: Manifest, project: Project,
-  opts: { /** Warn about resources with no server URL yet (default true; shell compiles bundle them instead). */ warnMissingUrl?: boolean } = {},
+  opts: {
+    /** Warn about resources with no server URL yet (default true; shell compiles bundle them instead). */
+    warnMissingUrl?: boolean
+    /** The caller compiles the .mat files itself (applyLocalShaders in `local` mode — the desktop
+     *  host paths): skip the "push it to compile the shader" notice, which would be wrong there. */
+    localShaders?: boolean
+  } = {},
 ): { entries: CompileEntry[], warnings: string[] } => {
   const pathById = buildPaths(project.assets)
   const serverByPath = new Map<string, { fileSrc?: string, shaders?: { platform: string, src: string }[] }>()
@@ -36,8 +42,11 @@ export const collectEntries = (
       entries.push({ path: file.path, type, fileSrc: src, absPath: file.absPath })
     } else if (type === "shader") {
       const shaders = serverByPath.get(file.path)?.shaders
-      if (!shaders?.length) warnings.push(`No compiled shader for ${file.path} — push it to compile the shader.`)
-      entries.push({ path: file.path, type, shaders })
+      if (!shaders?.length && !opts.localShaders) warnings.push(`No compiled shader for ${file.path} — push it to compile the shader.`)
+      // absPath: the local shader compile (compile/shaders.ts) reads the .mat source through it and
+      // selects the entries that carry it — without it a server-backed project's shaders were never
+      // compiled locally, and `desktop run` shipped only what the server had (nothing until a push).
+      entries.push({ path: file.path, type, shaders, absPath: file.absPath })
     } else {
       entries.push({ path: file.path, type, text: readFileSync(file.absPath, "utf8") })
     }

package/src/compile/headlessBundle.ts

@@ -8,6 +8,7 @@ import { applyProjectFonts } from "./fonts"
 import { applyAppAssetIcons } from "./assetIcons"
 import type { ScreenTarget } from "./screenEntry"
 import { note } from "../cli"
+import type { RunBackend } from "../dev/projectBackend"
 
 /*
  * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
@@ -34,11 +35,15 @@ export type HeadlessBundle = {
   warnings: string[]
   /** Whether asset URLs resolve from the local disk (`lecodesfile://`). */
   useLocalAssets: boolean
+  /** The url of the backend started for this run (`backend`), when the project has server files —
+   *  what the renderer is told to let through. */
+  serverUrl?: string
 }
 
 /** What a headless compile honours: `--entry` / `--public-url` / `--remote-assets` / `--wait-network`,
- *  and the screen module a `render <file>` named. */
-export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget }
+ *  and the screen module a `render <file>` named. `backend`: the run's backend — started here when the
+ *  project has server files, its url put in the app's stubs (without one they have no server to call). */
+export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget, backend?: RunBackend }
 
 /** Compile the local project for a headless run. */
 export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise<HeadlessBundle> => {
@@ -112,10 +117,12 @@ export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise
     const ambiguous = ambiguousEntryWarning(compileEntries)
     if (ambiguous) warnings.push(ambiguous)
   }
+  const serverUrl = await opts.backend?.start(compileEntries, (w) => warnings.push(w))
   const js = await compileProject({
     entries: compileEntries,
     name,
     publicUrl,
+    serverUrl,
     entryOverride: entryFlag,
     header: false,
     format: "iife",
@@ -129,5 +136,5 @@ export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise
     warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
   }
 
-  return { js, root, warnings, useLocalAssets }
+  return { js, root, warnings, useLocalAssets, serverUrl }
 }

package/src/compile/projectCompile.ts

@@ -133,17 +133,21 @@ type Typescript = NonNullable<CompileServerOptions["typescript"]>
  *  over: TypeScript 7 — what `install typescript` brings today — is the native compiler, with no
  *  `createProgram` to call. */
 const findTypescript = async (root: string): Promise<Typescript> => {
+  const api = (mod: any): Typescript | null => mod?.createProgram ? mod : mod?.default?.createProgram ? mod.default : null
   const from = (at: string): Typescript | null => {
-    try {
-      const mod = createRequire(at)("typescript")
-      return mod?.createProgram ? mod : mod?.default?.createProgram ? mod.default : null
-    } catch { return null }
+    try { return api(createRequire(at)("typescript")) } catch { return null }
   }
-  const prefix = join(peerDirInPrefix("typescript"), "package.json")
-  const found = from(join(root, "package.json")) ?? from(import.meta.url) ?? from(prefix)
+  // The peer is loaded by the PATH of its entry, and only once it is on disk: a lookup by name that
+  // missed before the install is remembered by the runtime, and would miss again right after it.
+  const dir = peerDirInPrefix("typescript")
+  const peer = (): Typescript | null => {
+    if (!existsSync(join(dir, "package.json"))) return null
+    try { return api(createRequire(import.meta.url)(join(dir, "lib", "typescript.js"))) } catch { return null }
+  }
+  const found = from(join(root, "package.json")) ?? from(import.meta.url) ?? peer()
   if (found) return found
   await installPeers(["typescript"], "The project's server code (*.server.ts)")
-  return from(prefix) ?? (() => { throw new Error(`The typescript installed in ${peerDirInPrefix("typescript")} has no compiler API`) })()
+  return peer() ?? (() => { throw new Error(`The typescript installed in ${dir} has no compiler API`) })()
 }
 
 /**

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

@@ -10,6 +10,9 @@ declare module "lecodes-headless/headless" {
     settleMs?: number
     /** Let data fetches hit the real network (off by default). */
     waitNetwork?: boolean
+    /** The url of the project's backend, run for this run: the app's calls to it are made and
+     *  waited for, its channel socket is real. */
+    backend?: string
     /** Resolve `lecodesfile://<abs-path>` resource URLs from the local filesystem (the `render`
      *  command emits these for a local project's assets). */
     localAssets?: boolean

package/src/dev/backendWorker.ts

@@ -1,10 +1,10 @@
-import { mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs"
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { format } from "node:util"
 import {
-  createAuthHost, createInvoker, createSubscribeGuard, describeServer, loadServerModules,
-  setChannelPublisher, setDbTransport, type AuthHost, type LoadedServer,
+  createAuthHost, createFilesHost, createInvoker, createSubscribeGuard, describeServer, loadServerModules,
+  setChannelPublisher, setDbTransport, type AuthHost, type Heic, type LoadedServer, type Sharp,
 } from "lecodes-sdk/server"
 import { loadPeer } from "../hosts/peerInstall"
 import type { FromWorker, LogLevel, ToWorker } from "./localBackend"
@@ -59,7 +59,7 @@ process.on("SIGINT", quit)
 process.on("SIGTERM", quit)
 
 /** Open the project's database and bring it to `schema`. Returns what the developer should be told. */
-const openDb = async (dir: string, schema: string): Promise<string[]> => {
+const openDb = async (dir: string, filesDir: string, schema: string): Promise<string[]> => {
   const { openDatabase } = await loadPeer<EmbeddedModule>("marcidb-embedded", undefined, { for: "lecodes dev", install: false })
     ?? (() => { throw new Error("marcidb-embedded is not installed") })()
   mkdirSync(dir, { recursive: true })
@@ -85,6 +85,9 @@ const openDb = async (dir: string, schema: string): Promise<string[]> => {
     const aside = `${dir}-old`
     rmSync(aside, { recursive: true, force: true })
     renameSync(dir, aside)
+    // the stored files are that database's: they go aside with it
+    rmSync(`${filesDir}-old`, { recursive: true, force: true })
+    if (existsSync(filesDir)) renameSync(filesDir, `${filesDir}-old`)
     mkdirSync(dir, { recursive: true })
     db = openDatabase(dir)
     await db.$sync(schema)
@@ -100,7 +103,7 @@ const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   ;(0, eval)(m.code)
   const server: LoadedServer = loadServerModules()
   const describe = describeServer(server)
-  const notes = describe.marci ? await openDb(m.dbDir, describe.marci) : []
+  const notes = describe.marci ? await openDb(m.dbDir, m.filesDir, describe.marci) : []
   // Sessions, passwords and email codes over the project's own db, as on the runner. A code that was
   // asked for is printed here, and DEV_CODE signs any email in without one — the developer is the
   // only user.
@@ -114,7 +117,15 @@ const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   authHost.install()
   const auth = authHost.enabled ? authHost : null
   const onError = (id: string, e: unknown) => post({ t: "log", level: "error", text: `${id}: ${(e as Error)?.stack ?? e}` })
-  invoke = createInvoker(server, { auth, onError })
+  // Stored files (`t.file()`): rows in the database, bytes in the folder beside it
+  const files = createFilesHost({
+    db: server.dbs[0] ?? null, dir: m.filesDir, log: (level, text) => post({ t: "log", level, text }),
+    // the codec of t.image() fields: a peer, installed by the parent when the bundle has one (projectBackend.ts)
+    sharp: async () => (await loadPeer<{ default: Sharp }>("sharp", undefined, { for: "lecodes dev", install: false }))?.default ?? null,
+    heic: async () => (await loadPeer<{ default: Heic }>("heic-decode", undefined, { for: "lecodes dev", install: false }))?.default ?? null,
+  })
+  files.install()
+  invoke = createInvoker(server, { auth, files, onError })
   subscribe = createSubscribeGuard(server, { auth, onError })
   post({ t: "loaded", describe, notes })
 }

package/src/dev/localBackend.ts

@@ -25,7 +25,7 @@ export type LogLevel = "log" | "info" | "warn" | "error" | "debug"
 type Ctx = Omit<RequestContext, "id">
 
 export type ToWorker =
-  | { t: "load", code: string, dbDir: string }
+  | { t: "load", code: string, dbDir: string, filesDir: string }
   | { t: "invoke", req: number, id: string, args: unknown[], ctx: Ctx }
   | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx }
   | { t: "stop" }
@@ -41,6 +41,8 @@ export type LocalBackendOptions = {
   root: string
   /** The database's folder (default `.lecodes/db`). */
   dbDir?: string
+  /** The stored files' folder (`t.file()`; default: beside the database — `.lecodes/files`). */
+  filesDir?: string
   log: (msg: string) => void
   onPublish: (ch: string, group: ChannelGroup | null, data: unknown) => void
   invokeTimeoutMs?: number
@@ -74,11 +76,15 @@ const selfCommand = (): string[] => {
   return [process.execPath, ...process.execArgv, entry]
 }
 
+/** Where a database's stored files are: beside it, named after it (`.lecodes/db` → `.lecodes/files`, `test-db` → `test-files`). */
+export const filesDirOf = (dbDir: string) => join(dirname(dbDir), basename(dbDir).replace(/db$/, "") + "files")
+
 export const startLocalBackend = (options: LocalBackendOptions): LocalBackend => {
   const { log } = options
   const invokeTimeoutMs = options.invokeTimeoutMs ?? 30_000
   const loadTimeoutMs = options.loadTimeoutMs ?? 15_000
   const dbDir = options.dbDir ?? join(options.root, LECODES_DIR, "db")
+  const filesDir = options.filesDir ?? filesDirOf(dbDir)
 
   let live: Live | null = null
   /** The bundle that is deployed — what a crashed or timed-out process is started from again. */
@@ -141,7 +147,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
         if (!closed) log(`[server:error] the server process exited (${status ?? "killed"}) — it starts again with the next call`)
       }
     })
-    child.send({ t: "load", code: bundle, dbDir } satisfies ToWorker)
+    child.send({ t: "load", code: bundle, dbDir, filesDir } satisfies ToWorker)
   })
 
   const stop = async (l: Live) => {