tileflow 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -23,8 +23,8 @@ executable. With another package manager, use its local-execution command and th
 do not add a second lockfile or rely on a globally installed CLI.
 
 `init` creates a singular `tileflow.config.ts` extending the official Streets map. `preview` serves
-the exported map using its configured view. `dev` is a compatibility alias for `preview`, not a
-replacement for an application's normal development server.
+the exported map using its configured view; it does not replace an application's normal development
+server.
 
 Local validation, compilation, and asset preparation require no account or API key. Preview and
 capture may fetch configured remote tiles and fonts. Config files are executable trusted code,
@@ -151,6 +151,23 @@ on that route. Capture does not start the server or discover ports. It accepts l
 selects exactly one target, verifies the concrete theme, and waits for the component's idle marker.
 Do not run a separate `tileflow preview` server beside the application.
 
+## Render a timed shot
+
+Commit a [capture shot](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-shots.md)
+under `shots` on the same map: a concrete theme, a viewport, and two or more center-camera
+keyframes, optionally with a theme blend. Then render it:
+
+```sh
+npx tileflow capture --shot dusk-flyover --json
+npx tileflow capture --shot dusk-flyover --format frames --out-dir evidence --json
+```
+
+The first command writes `.tileflow/captures/shots/dusk-flyover.webm`; the second writes
+`evidence/dusk-flyover/frame-0000.png` and the following frames. Each output has a sibling
+`.receipt.json` shot receipt. Repeat `--shot` or use `--all-shots` to render several shots; `--out`
+names the `.webm` file or frame directory of a single shot. Every frame waits for the map to be
+ready, so a slow machine renders more slowly without dropping frames.
+
 ## Review pixels without accepting changes
 
 After reviewing a render, create its baseline. Compare subsequent renders separately:
@@ -264,7 +281,7 @@ for the verified platform, setup, and development-artifact restrictions.
 
 Run `npx tileflow --help` or `npx tileflow <command> --help` for the installed command surface.
 The families cover map authoring, semantic language discovery, local visual evidence, datasets and
-icons, account sessions, coordinates, and hosted delivery. Hidden compatibility commands are not a
+icons, account sessions, coordinates, and hosted delivery. Hidden support commands are not a
 recommended application workflow.
 
 A manifest 404 usually means assets were not built/served at the component's configured URL.

package/dist/index.js

@@ -88,7 +88,7 @@ var sessionSchema = z.object({
 }).strict().refine((value) => Date.parse(value.expiresAt) > Date.parse(value.createdAt), {
   message: "session expiry must follow creation"
 });
-var authConfigV2Schema = z.object({
+var authConfigSchema = z.object({
   sessions: z.record(z.string().max(2048), sessionSchema),
   version: z.literal(2)
 }).strict().superRefine((value, context) => {
@@ -101,16 +101,6 @@ var authConfigV2Schema = z.object({
     }
   }
 });
-var legacyAuthConfigSchema = z.object({
-  apiKey: z.string().min(16).max(4096),
-  apiUrl: z.string().min(1).max(2048),
-  appUrl: z.string().max(2048).optional(),
-  createdAt: z.string().max(64).optional(),
-  deviceName: z.string().max(200).optional(),
-  keyPrefix: z.string().max(64).optional(),
-  projectId: z.string().max(200).optional(),
-  scopes: z.array(z.string().max(128)).max(32).optional()
-}).strict();
 function emptyAuthConfig() {
   return Object.freeze({ sessions: Object.freeze({}), version: 2 });
 }
@@ -128,24 +118,13 @@ async function readAuthFile(path = authConfigPath()) {
   } catch {
     return { kind: "invalid" };
   }
-  const v2 = authConfigV2Schema.safeParse(parsed);
-  if (v2.success) return { config: freezeConfig(v2.data), kind: "v2" };
-  const legacy = legacyAuthConfigSchema.safeParse(parsed);
-  if (legacy.success) {
-    return { config: Object.freeze(legacy.data), kind: "legacy_project_login" };
-  }
-  if (isSupersededProfileState(parsed)) return { kind: "superseded_profiles" };
-  return { kind: "invalid" };
+  const config = authConfigSchema.safeParse(parsed);
+  return config.success ? { config: freezeConfig(config.data), kind: "sessions" } : { kind: "invalid" };
 }
 async function loadAuthConfig(path = authConfigPath()) {
   const state = await readAuthFile(path);
   if (state.kind === "empty") return emptyAuthConfig();
-  if (state.kind === "v2") return state.config;
-  if (state.kind === "legacy_project_login" || state.kind === "superseded_profiles") {
-    throw new Error(
-      "The saved login uses the retired destination-credential model. Run `tileflow login` to authorize your Tileflow account."
-    );
-  }
+  if (state.kind === "sessions") return state.config;
   throw new Error("Tileflow auth state is invalid; no changes were made.");
 }
 async function installAccountSession(session, path = authConfigPath()) {
@@ -157,7 +136,7 @@ async function installAccountSession(session, path = authConfigPath()) {
   if (state.kind === "invalid") {
     throw new Error("Tileflow auth state is invalid; no changes were made.");
   }
-  const current = state.kind === "v2" ? state.config : emptyAuthConfig();
+  const current = state.kind === "sessions" ? state.config : emptyAuthConfig();
   const sessions = { ...current.sessions, [normalized.apiOrigin]: normalized };
   if (Object.keys(sessions).length > maximumOrigins) {
     throw new Error("Tileflow CLI API-origin limit reached.");
@@ -180,7 +159,7 @@ function removeAccountSession(config, apiUrl) {
   return { config: freezeConfig({ sessions, version: 2 }), removed };
 }
 async function writeAuthFileAtomic(config, path = authConfigPath()) {
-  const normalized = normalizeConfig(authConfigV2Schema.parse(config));
+  const normalized = normalizeConfig(authConfigSchema.parse(config));
   const source = `${JSON.stringify(normalized, null, 2)}
 `;
   if (Buffer.byteLength(source, "utf8") > maximumAuthFileBytes) {
@@ -226,9 +205,6 @@ function parseProjectReference(value) {
   );
   return match ? { organizationSlug: match[1], projectSlug: match[2] } : null;
 }
-function projectReference(value) {
-  return `@${value.organization.slug}/${value.project.slug}`;
-}
 function authConfigPath() {
   return resolve(homedir(), ".tileflow", "config.json");
 }
@@ -250,11 +226,6 @@ function freezeConfig(config) {
   );
   return Object.freeze({ sessions: Object.freeze(sessions), version: 2 });
 }
-function isSupersededProfileState(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const record = value;
-  return record.version === 2 && Boolean(record.profiles && typeof record.profiles === "object") && Boolean(record.selections && typeof record.selections === "object");
-}
 async function syncDirectory(path) {
   if (process.platform === "win32") return;
   const directory = await open(path, "r");
@@ -678,6 +649,7 @@ import { isAbsolute, relative as relative2, resolve as resolve3, sep as sep2 } f
 import {
   createTileflowCaptureSession,
   serializeTileflowCaptureReceipt,
+  serializeTileflowShotReceipt,
   setupTileflowCaptureBrowser,
   TileflowCaptureError,
   tileflowSyntheticAssetOrigin,
@@ -687,7 +659,8 @@ import {
   compareCodeUnits as compareCodeUnits3,
   normalizeTileflowCaptureScene,
   tileflowCaptureSceneNameSchema,
-  tileflowCaptureSceneSchema
+  tileflowCaptureSceneSchema,
+  tileflowCaptureShotNameSchema
 } from "@tileflow/core";
 import {
   createTileflowArtifactDiagnostics,
@@ -699,8 +672,8 @@ import { TileflowStyleValidationError } from "@tileflow/dev/validation";
 
 // src/capture-output.ts
 import { randomUUID } from "crypto";
-import { lstat, mkdir as mkdir2, open as open2, readFile as readFile2, rename as rename2, unlink as unlink2 } from "fs/promises";
-import { basename, dirname as dirname3, relative, resolve as resolve2, sep } from "path";
+import { lstat, mkdir as mkdir2, open as open2, readdir, readFile as readFile2, rename as rename2, rm, unlink as unlink2 } from "fs/promises";
+import { basename, dirname as dirname3, join, relative, resolve as resolve2, sep } from "path";
 var maximumAtomicArtifactBytes = 256 * 1024 * 1024;
 async function writeCapturePair(input) {
   const outputPath = resolve2(input.outputPath);
@@ -844,6 +817,119 @@ async function writeAtomicFile(input) {
     await removeOptional(temporary);
   }
 }
+var shotFrameFilePattern = /^frame-\d{4}\.png$/u;
+function shotFrameFileName(index) {
+  return `frame-${String(index).padStart(4, "0")}.png`;
+}
+async function stageShotFrameDirectory(input) {
+  const boundaryPath = resolve2(input.boundaryPath);
+  const directory = resolve2(input.directory);
+  await assertNoSymlinkComponents(dirname3(directory), boundaryPath);
+  await listShotFrameDirectory(directory);
+  await mkdir2(dirname3(directory), { recursive: true });
+  await assertNoSymlinkComponents(dirname3(directory), boundaryPath);
+  const staging = temporarySibling(directory, `${process.pid}.${randomUUID()}`, "frames");
+  await mkdir2(staging);
+  return {
+    boundaryPath,
+    directory,
+    staging,
+    write: (index, png) => writeSyncedExclusive(join(staging, shotFrameFileName(index)), png),
+    discard: () => rm(staging, { force: true, recursive: true })
+  };
+}
+async function commitShotFrameDirectory(input) {
+  const { stage } = input;
+  const receiptPath = resolve2(input.receiptPath);
+  const receipt = new TextEncoder().encode(input.receipt);
+  await assertNoSymlinkComponents(dirname3(stage.directory), stage.boundaryPath);
+  await assertNoSymlinkComponents(dirname3(receiptPath), stage.boundaryPath);
+  await assertNotSymlink(receiptPath);
+  const existingFrames = await listShotFrameDirectory(stage.directory);
+  const existingReceipt = await readOptional(receiptPath);
+  if (existingFrames && existingReceipt && Buffer.from(existingReceipt).equals(Buffer.from(receipt)) && await sameShotFrames(stage.directory, existingFrames, stage.staging)) {
+    await stage.discard();
+    return false;
+  }
+  if ((existingFrames || existingReceipt) && !input.managed && !input.force) {
+    throw new Error(
+      "Shot output already exists with different contents. Use --force to replace it."
+    );
+  }
+  const transaction = `${process.pid}.${randomUUID()}`;
+  const receiptTemporary = temporarySibling(receiptPath, transaction, "new");
+  const directoryBackup = temporarySibling(stage.directory, transaction, "previous");
+  const receiptBackup = temporarySibling(receiptPath, transaction, "previous");
+  const state = {
+    directoryBackedUp: false,
+    directoryInstalled: false,
+    receiptBackedUp: false,
+    receiptInstalled: false
+  };
+  try {
+    await writeSyncedExclusive(receiptTemporary, receipt);
+    await syncDirectory2(stage.staging);
+    if (existingFrames) {
+      await rename2(stage.directory, directoryBackup);
+      state.directoryBackedUp = true;
+    }
+    if (existingReceipt) {
+      await rename2(receiptPath, receiptBackup);
+      state.receiptBackedUp = true;
+    }
+    await rename2(stage.staging, stage.directory);
+    state.directoryInstalled = true;
+    await rename2(receiptTemporary, receiptPath);
+    state.receiptInstalled = true;
+    await syncDirectory2(dirname3(stage.directory));
+    if (dirname3(receiptPath) !== dirname3(stage.directory))
+      await syncDirectory2(dirname3(receiptPath));
+  } catch (error) {
+    if (state.receiptInstalled) await removeOptional(receiptPath).catch(() => void 0);
+    if (state.receiptBackedUp) await rename2(receiptBackup, receiptPath).catch(() => void 0);
+    if (state.directoryInstalled) {
+      await rename2(stage.directory, stage.staging).catch(() => void 0);
+    }
+    if (state.directoryBackedUp) {
+      await rename2(directoryBackup, stage.directory).catch(() => void 0);
+    }
+    throw error;
+  } finally {
+    await removeOptional(receiptTemporary).catch(() => void 0);
+  }
+  await Promise.allSettled([
+    rm(directoryBackup, { force: true, recursive: true }),
+    removeOptional(receiptBackup)
+  ]);
+  return true;
+}
+async function listShotFrameDirectory(directory) {
+  const info = await lstatOptional(directory);
+  if (!info) return void 0;
+  if (info.isSymbolicLink()) throw new Error("Capture output cannot be a symbolic link.");
+  if (!info.isDirectory()) throw new Error("Shot frame output must be a directory.");
+  const entries = await readdir(directory, { withFileTypes: true });
+  if (entries.some((entry) => !entry.isFile() || !shotFrameFilePattern.test(entry.name))) {
+    throw new Error(
+      "Shot frame output contains files that are not Tileflow frames. Choose an empty or Tileflow-owned directory."
+    );
+  }
+  return entries.map((entry) => entry.name).sort();
+}
+async function sameShotFrames(directory, names, staging) {
+  const staged = (await readdir(staging)).sort();
+  if (staged.length !== names.length || staged.some((name, index) => name !== names[index])) {
+    return false;
+  }
+  for (const name of names) {
+    const [existing, next] = await Promise.all([
+      readOptional(join(directory, name)),
+      readOptional(join(staging, name))
+    ]);
+    if (!existing || !next || !Buffer.from(existing).equals(Buffer.from(next))) return false;
+  }
+  return true;
+}
 function captureReceiptPath(outputPath) {
   return outputPath.toLowerCase().endsWith(".png") ? `${outputPath.slice(0, -4)}.receipt.json` : `${outputPath}.receipt.json`;
 }
@@ -984,7 +1070,14 @@ function registerCaptureCommands(program2, dependencies) {
       controller.close();
     }
   });
-  program2.command("capture").description("Render Tileflow scenes to PNG with a pinned headless browser").argument("[scenes...]", "named committed capture scenes").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--all", "capture every configured scene").option("--map <name>", "capture one map with an uncommitted camera").option("--theme <name>", "required concrete theme for exploratory --map capture").option("--center <lng,lat>", "exploratory center camera").option("--bounds <west,south,east,north>", "exploratory bounds camera").option("--zoom <number>", "exploratory center zoom").option("--bearing <number>", "exploratory camera bearing").option("--pitch <number>", "exploratory camera pitch").option("--width <pixels>", "exploratory viewport width").option("--height <pixels>", "exploratory viewport height").option("--dpr <ratio>", "exploratory device pixel ratio: 1 or 2").option("--app-origin <origin>", "loopback origin for committed application scenes").option("--url <url>", "one-off full loopback URL for exactly one named scene").option("--selector <selector>", "one-off application target selector").option("--frame <frame>", "application capture frame: map or viewport").option("--out <path>", "PNG path for one capture").option("--out-dir <path>", "directory for one or more captures").option("--force", "replace different explicit output files").option("--json", "print deterministic schema-version-1 JSON").option("--watch", "keep running and recapture after each valid local edit").option(
+  program2.command("capture").description(
+    "Render Tileflow scenes to PNG, or timed shots to video, with a pinned headless browser"
+  ).argument("[scenes...]", "named committed capture scenes").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--all", "capture every configured scene").option(
+    "--shot <name>",
+    "render a committed timed shot; repeat for more shots",
+    collectOption,
+    []
+  ).option("--all-shots", "render every committed timed shot").option("--format <format>", "shot output: webm (default) or frames").option("--map <name>", "capture one map with an uncommitted camera").option("--theme <name>", "required concrete theme for exploratory --map capture").option("--center <lng,lat>", "exploratory center camera").option("--bounds <west,south,east,north>", "exploratory bounds camera").option("--zoom <number>", "exploratory center zoom").option("--bearing <number>", "exploratory camera bearing").option("--pitch <number>", "exploratory camera pitch").option("--width <pixels>", "exploratory viewport width").option("--height <pixels>", "exploratory viewport height").option("--dpr <ratio>", "exploratory device pixel ratio: 1 or 2").option("--app-origin <origin>", "loopback origin for committed application scenes").option("--url <url>", "one-off full loopback URL for exactly one named scene").option("--selector <selector>", "one-off application target selector").option("--frame <frame>", "application capture frame: map or viewport").option("--out <path>", "PNG path for one scene, or .webm/frame directory for one shot").option("--out-dir <path>", "directory for one or more captures").option("--force", "replace different explicit output files").option("--json", "print deterministic schema-version-1 JSON").option("--watch", "keep running and recapture after each valid local edit").option(
     "--no-browser-install",
     "require the pinned browser to be prepared; never use system Chrome"
   ).addHelpText(
@@ -994,11 +1087,205 @@ function registerCaptureCommands(program2, dependencies) {
     try {
       await runCaptureCommand(scenes ?? [], options);
     } catch (error) {
-      printCaptureError(error, { command: "capture", json: options.json });
+      printCaptureError(error, {
+        command: isShotSelection(options) ? "capture.shot" : "capture",
+        json: options.json
+      });
       process.exitCode = 1;
     }
   });
 }
+function collectOption(value, previous) {
+  return [...previous, value];
+}
+function isShotSelection(options) {
+  return Boolean(options.allShots) || (options.shot?.length ?? 0) > 0;
+}
+function createTileflowShotCaptureJson(shots, cwd) {
+  return {
+    schemaVersion: 1,
+    command: "capture.shot",
+    shots: [...shots].sort((left, right) => compareCodeUnits3(left.capture.shot, right.capture.shot)).map(({ capture, outputPath, receiptPath }) => ({
+      shot: capture.shot,
+      map: capture.map,
+      theme: capture.theme,
+      status: "captured",
+      format: capture.format,
+      ...capture.codec ? { codec: capture.codec } : {},
+      outputPath: relativePath(cwd, outputPath),
+      receiptPath: relativePath(cwd, receiptPath),
+      sha256: capture.sha256,
+      framesSha256: capture.framesSha256,
+      frameCount: capture.frameCount,
+      fps: capture.fps,
+      durationMs: capture.durationMs,
+      width: capture.width,
+      height: capture.height,
+      dpr: capture.dpr,
+      renderer: capture.renderer,
+      networkDependent: capture.networkDependent,
+      warnings: [...capture.warnings].sort(compareCodeUnits3)
+    }))
+  };
+}
+function serializeTileflowShotCaptureJson(value) {
+  return `${JSON.stringify(value, null, 2)}
+`;
+}
+function shotReceiptPath(outputPath) {
+  return outputPath.toLowerCase().endsWith(".webm") ? `${outputPath.slice(0, -5)}.receipt.json` : `${outputPath}.receipt.json`;
+}
+async function runCaptureShotCommand(options) {
+  const cwd = process.cwd();
+  const format = options.format === "frames" ? "frames" : "webm";
+  const controller = installSignalAbortController();
+  const session = createTileflowCaptureSession({
+    allowBrowserInstall: options.browserInstall,
+    config: options.config,
+    cwd,
+    onBrowserInstallProgress: options.json ? void 0 : printInstallProgress,
+    signal: controller.signal
+  });
+  const stages = /* @__PURE__ */ new Map();
+  try {
+    const onFrame = format === "frames" ? async (frame) => {
+      let stage = stages.get(frame.shot);
+      if (!stage) {
+        const target = resolveShotOutputTarget(frame.shot, options, format, cwd);
+        stage = await stageShotFrameDirectory({
+          boundaryPath: target.boundaryPath,
+          directory: target.outputPath
+        });
+        stages.set(frame.shot, stage);
+      }
+      await stage.write(frame.index, frame.png);
+    } : void 0;
+    const shotOptions = { format, ...onFrame ? { onFrame } : {}, signal: controller.signal };
+    const result = options.allShots ? await session.captureAllShots(shotOptions) : await session.captureShots(options.shot ?? [], shotOptions);
+    const written = [];
+    for (const capture of result.shots) {
+      const target = resolveShotOutputTarget(capture.shot, options, format, cwd);
+      const receipt = serializeTileflowShotReceipt(capture.receipt);
+      if (capture.video) {
+        await writeAtomicFileSet({
+          boundaryPath: target.boundaryPath,
+          files: [
+            { path: target.outputPath, source: capture.video },
+            { path: target.receiptPath, source: receipt }
+          ],
+          force: Boolean(options.force),
+          label: "Shot output",
+          managed: target.managed
+        });
+      } else {
+        const stage = stages.get(capture.shot);
+        if (!stage) throw new Error(`Shot ${capture.shot} produced no frames.`);
+        await commitShotFrameDirectory({
+          force: Boolean(options.force),
+          managed: target.managed,
+          receipt,
+          receiptPath: target.receiptPath,
+          stage
+        });
+        stages.delete(capture.shot);
+      }
+      written.push({ capture, outputPath: target.outputPath, receiptPath: target.receiptPath });
+    }
+    if (!options.out && !options.outDir) await warnIfManagedCapturesAreNotIgnored(cwd);
+    const document = createTileflowShotCaptureJson(written, cwd);
+    if (options.json) {
+      process.stdout.write(serializeTileflowShotCaptureJson(document));
+      return;
+    }
+    for (const entry of document.shots) {
+      console.log(
+        `Rendered ${entry.shot} -> ${entry.outputPath} (${entry.frameCount} frames, ${entry.sha256.slice(0, 12)}).`
+      );
+      if (entry.networkDependent) {
+        console.error(`Shot ${entry.shot} used remote map resources.`);
+      }
+    }
+  } finally {
+    await Promise.allSettled([...stages.values()].map((stage) => stage.discard()));
+    await session.close();
+    controller.close();
+  }
+}
+function resolveShotOutputTarget(shot, options, format, cwd) {
+  const managed = !options.out && !options.outDir;
+  const directory = resolve3(cwd, options.outDir ?? ".tileflow/captures/shots");
+  const outputPath = options.out ? resolve3(cwd, options.out) : resolve3(directory, format === "webm" ? `${shot}.webm` : shot);
+  const receiptPath = shotReceiptPath(outputPath);
+  if (managed) {
+    const relativeToRoot = relative2(directory, outputPath);
+    if (relativeToRoot.startsWith("..") || relativeToRoot.includes(`..${sep2}`)) {
+      throw new Error("Managed shot output escaped .tileflow/captures/shots.");
+    }
+  }
+  relativePath(cwd, outputPath);
+  relativePath(cwd, receiptPath);
+  return {
+    boundaryPath: managed ? cwd : options.outDir ? directory : resolve3(outputPath, ".."),
+    managed,
+    outputPath,
+    receiptPath
+  };
+}
+function validateShotSelectionOptions(positionalScenes, options) {
+  const shots = options.shot ?? [];
+  if (options.allShots && shots.length > 0) {
+    throw new Error("Use either --shot or --all-shots, not both.");
+  }
+  if (positionalScenes.length > 0 || options.all || options.map) {
+    throw new Error("Render shots separately from scenes; --shot and --all-shots take no scenes.");
+  }
+  if (options.watch) {
+    throw new Error("--watch captures scenes; it does not render shots.");
+  }
+  const sceneOnlyOptions = [
+    options.center,
+    options.bounds,
+    options.zoom,
+    options.bearing,
+    options.pitch,
+    options.width,
+    options.height,
+    options.dpr,
+    options.theme,
+    options.url,
+    options.appOrigin,
+    options.selector,
+    options.frame
+  ];
+  if (sceneOnlyOptions.some((value) => value !== void 0)) {
+    throw new Error(
+      "Shots render committed cameras and themes; camera, viewport, theme, and application flags apply to scenes."
+    );
+  }
+  for (const shot of shots) {
+    if (!tileflowCaptureShotNameSchema.safeParse(shot).success) {
+      throw new Error("--shot expects a portable Tileflow shot name.");
+    }
+  }
+  if (options.format !== void 0 && options.format !== "webm" && options.format !== "frames") {
+    throw new Error("--format expects webm or frames.");
+  }
+  if (options.out && options.outDir) {
+    throw new Error("Use either --out or --out-dir, not both.");
+  }
+  if (options.out) {
+    if (options.allShots || new Set(shots).size !== 1) {
+      throw new Error("--out can be used only when rendering one shot. Use --out-dir instead.");
+    }
+    const isVideoPath = options.out.toLowerCase().endsWith(".webm");
+    if ((options.format ?? "webm") === "webm" && !isVideoPath) {
+      throw new Error("--out must name a .webm file.");
+    }
+    if (options.format === "frames" && (isVideoPath || /\.(?:json|png)$/iu.test(options.out))) {
+      throw new Error("--out must name a directory for --format frames.");
+    }
+  }
+}
 function createTileflowCaptureJson(captures, cwd) {
   return {
     schemaVersion: 1,
@@ -1048,6 +1335,10 @@ function serializeTileflowCaptureFailureJson(value) {
 async function runCaptureCommand(positionalScenes, options) {
   validateSelectionOptions(positionalScenes, options);
   await withTileflowConfigSecretsHidden(async () => {
+    if (isShotSelection(options)) {
+      await runCaptureShotCommand(options);
+      return;
+    }
     if (options.watch) {
       await runCaptureWatchCommand(positionalScenes, options);
       return;
@@ -1296,6 +1587,13 @@ function waitForAbort(signal) {
   );
 }
 function validateSelectionOptions(positionalScenes, options) {
+  if (isShotSelection(options)) {
+    validateShotSelectionOptions(positionalScenes, options);
+    return;
+  }
+  if (options.format !== void 0) {
+    throw new Error("--format applies to --shot and --all-shots.");
+  }
   const exploratoryOptions = [
     options.center,
     options.bounds,
@@ -1354,7 +1652,9 @@ function validateSelectionOptions(positionalScenes, options) {
     throw new Error("Exploratory camera, viewport, and theme flags require --map.");
   }
   if (!options.all && positionalScenes.length === 0) {
-    throw new Error("Select at least one scene, use --all, or use --map for exploration.");
+    throw new Error(
+      "Select at least one scene, use --all, use --map for exploration, or select shots with --shot."
+    );
   }
 }
 function createExploratoryScene(options) {
@@ -1496,6 +1796,8 @@ function captureFailurePhase(error, code) {
   if (code === "MAP_LOAD_FAILED") return "map-load";
   if (code === "SCREENSHOT_FAILED" || code === "INVALID_PNG") return "screenshot";
   if (code === "SCENE_NOT_FOUND" || code.startsWith("APPLICATION_")) return "scene-resolution";
+  if (code === "SHOT_NOT_FOUND") return "shot-resolution";
+  if (code.startsWith("VIDEO_")) return "video-encode";
   if (code === "ABORTED") return "capture";
   return "input-validation";
 }
@@ -2464,47 +2766,17 @@ async function requestMapCapability(session, target, scopes, options = {}) {
   } catch (error) {
     return { error: safeTransportError(error, "Map capability request failed."), ok: false };
   }
-  if (!response.ok) {
-    return { error: `Map capability request failed (${response.status}).`, ok: false };
-  }
-  const body = asRecord(response.body);
-  if (!response.json || typeof body.capability !== "string" || !body.capability.startsWith("tf_cap_") || body.capability.length > 8192 || typeof body.mapId !== "string" || !/^map_[A-Za-z0-9_-]{16}$/u.test(body.mapId) || body.mapId !== target.mapId || !validIsoDate(body.expiresAt) || !Array.isArray(body.scopes) || body.scopes.join("\0") !== [...scopes].sort().join("\0")) {
-    return { error: "Map capability response was invalid.", ok: false };
-  }
-  return { capability: body.capability, mapId: body.mapId, ok: true };
-}
-async function requestProjectCapability(session, project, scopes, options = {}) {
-  let response;
-  try {
-    response = await requestHostedJson(
-      session.apiOrigin,
-      "/v1/cli/project-capabilities",
-      {
-        ...jsonRequest("POST", { project, scopes }),
-        headers: {
-          ...authorizationHeaders(session.accountSession),
-          "Content-Type": "application/json"
-        }
-      },
-      options
-    );
-  } catch (error) {
-    return {
-      error: safeTransportError(error, "Project capability request failed."),
-      ok: false
-    };
-  }
   if (!response.ok) {
     return {
-      error: response.status === 401 ? rejectedAccountSessionMessage : `Project capability request failed (${response.status}).`,
+      error: response.status === 401 ? rejectedAccountSessionMessage : `Map capability request failed (${response.status}).`,
       ok: false
     };
   }
   const body = asRecord(response.body);
-  if (!response.json || typeof body.capability !== "string" || !body.capability.startsWith("tf_cap_") || body.capability.length > 8192 || body.reference !== project || !validIsoDate(body.expiresAt) || !Array.isArray(body.scopes) || body.scopes.join("\0") !== [...scopes].sort().join("\0")) {
-    return { error: "Project capability response was invalid.", ok: false };
+  if (!response.json || typeof body.capability !== "string" || !body.capability.startsWith("tf_cap_") || body.capability.length > 8192 || typeof body.mapId !== "string" || !/^map_[A-Za-z0-9_-]{16}$/u.test(body.mapId) || body.mapId !== target.mapId || !validIsoDate(body.expiresAt) || !Array.isArray(body.scopes) || body.scopes.join("\0") !== [...scopes].sort().join("\0")) {
+    return { error: "Map capability response was invalid.", ok: false };
   }
-  return { capability: body.capability, ok: true };
+  return { capability: body.capability, mapId: body.mapId, ok: true };
 }
 async function requestTeamCapability(session, team, scopes, options = {}) {
   let response;
@@ -3196,7 +3468,7 @@ import {
 // src/icon-diff-report.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { mkdir as mkdir3, readFile as readFile3, rename as rename3, unlink as unlink3, writeFile } from "fs/promises";
-import { basename as basename2, dirname as dirname6, join } from "path";
+import { basename as basename2, dirname as dirname6, join as join2 } from "path";
 import {
   compareCodeUnits as compareCodeUnits5,
   sha256Hex,
@@ -3663,7 +3935,7 @@ async function writeAtomicReport(path, html, force) {
     if (!isMissingFile3(error)) throw error;
   }
   await mkdir3(dirname6(path), { recursive: true });
-  const temporaryPath = join(
+  const temporaryPath = join2(
     dirname6(path),
     `.${basename2(path)}.${process.pid}.${randomUUID2()}.tmp`
   );
@@ -5292,18 +5564,6 @@ async function fetchAccountProjects(session, includeArchived) {
   }
   return { error: "Destination discovery exceeded its safe page limit.", ok: false, status: 502 };
 }
-async function resolveAccountProjectTarget(session, requestedProject) {
-  const result = await fetchAccountProjects(session, false);
-  if (!result.ok) return { error: result.error, kind: "remote", status: result.status };
-  if (requestedProject) {
-    const parsed = parseProjectReference(requestedProject);
-    if (!parsed) return { kind: "invalid", targets: result.items };
-    const target = result.items.find((candidate) => candidate.reference === requestedProject);
-    return target ? { kind: "selected", target } : { kind: "missing", targets: result.items };
-  }
-  if (result.items.length === 1) return { kind: "selected", target: result.items[0] };
-  return result.items.length ? { kind: "ambiguous", targets: result.items } : { kind: "missing", targets: [] };
-}
 async function requireCommandSession(options, dependencies) {
   let config;
   try {
@@ -8445,7 +8705,7 @@ program.command("build").description("Generate static Tileflow styles").option("
     printKeyValue("Output", pathLabel(resolve8(process.cwd(), options.out)));
   }
 );
-program.command("preview").alias("dev").description("Run a local map preview").option("-c, --config <path>", "config path", defaultConfigPath).option("--against-config <path>", "second config for the comparison workbench").option("--against-map <name>", "map on the right; defaults to --map").option("--against-scene <name>", "committed standalone scene on the right").option("--against-theme <name>", "concrete theme on the right; defaults to --theme").option("--host <host>", "bind host: an explicit IP address or localhost", defaultTileflowDevHost).option("--map <name>", "preview one configured map").option("--theme <name>", "preview one concrete theme; defaults to the map default").option("--renderer <renderer>", "artifact renderer: web or native", "web").option("-p, --port <port>", "preview port", "3333").option("--scene <name>", "preview one committed standalone map scene").option(
+program.command("preview").description("Run a local map preview").option("-c, --config <path>", "config path", defaultConfigPath).option("--against-config <path>", "second config for the comparison workbench").option("--against-map <name>", "map on the right; defaults to --map").option("--against-scene <name>", "committed standalone scene on the right").option("--against-theme <name>", "concrete theme on the right; defaults to --theme").option("--host <host>", "bind host: an explicit IP address or localhost", defaultTileflowDevHost).option("--map <name>", "preview one configured map").option("--theme <name>", "preview one concrete theme; defaults to the map default").option("--renderer <renderer>", "artifact renderer: web or native", "web").option("-p, --port <port>", "preview port", "3333").option("--scene <name>", "preview one committed standalone map scene").option(
   "--api-base-url <url>",
   "Tileflow API base URL used to resolve official map assets",
   process.env.TILEFLOW_API_URL ?? defaultApiUrl
@@ -8461,7 +8721,7 @@ program.command("preview").alias("dev").description("Run a local map preview").o
         process.stdout.write(
           `${JSON.stringify({
             schemaVersion: 1,
-            command: "dev",
+            command: "preview",
             event: "error",
             code: first?.code ?? "NATIVE_RENDERER_UNSUPPORTED",
             phase: first?.phase ?? "command-validation",
@@ -8481,7 +8741,7 @@ program.command("preview").alias("dev").description("Run a local map preview").o
         process.stdout.write(
           `${JSON.stringify({
             schemaVersion: 1,
-            command: "dev",
+            command: "preview",
             event: "error",
             code: "NATIVE_RENDERER_UNSUPPORTED",
             phase: "command-validation",
@@ -8613,7 +8873,7 @@ program.command("preview").alias("dev").description("Run a local map preview").o
           process.stdout.write(
             `${JSON.stringify({
               schemaVersion: 1,
-              command: "dev",
+              command: "preview",
               event: recovered ? "recovered" : state.status,
               generation: state.generation,
               ..."lastGoodGeneration" in state && state.lastGoodGeneration !== void 0 ? { lastGoodGeneration: state.lastGoodGeneration } : {},
@@ -8682,7 +8942,7 @@ program.command("preview").alias("dev").description("Run a local map preview").o
           process.stdout.write(
             `${JSON.stringify({
               schemaVersion: 1,
-              command: "dev",
+              command: "preview",
               event: "stopped",
               generation,
               ...nativeLifecycleFields
@@ -8700,24 +8960,10 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
 ).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").action(
   async (options) => {
     const source = resolveDeploySource(process.env);
-    const resolveApi = (selectedMap) => requireApiOptions(options, {
+    const resolveApi = () => requireApiOptions(options, {
       allowStoredCredential: allowsStoredDeployCredential(source),
       assertExplicitKeyMap: true,
-      capabilityScopes: ["styles:write"],
-      retryCommand: cliInvocation([
-        "tileflow",
-        "deploy",
-        "--config",
-        options.config,
-        "--manifest",
-        options.manifest,
-        "--api-url",
-        options.apiUrl ?? defaultApiUrl,
-        ...options.overwriteSelfHostedManifest ? ["--overwrite-self-hosted-manifest"] : [],
-        ...options.mapId ? ["--map-id", options.mapId] : [],
-        ...options.map && selectedMap ? ["--map", selectedMap] : [],
-        ...options.withNative ? ["--with-native"] : []
-      ])
+      capabilityScopes: ["styles:write"]
     });
     const apiUrl = normalizeApiOrigin(options.apiUrl ?? defaultApiUrl);
     delete process.env.TILEFLOW_API_KEY;
@@ -8823,7 +9069,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       return;
     }
     const existingManifest = outputManifest;
-    const api = await resolveApi(mapNames[0]);
+    const api = await resolveApi();
     if (!api) return;
     const hostedSpriteByPackageHash = /* @__PURE__ */ new Map();
     for (const iconPackage of compiledIcons.packages) {
@@ -9108,13 +9354,6 @@ program.command("status").description("Show deployed compiled styles").option("-
   try {
     api = await requireApiOptions(options, {
       capabilityScopes: ["status:read"],
-      retryCommand: cliInvocation([
-        "tileflow",
-        "status",
-        "--api-url",
-        options.apiUrl ?? defaultApiUrl,
-        ...options.json ? ["--json"] : []
-      ]),
       silent: options.json
     });
   } catch (error) {
@@ -9164,18 +9403,6 @@ registerIconDiffCommand(iconsCommand, {
       assertExplicitKeyMap: true,
       allowStoredCredential: allowsStoredDeployCredential(source),
       capabilityScopes: ["status:read"],
-      retryCommand: cliInvocation([
-        "tileflow",
-        "icons",
-        "diff",
-        "--against",
-        options.against,
-        ...options.config ? ["--config", options.config] : [],
-        "--map-id",
-        options.mapId,
-        "--api-url",
-        options.apiUrl ?? defaultApiUrl
-      ]),
       silent: true
     });
   }
@@ -9223,7 +9450,7 @@ async function runTileflowComparisonPreview(options, address) {
     const emit = (event) => {
       if (!options.json) return;
       process.stdout.write(
-        `${JSON.stringify({ schemaVersion: 1, command: "dev.compare", ...event })}
+        `${JSON.stringify({ schemaVersion: 1, command: "preview.compare", ...event })}
 `
       );
     };
@@ -9613,19 +9840,13 @@ async function loadExistingDeployManifest(manifestPath, options) {
 async function requireApiOptions(options, behavior = {}) {
   const apiUrl = normalizeApiOrigin(options.apiUrl ?? defaultApiUrl);
   const requestedMapId = options.mapId;
-  const requested = options.project ? parseProjectReference(options.project) : null;
-  if (requestedMapId && !/^map_[A-Za-z0-9_-]{16}$/u.test(requestedMapId)) {
+  if (!requestedMapId || !/^map_[A-Za-z0-9_-]{16}$/u.test(requestedMapId)) {
     if (!behavior.silent) logError("Managed Map ID is invalid.");
     process.exitCode = 1;
     return null;
   }
-  if (options.project && !requested) {
-    if (!behavior.silent) logError("Managed destination must use @organization/project syntax.");
-    process.exitCode = 1;
-    return null;
-  }
   if (options.apiKey) {
-    if (requestedMapId && behavior.assertExplicitKeyMap) {
+    if (behavior.assertExplicitKeyMap) {
       const profile = await validateApiKey(apiUrl, options.apiKey);
       if (!profile.ok) {
         if (!behavior.silent) logError(profile.error);
@@ -9638,33 +9859,7 @@ async function requireApiOptions(options, behavior = {}) {
         return null;
       }
     }
-    if (requested) {
-      const profile = await validateApiKey(apiUrl, options.apiKey);
-      if (!profile.ok) {
-        if (!behavior.silent) logError(profile.error);
-        process.exitCode = 1;
-        return null;
-      }
-      if (profile.value.credentialType === "team_api_key") {
-        if (!behavior.silent) logError("Team credentials require an explicit --map-id.");
-        process.exitCode = 1;
-        return null;
-      }
-      if (requested && projectReference(profile.value) !== options.project) {
-        if (!behavior.silent) {
-          logError(
-            `This project key belongs to ${projectReference(profile.value)}, not ${options.project}.`
-          );
-        }
-        process.exitCode = 1;
-        return null;
-      }
-    }
-    return {
-      apiKey: options.apiKey,
-      apiUrl,
-      ...requestedMapId ? { mapId: requestedMapId } : {}
-    };
+    return { apiKey: options.apiKey, apiUrl, mapId: requestedMapId };
   }
   const allowStoredCredential = behavior.allowStoredCredential !== false && allowsStoredDeployCredential(resolveDeploySource(process.env));
   if (!allowStoredCredential) {
@@ -9697,46 +9892,9 @@ async function requireApiOptions(options, behavior = {}) {
     process.exitCode = 1;
     return null;
   }
-  if (requestedMapId) {
-    const capability2 = await requestMapCapability(
-      resolvedSession.session,
-      { mapId: requestedMapId },
-      behavior.capabilityScopes ?? ["status:read"]
-    );
-    if (!capability2.ok) {
-      if (!behavior.silent) logError(capability2.error);
-      process.exitCode = 1;
-      return null;
-    }
-    return { apiKey: capability2.capability, apiUrl, mapId: capability2.mapId };
-  }
-  const target = await resolveAccountProjectTarget(resolvedSession.session, options.project);
-  if (target.kind === "remote") {
-    if (!behavior.silent) logError(target.error);
-    process.exitCode = 1;
-    return null;
-  }
-  if (target.kind !== "selected") {
-    if (!behavior.silent) {
-      const references = target.targets.map((candidate) => candidate.reference);
-      if (target.kind === "ambiguous") {
-        const retry = `${behavior.retryCommand ?? "tileflow <command>"} --project ${references[0]}`;
-        logError(`Managed destination is ambiguous: ${references.join(", ")}.`);
-        printNextSteps([`Retry exactly with ${command(retry)}.`]);
-      } else if (target.kind === "invalid") {
-        logError("Managed destination must use @organization/project syntax.");
-      } else {
-        logError(
-          options.project ? `Destination ${options.project} is not accessible to this account.` : "No active managed destination is accessible to this account."
-        );
-      }
-    }
-    process.exitCode = 1;
-    return null;
-  }
-  const capability = await requestProjectCapability(
+  const capability = await requestMapCapability(
     resolvedSession.session,
-    target.target.reference,
+    { mapId: requestedMapId },
     behavior.capabilityScopes ?? ["status:read"]
   );
   if (!capability.ok) {
@@ -9744,7 +9902,7 @@ async function requireApiOptions(options, behavior = {}) {
     process.exitCode = 1;
     return null;
   }
-  return { apiKey: capability.capability, apiUrl };
+  return { apiKey: capability.capability, apiUrl, mapId: capability.mapId };
 }
 function printTileflowPreviewError(error) {
   if (error instanceof TileflowStyleValidationError2) {
@@ -9895,12 +10053,6 @@ function plural(count, singular, pluralForm = `${singular}s`) {
 function command(value) {
   return pc6.cyan(value);
 }
-function cliInvocation(parts) {
-  return parts.map(quoteCliArgument).join(" ");
-}
-function quoteCliArgument(value) {
-  return /^[A-Za-z0-9_./:@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
-}
 function link(value) {
   return pc6.cyan(value);
 }

package/docs/cli-setup-and-defaults.md

@@ -37,8 +37,8 @@ npx tileflow preview --scene madrid-mobile
 To work on another map, point `--config` at another singular config. Multi-map catalogs are internal
 orchestration used by this repository's workbench and are not a second public config shape.
 
-`tileflow dev` remains a compatibility alias. The `preview` name distinguishes this SDK preview
-server from an application's own `npm run dev` process.
+The `preview` name distinguishes this SDK preview server from an application's own `npm run dev`
+process.
 
 `--api-base-url` selects the origin used by official World, Bathymetry vector, Bathymetry DEM,
 Nautical, and terrain TileJSON sources in the generated preview style. In particular, a hybrid

package/docs/command-families.md

@@ -5,7 +5,7 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 | Family            | Commands                                                                                       |
 | ----------------- | ---------------------------------------------------------------------------------------------- |
 | Semantic language | `language manifest`, `language schema`                                                         |
-| Map authoring     | `init`, `validate`, `inspect`, `explain`, `semantic-diff`, `build`, `preview` (`dev` alias)    |
+| Map authoring     | `init`, `validate`, `inspect`, `explain`, `semantic-diff`, `build`, `preview`                  |
 | Local evidence    | `setup capture`, `capture`, `visual compare`, `visual analyze`, `visual diff`, `visual update` |
 | Data and assets   | `tileset inspect`, `tileset publish/list/status/purge`, `inspect features`, `icons list/diff`  |
 | Team Icon Sets    | `icon-set publish/list/status/versions/uses/archive/unarchive/purge`                           |
@@ -15,7 +15,7 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 
 Run `tileflow <command> --help` (or the family help, such as `tileflow icons --help`) for the exact
 arguments and bounded JSON modes. `preview` defaults to the existing web renderer. The explicit
-`preview --renderer native` / `dev --renderer native` mode serves watched `native-v1` artifacts only;
+`preview --renderer native` mode serves watched `native-v1` artifacts only;
 Metro remains the React Native JavaScript development server. See
 [Native artifacts and local preview](./native-artifacts.md) for the endpoint and qualification
 boundary.
@@ -28,5 +28,5 @@ authority when resolving revisions and are the only commands that select revisio
 `tileflow.icons.lock.json`. See the
 [Team Icon Set workflow](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/team-icon-sets.md).
 
-The CLI retains the hidden `projects` command family as a compatibility and support surface for the
-internal application boundary. It is not part of the ordinary workflow or the product catalog.
+The hidden `projects` command family lists and manages the internal application destinations of an
+account for support. It is not part of the ordinary workflow or the product catalog.

package/docs/native-artifacts.md

@@ -30,7 +30,7 @@ The ordinary web commands and their default artifact bytes retain their existing
 
 ## Watch and serve native artifacts
 
-`preview` and its `dev` alias use the same renderer selector:
+`preview` selects the renderer with `--renderer`:
 
 ```sh
 npx tileflow preview --renderer native --map stores --theme light

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.12",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -35,15 +35,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@hono/node-server": "2.0.10",
-    "@tileflow/capture": ">=0.1.0-alpha.28 <0.1.0-beta.0",
-    "@tileflow/coordinates": ">=0.1.0-alpha.1 <0.1.0-beta.0",
-    "@tileflow/coordinates-runtime": ">=0.1.0-alpha.4 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.31 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.29 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.7 <0.1.0-beta.0",
+    "@hono/node-server": "2.1.3",
+    "@tileflow/capture": ">=0.1.0-alpha.30 <0.1.0-beta.0",
+    "@tileflow/coordinates": ">=0.1.0-alpha.2 <0.1.0-beta.0",
+    "@tileflow/coordinates-runtime": ">=0.1.0-alpha.5 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.34 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.31 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.8 <0.1.0-beta.0",
     "commander": "^15.0.0",
-    "hono": "4.13.5",
+    "hono": "4.13.7",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3"
   },