lecodes-cli 2.6.0 → 2.8.0

package/src/commands/render.ts

@@ -4,7 +4,8 @@ import { compileHeadlessBundle } from "../compile/headlessBundle"
 import { screenTargetFrom } from "../compile/screenEntry"
 import { findProjectRoot } from "../project/manifest"
 import { buildBundle } from "./compile"
-import { runBackend } from "../dev/projectBackend"
+import { projectRunBackend } from "../dev/devLink"
+import { callEndpoint } from "../dev/backendCall"
 import { resolvePicks } from "../hosts/flowPick"
 import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
@@ -139,6 +140,8 @@ type ScenarioFile = {
   device?: string
   safeArea?: string
   fixtures?: Record<string, unknown> | string
+  /** How long an expect waits by default, ms. */
+  timeout?: number
   steps: unknown
 }
 
@@ -175,6 +178,7 @@ const readScenarioFile = (path: string): ScenarioFile => {
   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".`)
+  if ((raw as { clients?: unknown }).clients !== undefined) throw new CliError(`"clients" (several clients in one case) runs under \`lecodes test\`: \`lecodes test ${path}\`.`)
   return { ...file, steps: resolvePicks(file.steps, dirname(resolve(path))) }
 }
 
@@ -209,6 +213,7 @@ const renderFlags = {
   "out-dir": str("where --script step outputs land", { value: "<dir>", default: "." }),
   clip: str("(--png) crop to one node's rect or a logical-px rect — a component / region render", { value: "<name|x,y,w,h>" }),
   fixtures: str("canned fetch responses (URL pattern → { status?, json?, text? }) — make backend-gated screens reachable headless; merged over the scenario file's own", { value: "<file>" }),
+  fresh: bool("start on an EMPTY database: the project's backend (a running lecodes dev's, else .lecodes/db) is emptied first — by default its data stays"),
   scale: num("PNG device-pixel scale", { default: 2 }),
   time: num("render at this animation time (0 = the initial frame-0 state)", { value: "<ms>" }),
   "no-after-animations": bool("keep frame 0 instead of advancing animations to their resting state"),
@@ -301,12 +306,14 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
   const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
   // Native plugins (project plugins/ dir + declared libraries) — the host scans CREATOR_PLUGIN_DIRS.
   const { dirs: pluginDirs } = desktopPluginLibraries(root)
-  // The project's backend, when it has one (the database of `lecodes dev`).
-  const backend = runBackend({ root, command: "lecodes render", log: (msg) => { if (logs || msg.includes("[server:error]")) logErr(msg) } })
+  // The project's backend, when it has one: a running `lecodes dev`'s (it holds the database), else one
+  // started for the run on its database (.lecodes/db). --fresh empties it first.
+  const backend = await projectRunBackend({ root, command: "lecodes render", note, log: (msg) => { if (logs || msg.includes("[server:error]")) logErr(msg) } })
   const { js, resources } = await buildBundle(bundleOptions(flags), {
-    localAssets: true, desktopRenderer, backend,
+    localAssets: true, desktopRenderer, backend, ambiguousEntry: "error",
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
   })
+  if (flags.fresh) await backend.reset()
   // The host writes PNGs but never creates folders — make every output dir up front.
   if (!sim) mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
 
@@ -369,18 +376,11 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
   }, timeoutMs)
   killer.unref?.()
 
-  // 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
-    }),
-  }
+  // The project's backend, when it has one: a running `lecodes dev`'s (it holds the database), else one
+  // started for the run on its database (.lecodes/db). --fresh empties it first.
+  const backend = await projectRunBackend({ root: projectRoot, command: "lecodes render", note, log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } })
   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 })
+  if (flags.fresh && serverUrl) await backend.reset()
   const renderer = await requireRenderer()
 
   // Flags override the scenario file's envelope; both fall back to the project default (a
@@ -427,16 +427,27 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
 
   // --script: drive the compiled app through the scenario steps against a live session.
   if (scenario) {
-    const steps = renderer.parseScenarioSteps(scenario.steps)
+    // A running lecodes dev's backend keeps its devices' clock: the run is on real time then (no `clock`
+    // step; a `wait` waits), as `dev --bots` is.
+    const live = !!(serverUrl && backend.dev)
+    const steps = (() => {
+      try { return renderer.parseScenarioSteps(scenario.steps, live ? { realTime: true } : {}) }
+      catch (e) { throw new CliError(`${flags.script}: ${(e as Error).message}`) }
+    })()
     const outDir = flags["out-dir"]
     // Screenshots require pixels; otherwise rasterize opportunistically (napi installed → failure
     // PNGs and real Skia text metrics, absent → deterministic HeadlessHost metrics).
     const needsRaster = steps.some((s) => s.screenshot !== undefined)
     note(`Running ${steps.length} step${steps.length === 1 ? "" : "s"}…`)
-    const session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto" })
-    try {
-      const result = await renderer.runScenario(session, steps, fileScenarioIO(outDir))
-      for (const w of [ ...warnings, ...session.warnings ]) warnErr(w)
+    // one client, the case runner's: its clock is the backend's too (not a dev's), and `call` steps reach the backend as it
+    let session: Awaited<ReturnType<typeof renderer.createSession>> | null = null
+    {
+      const result = await renderer.runCase({
+        clients: [{ name: "app", start: async (env) => (session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto", ...env })) }],
+        single: true, steps, io: fileScenarioIO(outDir), timeoutMs: scenario.timeout, realTime: live,
+        backend: serverUrl ? { url: serverUrl, call: (id, args, device) => callEndpoint(serverUrl, id, args, device), ...(live ? {} : { setClock: (ms: number) => backend.setClock(ms) }) } : undefined,
+      })
+      for (const w of [ ...warnings, ...((session as { warnings: string[] } | null)?.warnings ?? []) ]) warnErr(w)
       for (const st of result.steps) {
         logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}\n  ${c.red(st.error ?? "failed")}`)
       }
@@ -445,8 +456,6 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
       }
       logErr(result.ok ? c.green(`✓ ${result.steps.length}/${steps.length} steps passed`) : c.red(`✗ failed at step ${result.steps.length} of ${steps.length}`))
       return done((cb) => cb(), result.ok ? 0 : 1)
-    } finally {
-      session.dispose()
     }
   }
 

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})` }
+}