lecodes-cli 2.6.0 → 2.8.1

package/src/commands/test.ts

@@ -5,6 +5,7 @@ import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer
 import { desktopRenderFlags, fileScenarioIO, parseNativeViews, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
 import { buildBundle } from "./compile"
 import { runBackend } from "../dev/projectBackend"
+import { callEndpoint } from "../dev/backendCall"
 import { resolvePicks } from "../hosts/flowPick"
 import { findProjectRoot } from "../project/manifest"
 import { runDesktopRender } from "../hosts/desktopRenderer"
@@ -33,6 +34,13 @@ import { bundleFlags, bundleOptions } from "./shared"
  * A failing step stops its flow and dumps the failing frame (JSON + PNG when @napi-rs/canvas is
  * installed) under tests/.artifacts/<flow>/ so a red test explains itself without a rerun.
  *
+ * A file case may run several clients (`"clients": { "ann": {}, "bob": { "height": 640 } }` in its
+ * envelope): the app started once per client, each a headless session of its own in this process (its
+ * own storage, clock reader, fetch and socket), all against the case's backend; a step names its clients
+ * and the case keeps one clock (runCase in lecodes-headless — the backend's clock follows it over the dev
+ * backend's IPC, `setClock`). A case with only `call` / `clock` steps and no `clients` starts no app: a
+ * server test. Artifacts of a multi-client case go per client: tests/.artifacts/<flow>/<client>/.
+ *
  * `--desktop` runs the file scenarios through the NATIVE host (desktopScript.ts — targets by name or
  * coordinates, expect.log + expect.paint checked, the semantic expects reported skipped). The
  * design-derived flows need `expect.screen` and `fill`, which the host can't answer, so they stay
@@ -46,7 +54,7 @@ import { bundleFlags, bundleOptions } from "./shared"
 type DesignEdge = { from: string, to: string, label?: string, activator?: string }
 type DesignMeta = { screens?: Record<string, unknown>, edges?: DesignEdge[] }
 
-type FlowCase = {
+export type FlowCase = {
   name: string
   kind: "file" | "flow"
   steps: unknown
@@ -59,6 +67,37 @@ type FlowCase = {
   settle?: number
   device?: string
   safeArea?: string
+  /** Several clients: name → its own viewport / device (file scenarios only). */
+  clients?: Record<string, ClientEnvelope>
+  /** How long an expect waits by default in this case, ms. */
+  timeout?: number
+  /** The `${name}`s the run must give (`"vars": ["code"]`): a flow for `lecodes dev --bots … --var code=4821`,
+   *  played beside a human — `lecodes test` does not run it. */
+  vars?: string[]
+}
+
+/** What a client of a multi-client case may set for itself (else the case's own). */
+export type ClientEnvelope = { width?: number, height?: number, device?: string, safeArea?: string }
+const CLIENT_KEYS = new Set(["width", "height", "device", "safeArea"])
+
+/** The step kinds of the headless case runner (runCase) the native and browser runners don't take yet. */
+const CASE_STEP_KEYS = ["call", "clock", "save", "offline", "restart", "close"]
+
+/** A case with no `clients` whose steps are all `call` / `clock` (or `wait`): a server test — no app is started. */
+export const isServerCase = (kase: FlowCase): boolean =>
+  kase.kind === "file" && (kase.clients ? Object.keys(kase.clients).length === 0
+    : Array.isArray(kase.steps) && kase.steps.length > 0 && kase.steps.every((s) => typeof s === "object" && s !== null && ((s as Record<string, unknown>).call !== undefined || (s as Record<string, unknown>).clock !== undefined)))
+
+/** The envelope's `clients`: names (they are folder names too) → per-client overrides. */
+const readClients = (raw: unknown, displayName: string): Record<string, ClientEnvelope> | undefined => {
+  if (raw === undefined) return undefined
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new CliError(`"${displayName}": "clients" maps names to their settings: { "ann": {}, "bob": { "height": 640 } }.`)
+  for (const [name, o] of Object.entries(raw)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(name)) throw new CliError(`"${displayName}": client name "${name}" — letters, digits, _ and - only (it names the client's artifact folder).`)
+    if (typeof o !== "object" || o === null || Array.isArray(o)) throw new CliError(`"${displayName}": clients.${name} must be an object ({} for the case's own settings).`)
+    for (const k of Object.keys(o)) if (!CLIENT_KEYS.has(k)) throw new CliError(`"${displayName}": clients.${name}.${k} — a client sets ${[...CLIENT_KEYS].join(", ")}.`)
+  }
+  return raw as Record<string, ClientEnvelope>
 }
 
 type SkippedFlow = { name: string, reason: string }
@@ -124,10 +163,10 @@ export const deriveDesignFlows = (meta: DesignMeta, entryScreen: string): { flow
   return { flows, skipped }
 }
 
-const slug = (s: string): string => s.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "case"
+export const slug = (s: string): string => s.replace(/[^a-zA-Z0-9-_]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "case"
 
 /** Read one tests/*.flow.json (envelope + steps, or a bare step array). */
-const readFlowFile = (abs: string, displayName: string): FlowCase => {
+export const readFlowFile = (abs: string, displayName: string): FlowCase => {
   let raw: unknown
   try {
     raw = JSON.parse(readFileSync(abs, "utf8"))
@@ -138,11 +177,15 @@ const readFlowFile = (abs: string, displayName: string): FlowCase => {
   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 }
+  const file = raw as { name?: string, width?: number, height?: number, settle?: number, device?: string, safeArea?: string, fixtures?: Record<string, unknown> | string, clients?: unknown, timeout?: unknown, vars?: unknown, steps: unknown }
+  if (file.timeout !== undefined && (typeof file.timeout !== "number" || file.timeout < 0)) throw new CliError(`"${displayName}": "timeout" is how long an expect waits, ms.`)
+  if (file.vars !== undefined && !(Array.isArray(file.vars) && file.vars.every((v) => typeof v === "string" && v !== ""))) throw new CliError(`"${displayName}": "vars" lists the names a run gives (--var name=value): ["code"].`)
   return {
     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,
+    clients: readClients(file.clients, displayName), timeout: file.timeout as number | undefined,
+    vars: file.vars as string[] | undefined,
   }
 }
 
@@ -171,7 +214,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>/. 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).",
+  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\nA flow file may run several clients against that backend (\"clients\": { \"ann\": {}, \"bob\": {} } in its envelope; every step then names its \"client\" / \"clients\"), call server functions directly (\"call\" + \"as\"), keep values for later steps (\"save\", then ${name}), jump the case's one clock — the apps' and the server's (\"clock\": \"+92s\"), take a client offline, restart or close it (\"offline\", \"restart\", \"close\"). A file whose envelope lists \"vars\" (the ${name}s a run gives: a flow for `lecodes dev --bots … --var`) is not run. An expect waits until it holds (\"timeout\", default 5000 ms). A file of only call / clock steps starts no app: a server test. These run headless only.\n\nThe backend of a test is always its own, never a running `lecodes dev`'s: a test does not see or change the data the developer plays with (the other commands talk to a running dev — `lecodes dev --bots` runs a flow there).\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),
@@ -196,7 +239,7 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   // The project's backend, when it has one: on a database of its own, emptied before every case.
   // (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 native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer, backend: backend!, ambiguousEntry: "error" }) : null
   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
@@ -275,6 +318,12 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
     throw new CliError(`--flows needs a design graph (${designMetaPath} not found).`)
   }
 
+  // a flow that takes values from its run (`"vars"`) is played beside a human (lecodes dev --bots), not a test
+  for (const k of cases.filter((k) => k.kind === "file" && k.vars?.length)) {
+    note(`${k.name}: a flow for lecodes dev --bots (it takes --var ${k.vars!.join(", ")}) — not run by lecodes test.`)
+  }
+  for (let i = cases.length - 1; i >= 0; i--) if (cases[i].kind === "file" && cases[i].vars?.length) cases.splice(i, 1)
+
   if (cases.length === 0) {
     for (const w of warnings) warnErr(w)
     throw new CliError(`No tests found. Write tests/*.flow.json scenarios, or draw activator edges in the design board (design/meta.json).`)
@@ -282,7 +331,9 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
 
   // Hard timeout across the whole run (each case is bounded by settles, but a pathological app can
   // still spin) — generous per-case allowance, overridable.
-  const timeoutMs = flags.timeout || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.length * 10000)
+  // (an expect waits in real time, on every client of its case: a case's share grows with both)
+  const caseShare = (k: FlowCase) => 10000 + (Array.isArray(k.steps) ? k.steps.length : 0) * 1000 * Math.max(1, Object.keys(k.clients ?? {}).length)
+  const timeoutMs = flags.timeout || (desktop ? 60000 + cases.length * 60000 : 20000 + cases.reduce((n, k) => n + caseShare(k), 0))
   const killer = setTimeout(() => {
     warnErr(`Test run timed out after ${timeoutMs}ms (raise --timeout or lower --settle).`)
     process.exit(1)
@@ -382,6 +433,14 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
     let result: CaseResult
     // every case starts on an empty database, like it starts in a fresh host
     if (backend && results.length > 0) await backend.reset()
+    const caseOnly = (desktop || lite) && Array.isArray(kase.steps) ? CASE_STEP_KEYS.find((k) => (kase.steps as Record<string, unknown>[]).some((st) => st !== null && typeof st === "object" && k in st)) : undefined
+    if ((desktop || lite) && (kase.clients || isServerCase(kase) || caseOnly)) {
+      const what = kase.clients ? "several clients" : isServerCase(kase) ? "a server test" : `"${caseOnly}" steps`
+      result = { name: kase.name, kind: kase.kind, ok: false, steps: [], error: `${what} — headless only for now: run it with \`lecodes test\` (no --desktop / --lite / --web)`, artifacts: [] }
+      results.push(result)
+      reportCase(result)
+      continue
+    }
     if (lite) {
       try {
         result = await runLiteCase(kase)
@@ -404,30 +463,37 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
       continue
     }
     try {
-      const steps = renderer!.parseScenarioSteps(kase.steps)
-      // Every case runs in a FRESH session — no state bleeds between flows.
-      const session = await renderer!.createSession(js, {
-        width: flags.width || kase.width || projectViewport?.width || 390,
-        height: flags.height || kase.height || projectViewport?.height || 844,
+      const server = isServerCase(kase)
+      const names = kase.clients ? Object.keys(kase.clients) : undefined
+      const steps = renderer!.parseScenarioSteps(kase.steps, server ? { server: true } : { clients: names })
+      // Every case runs in FRESH sessions — no state bleeds between flows. Several clients: one each,
+      // with what the envelope says of each; the app's console is told under the client's name.
+      const sessionOptions = (name: string | undefined, own: ClientEnvelope = {}) => ({
+        width: flags.width || own.width || kase.width || projectViewport?.width || 390,
+        height: flags.height || own.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),
+        ...resolveSafeAreaChoice(flags["safe-area"] ?? own.safeArea ?? kase.safeArea, flags.device ?? own.device ?? kase.device),
         nativeViews: parseNativeViews(flags["native-view"]),
-        onConsole,
+        onConsole: onConsole && name ? (level: string, text: string) => onConsole(level, `${c.dim(`[${name}]`)} ${text}`) : onConsole,
       })
-      try {
-        const io = fileScenarioIO(resolve(artifactsRoot, slug(kase.name)))
-        const outcome = await renderer!.runScenario(session, steps, io)
-        result = {
-          name: kase.name, kind: kase.kind, ok: outcome.ok,
-          steps: outcome.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error })),
-          artifacts: outcome.failureArtifacts.map((p) => resolve(artifactsRoot, slug(kase.name), p)),
-        }
-      } finally {
-        session.dispose()
+      const clients = server ? []
+        : kase.clients ? Object.entries(kase.clients).map(([name, own]) => ({ name, start: (env: import("lecodes-headless/headless").ClientStart) => renderer!.createSession(js, { ...sessionOptions(name, own), ...env }) }))
+        : [{ name: "app", start: (env: import("lecodes-headless/headless").ClientStart) => renderer!.createSession(js, { ...sessionOptions(undefined), ...env }) }]
+      const serverUrl = headless!.serverUrl
+      const io = fileScenarioIO(resolve(artifactsRoot, slug(kase.name)))
+      const outcome = await renderer!.runCase({
+        clients, single: !kase.clients, steps, io, timeoutMs: kase.timeout,
+        // the case's backend: `call` steps reach it as a device would, and its clock is the case's
+        backend: serverUrl && backend ? { url: serverUrl, call: (id, args, device) => callEndpoint(serverUrl, id, args, device), setClock: (ms) => backend.setClock(ms) } : undefined,
+      })
+      result = {
+        name: kase.name, kind: kase.kind, ok: outcome.ok,
+        steps: outcome.steps.map((s) => ({ desc: s.desc, ok: s.ok, error: s.error })),
+        artifacts: outcome.failureArtifacts.map((p) => resolve(artifactsRoot, slug(kase.name), p)),
       }
     } catch (e) {
       // A malformed scenario / session crash is a failed case, not a dead run.

package/src/commands/web.ts

@@ -10,6 +10,7 @@ import { startPreview } from "../web/preview"
 import { bundleFlags } from "./shared"
 import { lanCandidates, loadDevToken } from "./dev"
 import { devCertificate } from "../dev/https"
+import { findRunningDev, recordDevPort } from "../dev/devLink"
 
 /*
  * `lecodes web` — the project as a WEB PAGE (Web Lite: DOM and CSS, the browser's layout, text and
@@ -21,7 +22,9 @@ import { devCertificate } from "../dev/https"
  *   build    a folder any static hosting serves (web/build.ts)
  *   preview  serve a built folder, as a hosting would
  *
- * Fully local: no login, no le.codes backend.
+ * Fully local: no login, no le.codes backend. The project's backend is the one of a running
+ * `lecodes dev` of it when there is one (dev/devLink.ts: the page's /server routes are forwarded there);
+ * else `web dev` runs it, and is the one the other commands find.
  */
 
 const DEFAULT_PORT = 4488
@@ -51,7 +54,7 @@ const kb = (bytes: number): string => bytes < 1024 ? `${bytes} B` : bytes < 1024
 const dev = defineCommand({
   name: "dev",
   summary: "Open the project as a web page, reloaded on every save",
-  description: "Serves the project's bundle and assets with the page of Web Lite around them; a save recompiles and runs the app again, the page's console output and errors stream back here. The address's hash is the route the app is opened with (#/product/42 → app.launchUrl). A web half of the project's own (app.json `\"ar\": { \"web\": \"./plugins/ar-8thwall\" }`) is built with every compile and served beside the page, its `web.static` folder from the project.\n\n`--https`: the page over https, for a phone's camera and motion sensors (a browser gives them to a secure page only) — a self-signed certificate for localhost and this machine's LAN addresses, made once and kept in ~/.lecodes/dev-https/. The phone's browser warns about it: accept it once.",
+  description: "Serves the project's bundle and assets with the page of Web Lite around them; a save recompiles and runs the app again, the page's console output and errors stream back here. The project's backend is a running `lecodes dev`'s when there is one (its database and data; the page's calls are forwarded there), else it runs here. The address's hash is the route the app is opened with (#/product/42 → app.launchUrl). A web half of the project's own (app.json `\"ar\": { \"web\": \"./plugins/ar-8thwall\" }`) is built with every compile and served beside the page, its `web.static` folder from the project.\n\n`--https`: the page over https, for a phone's camera and motion sensors (a browser gives them to a secure page only) — a self-signed certificate for localhost and this machine's LAN addresses, made once and kept in ~/.lecodes/dev-https/. The phone's browser warns about it: accept it once.",
   flags: {
     port: num("server port", { default: DEFAULT_PORT }),
     entry: bundleFlags.entry,
@@ -70,17 +73,23 @@ const dev = defineCommand({
     const scheme = flags.https ? "https" : "http"
     const origin = `${scheme}://localhost:${port}`
     const tls = flags.https ? await devCertificate(lans) : undefined
+    const token = loadDevToken(root)
+    // one backend per project on this machine: a running `lecodes dev` of it runs it — this page's calls go there
+    const owner = await findRunningDev(root)
     const server = await startDevServer({
-      root, manifest, name, origin, port,
-      token: loadDevToken(root),
+      root, manifest, name, origin, port, token,
       entryOverride: flags.entry,
       lite,
       tls,
       log: note,
+      backendUrl: owner?.url,
     }).catch((e: unknown) => {
       const msg = e instanceof Error ? e.message : String(e)
       throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
     })
+    if (owner) note(`The project's backend: the running lecodes dev's (port ${owner.port}) — its database, its data.`)
+    // the backend runs here: the other commands find it (not over https: they speak plain http to this machine)
+    else if (!tls) recordDevPort(root, server.port)
 
     note("Compiling…")
     const first = await server.recompile()

package/src/compile/headlessBundle.ts

@@ -4,7 +4,7 @@ import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
 import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
 import { collectEntries } from "./collect"
 import { collectLocalEntries } from "./collectLocal"
-import { ambiguousEntryWarning, compileProject } from "./projectCompile"
+import { compileProject, requireUnambiguousEntry } from "./projectCompile"
 import { applyProjectFonts } from "./fonts"
 import { applyAppAssetIcons } from "./assetIcons"
 import type { ScreenTarget } from "./screenEntry"
@@ -112,12 +112,11 @@ export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise
   // headless renders stay deterministic and offline after the first fetch (like local assets).
   await applyAppAssetIcons(compileEntries)
 
-  note("Compiling…")
+  // A guessed entry fails here, before the compile: render / test would otherwise run the wrong file
+  // and report only its symptoms ("Nothing was rendered", "got an unnamed screen").
   const entryFlag = opts.screen?.entryPath ?? opts.entry
-  if (!entryFlag) {
-    const ambiguous = ambiguousEntryWarning(compileEntries)
-    if (ambiguous) warnings.push(ambiguous)
-  }
+  requireUnambiguousEntry(compileEntries, entryFlag)
+  note("Compiling…")
   const serverUrl = await opts.backend?.start(compileEntries, (w) => warnings.push(w))
   const js = await compileProject({
     entries: compileEntries,

package/src/compile/projectCompile.ts

@@ -5,6 +5,7 @@ import type { FileKind } from "../project/manifest"
 import { distRoot } from "../hosts/distRoot"
 import { installPeers } from "../hosts/peerInstall"
 import { peerDirInPrefix } from "../hosts/peers"
+import { CliError } from "../cli"
 import {
   compileProjectWithMap as sdkCompileProjectWithMap, compileServerBundle, detectEntry, inlineSourceMapComment, isServerPath, scanModulesChisel,
   localAssetNames, ENTRY_CONVENTION, findEnvLeaks, EnvLeakError, type BundleBake, type CompileServerOptions,
@@ -101,15 +102,44 @@ export type CompileOptions = {
   env?: Record<string, string>
 }
 
-/** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
- *  the pick still works, but the developer should make the entry explicit. Null when unambiguous.
- *  Callers skip this when an explicit --entry / entryOverride is in play. */
-export const ambiguousEntryWarning = (entries: { path: string, type?: string, text?: string }[]): string | null => {
+type EntryFiles = { path: string, type?: string, text?: string }[]
+
+/** An auto-detected entry that is a guess: several import-graph roots and no main.ts among them to
+ *  settle it, so the pick goes by size. Null when the detection is not a guess. */
+const guessedEntry = (entries: EntryFiles): { picked: string, roots: string[] } | null => {
   const { entry, roots } = detectEntry(entries, scanModulesChisel)
   if (!entry || roots.length < 2 || roots.includes(ENTRY_CONVENTION)) return null
-  return `Ambiguous entrypoint: nothing imports ${roots.join(", ")} — picked ${entry}. Rename your entry to main.ts (or pass --entry).`
+  return { picked: entry, roots }
+}
+
+/** `compile` / `dev` / `web`: a guessed entry is a warning — the pick still works, but the developer
+ *  should make the entry explicit. Null when unambiguous. Callers skip this when an explicit
+ *  --entry / entryOverride is in play. */
+export const ambiguousEntryWarning = (entries: EntryFiles): string | null => {
+  const guess = guessedEntry(entries)
+  if (!guess) return null
+  return `Ambiguous entrypoint: nothing imports ${guess.roots.join(", ")} — picked ${guess.picked}. Rename your entry to main.ts (or pass --entry).`
 }
 
+/** `render` / `test`: a guessed entry is an error, thrown before the compile. A stray unimported file
+ *  picked as the app otherwise surfaces as "Nothing was rendered" / every case "got an unnamed
+ *  screen", with the cause printed last. An explicit entry (`--entry`, a screen's generated entry)
+ *  settles it: the detection is not consulted. */
+export const requireUnambiguousEntry = (entries: EntryFiles, explicitEntry: string | undefined): void => {
+  if (explicitEntry) return
+  const guess = guessedEntry(entries)
+  if (!guess) return
+  throw new CliError(
+    `Ambiguous entrypoint: nothing imports ${guess.roots.join(", ")}. ` +
+    `The guess would be ${guess.picked}. ` +
+    `Name the app's entry main.ts, or pass --entry <path>. ` +
+    `An unimported helper is an entry candidate: import it, or move it out of the project.`,
+  )
+}
+
+/** How a builder treats a guessed entry (see the two helpers above). Default `warn`. */
+export type AmbiguousEntryPolicy = "warn" | "error"
+
 /** A file of the compile by its root path (`/assets/lightmap/level.bake`) — how `bake()` reads the manifest it names:
  *  the entries' own files on disk. */
 const resourceReader = (entries: CompileEntry[]) => {

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

@@ -58,6 +58,12 @@ declare module "lecodes-headless/headless" {
     raster?: boolean | "auto"
     /** Device-pixel scale for png() (default 2). */
     scale?: number
+    /** The app's storage — a map the caller keeps survives the session (a flow's `restart`). */
+    storage?: Map<string, string>
+    /** What the app's `Date.now()` reads at clock 0 (default: the wall clock at launch). */
+    epochMs?: number
+    /** Before every step of the virtual clock: the time it steps to (ms since launch). */
+    onTime?: (clockMs: number) => void
   }
   export type Session = {
     warnings: string[]
@@ -99,6 +105,12 @@ declare module "lecodes-headless/headless" {
   }
   export type ScenarioStep = {
     name?: string
+    client?: string
+    clients?: string[] | "*"
+    /** How long this step's expect (and target) waits, ms. */
+    timeout?: number
+    /** End the step's clients (`restart` opens them again). */
+    close?: true
     tap?: SessionTarget
     type?: string
     text?: string
@@ -128,9 +140,46 @@ declare module "lecodes-headless/headless" {
   export type ScenarioIO = { write: (relPath: string, data: string | Uint8Array) => void }
   export type StepOutcome = { index: number, desc: string, ok: boolean, error?: string }
   export type ScenarioOutcome = { ok: boolean, steps: StepOutcome[], failureArtifacts: string[] }
-  export function parseScenarioSteps(raw: unknown): ScenarioStep[]
+  /** What a step list is parsed for: a case's clients (absent: one), or a server test (no UI client); the
+   *  variables a run is given (`vars`), and a case on real time (`realTime`: a `clock` step is an error). */
+  export type ScenarioShape = { clients?: string[], server?: boolean, vars?: string[], realTime?: boolean }
+  export function parseScenarioSteps(raw: unknown, shape?: ScenarioShape): ScenarioStep[]
   export function describeStep(step: ScenarioStep): string
+  /** `"+92s"` / `"+1500ms"` / `"+2m"` → ms (undefined: not a jump forward). */
+  export function parseClockJump(v: unknown): number | undefined
+
+  // ---- a case: several clients, one clock, a backend (lecodes test) ----
+  export type ClientStart = { storage: Map<string, string>, epochMs: number, onTime: (clockMs: number) => void }
+  export type CaseClient = { name: string, start: (env: ClientStart) => Promise<Session> }
+  export type CallOutcome = { ok: true, result: unknown } | { ok: false, status: number, message: string }
+  export type CallDevice = { token: () => string | null, store: (token: string | null) => void }
+  export type CaseBackend = {
+    url: string
+    call?: (id: string, args: unknown[], device: CallDevice) => Promise<CallOutcome>
+    setClock?: (offsetMs: number) => void
+  }
+  export type CaseOptions = {
+    clients: CaseClient[]
+    single?: boolean
+    steps: ScenarioStep[]
+    io: ScenarioIO
+    backend?: CaseBackend
+    timeoutMs?: number
+    artifactPrefix?: string
+    keepOpen?: boolean
+    /** The case runs on the machine's clock (a backend other devices use): clients follow real time, `wait` waits, `clock` fails, `setClock` is never called. */
+    realTime?: boolean
+    /** A failing step does not end the case. */
+    keepGoing?: boolean
+    /** `${name}` values known from the start. */
+    vars?: Record<string, unknown>
+    onStepStart?: (index: number, desc: string) => void
+    onStep?: (outcome: StepOutcome) => void
+    /** (realTime) After the steps (their outcome, the clients still open): those stay, on real time, until what this returns settles. */
+    linger?: (outcome: ScenarioOutcome, open: string[]) => Promise<unknown>
+  }
+  export function runCase(opts: CaseOptions): Promise<ScenarioOutcome>
   export function runScenario(
-    session: Session, steps: ScenarioStep[], io: ScenarioIO, opts?: { artifactPrefix?: string },
+    session: Session, steps: ScenarioStep[], io: ScenarioIO, opts?: { artifactPrefix?: string, backend?: CaseBackend, timeoutMs?: number },
   ): Promise<ScenarioOutcome>
 }

package/src/dev/backendCall.ts

@@ -0,0 +1,44 @@
+import { firstCallGate, type FirstCallGate } from "lecodes-sdk/server"
+
+/*
+ * An endpoint call made from the CLI as one device would make it — a flow's `call` step (`lecodes test`)
+ * and `lecodes call`. The wire is the client transport's (sdk/src/runtime/rpc.ts): `POST <url>/api/<id>`
+ * with `{"args":[…]}` and the device's token as the bearer, the envelope always HTTP 200; a `session` in
+ * the envelope is the device's token from now on. And its first-call rule (sdk/src/runtime/firstCall.ts):
+ * a device with no token sends its first call alone, so a backend that mints one on first contact
+ * (`request.session`, a guest session) mints ONE for the device however many calls it starts at once.
+ */
+
+/** Who calls: the token it holds (null = none yet) and where a new one goes. */
+export type CallDevice = { token: () => string | null, store: (token: string | null) => void }
+
+/** What the call answered: the result, or the failure the app would see as an `RpcError`
+ *  (status 0 = the backend was not reached). */
+export type CallOutcome = { ok: true, result: unknown } | { ok: false, status: number, message: string }
+
+const gates = new WeakMap<CallDevice, FirstCallGate>()
+
+/** Call endpoint `id` (`<file>#<export>`) of the backend at `url` as `device`. Never throws. */
+export const callEndpoint = (url: string, id: string, args: unknown[], device: CallDevice): Promise<CallOutcome> => {
+  let gate = gates.get(device)
+  if (!gate) { gate = firstCallGate(); gates.set(device, gate) }
+  return gate(() => !!device.token(), () => post(url, id, args, device))
+}
+
+const post = async (url: string, id: string, args: unknown[], device: CallDevice): Promise<CallOutcome> => {
+  const headers: Record<string, string> = { "content-type": "application/json" }
+  const token = device.token()
+  if (token) headers.authorization = `Bearer ${token}`
+  let res: Response
+  try {
+    res = await fetch(`${url.replace(/\/+$/, "")}/api/${encodeURIComponent(id)}`, { method: "POST", headers, body: JSON.stringify({ args }) })
+  } catch (e) {
+    return { ok: false, status: 0, message: `Endpoint ${id}: request failed (${(e as Error)?.message ?? e})` }
+  }
+  let body: any = null
+  try { body = await res.json() } catch { /* not an envelope */ }
+  if (body && typeof body === "object" && "session" in body) device.store(body.session ?? null)
+  if (body?.ok === true) return { ok: true, result: body.result ?? null }
+  if (body?.ok === false) return { ok: false, status: body.status ?? res.status, message: body.message ?? "" }
+  return { ok: false, status: res.status, message: `Endpoint ${id}: unexpected response (HTTP ${res.status})` }
+}

package/src/dev/backendWorker.ts

@@ -4,8 +4,9 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { format } from "node:util"
 import {
-  createAuthHost, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer, loadServerModules, runSeed,
-  setChannelPublisher, setDbTransport, setEnv, type AuthHost, type Heic, type LoadedServer, type PushRelay, type Sharp,
+  createAuthHost, createComputedHost, createFakeWatchSource, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer,
+  embeddedWatchSource, isReadOp, loadServerModules, outsideRequests, runSeed, setChannelPublisher, setDbTransport, setEnv, setPresenceProvider, setServerClock,
+  type AuthHost, type ComputedHost, type EmbeddedWatchHandle, type Heic, type LoadedServer, type MarciOp, type PushRelay, type Sharp,
 } from "lecodes-sdk/server"
 import { loadPeer } from "../hosts/peerInstall"
 import { ApiError, sendPush } from "../platform/api"
@@ -21,9 +22,21 @@ import type { FromWorker, LogLevel, PushSender, ToWorker } from "./localBackend"
  * 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.
+ *
+ * A computed's reads are watched by the embedded engine (sdk/server `embeddedWatchSource` over the
+ * handle's `watch`, marcidb-embedded 0.18 on; an older package refuses a subscription to a computed that
+ * reads the database, with that reason), and the bundle's own `op.watch` is the same handle's. LECODES_WATCH=fake
+ * (a test's knob) puts a stand-in in the computeds' place: every write this process sends signals the
+ * watches of the model it wrote — the one process that holds the database sees every write.
+ *
+ * Presence (`watchers`, `members`) is the parent's hub's table: a read is a `presence` message, the answer
+ * a `presenceResult`; a `presenceChanged` runs the computeds that read that key again.
+ *
+ * Under `lecodes test` a case has one clock: the parent's `clock` message moves this process's `Date.now()`
+ * (sdk/server `setServerClock`) with the apps' virtual clocks; `load` carries the offset a process starts with.
  */
 
-type Embedded = {
+type Embedded = EmbeddedWatchHandle & {
   exec(op: unknown): Promise<any>
   batch(ops: unknown[]): Promise<any[]>
   $sync(schema: string): Promise<null>
@@ -45,9 +58,15 @@ const DEV_CODE = "000000"
 let db: Embedded | null = null
 let invoke: ReturnType<typeof createInvoker> | null = null
 let subscribe: ReturnType<typeof createSubscribeGuard> | null = null
+let computed: ComputedHost | null = null
 let authHost: AuthHost | null = null
+const fakeWatch = process.env.LECODES_WATCH === "fake" ? createFakeWatchSource() : null
+/** presence reads on their way to the parent's hub, by their `req` */
+const asks = new Map<number, (sessions: number[]) => void>()
+let nextAsk = 1
 
 const quit = () => {
+  try { computed?.close() } catch { /* nothing to let go */ }
   try { db?.close() } catch { /* already closed */ }
   process.exit(0)
 }
@@ -69,7 +88,8 @@ const openDb = async (dir: string, filesDir: string, schema: string): Promise<st
     db = openDatabase(dir)
   } catch (e) {
     // one process holds a database: the engine's lock is the sign of a second server on this project
-    if (/Locked/i.test((e as Error).message)) throw new Error(`The project's database (${dir}) is in use — this project's backend is already running (another \`lecodes dev\` or \`lecodes desktop run\`). Stop it first.`)
+    // ("is in use" is what the commands that run the app match on: dev/devLink.ts says who could hold it)
+    if (/Locked/i.test((e as Error).message)) throw new Error(`The project's database (${dir}) is in use — another process of this project holds it (a \`lecodes dev\`, a \`desktop run\`, a \`render\`). Stop it first.`)
     throw e
   }
   try {
@@ -114,10 +134,28 @@ const pushRelay = (sender: PushSender): PushRelay => async (to, message) => {
 
 const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   const noDb = () => { throw new Error("db: the database is not open yet — query it inside an endpoint, not while the module loads") }
-  setDbTransport({ exec: (op) => (db ?? noDb()).exec(op), batch: (ops) => (db ?? noDb()).batch(ops) })
+  // the stand-in watch source hears of every write that went through (a test's knob, above)
+  const wrote = (ops: MarciOp[]) => { for (const op of ops) if (!isReadOp(op)) fakeWatch?.fireModel(op.model) }
+  setDbTransport({
+    exec: async (op) => { const r = await (db ?? noDb()).exec(op); wrote([op]); return r },
+    batch: async (ops) => { const r = await (db ?? noDb()).batch(ops); wrote(ops); return r },
+    // the bundle's `op.watch`: the handle's poll, made outside the request that asked (its callbacks outlive it)
+    watch: (op, listener) => {
+      const handle = db ?? noDb()
+      if (typeof handle.watch !== "function") throw new Error("db: this marcidb-embedded has no watch (it came with marcidb-embedded 0.18) — update it")
+      return outsideRequests(() => handle.watch!(op, listener))
+    },
+  })
   setChannelPublisher((ch, group, data) => post({ t: "publish", ch, group, data }))
-  // The project's keys (its .env), before any module-level code can read one
+  // who is subscribed where is the parent's hub's: `watchers` / `members` ask it
+  setPresenceProvider((id, key) => new Promise((resolve) => {
+    const req = nextAsk++
+    asks.set(req, resolve)
+    post({ t: "presence", req, id, key })
+  }))
+  // The project's keys (its .env), before any module-level code can read one; the clock a test runs on, too
   setEnv(m.env)
+  setServerClock(m.clock ?? 0)
   // The bundle is a plain script (chisel esm output with only side effects): registers globalThis.__lecodesServer
   ;(0, eval)(m.code)
   const server: LoadedServer = loadServerModules()
@@ -164,6 +202,7 @@ const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   }
   invoke = createInvoker(server, { auth, files, onError })
   subscribe = createSubscribeGuard(server, { auth, onError })
+  computed = createComputedHost(server, { auth, onError, watch: fakeWatch ?? embeddedWatchSource(() => db) })
   post({ t: "loaded", describe, notes })
 }
 
@@ -177,9 +216,23 @@ process.on("message", async (m: ToWorker) => {
       return post({ t: "result", req: m.req, result })
     }
     case "subscribe": {
-      const result = subscribe ? await subscribe(m.ch, m.args, m.ctx) : { ok: false as const, status: 503, message: "server not loaded" }
+      const result = !subscribe || !computed ? { ok: false as const, status: 503, message: "server not loaded" }
+        : m.sub === undefined ? await subscribe(m.ch, m.args, m.ctx) : await computed.start(m.ch, m.args, m.ctx, m.sub)
       return post({ t: "result", req: m.req, result })
     }
+    case "unsubscribe":
+      computed?.end(m.sub)
+      return
+    case "presenceResult":
+      asks.get(m.req)?.(m.sessions)
+      asks.delete(m.req)
+      return
+    case "presenceChanged":
+      computed?.presenceChanged(m.id, m.key)
+      return
+    case "clock":
+      setServerClock(m.offsetMs)
+      return
     case "stop":
       return quit()
   }