@m0saic/templates 0.2.0

package/dist/m0saic/media/screencap_grid/v2/screencap-grid.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Screencap Grid v2 — the v1 grid rebuilt on inset-recovery placement
+ * (handbook feasibility-precision-quantization.md §3c; `placeInsetPieces`).
+ *
+ * # Why v1 was superseded (the ideal-cell inset math)
+ *
+ * v1 realized the inter-tile gap with `gridCellInset`: a gutterless equal-split
+ * grid plus per-cell half-gap FRACTIONS computed against the IDEAL cell size
+ * (`gridW / cols`). Two failure modes make that approximate, not exact:
+ *
+ * 1. **Ideal vs quantized cells.** The engine floors `frac × actualCellPx`
+ *    against the cell the split ACTUALLY produced. Under the content-driven
+ *    info pane the grid region height is arbitrary (e.g. 1080 − 110 = 970px →
+ *    4 rows of 243/242/243/242), so the same fraction recovers 1px on one row
+ *    and 0px on the next — a 2px gap wobbles between 2px and 0px depending on
+ *    how each cell rounded.
+ * 2. **Floor loss on exact fractions.** Even when cells divide evenly, a plain
+ *    `n / cell` fraction can floor-lose the pixel (`floor((1/480)·480) → 0`
+ *    under IEEE) — the half-pixel-centering problem `placeInsetRects`
+ *    documents and solves.
+ *
+ * The v1 template stays registered (deprecated) as the reference for exactly
+ * this pitfall; it is the natural math a template author reaches for first.
+ *
+ * # The v2 model
+ *
+ * Every painted rect is computed in INTEGER pixels — the pane band and the
+ * gap-carved tiles (interior boundaries give `floor(gap/2)` to the right/lower
+ * neighbor and `ceil(gap/2)` to the left/upper one, so adjacent tiles sit
+ * exactly `tileGapPx` apart and odd gaps sum exactly; outer edges stay
+ * full-bleed). One `placeInsetPieces` call over the canvas then owns the
+ * quantization: cells round OUTWARD to a divisor lattice (bounded precision,
+ * basis ≤ 120 — the m0 stays composable when this template is nested via a
+ * mosaicx invocation) and each source carries a half-pixel-centered recovery
+ * inset that paints it back on its exact rect. Zero drift at every canvas;
+ * quantization collisions cost overlay LAYERS, never correctness.
+ *
+ * Per-tile timestamps are pieces sharing their tile's rect at `importance: 1`
+ * (guaranteed to paint above), so the chip hugs the visible tile instead of
+ * hanging into the gap as it could in v1.
+ *
+ * # Custom grid (escape hatch)
+ *
+ * The authored m0 is kept VERBATIM (the string is the product) and nested
+ * under the pane split, as in v1. Its gap stays a render-time per-frame inset,
+ * but fixed: fractions are computed per SIDE from each frame's ACTUAL rendered
+ * dims, half-pixel-centered, floor/ceil-split so odd gaps sum exactly, and
+ * edge-aware (frames touching the grid-region boundary stay flush, matching
+ * the generated grid's full-bleed contract — v1 carved all four sides). The
+ * pane wrapper is a pixel-weight split, exact at the head; a custom grid
+ * trades nested-precision boundedness for authored geometry by design.
+ */
+import type { MosaicColor, MosaicEngineContext, MosaicRenderableFile, MosaicTemplate } from "@m0saic/types";
+import { type ScreencapOutputFormat, type TextAlign, type TileCorner } from "../v1/screencap-grid";
+/** Info-pane group. */
+export type ScreencapInfoPaneConfig = {
+    /** Show the info pane with filename + metadata above the grid. Default true. */
+    show?: boolean;
+    /** Horizontal alignment of the pane text. Default "left". */
+    align?: TextAlign;
+};
+/** Per-tile timestamp group. */
+export type ScreencapTimestampsConfig = {
+    /** Overlay a timestamp in each tile. Default true. */
+    show?: boolean;
+    /** Which corner the chip sits in. Default "br". */
+    corner?: TileCorner;
+    /** Text color. Default white. */
+    color?: MosaicColor;
+    /** Chip background behind the glyphs. Default black. */
+    bgColor?: MosaicColor;
+};
+/** Tile presentation group. */
+export type ScreencapTilesConfig = {
+    /** Gap between tiles, in pixels — EXACT at every canvas. Default 2. */
+    gapPx?: number;
+    /** cover crops to fill the cell; contain letterboxes the frame. Default "cover". */
+    fit?: "contain" | "cover";
+};
+export declare const fBool: (label: string, description?: string) => any;
+export declare const fNum: (label: string, description?: string, control?: any, constraints?: any) => any;
+export declare const fEnum: (label: string, oneOf: string[], description?: string) => any;
+export declare const fColor: (label: string, description?: string) => any;
+export type ScreencapGridV2Props = {
+    /**
+     * The grid's source input(s) — THE source knob. When set with length > 1
+     * the template fans out as an `emit: "multi"` pipeline: one render per
+     * file, named after the file's basename. With length 1 it renders a
+     * single grid.
+     */
+    sourceIds?: string[];
+    /**
+     * Deliverable format: "png" renders a static contact sheet (each tile a
+     * frozen frame at its timestamp); "mp4" renders an animated grid (each
+     * tile plays from its timestamp). Default "png".
+     */
+    outputFormat?: ScreencapOutputFormat;
+    /** Number of grid rows. */
+    rows?: number;
+    /** Number of grid columns. */
+    cols?: number;
+    /** Info pane (collapsible group). */
+    infoPane?: ScreencapInfoPaneConfig;
+    /** Per-tile timestamps (collapsible group). */
+    timestamps?: ScreencapTimestampsConfig;
+    /** Tile gap + fit (collapsible group). */
+    tiles?: ScreencapTilesConfig;
+    /**
+     * Advanced (collapsible group): `customGrid` — a custom m0 layout string
+     * used for the grid instead of the generated `rows × cols` grid. One media
+     * tile (with its timestamp) is bound per rendered cell, in document order.
+     * When set, `rows`/`cols` are ignored. Accepts a bare m0 or a pasted `.m0`
+     * file (header comments are stripped); kept verbatim in the document.
+     */
+    advanced?: {
+        customGrid?: string;
+    };
+    /**
+     * Dev-only geometry contract (generated-grid path): assert every tile's
+     * computed rect survived to the pixels at this canvas; on violation render
+     * a GEOMETRY_CONTRACT error mosaic. Deterministic default false.
+     */
+    debugGeometry?: boolean;
+};
+/** Em budget for one pane line at this canvas width and font size. */
+export declare function paneLineEmBudget(canvasW: number, fontSize: number): number;
+/**
+ * Middle-ellipsize to an em budget, keeping the TAIL — for filenames, where
+ * the extension and trailing qualifiers are the part worth preserving.
+ * Script-aware via `textEmUnits` (CJK counts wide). Half-unit tolerance so
+ * exact-budget strings keep their last char (the donut fitToHole lesson).
+ */
+export declare function ellipsizeMiddleEm(text: string, maxUnits: number): string;
+export type TilePxRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Exact integer tile rects for a rows × cols grid filling the region below
+ * the info pane. Cell boundaries are proportional rounds of the region
+ * (`round(i · span / n)` — cells differ by at most 1px); interior boundaries
+ * carve the gap `floor(gap/2)` / `ceil(gap/2)` between the two neighbors so
+ * adjacent painted tiles are EXACTLY `tileGapPx` apart (odd gaps included).
+ * Outer edges are full-bleed (row 0 hugs the pane; the grid runs edge to
+ * edge). The gap is clamped per axis so no tile collapses below 1px.
+ *
+ * Row-major order (matches the tile → timestamp source pairing).
+ */
+export declare function computeGridTileRects(args: {
+    canvasW: number;
+    canvasH: number;
+    /** Info-pane pixel height. 0 → no pane; the grid starts at y=0. */
+    paneHeightPx: number;
+    rows: number;
+    cols: number;
+    tileGapPx: number;
+}): TilePxRect[];
+/** Per-side fractional inset (the object form of `MosaicBoxFrac`). */
+export type CustomTileInset = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/**
+ * Per-frame gap inset for the CUSTOM-grid path, from the frame's ACTUAL
+ * rendered dims. Half-pixel-centered per side (`(n + 0.5) / dim` — plain
+ * `n / dim` floor-loses; see `placeInsetRects`), floor/ceil-split so a
+ * shared boundary's two carves sum to exactly `gapPx`, and edge-aware:
+ * sides on the grid-region boundary stay flush (full-bleed). Carves that
+ * would collapse the tile below 1px, or exceed the engine's inset cap,
+ * drop that axis's carve. Returns undefined when no side carves.
+ */
+export declare function customGridTileInset(frame: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, gapPx: number, regionW: number, regionH: number): CustomTileInset | undefined;
+/**
+ * Top-level dispatcher.
+ *
+ * - 0 inputs → fail-fast error mosaic.
+ * - 1 input → single `MosaicDocument`.
+ * - N inputs → `MosaicDocumentPipeline` with `emit: "multi"`,
+ *              one step per input.
+ *
+ * The `outputFormat` knob picks the mode: png → static contact sheet,
+ * mp4 → animated grid.
+ */
+export declare function renderScreencapGridV2(props: ScreencapGridV2Props, ctx: MosaicEngineContext): Promise<MosaicRenderableFile>;
+export declare const ScreencapGridV2: MosaicTemplate<ScreencapGridV2Props>;