@tileflow/core 0.1.0-alpha.32 → 0.1.0-alpha.34

package/dist/{capture-scene-BaAJjGq7.d.ts → capture-shot-ChPQvPyi.d.ts}

@@ -168,4 +168,124 @@ type NormalizedTileflowCaptureScene = {
 declare function normalizeTileflowCaptureScene(input: TileflowCaptureScene): NormalizedTileflowCaptureScene;
 declare function normalizeTileflowCaptureId(value: string | undefined): string | undefined;
 
-export { type NormalizedTileflowCaptureScene as N, type TileflowCaptureScene as T, type TileflowCaptureApplicationTarget as a, type TileflowCaptureBoundsCamera as b, type TileflowCaptureCamera as c, type TileflowCaptureCenterCamera as d, type TileflowCaptureMapTarget as e, type TileflowCaptureTarget as f, type TileflowCaptureViewport as g, normalizeTileflowCaptureScene as h, tileflowCaptureBoundsCameraSchema as i, tileflowCaptureCameraSchema as j, tileflowCaptureCenterCameraSchema as k, tileflowCaptureIdSchema as l, tileflowCaptureMapTargetSchema as m, normalizeTileflowCaptureId as n, tileflowCaptureSceneLimits as o, tileflowCaptureSceneNameSchema as p, tileflowCaptureSceneSchema as q, tileflowCaptureSceneSchemaVersion as r, tileflowCaptureTargetSchema as s, tileflowCaptureApplicationTargetSchema as t, tileflowCaptureViewportSchema as u, tileflowCaptureSceneFitIssue as v };
+/** A camera between keyframes: always the center form, with bearing and pitch resolved. */
+type TileflowShotCamera = {
+    type: 'center';
+    center: [number, number];
+    zoom: number;
+    bearing: number;
+    pitch: number;
+};
+
+declare const tileflowCaptureShotSchemaVersion: 1;
+declare const tileflowCaptureShotLimits: Readonly<{
+    blendThemes: Readonly<{
+        maximum: 8;
+        minimum: 2;
+    }>;
+    defaultFps: 30;
+    durationMs: Readonly<{
+        maximum: 60000;
+    }>;
+    fps: readonly [24, 25, 30, 50, 60];
+    keyframes: Readonly<{
+        maximum: 64;
+        minimum: 2;
+    }>;
+    maximumFrames: 3600;
+}>;
+/** Shot names follow the same portable artifact-name rules as scene names. */
+declare const tileflowCaptureShotNameSchema: z.ZodString;
+declare const tileflowCaptureShotBlendSchema: z.ZodObject<{
+    themes: z.ZodArray<z.ZodString>;
+    position: z.ZodNumber;
+}, z.core.$strict>;
+declare const tileflowCaptureShotKeyframeSchema: z.ZodObject<{
+    at: z.ZodNumber;
+    camera: z.ZodObject<{
+        type: z.ZodLiteral<"center">;
+        center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        zoom: z.ZodNumber;
+        bearing: z.ZodOptional<z.ZodNumber>;
+        pitch: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    blend: z.ZodOptional<z.ZodObject<{
+        themes: z.ZodArray<z.ZodString>;
+        position: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const tileflowCaptureShotSchema: z.ZodObject<{
+    theme: z.ZodString;
+    viewport: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        dpr: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    }, z.core.$strict>;
+    fps: z.ZodOptional<z.ZodLiteral<24 | 25 | 30 | 50 | 60>>;
+    keyframes: z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        camera: z.ZodObject<{
+            type: z.ZodLiteral<"center">;
+            center: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+            zoom: z.ZodNumber;
+            bearing: z.ZodOptional<z.ZodNumber>;
+            pitch: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        blend: z.ZodOptional<z.ZodObject<{
+            themes: z.ZodArray<z.ZodString>;
+            position: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    easing: z.ZodOptional<z.ZodEnum<{
+        linear: "linear";
+        smooth: "smooth";
+    }>>;
+    map: z.ZodString;
+}, z.core.$strict>;
+type TileflowCaptureShotBlend = z.infer<typeof tileflowCaptureShotBlendSchema>;
+type TileflowCaptureShotKeyframe = z.infer<typeof tileflowCaptureShotKeyframeSchema>;
+type TileflowCaptureShot = z.infer<typeof tileflowCaptureShotSchema>;
+type TileflowCaptureShotEasing = 'linear' | 'smooth';
+type NormalizedTileflowCaptureShotCamera = TileflowShotCamera;
+type NormalizedTileflowCaptureShot = {
+    map: string;
+    theme: string;
+    viewport: {
+        width: number;
+        height: number;
+        dpr: 1 | 2;
+    };
+    fps: 24 | 25 | 30 | 50 | 60;
+    easing: TileflowCaptureShotEasing;
+    keyframes: Array<{
+        at: number;
+        camera: NormalizedTileflowCaptureShotCamera;
+        blend?: {
+            themes: string[];
+            position: number;
+        };
+    }>;
+};
+/** One rendered frame of a shot: the camera and blend position at `at` milliseconds. */
+type TileflowCaptureShotFrame = {
+    index: number;
+    at: number;
+    camera: NormalizedTileflowCaptureShotCamera;
+    /** Present when the shot blends themes. */
+    blendPosition?: number;
+};
+declare function normalizeTileflowCaptureShot(input: TileflowCaptureShot): NormalizedTileflowCaptureShot;
+/**
+ * The number of frames a shot renders: one at the start and one every `1 / fps` seconds up to its
+ * last keyframe. The last keyframe is a frame when its time is a whole number of frame intervals.
+ */
+declare function tileflowCaptureShotFrameCount(shot: Pick<TileflowCaptureShot, 'fps' | 'keyframes'>): number;
+/**
+ * Interpolates every frame of a shot. Frame `i` shows the shot at `i * 1000 / fps` milliseconds.
+ * Within each keyframe segment the center moves in Web Mercator coordinates along the shorter way
+ * around the world, zoom and pitch change linearly, bearing turns along the shorter arc, and the
+ * blend position changes linearly; `easing: 'smooth'` eases each segment in and out.
+ */
+declare function tileflowCaptureShotFrames(shot: TileflowCaptureShot | Omit<TileflowCaptureShot, 'map'>): TileflowCaptureShotFrame[];
+
+export { tileflowCaptureSceneSchemaVersion as A, tileflowCaptureShotBlendSchema as B, tileflowCaptureShotFrameCount as C, tileflowCaptureShotFrames as D, tileflowCaptureShotKeyframeSchema as E, tileflowCaptureShotLimits as F, tileflowCaptureShotNameSchema as G, tileflowCaptureShotSchema as H, tileflowCaptureShotSchemaVersion as I, tileflowCaptureTargetSchema as J, tileflowCaptureViewportSchema as K, tileflowCaptureSceneFitIssue as L, type NormalizedTileflowCaptureScene as N, type TileflowCaptureScene as T, type TileflowCaptureShot as a, type NormalizedTileflowCaptureShot as b, type NormalizedTileflowCaptureShotCamera as c, type TileflowCaptureApplicationTarget as d, type TileflowCaptureBoundsCamera as e, type TileflowCaptureCamera as f, type TileflowCaptureCenterCamera as g, type TileflowCaptureMapTarget as h, type TileflowCaptureShotBlend as i, type TileflowCaptureShotEasing as j, type TileflowCaptureShotFrame as k, type TileflowCaptureShotKeyframe as l, type TileflowCaptureTarget as m, type TileflowCaptureViewport as n, normalizeTileflowCaptureId as o, normalizeTileflowCaptureScene as p, normalizeTileflowCaptureShot as q, tileflowCaptureBoundsCameraSchema as r, tileflowCaptureCameraSchema as s, tileflowCaptureApplicationTargetSchema as t, tileflowCaptureCenterCameraSchema as u, tileflowCaptureIdSchema as v, tileflowCaptureMapTargetSchema as w, tileflowCaptureSceneLimits as x, tileflowCaptureSceneNameSchema as y, tileflowCaptureSceneSchema as z };

package/dist/capture.d.ts

@@ -1,4 +1,4 @@
-export { N as NormalizedTileflowCaptureScene, a as TileflowCaptureApplicationTarget, b as TileflowCaptureBoundsCamera, c as TileflowCaptureCamera, d as TileflowCaptureCenterCamera, e as TileflowCaptureMapTarget, T as TileflowCaptureScene, f as TileflowCaptureTarget, g as TileflowCaptureViewport, n as normalizeTileflowCaptureId, h as normalizeTileflowCaptureScene, t as tileflowCaptureApplicationTargetSchema, i as tileflowCaptureBoundsCameraSchema, j as tileflowCaptureCameraSchema, k as tileflowCaptureCenterCameraSchema, l as tileflowCaptureIdSchema, m as tileflowCaptureMapTargetSchema, v as tileflowCaptureSceneFitIssue, o as tileflowCaptureSceneLimits, p as tileflowCaptureSceneNameSchema, q as tileflowCaptureSceneSchema, r as tileflowCaptureSceneSchemaVersion, s as tileflowCaptureTargetSchema, u as tileflowCaptureViewportSchema } from './capture-scene-BaAJjGq7.js';
+export { N as NormalizedTileflowCaptureScene, b as NormalizedTileflowCaptureShot, c as NormalizedTileflowCaptureShotCamera, d as TileflowCaptureApplicationTarget, e as TileflowCaptureBoundsCamera, f as TileflowCaptureCamera, g as TileflowCaptureCenterCamera, h as TileflowCaptureMapTarget, T as TileflowCaptureScene, a as TileflowCaptureShot, i as TileflowCaptureShotBlend, j as TileflowCaptureShotEasing, k as TileflowCaptureShotFrame, l as TileflowCaptureShotKeyframe, m as TileflowCaptureTarget, n as TileflowCaptureViewport, o as normalizeTileflowCaptureId, p as normalizeTileflowCaptureScene, q as normalizeTileflowCaptureShot, t as tileflowCaptureApplicationTargetSchema, r as tileflowCaptureBoundsCameraSchema, s as tileflowCaptureCameraSchema, u as tileflowCaptureCenterCameraSchema, v as tileflowCaptureIdSchema, w as tileflowCaptureMapTargetSchema, L as tileflowCaptureSceneFitIssue, x as tileflowCaptureSceneLimits, y as tileflowCaptureSceneNameSchema, z as tileflowCaptureSceneSchema, A as tileflowCaptureSceneSchemaVersion, B as tileflowCaptureShotBlendSchema, C as tileflowCaptureShotFrameCount, D as tileflowCaptureShotFrames, E as tileflowCaptureShotKeyframeSchema, F as tileflowCaptureShotLimits, G as tileflowCaptureShotNameSchema, H as tileflowCaptureShotSchema, I as tileflowCaptureShotSchemaVersion, J as tileflowCaptureTargetSchema, K as tileflowCaptureViewportSchema } from './capture-shot-ChPQvPyi.js';
 import { z } from 'zod';
 
 /** Canonical, filesystem-safe identity shared by authored and emitted Tileflow resources. */

package/dist/capture.js

@@ -267,9 +267,219 @@ function hasControlCharacter(value) {
   }
   return false;
 }
+
+// src/capture-shot.ts
+import { z as z4 } from "zod";
+
+// src/capture-shot-motion.ts
+function tileflowShotStateAt(shot, at) {
+  const { keyframes } = shot;
+  const first = keyframes[0];
+  const last = keyframes.at(-1);
+  if (!first || !last || keyframes.length < 2)
+    throw new TypeError("A shot needs at least two keyframes.");
+  const time = Math.min(last.at, Math.max(first.at, Number.isFinite(at) ? at : first.at));
+  let segment = 0;
+  while (segment < keyframes.length - 2 && time > keyframes[segment + 1].at) segment += 1;
+  const from = keyframes[segment];
+  const to = keyframes[segment + 1];
+  const linear = Math.min(1, Math.max(0, (time - from.at) / (to.at - from.at)));
+  const t = shot.easing === "linear" ? linear : smoothstep(linear);
+  return {
+    at: time,
+    camera: interpolateCamera(cameraOf(from), cameraOf(to), t),
+    ...from.blend && to.blend ? { blendPosition: interpolateNumber(from.blend.position, to.blend.position, t) } : {}
+  };
+}
+function cameraOf({ camera }) {
+  return {
+    type: "center",
+    center: [camera.center[0], camera.center[1]],
+    zoom: camera.zoom,
+    bearing: camera.bearing ?? 0,
+    pitch: camera.pitch ?? 0
+  };
+}
+var maximumMercatorLatitude = 85.051129;
+function interpolateCamera(from, to, t) {
+  return {
+    type: "center",
+    center: interpolateCenter(from.center, to.center, t),
+    zoom: interpolateNumber(from.zoom, to.zoom, t),
+    bearing: interpolateBearing(from.bearing, to.bearing, t),
+    pitch: interpolateNumber(from.pitch, to.pitch, t)
+  };
+}
+function interpolateNumber(from, to, t) {
+  if (t <= 0 || from === to) return from;
+  if (t >= 1) return to;
+  return from + (to - from) * t;
+}
+function interpolateCenter(from, to, t) {
+  if (t <= 0 || from[0] === to[0] && from[1] === to[1]) return [from[0], from[1]];
+  if (t >= 1) return [to[0], to[1]];
+  const start = mercatorFromLngLat(from);
+  const end = mercatorFromLngLat(to);
+  let dx = end[0] - start[0];
+  if (dx > 0.5) dx -= 1;
+  else if (dx < -0.5) dx += 1;
+  return lngLatFromMercator([start[0] + dx * t, start[1] + (end[1] - start[1]) * t]);
+}
+function interpolateBearing(from, to, t) {
+  if (t <= 0 || from === to) return from;
+  if (t >= 1) return to;
+  const delta = ((to - from) % 360 + 540) % 360 - 180;
+  return wrapDegrees(from + delta * t);
+}
+function mercatorFromLngLat([longitude, latitude]) {
+  const clamped = Math.max(-maximumMercatorLatitude, Math.min(maximumMercatorLatitude, latitude));
+  return [
+    (180 + longitude) / 360,
+    (180 - 180 / Math.PI * Math.log(Math.tan(Math.PI / 4 + clamped * Math.PI / 360))) / 360
+  ];
+}
+function lngLatFromMercator([x, y]) {
+  const latitude = 360 / Math.PI * Math.atan(Math.exp((180 - y * 360) * Math.PI / 180)) - 90;
+  return [wrapDegrees(x * 360 - 180), latitude];
+}
+function wrapDegrees(value) {
+  if (value >= -180 && value <= 180) return value;
+  return ((value + 180) % 360 + 360) % 360 - 180;
+}
+function smoothstep(t) {
+  return t * t * (3 - 2 * t);
+}
+
+// src/capture-shot.ts
+var tileflowCaptureShotSchemaVersion = 1;
+var tileflowCaptureShotLimits = Object.freeze({
+  blendThemes: Object.freeze({ maximum: 8, minimum: 2 }),
+  defaultFps: 30,
+  durationMs: Object.freeze({ maximum: 6e4 }),
+  fps: Object.freeze([24, 25, 30, 50, 60]),
+  keyframes: Object.freeze({ maximum: 64, minimum: 2 }),
+  maximumFrames: 3600
+});
+var tileflowCaptureShotNameSchema = tileflowCaptureSceneNameSchema;
+var tileflowCaptureShotBlendSchema = z4.object({
+  themes: z4.array(tileflowThemeNameSchema).min(tileflowCaptureShotLimits.blendThemes.minimum).max(tileflowCaptureShotLimits.blendThemes.maximum),
+  position: z4.number().finite().min(0)
+}).strict().superRefine((blend, context) => {
+  if (new Set(blend.themes).size !== blend.themes.length) {
+    context.addIssue({ code: "custom", message: "Expected distinct themes", path: ["themes"] });
+  }
+  if (blend.position > blend.themes.length - 1) {
+    context.addIssue({
+      code: "custom",
+      message: `Expected a position from 0 to ${blend.themes.length - 1}`,
+      path: ["position"]
+    });
+  }
+});
+var tileflowCaptureShotKeyframeSchema = z4.object({
+  at: z4.number().int().min(0).max(tileflowCaptureShotLimits.durationMs.maximum),
+  camera: tileflowCaptureCenterCameraSchema,
+  blend: tileflowCaptureShotBlendSchema.optional()
+}).strict();
+var tileflowCaptureShotFields = {
+  theme: tileflowThemeNameSchema,
+  viewport: tileflowCaptureViewportSchema,
+  fps: z4.literal(tileflowCaptureShotLimits.fps).optional(),
+  keyframes: z4.array(tileflowCaptureShotKeyframeSchema).min(tileflowCaptureShotLimits.keyframes.minimum).max(tileflowCaptureShotLimits.keyframes.maximum),
+  easing: z4.enum(["smooth", "linear"]).optional()
+};
+var tileflowCaptureShotSchema = z4.object({ map: tileflowPortableIdSchema, ...tileflowCaptureShotFields }).strict().superRefine(checkShotTiming);
+var tileflowMapShotSchema = z4.object(tileflowCaptureShotFields).strict().superRefine(checkShotTiming);
+function normalizeTileflowCaptureShot(input) {
+  const shot = tileflowCaptureShotSchema.parse(input);
+  return { map: shot.map, ...normalizeShotFields(shot) };
+}
+function tileflowCaptureShotFrameCount(shot) {
+  const fps = shot.fps ?? tileflowCaptureShotLimits.defaultFps;
+  const duration = shot.keyframes.at(-1)?.at ?? 0;
+  return Math.floor(duration * fps / 1e3 + 1e-9) + 1;
+}
+function tileflowCaptureShotFrames(shot) {
+  const { map: _map, ...fields } = shot;
+  const normalized = normalizeShotFields(tileflowMapShotSchema.parse(fields));
+  const count = tileflowCaptureShotFrameCount(normalized);
+  const duration = normalized.keyframes.at(-1).at;
+  const frames = [];
+  for (let index = 0; index < count; index += 1) {
+    const at = Math.min(duration, index * 1e3 / normalized.fps);
+    frames.push({ index, ...tileflowShotStateAt(normalized, at) });
+  }
+  return frames;
+}
+function normalizeShotFields(shot) {
+  return {
+    theme: shot.theme,
+    viewport: { ...shot.viewport, dpr: shot.viewport.dpr ?? 1 },
+    fps: shot.fps ?? tileflowCaptureShotLimits.defaultFps,
+    easing: shot.easing ?? "smooth",
+    keyframes: shot.keyframes.map((keyframe) => ({
+      at: keyframe.at,
+      camera: {
+        type: "center",
+        center: keyframe.camera.center,
+        zoom: keyframe.camera.zoom,
+        bearing: keyframe.camera.bearing ?? 0,
+        pitch: keyframe.camera.pitch ?? 0
+      },
+      ...keyframe.blend ? { blend: { themes: [...keyframe.blend.themes], position: keyframe.blend.position } } : {}
+    }))
+  };
+}
+function checkShotTiming(shot, context) {
+  const { keyframes } = shot;
+  if (keyframes[0] && keyframes[0].at !== 0) {
+    context.addIssue({
+      code: "custom",
+      message: "Expected the first keyframe at 0 milliseconds",
+      path: ["keyframes", 0, "at"]
+    });
+  }
+  for (let index = 1; index < keyframes.length; index += 1) {
+    if (keyframes[index].at <= keyframes[index - 1].at) {
+      context.addIssue({
+        code: "custom",
+        message: "Expected a time after the previous keyframe",
+        path: ["keyframes", index, "at"]
+      });
+    }
+  }
+  const blended = keyframes.filter((keyframe) => keyframe.blend !== void 0);
+  if (blended.length > 0) {
+    const themes = JSON.stringify(blended[0].blend.themes);
+    keyframes.forEach((keyframe, index) => {
+      if (!keyframe.blend) {
+        context.addIssue({
+          code: "custom",
+          message: "Expected a blend on every keyframe when one keyframe blends themes",
+          path: ["keyframes", index, "blend"]
+        });
+      } else if (JSON.stringify(keyframe.blend.themes) !== themes) {
+        context.addIssue({
+          code: "custom",
+          message: "Expected the same themes, in the same order, on every keyframe",
+          path: ["keyframes", index, "blend", "themes"]
+        });
+      }
+    });
+  }
+  const frames = tileflowCaptureShotFrameCount(shot);
+  if (frames > tileflowCaptureShotLimits.maximumFrames) {
+    context.addIssue({
+      code: "custom",
+      message: `Expected at most ${tileflowCaptureShotLimits.maximumFrames} frames; this shot renders ${frames}`,
+      path: ["keyframes", keyframes.length - 1, "at"]
+    });
+  }
+}
 export {
   normalizeTileflowCaptureId,
   normalizeTileflowCaptureScene,
+  normalizeTileflowCaptureShot,
   tileflowCaptureApplicationTargetSchema,
   tileflowCaptureBoundsCameraSchema,
   tileflowCaptureCameraSchema,
@@ -281,6 +491,14 @@ export {
   tileflowCaptureSceneNameSchema,
   tileflowCaptureSceneSchema,
   tileflowCaptureSceneSchemaVersion,
+  tileflowCaptureShotBlendSchema,
+  tileflowCaptureShotFrameCount,
+  tileflowCaptureShotFrames,
+  tileflowCaptureShotKeyframeSchema,
+  tileflowCaptureShotLimits,
+  tileflowCaptureShotNameSchema,
+  tileflowCaptureShotSchema,
+  tileflowCaptureShotSchemaVersion,
   tileflowCaptureTargetSchema,
   tileflowCaptureViewportSchema,
   tileflowPortableIdSchema,