@m0saic/templates 0.2.0

package/dist/m0saic/media/screencap_grid_aspect_safe/v1/screencap-grid-aspect-safe.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Aspect-safe screencap grid — sibling of `screencap_grid` that fans
+ * out into a *coordinated landscape + portrait pair* per input file.
+ *
+ * Per source video the template emits two outputs (one desktop /
+ * landscape, one mobile / portrait) whose grids:
+ *   - have the same total cell count;
+ *   - have matching cell aspect ratios across orientations (NOT a
+ *     naive transpose);
+ *   - render quantization-free at their respective canvases.
+ *
+ * The coordinated pair is picked by `aspectSafeGrid` from
+ * `@m0saic/dsl-stdlib`. To give the user a "scroll through grids" UX,
+ * the template enumerates a cell-count window
+ * (`targetCellCountMin..targetCellCountMax`) and ranks the resulting
+ * pairs. The `gridChoice` prop indexes into that ranked list.
+ *
+ * The shape question comes first: `cellShape` declares what shape the
+ * CELLS should be — "landscape" (16:9, the default), "square", or
+ * "portrait" (9:16), with `targetCellAspect` as the exact-ratio escape
+ * hatch — and the search finds, per orientation, the (rows, cols) that
+ * realizes that shape at the same cell count (a portrait shape ⇒ many
+ * columns on the landscape canvas, many rows on the portrait one).
+ * Ranking is shape-first: both orientations' distance to the target;
+ * cross-orientation match follows by triangle inequality.
+ *
+ * Multi-input: just like `screencap_grid`, `sourceIds: string[]`
+ * triggers an `emit: "multi"` pipeline. Combined with the per-input
+ * landscape + portrait fan-out, N inputs produce 2 × N output files.
+ *
+ * Aligned with `screencap_grid/v2` (2026-07-21; the former
+ * `…_aspect_safe_png/v1` + `…_aspect_safe_mp4/v1` twins are collapsed
+ * into this one template — same hard-replace move as the screengrid
+ * png/mp4 merge; the gridCellInset negative example is archived at
+ * `screencap_grid/v1`):
+ *   - `outputFormat` knob picks png (static contact sheet) vs mp4
+ *     (animated grid); each step document bakes its own `format`
+ *     (watermark/trickplay precedent) and the template-level format
+ *     hint is gone.
+ *   - Layout is the v2 machinery: integer gap-carved tile rects
+ *     (`computeGridTileRects`) placed via `placeInsetPieces` — gaps
+ *     are pixel-exact at every orientation canvas (the deprecated
+ *     `gridCellInset` ideal-cell fractions wobbled ±1px under the
+ *     content-driven info pane). Timestamps are same-rect pieces at
+ *     `importance: 1`, so the chip is guaranteed above its tile and
+ *     hugs the visible (gap-carved) tile edge.
+ *   - Static steps carry the nominal single-frame 40ms duration;
+ *     animated steps track `ctx.target.durationMs`.
+ */
+import type { MosaicEngineContext, MosaicRenderableFile, MosaicTemplate } from "@m0saic/types";
+import type { MosaicColor } from "@m0saic/types";
+import { aspectSafeGrid } from "@m0saic/dsl-stdlib";
+import { type ScreencapOutputFormat, type TextAlign, type TileCorner } from "../../screencap_grid/v1/screencap-grid";
+import { type ScreencapInfoPaneConfig, type ScreencapTimestampsConfig, type ScreencapTilesConfig } from "../../screencap_grid/v2/screencap-grid";
+/** Preset cell shapes — the answer to "what shape should a cell be?". */
+export type AspectSafeCellShape = "landscape" | "square" | "portrait";
+/** The aspect ratio each preset targets (width / height). */
+export declare const CELL_SHAPE_RATIOS: Record<AspectSafeCellShape, number>;
+/** Pair-search tuning (the "Grid Search" group). */
+export type AspectSafeSearchConfig = {
+    /** Exact target cell aspect (w/h) — OVERRIDES `cellShape` when set. */
+    cellAspect?: number;
+    /** Lower bound of the cell-count sweep. */
+    minCells?: number;
+    /** Upper bound of the cell-count sweep. */
+    maxCells?: number;
+};
+/** Output canvas dims per orientation (the "Canvas" group). */
+export type AspectSafeCanvasConfig = {
+    landscapeW?: number;
+    landscapeH?: number;
+    portraitW?: number;
+    portraitH?: number;
+};
+export type ScreencapGridAspectSafeProps = {
+    /** The grid's source input(s) — emit:multi fan-out (2 outputs per file). */
+    sourceIds?: string[];
+    /**
+     * Deliverable format: "png" renders static contact sheets (each tile a
+     * frozen frame at its timestamp); "mp4" renders animated grids (each
+     * tile plays from its timestamp). Default "png".
+     */
+    outputFormat?: ScreencapOutputFormat;
+    /**
+     * The shape question — what shape should the CELLS be? Drives the pair
+     * search: pairs are ranked by how close BOTH orientations' cells sit to
+     * this shape (sum of log-distances; the cross-orientation match follows
+     * automatically), and the shape biases which (rows, cols) factorization
+     * each cell count picks — e.g. portrait cells put many columns on the
+     * landscape canvas and many rows on the portrait one. Default
+     * "landscape" (16:9 cells — the natural shape for video frames).
+     */
+    cellShape?: AspectSafeCellShape;
+    /**
+     * Index into the ranked list of (landscape, portrait) pairs enumerated
+     * across the search window. 0 = best-ranked (both orientations' cells
+     * closest to the wanted cell shape; cross-orientation match + density as
+     * tiebreaks). Out-of-range gets clamped.
+     */
+    gridChoice?: number;
+    /** Pair-search tuning (collapsible group): exact aspect + cell-count window. */
+    search?: AspectSafeSearchConfig;
+    /** Output canvas dims per orientation (collapsible group). */
+    canvas?: AspectSafeCanvasConfig;
+    /** Info pane (collapsible group). */
+    infoPane?: ScreencapInfoPaneConfig;
+    /** Per-tile timestamps (collapsible group). */
+    timestamps?: ScreencapTimestampsConfig;
+    /** Tile gap + fit (collapsible group). */
+    tiles?: ScreencapTilesConfig;
+    /**
+     * Dev-only geometry contract: assert every tile's computed rect survived
+     * to the pixels at each orientation canvas; on violation that step renders
+     * a GEOMETRY_CONTRACT error mosaic. Deterministic default false.
+     */
+    debugGeometry?: boolean;
+};
+type ResolvedConfig = {
+    inputs: string[];
+    /** Target cell aspect (w/h), or null = legacy cross-match-only ranking. */
+    targetCellAspect: number | null;
+    gridChoice: number;
+    countMin: number;
+    countMax: number;
+    landscapeW: number;
+    landscapeH: number;
+    portraitW: number;
+    portraitH: number;
+    withInfoPane: boolean;
+    headerAlign: TextAlign;
+    withTileTimestamp: boolean;
+    timestampCorner: TileCorner;
+    timestampColor: MosaicColor;
+    timestampBgColor: MosaicColor;
+    tileGapPx: number;
+    tileFit: "contain" | "cover";
+    debugGeometry: boolean;
+};
+type AspectSafePair = ReturnType<typeof aspectSafeGrid>;
+/**
+ * How far BOTH orientations' cells sit from the target shape — the sum of
+ * per-orientation log-distances. Log space keeps 1.5 and 1/1.5 equally far
+ * from square; summing both orientations means a pair only ranks well when
+ * EACH canvas realizes the wanted shape (and then the cross-orientation
+ * match follows by the triangle inequality: delta ≤ distL + distP).
+ */
+export declare function targetShapeDistance(pair: AspectSafePair, target: number): number;
+/**
+ * Enumerate coordinated landscape/portrait pairs across the cell-count
+ * window. Each `targetCellCount` is tried with tolerance 0 (exact
+ * count). Failures (no feasible pair) are silently dropped. Results
+ * are sorted so the best pair lands at index 0:
+ *
+ * With `targetCellAspect` set (shape-first — the shape question decides):
+ *   1. Smallest {@link targetShapeDistance} first (both orientations'
+ *      cells closest to the wanted shape).
+ *   2. Then smallest `cellAspectLogDelta` (cross-orientation match).
+ *   3. Then larger cellCount (denser grid).
+ * The target is also passed INTO `aspectSafeGrid` per cell count, so each
+ * count picks its shape-aligned (rows, cols) factorization — ranking alone
+ * could not recover a factorization the builder didn't pick.
+ *
+ * Without a target (legacy):
+ *   1. Smallest `cellAspectLogDelta` first (best cross-orientation
+ *      cell-shape match).
+ *   2. Tied AR match → larger cellCount wins (more cells = denser
+ *      grid, which is usually what the user wants).
+ */
+export declare function enumerateAspectSafePairs(cfg: Pick<ResolvedConfig, "countMin" | "countMax" | "landscapeW" | "landscapeH" | "portraitW" | "portraitH"> & Partial<Pick<ResolvedConfig, "targetCellAspect">>): AspectSafePair[];
+/**
+ * Top-level dispatcher. Always returns a pipeline on success (even
+ * for a single input — 2 orientations means 2 steps). Returns an
+ * error mosaic when inputs are missing or no feasible grid pair
+ * exists in the search range. The `outputFormat` knob picks the mode:
+ * png → static contact sheets, mp4 → animated grids.
+ */
+export declare function renderScreencapGridAspectSafe(props: ScreencapGridAspectSafeProps, ctx: MosaicEngineContext): Promise<MosaicRenderableFile>;
+export declare const ScreencapGridAspectSafe: MosaicTemplate<ScreencapGridAspectSafeProps>;
+export {};