@nika-js/onlymap 0.6.15 → 0.6.17

package/CHANGELOG.md

@@ -8,6 +8,27 @@ Note: npm collapsed a few closely-spaced releases — the GPX/FlatGeobuf (0.5.4)
 and GeoParquet (0.5.5) work shipped to npm together as **0.5.6**, so npm's
 version list jumps 0.5.3 → 0.5.6. Each logical version is listed here regardless.
 
+## 0.6.17 — 2026-08-25
+
+### Added
+- **Sharp story flybys over 3D tiles.** `<om-story warm-tiles>` pre-loads every 3D tileset's tiles along the story's camera route in the background before playback, so fly-bys no longer pop in or refine from blurry to clear mid-flight. Also available as the `warm-tiles` action for one-off takes; per-layer `load-options='{"tileset":{"maximumMemoryUsage":512}}'` keeps more tiles cached for long routes.
+- **Flawless flyby takes with `<om-story paced>`.** Where pre-loading isn't enough (very heavy scenes like Google Photorealistic 3D Tiles), a paced story holds each frame until the 3D tiles under the camera have fully sharpened before moving on — the flight takes longer to play, but no frame ever shows blurry tiles, which is exactly what a recorded take needs. Combine with `warm-tiles` to shorten the holds; each frame reports its wait through the new `om-paced-tick` event.
+- **Record a story straight to video: `npx onlymapjs record map.html --out flyby.mp4`.** Plays the story load-paced in headless Chromium and writes an H.264/VP9 video in which every frame's 3D tiles are fully sharp — widgets, overlays, and provider attribution included. Uses ffmpeg when installed (otherwise you get the PNG frames plus the exact command to run); `--fps`, `--width/--height/--scale` (retina takes), `--story`, `--keep-frames`, `--timeout`, `--max-hold`. Frames captured before a deadline hit are kept for salvage instead of discarded. Custom recorders can hook the same seam with `storyEl.setPacedCapture(...)` — the story waits for your capture before advancing, so screenshots can never tear between frames.
+- **`--gpu` makes recordings several times faster on heavy 3D scenes.** Headless Chromium renders on software GL by default, which slows every tile-refinement round; `--gpu` switches `onlymapjs record` to the machine's real GPU (measured ~3× shorter tile holds on a Google Photorealistic 3D Tiles take, identical output sharpness). Recommended whenever a recording holds long for tiles.
+- **`paced-max-hold` on `<om-story>`** tunes how long a paced frame may wait for tiles before moving on (default 10s — the safety valve that keeps a dead tile server from freezing playback). Very heavy scenes can genuinely need longer per frame; raise it (e.g. `paced-max-hold="30s"`, or `--max-hold 30` when recording), or set `"none"` to wait unconditionally — the truly-no-blurry-frame mode for recorded takes.
+
+### Fixed
+- **Story fly-to steps written as `longitude="…" latitude="…"` now actually pan the camera.** Previously only the documented `center="[lng, lat]"` form moved the map (bare longitude/latitude were silently ignored by playback, though route pre-loading read them); both forms now work everywhere, and zoom-only fly-to steps are included in route pre-loading too.
+- **Warm-up passes are sturdier.** Pre-loading now waits for tilesets that are still fetching their `tileset.json` instead of silently warming nothing; a partial warm on any tileset is reported as partial; overlapping warm passes no longer leave a tileset rendering coarser than authored; and `samples`/`budget` values written as attributes (strings) are honored.
+- **Paced playback is sturdier too.** Pausing then seeking in the same breath no longer loses the camera position; a failing recorder capture pauses the story instead of wedging it; and a dead tile server on the final frame can always be escaped with pause — even under `paced-max-hold="none"`.
+
+## 0.6.16 — 2026-08-24
+
+### Added
+- **Packaged mobile apps now identify themselves in usage telemetry.** `configureTelemetry({ platform, appId })` lets a native host (like `@nika-js/onlymap-native`) report the store app identity and platform instead of a meaningless embedded-WebView hostname. Web pages are unaffected; the same privacy rules apply.
+
+### Fixed
+- **A license key that cannot verify now says so on the page.** In a context without `crypto.subtle` (an insecure or misconfigured embed), key verification used to log only a console warning while the map silently ran in the free tier; it now also raises a structured validation error with a fix hint through the normal error channel.
 ## 0.6.15 — 2026-08-21
 
 ### Changed

package/README.md

@@ -147,7 +147,7 @@ Built-in actions wire to picks, widget buttons (`data-emit`), or script (`ctx.em
 
 **Animation:** camera moves accept a duration — `map.flyTo(coords, zoom, { duration: 1200, curve: true })`, or the `fly-to` action (`center`/`zoom`/`pitch`/`bearing`/`duration`) from any behavior or button; `prefers-reduced-motion` is honored (moves become instant, final state identical). Per-prop GPU transitions via the `transition` attribute: `transition="get-fill-color 800ms"` fades color changes; on a streaming layer, `transition="get-position 300ms"` makes entities glide between updates.
 
-**Map stories:** a guided tour as markup — `<om-story>` holds `<om-step>` children that fire the same actions behaviors use, on a timeline (`duration`, `delay`, `parallel`); the built-in `type="player"` widget gives play/pause/scrub, seeking restores the scene's captured initial state, one story is active per map, and grabbing the map pauses playback. Effect verbs — `fade`, `pulse`, `trace` (progressive TripsLayer draw-on; with `feature-id`, a single polygon draws itself on inside its own layer), and `populate` (rows drop in one by one via a GPU filter sweep) — work as step shorthands or plain actions. The story is a sibling that references layers by id — delete it and the map is unchanged. Guide: [docs/stories.md](docs/stories.md).
+**Map stories:** a guided tour as markup — `<om-story>` holds `<om-step>` children that fire the same actions behaviors use, on a timeline (`duration`, `delay`, `parallel`); the built-in `type="player"` widget gives play/pause/scrub, seeking restores the scene's captured initial state, one story is active per map, and grabbing the map pauses playback. Effect verbs — `fade`, `pulse`, `trace` (progressive TripsLayer draw-on; with `feature-id`, a single polygon draws itself on inside its own layer), and `populate` (rows drop in one by one via a GPU filter sweep) — work as step shorthands or plain actions. The story is a sibling that references layers by id — delete it and the map is unchanged. For flybys over 3D tilesets, `warm-tiles` pre-loads the route's tiles in the background before playback, and `paced` goes further: the story steps its own clock and never advances a frame while a tileset is still refining, so no frame ever shows unrefined tiles — wall-clock stretches instead (built for recorded takes; emits `om-paced-tick {t, waitedMs}` per frame, and the two compose — warm first, wait less). `npx @nika-js/onlymap record map.html --out flyby.mp4` turns that guarantee into an actual video: one screenshot per paced frame in headless Chromium (widgets and attribution included), assembled with ffmpeg. Guide: [docs/stories.md](docs/stories.md).
 
 **Classified symbology:** `classify-by="magnitude" classify-scale="jenks" classify-classes="5" classify-ramp="viridis"` computes class breaks *from the data* (quantile, equal-interval, or Jenks natural breaks), styles the layer with a named ramp, and auto-generates the classes legend — no domains or colors to hand-author; an explicit `get-fill-color`/`color` always wins. **Temporal playback:** `<om-widget type="time-slider" layer="…" field="time" duration="20s" window="86400000" format="date">` is a play/pause/scrub control over a layer's time field, driving the same `filter-layer` mechanics as the filter widget (stats stay coherent; `loop` restarts the sweep).
 
@@ -337,7 +337,7 @@ The `appId` must come from trusted native build metadata, never page/bridge inpu
 
 ## Telemetry
 
-The library reports one **deployment-scoped** usage snapshot per map per page load — layer types and counts, widget types, renderer; hostname only, no page URLs, no visitor identifiers, and `headless` (test) maps never report — plus errors caused by the library's own code (own-bundle stack filtering, scrubbed, rate-limited). Reports go to a first-party endpoint, never a third-party domain. Opt out globally with `OmMap.configureTelemetry({ disabled: true })` or per map with `telemetry="off"`. Full schema, rules, and the license disclosure: [docs/telemetry.md](docs/telemetry.md), LICENSE.md §11.
+The library reports one **deployment-scoped** usage snapshot per map per page load — layer types and counts, widget types, renderer; hostname only (a packaged mobile app reports its declared app id instead, since an embedded WebView's hostname identifies nothing), no page URLs, no visitor identifiers, and `headless` (test) maps never report — plus errors caused by the library's own code (own-bundle stack filtering, scrubbed, rate-limited). Reports go to a first-party endpoint, never a third-party domain. Opt out globally with `OmMap.configureTelemetry({ disabled: true })` or per map with `telemetry="off"`. Full schema, rules, and the license disclosure: [docs/telemetry.md](docs/telemetry.md), LICENSE.md §11.
 
 ## Not implemented yet (honestly)
 

package/bin/onlymapjs.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { createServer } from "node:http";
-import { dirname, extname, join, resolve, sep } from "node:path";
+import { basename, dirname, extname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const CUSTOM_DATA = "./node_modules/@nika-js/onlymap/onlymapjs.html-data.json";
@@ -11,6 +12,7 @@ function usage() {
   console.log(`Usage:
   onlymapjs init [--force]
   onlymapjs check-layout <manifest.html>
+  onlymapjs record <manifest.html> [options]
   onlymapjs --help
 
 Commands:
@@ -18,12 +20,62 @@ Commands:
   check-layout
              Load a browser-runnable manifest in isolated headless Chromium,
              audit real widget geometry at 360/640/768/1024px, and exit 0/1.
-
-Options:
+  record     Play a story load-paced in isolated headless Chromium and write a
+             video in which every frame's 3D tiles are fully refined — no
+             pop-in, no blur, however slow the tile server. Captures one
+             screenshot per story frame (widgets, overlays, and attribution
+             included) and assembles with ffmpeg when available (PNG frames +
+             a printed ffmpeg command otherwise). Needs Playwright.
+
+Options (init):
   --force    Overwrite .vscode/${SNIPPET_FILE} if it already exists.
+
+Options (record):
+  --story <id>     Which <om-story> to record (default: the first one).
+  --out <file>     Output path; .mp4 (H.264) or .webm (VP9). Default <manifest>.mp4.
+  --fps <n>        Story frames per second (default: the story's paced="…" value, else 30).
+  --width <px>     Viewport width in CSS px (default 1280).
+  --height <px>    Viewport height in CSS px (default 720).
+  --scale <n>      Device scale factor — 2 renders retina frames (default 1).
+  --gpu            Render on the real GPU (ANGLE Metal on macOS) instead of
+                   headless Chromium's default software GL — measured ~3×
+                   shorter tile holds on Google Photorealistic 3D Tiles.
+  --keep-frames    Keep the PNG frame directory next to the output.
+  --timeout <s>    Overall recording deadline in seconds (default 600). Frames
+                   captured before a deadline hit are kept for salvage.
+  --max-hold <s|none>
+                   Per-frame tile-wait cap (default 10). Heavy tilesets that
+                   keep hitting the cap may carry residual blur — raise it, or
+                   pass "none" to wait unconditionally for full refinement
+                   (guaranteed-sharp; only --timeout bounds the run then).
 `);
 }
 
+async function importPlaywright(commandName) {
+  try {
+    return await import("playwright");
+  } catch (error) {
+    if (error?.code === "ERR_MODULE_NOT_FOUND" || String(error).includes("Cannot find package 'playwright'")) {
+      throw new Error(
+        `${commandName} needs Playwright in this project.\n` +
+          "Install it with:\n  npm install --save-dev playwright\n  npx playwright install chromium",
+      );
+    }
+    throw error;
+  }
+}
+
+async function launchChromium(playwright, args = []) {
+  try {
+    return await playwright.chromium.launch({ headless: true, args });
+  } catch (error) {
+    if (String(error).includes("Executable doesn't exist") || String(error).includes("browserType.launch")) {
+      throw new Error(`Chromium is not installed for Playwright.\nRun:\n  npx playwright install chromium\n\n${String(error)}`);
+    }
+    throw error;
+  }
+}
+
 const MIME_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -107,18 +159,7 @@ async function checkLayout(manifestArg) {
     throw new Error(`check-layout expects an .html manifest, received: ${manifestPath}`);
   }
 
-  let playwright;
-  try {
-    playwright = await import("playwright");
-  } catch (error) {
-    if (error?.code === "ERR_MODULE_NOT_FOUND" || String(error).includes("Cannot find package 'playwright'")) {
-      throw new Error(
-        "check-layout needs Playwright in this project.\n" +
-          "Install it with:\n  npm install --save-dev playwright\n  npx playwright install chromium",
-      );
-    }
-    throw error;
-  }
+  const playwright = await importPlaywright("check-layout");
 
   const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
   const { auditLayout } = await import(new URL("../dist/onlymapjs.js", import.meta.url));
@@ -127,14 +168,7 @@ async function checkLayout(manifestArg) {
   try {
     console.log(`Auditing ${manifestPath}`);
     console.log("Note: check-layout executes this page's scripts inside an isolated headless Chromium context.");
-    try {
-      browser = await playwright.chromium.launch({ headless: true });
-    } catch (error) {
-      if (String(error).includes("Executable doesn't exist") || String(error).includes("browserType.launch")) {
-        throw new Error(`Chromium is not installed for Playwright.\nRun:\n  npx playwright install chromium\n\n${String(error)}`);
-      }
-      throw error;
-    }
+    browser = await launchChromium(playwright);
     const context = await browser.newContext({ serviceWorkers: "block" });
     const page = await context.newPage();
     const pageErrors = [];
@@ -165,6 +199,233 @@ async function checkLayout(manifestArg) {
   }
 }
 
+function parseRecordArgs(rest) {
+  const opts = { manifest: undefined, out: undefined, story: undefined, fps: undefined, width: 1280, height: 720, scale: 1, keepFrames: false, timeoutS: 600, maxHoldS: undefined };
+  const numberFor = (flag, raw) => {
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0) throw new Error(`${flag} needs a positive number, received: ${raw}`);
+    return value;
+  };
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    const next = () => {
+      i += 1;
+      if (i >= rest.length) throw new Error(`${arg} needs a value.`);
+      return rest[i];
+    };
+    if (arg === "--out") opts.out = next();
+    else if (arg === "--story") opts.story = next();
+    else if (arg === "--fps") opts.fps = numberFor("--fps", next());
+    else if (arg === "--width") opts.width = numberFor("--width", next());
+    else if (arg === "--height") opts.height = numberFor("--height", next());
+    else if (arg === "--scale") opts.scale = numberFor("--scale", next());
+    else if (arg === "--keep-frames") opts.keepFrames = true;
+    else if (arg === "--gpu") opts.gpu = true;
+    else if (arg === "--timeout") opts.timeoutS = numberFor("--timeout", next());
+    else if (arg === "--max-hold") {
+      const raw = next();
+      opts.maxHoldS = raw === "none" ? "none" : numberFor("--max-hold", raw);
+    }
+    else if (arg.startsWith("--")) throw new Error(`Unknown record option: ${arg}`);
+    else if (opts.manifest === undefined) opts.manifest = arg;
+    else throw new Error(`Unexpected argument: ${arg}`);
+  }
+  if (!opts.manifest) throw new Error("record needs a manifest HTML path.\nUsage: onlymapjs record <manifest.html> [options]");
+  return opts;
+}
+
+function ffmpegAvailable() {
+  const probe = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" });
+  return !probe.error && probe.status === 0;
+}
+
+function ffmpegArgs(framesDir, outPath, fps) {
+  const codec =
+    extname(outPath).toLowerCase() === ".webm"
+      ? ["-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "30"]
+      : ["-c:v", "libx264", "-crf", "18", "-movflags", "+faststart"];
+  // The crop keeps dimensions even — yuv420p (the compatibility pixel format) requires it.
+  return ["-y", "-framerate", String(fps), "-start_number", "0", "-i", join(framesDir, "%06d.png"), "-vf", "crop=trunc(iw/2)*2:trunc(ih/2)*2", ...codec, "-pix_fmt", "yuv420p", outPath];
+}
+
+async function recordStory(rest) {
+  const opts = parseRecordArgs(rest);
+  const manifestPath = resolve(process.cwd(), opts.manifest);
+  if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) throw new Error(`Manifest not found: ${manifestPath}`);
+  if (extname(manifestPath).toLowerCase() !== ".html") throw new Error(`record expects an .html manifest, received: ${manifestPath}`);
+  const outPath = resolve(process.cwd(), opts.out ?? `${basename(manifestPath, ".html")}.mp4`);
+  const outExt = extname(outPath).toLowerCase();
+  if (outExt !== ".mp4" && outExt !== ".webm") throw new Error(`--out must end in .mp4 or .webm, received: ${outPath}`);
+
+  const playwright = await importPlaywright("record");
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const { server, url } = await startStaticServer(manifestPath, packageRoot);
+  // Frames go next to the output and SURVIVE a failed run — a deadline hit
+  // after 70 tile-bound frames must salvage them, not discard them. Only a
+  // fully successful encode (without --keep-frames) cleans up. Cleared up
+  // front so a shorter re-run can't inherit stale higher-numbered frames.
+  const framesDir = `${outPath}.frames`;
+  rmSync(framesDir, { recursive: true, force: true });
+  mkdirSync(framesDir, { recursive: true });
+
+  let browser;
+  let frames = 0;
+  try {
+    console.log(`Recording ${manifestPath}`);
+    console.log("Note: record executes this page's scripts inside an isolated headless Chromium context.");
+    // Headless Chromium renders on SwiftShader (software GL) by default —
+    // tile refinement advances on the page's render loop, so heavy 3D scenes
+    // hold far longer than they would on the user's GPU. --gpu opts into
+    // hardware rendering (ANGLE Metal on macOS, default ANGLE elsewhere).
+    browser = await launchChromium(playwright, opts.gpu ? [process.platform === "darwin" ? "--use-angle=metal" : "--use-angle=default"] : []);
+    if (opts.gpu) console.log("GPU rendering requested (--gpu).");
+    else console.log("Tip: --gpu renders on the real GPU — typically several times shorter tile holds on heavy 3D scenes.");
+    const context = await browser.newContext({
+      serviceWorkers: "block",
+      viewport: { width: Math.round(opts.width), height: Math.round(opts.height) },
+      deviceScaleFactor: opts.scale,
+    });
+    const page = await context.newPage();
+    const pageErrors = [];
+    page.on("pageerror", (error) => pageErrors.push(String(error).split("\n")[0]));
+    // om-tiles-warmed fires on <om-map> before our handlers can attach —
+    // catch it from the capture phase at the document, from t=0.
+    await page.addInitScript(() => {
+      window.__omRecord = { warmed: null };
+      document.addEventListener("om-tiles-warmed", (event) => (window.__omRecord.warmed = event.detail), true);
+    });
+    await page.goto(url, { waitUntil: "domcontentloaded" });
+
+    let info;
+    try {
+      info = await page.evaluate(
+        async ({ storyId }) => {
+          const story = storyId ? document.getElementById(storyId) : document.querySelector("om-story");
+          if (!story || story.tagName.toLowerCase() !== "om-story") {
+            throw new Error(storyId ? `No <om-story id="${storyId}"> on this page.` : "No <om-story> on this page.");
+          }
+          const mapEl = story.closest("om-map");
+          if (!mapEl) throw new Error("The story is not inside an <om-map>.");
+          await mapEl.ready;
+          mapEl.setAttribute("data-om-recording", "");
+          const looped = story.hasAttribute("loop");
+          story.removeAttribute("loop"); // a looping take never ends — record one pass
+          return {
+            hasWarm: story.hasAttribute("warm-tiles"),
+            authoredFps: Number(story.getAttribute("paced")) > 0 ? Number(story.getAttribute("paced")) : null,
+            durationMs: story.duration,
+            looped,
+          };
+        },
+        { storyId: opts.story ?? null },
+      );
+    } catch (error) {
+      const detail = pageErrors.length ? `\nPage errors:\n  ${pageErrors.slice(0, 3).join("\n  ")}` : "";
+      throw new Error(`${error instanceof Error ? error.message : String(error)}${detail}`);
+    }
+    if (info.looped) console.log("Story has loop — recording a single pass.");
+
+    const fps = opts.fps ?? info.authoredFps ?? 30;
+    // The driver advances BEFORE its first tick (no t=0 frame): D ms at f fps
+    // is exactly ceil(D*f/1000) frames; a zero-duration story still ticks once.
+    const estFrames = Math.max(1, Math.ceil((info.durationMs * fps) / 1000));
+    console.log(`Story duration ${(info.durationMs / 1000).toFixed(1)}s → ~${estFrames} frames at ${fps} story-fps.`);
+
+    if (info.hasWarm) {
+      console.log("Story has warm-tiles — waiting for the route pre-load (shortens per-frame waits)…");
+      await page
+        .waitForFunction(() => window.__omRecord.warmed, undefined, { timeout: 240_000 })
+        .catch(() => console.log("warm-tiles did not finish in 4 min — recording anyway (pacing covers correctness)."));
+    }
+
+    const mapHandle = await page.$("om-map[data-om-recording]");
+    if (!mapHandle) throw new Error("Could not locate the recording <om-map>.");
+    let waitedTotal = 0;
+    await page.exposeFunction("__omRecordFrame", async (t, waitedMs) => {
+      await mapHandle.screenshot({ path: join(framesDir, `${String(frames).padStart(6, "0")}.png`) });
+      frames += 1;
+      waitedTotal += waitedMs;
+      const pct = info.durationMs > 0 ? Math.min(100, Math.round((t / info.durationMs) * 100)) : 0;
+      process.stdout.write(`\r  frame ${frames}${estFrames ? `/${estFrames}` : ""} (${pct}%) — story t=${(t / 1000).toFixed(2)}s, held ${(waitedTotal / 1000).toFixed(1)}s for tiles `);
+    });
+
+    let timeoutHandle;
+    const deadline = new Promise((_, reject) => {
+      timeoutHandle = setTimeout(
+        () =>
+          reject(
+            new Error(
+              `record hit the ${opts.timeoutS}s deadline (--timeout raises it). ${frames} frame(s) salvaged in ${framesDir} — assemble the partial take with:\n  ffmpeg ${ffmpegArgs(framesDir, outPath, fps).join(" ")}${pageErrors.length ? `\nPage errors (possible real cause):\n  ${pageErrors.slice(0, 3).join("\n  ")}` : ""}`,
+            ),
+          ),
+        opts.timeoutS * 1000,
+      );
+    });
+    try {
+      await Promise.race([
+        page.evaluate(
+          ({ storyId, fps: pacedFps, maxHoldS }) =>
+            new Promise((resolveDone, rejectDone) => {
+              const story = storyId ? document.getElementById(storyId) : document.querySelector("om-story");
+              // An autoplay story is already PLAYING un-paced by now (its
+              // ready-hook beat this evaluate) and play() would no-op — reset
+              // it so the paced driver actually takes over.
+              if (story.state !== "idle") {
+                story.pause();
+                story.seek(0);
+              }
+              story.setAttribute("paced", String(pacedFps));
+              if (maxHoldS) story.setAttribute("paced-max-hold", maxHoldS === "none" ? "none" : `${maxHoldS}s`);
+              story.setPacedCapture((tick) => window.__omRecordFrame(tick.t, tick.waitedMs));
+              // om-paced-tick fires AFTER the frame's capture resolved, so the
+              // ended-state tick means every frame is on disk.
+              story.addEventListener("om-paced-tick", () => {
+                if (story.state === "ended") {
+                  story.setPacedCapture(null);
+                  resolveDone();
+                }
+              });
+              // A run that stops without ending (a rejecting capture lands the
+              // story in "paused"; a page script pausing it) must fail fast,
+              // not idle to the deadline.
+              story.addEventListener("om-story-tick", (event) => {
+                if (event.detail.state === "paused") rejectDone(new Error('The story stopped mid-record (state "paused") — a failing capture or a page script paused it.'));
+              });
+              try {
+                story.play();
+              } catch (error) {
+                rejectDone(error);
+              }
+            }),
+          { storyId: opts.story ?? null, fps, maxHoldS: opts.maxHoldS ?? null },
+        ),
+        deadline,
+      ]);
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+    process.stdout.write("\n");
+    if (frames === 0) throw new Error("The story produced no frames — does it have any steps?");
+
+    if (ffmpegAvailable()) {
+      console.log(`Encoding ${outPath} …`);
+      const run = spawnSync("ffmpeg", ffmpegArgs(framesDir, outPath, fps), { stdio: ["ignore", "ignore", "pipe"] });
+      if (run.status !== 0) throw new Error(`ffmpeg failed:\n${run.stderr?.toString().slice(-2000) ?? "(no stderr)"}`);
+      console.log(`DONE: ${outPath} — ${frames} frames at ${fps} fps, every frame fully refined.`);
+      if (opts.keepFrames) console.log(`Frames kept in ${framesDir}`);
+      else rmSync(framesDir, { recursive: true, force: true }); // full success — the video subsumes the frames
+      return 0;
+    }
+    // No ffmpeg: the frames ARE the deliverable.
+    console.log(`ffmpeg not found — ${frames} PNG frame(s) written to ${framesDir}`);
+    console.log(`Assemble with:\n  ffmpeg ${ffmpegArgs(framesDir, outPath, fps).join(" ")}`);
+    return 0;
+  } finally {
+    await browser?.close();
+    await new Promise((resolveClose) => server.close(resolveClose));
+  }
+}
+
 function parseJsonc(text) {
   let out = "";
   let inString = false;
@@ -320,6 +581,8 @@ try {
   } else if (command === "check-layout") {
     if (rest.length !== 1) throw new Error("Usage: onlymapjs check-layout <manifest.html>");
     process.exitCode = await checkLayout(rest[0]);
+  } else if (command === "record") {
+    process.exitCode = await recordStory(rest);
   } else {
     console.error(`Unknown command: ${command}\n`);
     usage();

package/dist/{LercDecode.es-BWmtr6fp.js → LercDecode.es-DjPA9zLm.js}

@@ -19,7 +19,7 @@ async function v(N = {}) {
   if (n) {
     const { createRequire: I } = await import(
       /*webpackIgnore:true*/
-      "./lerc-Cw1YMyb0.js"
+      "./lerc-BD1Any2Z.js"
     ).then((g) => g._);
     var O = I(import.meta.url);
   }

package/dist/actions.d.ts

@@ -1,12 +1,3 @@
-/**
- * The action registry (spec: "Module Breakdown / Behavior Engine" — "Action
- * payload contract"). One event name maps to one action handler with one
- * payload schema, honored identically across all three emit surfaces —
- * `ctx.emit(name, payload)`, `data-emit`, and `<om-behavior>` — an action
- * reads the same keys regardless of how it was triggered. `registerAction`
- * is re-exported from the package entry point (index.ts) as the public
- * `OmMap.registerAction` surface.
- */
 import type { RuntimeCore } from "./runtime-core";
 import type { LayerIR } from "./ir";
 export type ActionHandler = (payload: Record<string, unknown>, mapEl: Element, core: RuntimeCore, layerIRs: ReadonlyMap<string, LayerIR>) => void;

package/dist/{basemap-DQeUv-pk.js → basemap-DwN5jPCj.js}

@@ -1,4 +1,4 @@
-import { C as ny, L as sy, M as oy, m as ay, c as ka, z as oc, a as Sd, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-Bnkk4jcp.js";
+import { C as ny, L as sy, M as oy, m as ay, c as ka, a as Sd, z as oc, G as sm, V as ly, W as cy, b as uy, g as hy, d as Vu, f as Ed, e as dy, l as py, u as fy, D as Qf, h as my } from "./index-CX4qxgVT.js";
 const Cd = Math.PI / 180, gy = 180 / Math.PI;
 function em(Pe, Q = 0) {
   const me = Math.min(180, Pe) * Cd;

package/dist/elements/om-map.d.ts

@@ -279,6 +279,13 @@ export declare class OmMapElement extends HTMLElementBase {
         pitch: number;
         bearing: number;
     } | undefined;
+    /** Live Tileset3D per currently-present 3D-tiles layer — the paced-flyby driver's isLoaded() gate (same surface the warm-tiles action reads). */
+    getLiveTilesetsInternal(): Map<string, unknown>;
+    /** Rendered viewport size — the paced driver's fly-to arc math needs real dims (undefined until the renderer has one). */
+    getViewportSizeInternal(): {
+        width: number;
+        height: number;
+    } | undefined;
     /** Resolved scene-lighting IR (headless test inspection) — null = deck default lights. */
     getLightingInternal(): LightingIR | null;
     /** Resolved terrain IR (headless test inspection) — null = no surface. */

package/dist/elements/om-story.d.ts

@@ -11,6 +11,12 @@ export declare class OmStoryElement extends HTMLElementBase {
     private lastTimestamp;
     /** Set by the test harness (advanceInternal): the clock is driven manually, never by rAF. */
     private manualClock;
+    /** Generation token for the paced driver — bumping it aborts any in-flight run (replay, disconnect). */
+    private pacedGen;
+    /** True while the paced driver owns the camera — fireDueSteps must not dispatch camera actions against it. */
+    private pacedDriving;
+    private warnedPacedCameraSkip;
+    private pacedCapture;
     private captured;
     private capturedCamera;
     private warnedCustomActions;
@@ -23,6 +29,19 @@ export declare class OmStoryElement extends HTMLElementBase {
     play(): void;
     pause(): void;
     seek(ms: number): void;
+    /**
+     * Per-frame capture hook for paced runs (the recorder seam, issue #16):
+     * called after each paced frame is fully refined and BEFORE the frame's
+     * om-paced-tick event; the story does not advance to the next frame until
+     * the returned promise resolves, so `await mapEl.snapshot()` — or a
+     * driving tool's screenshot — is race-free by construction. The final
+     * om-paced-tick therefore also guarantees every capture has completed.
+     * Pass null to clear.
+     */
+    setPacedCapture(cb: ((tick: {
+        t: number;
+        waitedMs: number;
+    }) => void | Promise<void>) | null): void;
     /**
      * Test-harness clock drive (spec: "Consumer Testing Surface" +
      * "Map Stories"): switches this story to a manual clock permanently and
@@ -32,6 +51,16 @@ export declare class OmStoryElement extends HTMLElementBase {
     advanceInternal(ms: number): void;
     private startClock;
     private stopClock;
+    /**
+     * Load-paced playback (docs/design/paced-flyby.md): manual stepping via
+     * the pure runPacedFlyby driver — it owns the camera per frame
+     * (cameraAtTime over the same fly-to arc route warming samples, written
+     * through the instant setView path) and gates every advance on all live
+     * tilesets reporting isLoaded(). Emits om-paced-tick {t, waitedMs} per
+     * frame (the recorder hook). `paced` may carry a frame rate (`paced="60"`,
+     * default 30 — story-time fps of the output, not a wall-clock promise).
+     */
+    private startPaced;
     private advanceBy;
     private fireDueSteps;
     /** Steps and the timeline are (re)built lazily when idle — mid-play DOM edits apply on the next play/seek. */

package/dist/{geoparquet-DsYXvvEo.js → geoparquet-DG3VtNgs.js}

@@ -1,4 +1,4 @@
-import { r as p, n as d } from "./index-Bnkk4jcp.js";
+import { r as p, n as d } from "./index-CX4qxgVT.js";
 function g(t) {
   if (t == null) return !0;
   const e = t, n = e.id?.code;

package/dist/html-data.d.ts

@@ -15,7 +15,7 @@ interface TagData {
     }[];
 }
 /** Hand-authored action list — validated against hasAction() in html-data.test.ts. */
-export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "export-region-3d", "measure-mode", "measure-clear", "measure-units", "set-basemap", "set-lighting", "set-terrain", "set-clip-box", "clip-box-edit", "set-widgets-visible", "undo", "redo"];
+export declare const BUILTIN_ACTIONS: readonly ["toggle-layer", "zoom-in", "zoom-out", "filter-layer", "highlight-feature", "fade", "pulse", "populate", "trace", "story-play", "story-pause", "story-seek", "fly-to", "zoom-to-feature", "show-overlay", "hide-overlay", "show-tooltip", "hide-tooltip", "draw-mode", "draw-commit", "draw-cancel", "draw-delete", "draw-clear", "draw-config", "draw-save", "export-region-3d", "measure-mode", "measure-clear", "measure-units", "set-basemap", "set-lighting", "set-terrain", "set-clip-box", "clip-box-edit", "set-widgets-visible", "undo", "redo", "warm-tiles"];
 /** Hand-authored widget types — validated against the widget registry in html-data.test.ts. */
 export declare const BUILTIN_WIDGETS: readonly ["legend", "layer-switcher", "zoom-controls", "scale-bar", "attribution", "filter", "vega-lite", "dynamic-chart", "player", "draw", "measure", "basemap-switcher", "lighting", "clip-box", "undo-redo", "widgets-toggle", "time-slider", "ifc-browser", "ifc-legend", "feature-inspector", "ifc-inspector", "ifc-loader", "ifc-clash"];
 export declare function buildHtmlCustomData(): {

package/dist/{index-BTJy4dWy.js → index-BM-txQRw.js}

@@ -1,4 +1,4 @@
-import { ae as _t, af as Ct } from "./index-Bnkk4jcp.js";
+import { ae as _t, af as Ct } from "./index-CX4qxgVT.js";
 function Yt(e, r, t = 2, i, o = "xy") {
   const s = r && r.length, l = s ? r[0] * t : e.length;
   let c = Ut(e, 0, l, t, !0, i && i[0], o);