animader-cli 0.0.0-stage → 0.1.1

package/adapters/devsession.mjs

@@ -0,0 +1,619 @@
+// The dev session operation (plan section 5): everything `animader dev`
+// does between argv and the process signal wait. It owns one serving
+// lifecycle:
+//
+//   session root (outside the project) ─┬─ generation store (staging,
+//                                        │   publish, retention, sweep)
+//   dev server (player/error page,      │
+//   pinned /gen/<id>/ mounts, channel) ─┘
+//   build loop  ── build = inspect + resolve seconds + runSnapshotBuild
+//                 in a work tree BESIDE the fresh staging root, moved into
+//                 it once finished; publish = store.publish + reload
+//                 broadcast; a dirty candidate is discarded and rebuilt,
+//                 and so is a candidate whose own inputs moved on disk
+//                 while it was built — isStale re-stats them at the
+//                 publish decision, so no event delivery is waited on
+//   watcher     ── filtered recursive fs.watch; every filtered event is a
+//                 PROMPT, never a decision
+//   sweep       ── the stat safety net over the last build's consumed-input
+//                 rows (the receipt's inputs.files) and their directories,
+//                 feeding the SAME loop entry point: a platform watcher
+//                 that goes silent after an atomic save — or a network
+//                 filesystem that answers nothing — still gets its one
+//                 build per edit
+//   session     ── the only decider of "did the inputs change?": a prompt
+//                 from either source asks the loop to LOOK, and before a
+//                 scheduled build starts the session compares the input
+//                 set on disk against its own `attempted` snapshot —
+//                 written when a build starts, pass or fail — and skips
+//                 without building while they are equal, so a replayed
+//                 pre-start write, a platform's late duplicate delivery
+//                 and a failed build's own prompts cost nothing, while
+//                 any real change on disk always answers exactly one
+//                 build. The same comparison decides at the publish
+//                 boundary: a prompt that arrived while the candidate
+//                 was in flight is dropped when the candidate's own start
+//                 snapshot covers its path and the disk still holds that
+//                 identity (the write was consumed; the macOS FSEvents
+//                 late delivery builds nothing), and keeps the discard
+//                 whenever the snapshot cannot speak for the prompted
+//                 path — the same fail-safe direction every unanswerable
+//                 stat takes
+//
+// Each tree under the session root has exactly one owner: a build owns its
+// work tree (input copy and pipeline scratch) and removes it, the store owns
+// the staging roots (one finished generation tree each) and removes them.
+// The server starts BEFORE the first build, so an initial build failure
+// serves the error/recovery page while the watcher stays available; the
+// last successful generation keeps serving byte-identically through failed
+// rebuilds. stop() closes the watcher and the loop, waits for the loop's
+// last cycle to settle (the loop's close must not block on a build, but
+// nothing may remove the session tree under a live writer), then closes
+// the channel connections, the server and the store, in that order.
+
+import { promises as fsp } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+import { runSnapshotBuild, createBuildProducers } from './build-node.mjs';
+import { startDevServer } from './devserver.mjs';
+import { launchBrowser } from './launch.mjs';
+import { createGenerationStore } from './generations.mjs';
+import { createProjectWatchFilter, watchProject, createInputSweep, statRow, statDir, DEFAULT_SWEEP_INTERVAL_MS } from './watch.mjs';
+import { createNodeIo } from './node-fs.mjs';
+import { createPngineNative } from './pngine.mjs';
+import { createBuildLoop } from '../lib/buildloop.mjs';
+import { errorLines, DemoError } from '../lib/errors.mjs';
+import { inspectProject, PROJECT_FILES, SOUNDTRACK_NAMES } from '../lib/contract.mjs';
+import { contributorToolchain, resolveToolchain } from '../src/toolchain.mjs';
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * The fixed seat names the session always carries in its input snapshot,
+ * even before the first build has returned receipt rows to record: their
+ * identities (a missing seat is its own value — exactly one soundtrack
+ * candidate survives inspection) are what a first, failing build's
+ * attempted snapshot can still see, so the edit that fixes it answers a
+ * build rather than a skip.
+ */
+const SEAT_INPUT_ROWS = Object.freeze([
+  PROJECT_FILES.program,
+  PROJECT_FILES.timeline,
+  ...SOUNDTRACK_NAMES,
+]);
+
+/**
+ * @param {Object} options
+ * @param {string} options.folder the project folder (realpath'd here; a
+ *   missing folder is a hard failure before any server work)
+ * @param {number} [options.port] 127.0.0.1 port; 0 chooses a free one
+ * @param {boolean} [options.open] attempt the browser launch once the
+ *   first build settles
+ * @param {boolean} [options.watch] watch for edits and rebuild (the
+ *   `--no-watch` spelling passes false)
+ * @param {() => Promise<{seconds: number}>} options.resolveSeconds the
+ *   per-build host-length resolution (animader.json validated, then any
+ *   explicit override)
+ * @param {(line: string) => void} [options.out] stdout line writer
+ * @param {(line: string) => void} [options.err] stderr line writer
+ * @param {{native?: object, toolchain?: object, vendorRoot?: string, producers?: object,
+ *          launch?: Function, watchImpl?: Function}} [options.hosts] test
+ *   seams; the defaults are this workspace's real pngine CLI, the
+ *   prepared bundle, the real build producer ports, the platform-aware
+ *   browser launcher and the host's own recursive fs.watch
+ * @param {number} [options.debounceMs] the burst-coalescing window
+ * @param {number} [options.sweepIntervalMs] the stat safety net's period
+ *   (default ~1 s; 0 is not a period)
+ * @param {string} [options.sessionRoot] the session tree's own root
+ *   directory, ensured to exist (default: a fresh OS temporary directory,
+ *   outside the project)
+ * @returns {Promise<{served: object, store: object, stop: () => Promise<{published: boolean, lastError: Object|null}>}>}
+ */
+export async function runDevSession({
+  folder,
+  port = 0,
+  open = true,
+  watch = true,
+  resolveSeconds,
+  out = (line) => process.stdout.write(`${line}\n`),
+  err = (line) => process.stderr.write(`${line}\n`),
+  hosts = {},
+  debounceMs,
+  sweepIntervalMs = DEFAULT_SWEEP_INTERVAL_MS,
+  sessionRoot,
+}) {
+  if (typeof resolveSeconds !== 'function') {
+    throw new TypeError('runDevSession needs a resolveSeconds function (the shared config resolution)');
+  }
+
+  let real;
+  try {
+    real = await realpath(folder);
+  } catch {
+    throw new DemoError('folder_missing', `the project folder does not exist: ${folder}`, {
+      exitCode: 3,
+      remedy: 'Pass the folder that holds program.sjon, timeline.piece.sjon and one of soundtrack.wav, soundtrack.ogg, soundtrack.opus.',
+    });
+  }
+
+  const io = createNodeIo();
+  const toolchain = hosts.toolchain ?? (hosts.vendorRoot !== undefined
+    ? contributorToolchain({ vendorRoot: hosts.vendorRoot })
+    : await resolveToolchain());
+  const runtime = { verify: () => toolchain.verifyRuntime() };
+  const native = hosts.native ?? createPngineNative({ binary: toolchain.pngine.cli });
+  const producers = hosts.producers ?? createBuildProducers({ toolchain });
+  const launch = hosts.launch ?? ((url) => launchBrowser(url));
+
+  const root = sessionRoot ?? await fsp.mkdtemp(join(tmpdir(), 'animader-dev-session-'));
+  await fsp.mkdir(root, { recursive: true });
+  const store = createGenerationStore({ root });
+  let lastError = null;
+  let everPublished = false;
+  let watcher = null;
+  let sweep = null;
+  // The publish-time freshness record: the receipt input rows of the last
+  // build that returned one, stat'd at the instant each build STARTS — the
+  // same "everything up to this instant is inside this build" boundary the
+  // sweep's accounted() draws. isStale re-stats those rows when the build
+  // resolves: any difference means an input moved under the candidate, and
+  // the candidate is discarded and rebuilt even if no watcher event has
+  // been delivered yet (the decision reads the filesystem; it does not
+  // wait for delivery).
+  let inputRows = [];
+
+  // The session's own record of the inputs the last attempted build
+  // covers — the snapshot the skip compares. Written when a build STARTS
+  // (pass or fail: a failed attempt still counts as attempted, which is
+  // what keeps its own prompts from retrying it) over the last returning
+  // build's receipt rows plus the fixed seat names, at the same boundary
+  // accounted() draws; re-adopted at each publish over the receipt's own
+  // rows, so the snapshot always covers what the served generation
+  // consumed. Files carry `statRow` identities, directories the same
+  // filtered listing keys the sweep compares; a missing path is its own
+  // value, so a deletion is a change and an unanswerable stat is a
+  // change. Null until the first build starts; the skip fails open then.
+  let attempted = null; // { files: Map<path, identity>, dirs: Map<dir, key> }
+
+  // Project-relative input rows ('/'-separated, the receipt's spelling)
+  // and the directories that hold them, as absolute paths.
+  const inputPath = (row) => join(real, ...row.split('/'));
+  const inputDirRow = (row) => {
+    const cut = row.lastIndexOf('/');
+    return cut === -1 ? '' : row.slice(0, cut);
+  };
+
+  // The one path policy everything shares: the watcher's filter, the
+  // sweep's directory listings and this session's own snapshots.
+  const watchFilter = createProjectWatchFilter({ projectRoot: real });
+
+  // ANIMADER_WATCH_TRACE=1: one line per prompt decision (the prompted
+  // path, its identity, the attempted identity for that path, and the
+  // verdict), one line per build (its reason: changed, or the rebuild a
+  // stale-at-publish discard owes), one line per publish (the generation
+  // and the published snapshot's digest). The prompt LABELS are recorded
+  // always — the discard decision's fail-safe needs to know which paths
+  // arrived during a build — but nothing is stat'd, hashed or printed for
+  // the trace unless the flag is set. The escape hatch exists for the day
+  // a platform disagrees, so the next step is a trace file rather than
+  // another hypothesis.
+  const traceEnabled = process.env.ANIMADER_WATCH_TRACE === '1';
+  const trace = (line) => { if (traceEnabled) err(`watch trace: ${line}`); };
+  const pendingPrompts = []; // project-relative labels (or '(no path)'), awaiting the next decision
+  let owedBuildReason = null; // 'stale-at-publish' when a discard owes the next build
+
+  const served = await startDevServer({
+    generations: store,
+    runtimeRoot: toolchain.runtime.kind === 'dir' ? toolchain.runtime.root : undefined,
+    runtimeFiles: toolchain.runtime.kind === 'map' ? await installedRuntimeFiles(toolchain, root) : undefined,
+    latestError: () => lastError,
+    // A request-path fault reaches the session's dev log (the err seam),
+    // never a silent bare 500.
+    onFault: (line) => err(line),
+    port,
+  });
+
+  out('animader dev — edit, build and reload (one generation per build)');
+  out(`project: ${real}`);
+  out(`serving: ${served.url}`);
+  out('page: the player at / (an error/recovery page until the first build succeeds)');
+  out('channel: /dev (development only: reload on successful builds, stale on failures)');
+
+  function reportBuildError(error) {
+    lastError = error;
+    for (const line of errorLines(error)) err(line);
+    if (!everPublished) {
+      out('no generation yet: / serves the build error page until a build succeeds');
+    }
+    served.channel.broadcast('stale', {
+      error: {
+        code: error?.code ?? null,
+        message: error?.message ?? String(error),
+        remedy: error?.remedy ?? null,
+      },
+    });
+  }
+
+  /**
+   * The installed runtime mount: the manifest's resolved files plus the
+   * rendered provenance document the page's boot fetches from
+   * /runtime/provenance.json. The rendered file lives in this session's
+   * own tree, so the store's cleanup owns it.
+   */
+  async function installedRuntimeFiles(toolchain, sessionRoot) {
+    const files = await toolchain.runtime.files();
+    const { provenance } = await toolchain.verifyRuntime();
+    const provenancePath = join(sessionRoot, 'runtime-provenance.json');
+    await fsp.writeFile(provenancePath, `${JSON.stringify(provenance, null, 2)}\n`);
+    files.push({ path: 'provenance.json', source: provenancePath });
+    return files;
+  }
+
+  async function build() {
+    // The sweep's baselines move to NOW before anything is read: every
+    // change up to this instant is inside the build that starts here, so
+    // the sweep cannot re-report it as a second change (a watcher event
+    // plus a sweep hit for one edit stays exactly one build). This runs
+    // for failing builds too: their inputs are accounted all the same,
+    // which is what keeps a failed rebuild from looping on the sweep.
+    sweep?.accounted();
+    // The attempted snapshot, drawn at the same boundary: every input row
+    // the last returning build recorded, plus the fixed seat names and
+    // the filtered listings of the directories that hold them. Before the
+    // first build returns there are no receipt rows — the seats and the
+    // root listing stand in for them. This is written before anything is
+    // read and survives a failing build: the inputs a failed build
+    // attempted are exactly these, so no prompt for them can retry it.
+    const startRows = [...new Set([...inputRows, ...SEAT_INPUT_ROWS])];
+    const startFiles = await Promise.all(startRows.map(async (row) => [inputPath(row), await statRow(inputPath(row))]));
+    const startDirs = await Promise.all(
+      [...new Set(startRows.map(inputDirRow))].map(async (dirRow) => [inputPath(dirRow), await statDir(inputPath(dirRow), watchFilter)]),
+    );
+    attempted = { files: new Map(startFiles), dirs: new Map(startDirs) };
+    const buildReason = owedBuildReason ?? 'changed';
+    owedBuildReason = null;
+    trace(`build: reason=${buildReason}`);
+    // The candidate's own freshness baseline, taken in the same pass: the
+    // receipt rows of the last returning build, at the identities they
+    // hold now. Anything that differs from this record by the time the
+    // build resolves moved under the candidate, whether or not any event
+    // said so.
+    const freshness = inputRows.map((row) => {
+      const path = inputPath(row);
+      return [path, attempted.files.get(path)];
+    });
+    const staging = await store.stagingRoot();
+    let work = null;
+    try {
+      // A fresh inspection per build: the soundtrack selection and the
+      // authored bytes are whatever the project holds now, and the
+      // pipeline's own drift check refuses a project that changed under
+      // the snapshot.
+      const project = await inspectProject({ folder: real, io });
+      const { seconds } = await resolveSeconds();
+      // The snapshot's input copy and the pipeline's scratch live beside
+      // the staging root (this build owns and removes that work tree), so
+      // the staging root holds exactly the finished generation tree and
+      // only the store ever removes it — one owner per tree.
+      const { built, work: workTree, workProject } = await runSnapshotBuild({
+        project,
+        seconds,
+        projectName: basename(real),
+        native,
+        runtime,
+        producers,
+        io,
+        workRoot: root,
+      });
+      // The sweep's next set is THIS build's own consumed-input record —
+      // the receipt's rows, the one input list that cannot drift from
+      // what the build actually reads (program, timeline, soundtrack and
+      // every authored resource beside them, kernels included). The
+      // publish-time freshness record adopts the same rows: the next
+      // build's baseline stats them at its own start.
+      const rows = built.receipt.inputs.files.map((row) => row.path);
+      sweep?.inputs(rows);
+      inputRows = rows;
+      work = workTree;
+      const dir = join(staging, 'project');
+      await fsp.rename(workProject, dir);
+      await fsp.rm(work, { recursive: true, force: true });
+      work = null;
+      return {
+        staging,
+        dir,
+        seconds,
+        soundtrack: project.files.soundtrack.name,
+        freshness,
+        // The same start snapshot's directory keys: the discard decision
+        // re-stats them beside the file rows, so a file created inside a
+        // covered directory while this build ran still discards the
+        // candidate even when no prompt for it arrives.
+        startDirs: [...startDirs],
+      };
+    } catch (cause) {
+      if (work !== null) {
+        await fsp.rm(work, { recursive: true, force: true }).catch(() => {});
+      }
+      await fsp.rm(staging, { recursive: true, force: true });
+      throw cause;
+    }
+  }
+
+  async function discard(candidate) {
+    await fsp.rm(candidate.staging, { recursive: true, force: true });
+    out('build discarded: the project changed during the build; rebuilding before publishing');
+  }
+
+  /**
+   * The publish-time authority on whether the candidate's inputs moved:
+   * re-stat every row baselined when its build started and answer true on
+   * any difference — a changed identity, a path now missing, a replaced
+   * file — or on a stat that cannot answer at all. Unanswerable is a
+   * change here, the safe direction for a publish decision (unlike a
+   * 404): a candidate whose freshness cannot be proven is never served.
+   * The same pass covers the start snapshot's directory keys, and every
+   * prompt that arrived while the candidate was in flight is judged
+   * against that snapshot: a prompt whose path it covers has just been
+   * proven equal — the build consumed that write, and the prompt is a
+   * late duplicate (the macOS FSEvents shape) that must be dropped —
+   * while a prompt the snapshot cannot speak for keeps the discard, the
+   * same safe direction `needsBuild` takes. Before the first build
+   * returns there are no rows, so the initial candidate is judged by the
+   * loop's dirty flag alone.
+   */
+  async function isStale(candidate) {
+    for (const [path, was] of candidate.freshness) {
+      const now = await statRow(path);
+      if (now !== was || (typeof now === 'string' && now.startsWith('unreadable:'))) {
+        trace('discard: the candidate\'s inputs moved while it was built (stale at publish)');
+        owedBuildReason = 'stale-at-publish';
+        return true;
+      }
+    }
+    for (const [dir, wasKey] of candidate.startDirs ?? []) {
+      if (wasKey !== await statDir(dir, watchFilter)) {
+        trace('discard: the candidate\'s input directories moved while it was built (stale at publish)');
+        owedBuildReason = 'stale-at-publish';
+        return true;
+      }
+    }
+    // The prompts that arrived while this candidate was in flight (both
+    // sources feed the same list). The passes above proved every covered
+    // path equal, so a covered prompt is a duplicate the build already
+    // consumed; an uncovered prompt — a new path the start snapshot
+    // cannot speak for, or an event that named no path — keeps the
+    // discard: dropping what cannot be proven would be the missed-edit
+    // direction.
+    const batch = pendingPrompts.splice(0);
+    let kept = false;
+    for (const label of batch) {
+      if (!coveredByStartSnapshot(candidate, label)) {
+        kept = true;
+        break;
+      }
+    }
+    await tracePromptDecisions(batch, kept ? 'keep' : 'drop');
+    if (kept) {
+      trace('discard: a prompt arrived during the build for a path its start snapshot does not cover');
+      owedBuildReason = 'stale-at-publish';
+      return true;
+    }
+    return false;
+  }
+
+  /** Can the candidate's own start snapshot speak for a prompted path?
+   *  Only a covered path can be proven already-consumed; everything else
+   *  keeps the discard. */
+  function coveredByStartSnapshot(candidate, label) {
+    if (label === '(no path)') return false;
+    const isDir = label.endsWith('/');
+    const path = inputPath(label.replace(/\/+$/, ''));
+    return isDir
+      ? candidate.startDirs?.some(([dir]) => dir === path) === true
+      : candidate.freshness.some(([file]) => file === path);
+  }
+
+  async function publish(candidate) {
+    const generation = await store.publish({
+      staging: candidate.staging,
+      dir: candidate.dir,
+      seconds: candidate.seconds,
+      soundtrack: candidate.soundtrack,
+    });
+    everPublished = true;
+    lastError = null;
+    // The attempted snapshot moves to what this publish made current: the
+    // receipt's own rows. A row the candidate baselined keeps that
+    // baseline's identity — isStale just proved the disk still holds it,
+    // so it is what the build provably consumed; a row the baseline never
+    // covered (an input created since the last receipt) is stat'd now,
+    // the same adoption the sweep's own inputs() makes. Directory keys
+    // already held stay held for the same reason the sweep keeps them (a
+    // listing that moved during the build must still look moved), and
+    // every row, held or new, is re-read whole when the next build
+    // starts. A prompt that arrives now finds the inputs equal to the
+    // published attempt and builds nothing.
+    const consumed = new Map(candidate.freshness);
+    const held = attempted ?? { files: new Map(), dirs: new Map() };
+    const rows = [...new Set(inputRows)];
+    attempted = {
+      files: new Map(await Promise.all(rows.map(async (row) => {
+        const path = inputPath(row);
+        return [path, consumed.has(path) ? consumed.get(path) : await statRow(path)];
+      }))),
+      dirs: new Map(await Promise.all([...new Set(rows.map(inputDirRow))].map(async (dirRow) => {
+        const dir = inputPath(dirRow);
+        return [dir, held.dirs.has(dir) ? held.dirs.get(dir) : await statDir(dir, watchFilter)];
+      }))),
+    };
+    if (traceEnabled) {
+      const digest = createHash('sha256')
+        .update([...attempted.files].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, identity]) => `${relative(real, path)}\0${identity}\n`).join(''))
+        .update([...attempted.dirs].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([dir, key]) => `d:${relative(real, dir)}\0${key}\n`).join(''))
+        .digest('hex')
+        .slice(0, 12);
+      trace(`publish: generation=${generation.id} snapshot=${digest}`);
+    }
+    out(`build ${generation.id}: ok — ${candidate.seconds}s, soundtrack ${candidate.soundtrack}`);
+    out(`generation ${generation.id}: ${store.pageUrl(generation.id)} (immutable while retained)`);
+    served.channel.broadcast('reload', {
+      generation: generation.id,
+      url: store.pageUrl(generation.id),
+    });
+  }
+
+  const loop = createBuildLoop({ build, discard, publish, onError: reportBuildError, isStale, shouldBuild: needsBuild, debounceMs });
+
+  /**
+   * The session's answer to "does a prompt owe a build?", asked by the
+   * loop whenever a scheduled build is about to start: one stat pass over
+   * the attempted snapshot's recorded rows and directory listings,
+   * compared by identity. Nothing attempted yet (before the first build
+   * starts) fails open and builds; after that, equal means skip — the
+   * last attempt already covers exactly what is on disk, whether it
+   * published or failed. An unanswerable stat is its own identity
+   * difference, the safe direction: the skip can never hide an edit it
+   * could not read.
+   */
+  async function needsBuild() {
+    if (attempted === null) return true;
+    const files = await Promise.all(
+      [...attempted.files].map(async ([path, was]) => was !== await statRow(path)),
+    );
+    const moved = files.some(Boolean)
+      || (await Promise.all([...attempted.dirs].map(async ([dir, was]) => was !== await statDir(dir, watchFilter)))).some(Boolean);
+    await tracePromptDecisions(pendingPrompts.splice(0), moved ? 'build' : 'skip');
+    return moved;
+  }
+
+  /**
+   * One trace line per prompt awaiting this decision: the prompted path
+   * (project-relative, or '(no path)'), its identity on disk now, the
+   * attempted identity for that path, and the verdict. The batch arrives
+   * already taken — both decision points (the cycle-entry skip and the
+   * discard decision's drop/keep) consume the list regardless of the
+   * flag, so a prompt is never judged twice. Records nothing unless
+   * ANIMADER_WATCH_TRACE is set.
+   */
+  async function tracePromptDecisions(batch, verdict) {
+    if (!traceEnabled) return;
+    for (const label of batch) {
+      await traceOnePrompt(label, verdict);
+    }
+  }
+
+  async function traceOnePrompt(label, verdict) {
+    if (label === '(no path)') {
+      trace('prompt (no path) → ' + verdict);
+      return;
+    }
+    const isDir = label.endsWith('/');
+    const path = inputPath(label.replace(/\/+$/, ''));
+    const identity = isDir ? await statDir(path, watchFilter) : await statRow(path);
+    const was = isDir ? attempted.dirs.get(path) : attempted.files.get(path);
+    trace(`prompt ${label} identity=${identity} attempted=${was ?? '(none)'} → ${verdict}`);
+  }
+
+  // Both prompt sources feed the SAME loop entry point, and neither
+  // decides anything: the watcher's filtered event is one prompt, and the
+  // sweep's own difference report is another. Every label is recorded
+  // (the discard decision's fail-safe judges them against the build's
+  // start snapshot) and consumed by whichever decision runs next — the
+  // cycle-entry skip or the discard decision. Whether a prompt means a
+  // change is answered here alone, from the filesystem, against the
+  // session's own snapshot — never from the event's metadata, a wall
+  // clock or a comparison against a baseline of events.
+  const promptWatcherChange = (source) => {
+    pendingPrompts.push(source === null ? '(no path)' : relative(real, source).split('\\').join('/'));
+    loop.notifyChange();
+  };
+  const promptSweepChange = (reasons) => {
+    pendingPrompts.push(...reasons);
+    loop.notifyChange();
+  };
+
+  // The watcher starts BEFORE the initial build: an edit landing during
+  // that first build is exactly the dirty-candidate case the loop discards
+  // and rebuilds, so no change window exists between watching and building.
+  // The stat sweep stands beside it from the same instant, over the same
+  // exclusion filter, feeding the same loop entry point: whatever the
+  // platform watcher does or does not report, an authored edit still gets
+  // its one build.
+  if (watch) {
+    sweep = createInputSweep({
+      folder: real,
+      filter: watchFilter,
+      intervalMs: sweepIntervalMs,
+      onChange: promptSweepChange,
+    });
+    try {
+      watcher = watchProject({
+        folder: real,
+        filter: watchFilter,
+        onChange: promptWatcherChange,
+        onError: (error) => {
+          for (const line of errorLines(error)) err(line);
+          // Watching stops loudly; serving, the last generation and the
+          // stat sweep stay, so edits still rebuild.
+          watcher?.close();
+          watcher = null;
+        },
+        watchImpl: hosts.watchImpl,
+      });
+      out(`watching: ${real} (recursive; out/, dist/ and build debris excluded)`);
+    } catch (cause) {
+      for (const line of errorLines(cause)) err(line);
+      out('serving without a platform watcher: the stat sweep still rebuilds on edits; fix the named problem and restart animader dev for immediate watcher events');
+    }
+    out(`sweeping: the last build's input set and its directories every ${sweepIntervalMs}ms (stat safety net beside the watcher)`);
+  } else {
+    out('watching disabled (--no-watch): this build is served without rebuilds');
+  }
+
+  // The initial build runs through the same loop as every later one. The
+  // session returns live: `settled` resolves once the first build (and any
+  // change-during-build follow-up) is done.
+  loop.kick();
+  const settled = loop.idle();
+  const opened = settled.then(async () => {
+    if (!open) return;
+    const launched = await launch(served.url);
+    if (launched.ok) {
+      out(`opened ${served.url} with ${launched.command}`);
+    } else {
+      err(`browser launch failed: ${launched.reason}`);
+      err(`open ${served.url} manually; the server is still running and no launch is claimed.`);
+    }
+  });
+  void opened.catch(() => {});
+
+  let stopped = false;
+  async function stop() {
+    if (stopped) return { published: everPublished, lastError };
+    stopped = true;
+    watcher?.close();
+    sweep?.close();
+    await loop.close();
+    // The loop's close() is final but deliberately does not wait for an
+    // in-flight build (it must not block on one), and that cycle still
+    // writes into the session root — including one further build a dirty
+    // cycle had queued inside itself. stop() is where the writers can be
+    // ordered against the removal, so it waits for the last cycle to
+    // settle before anything deletes the trees: `running` goes false only
+    // after the cycle's final discard or publish step, and once it is
+    // false no step can start again (close() saw to that).
+    while (loop.running) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    await served.close();
+    await store.dispose();
+    return { published: everPublished, lastError };
+  }
+
+  return { served, store, stop, settled };
+}