@m0saic/templates 0.2.0

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

@@ -0,0 +1,162 @@
+/**
+ * ⚠️ DEPRECATED (2026-07-21) — superseded by `./v2` (`@m0saic/media/screencap_grid/v2`).
+ *
+ * Archived as the canonical "ideal-cell gap inset" reference. This version
+ * realizes the inter-tile gap with `gridCellInset`: half-gap FRACTIONS
+ * computed against the IDEAL cell size (`gridW / cols`), applied by the
+ * engine as `floor(frac × actualCellPx)` against the QUANTIZED cell the
+ * equal split actually produced. It is the natural math a template author
+ * reaches for first — and it is approximate, not exact:
+ *
+ * 1. 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. Even on exactly-dividing cells, a plain `n / cell` fraction can
+ *    floor-lose the pixel (`floor((1/480)·480) → 0` under IEEE) — the
+ *    half-pixel-centering problem `placeInsetRects` documents.
+ * 3. The custom-grid path's uniform `(gap/2)/dim` fractions shared failure
+ *    mode 2, and the timestamp chips (no inset at all) could hang into the
+ *    carved gap.
+ *
+ * v2 fixes all three by computing every painted rect in integer pixels and
+ * emitting the layout through `placeInsetPieces` (inset-recovery, handbook
+ * feasibility-precision-quantization.md §3c) — pixel-exact gaps at every
+ * canvas, bounded precision. The pure formatting/timestamp helpers below are
+ * NOT deprecated — v2 and the aspect-safe sibling import them from here.
+ */
+import type { MosaicColor, MosaicEngineContext, MosaicMediaMetadata, MosaicRenderableFile, MosaicSource, MosaicTemplate } from "@m0saic/types";
+export type ScreencapGridProps = {
+    /**
+     * 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;
+    /** Show the info pane with filename + metadata above the grid. Height is auto-calculated from content. */
+    withInfoPane?: boolean;
+    /** Horizontal alignment of the info-pane text (filename + metadata). Default "left". */
+    headerAlign?: TextAlign;
+    /** Whether to overlay a timestamp in each tile. */
+    withTileTimestamp?: boolean;
+    /** Which corner the per-tile timestamp sits in. Default "br" (bottom-right). */
+    timestampCorner?: TileCorner;
+    /** Timestamp text color. Default white. */
+    timestampColor?: MosaicColor;
+    /** Timestamp background color (the chip behind the text). Default none (transparent). */
+    timestampBgColor?: MosaicColor;
+    /**
+     * Gap between tiles, in pixels. Applied as a per-tile inset (a render-time
+     * rect shrink) rather than DSL gutters — so it's pixel-exact, nudges 1px at
+     * a time, and adds no DSL tokens (keeps the grid cheap). Default 2.
+     *
+     * The grid always fills the canvas (gutterless cells + this inset gap); the
+     * cells read as equal, so there's no separate canvas-fit mode.
+     */
+    tileGapPx?: number;
+    /**
+     * How each frame fills its tile. `cover` crops to fill the cell; `contain`
+     * letterboxes the whole frame (spare area shows the grid document's
+     * background). Default "cover".
+     */
+    tileFit?: "contain" | "cover";
+    /**
+     * Escape hatch: 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 — so you can give some cells emphasis
+     * (bigger frames) by authoring the geometry yourself. When set, `rows`/`cols`
+     * are ignored; every other knob (info pane, header align, timestamp, gap)
+     * still applies. Accepts a bare m0 or a pasted `.m0` file (header comments
+     * are stripped).
+     */
+    customGrid?: string;
+};
+/** Deliverable format for the grid — static PNG sheet or animated MP4. */
+export type ScreencapOutputFormat = "png" | "mp4";
+/** Horizontal text alignment for the info-pane header. */
+export type TextAlign = "left" | "center" | "right";
+/** Corner placement for a per-tile overlay (e.g. the timestamp). */
+export type TileCorner = "tl" | "tr" | "bl" | "br";
+/**
+ * Build a per-tile timestamp overlay text source. Shared by screencap_grid and
+ * the aspect-safe variant so corner placement, text color, and the
+ * behind-glyphs box background (drawtext `box`, NOT a full-rect fill) stay
+ * identical across both. `bgColor === "none"` → no box.
+ */
+export declare function buildTimestampSource(opts: {
+    /** Seek time in ms (0 for stills). */
+    t: number;
+    mode: "static" | "animated";
+    isVideo: boolean;
+    corner: TileCorner;
+    color: MosaicColor;
+    bgColor: MosaicColor;
+}): MosaicSource;
+/** Title font size derived from output height, not pane height. */
+export declare function infoPaneTitleFontSize(targetH: number): number;
+/** Metadata font size derived from output height, not pane height. */
+export declare function infoPaneMetaFontSize(targetH: number): number;
+/**
+ * Estimate the pixel height needed for the info pane content.
+ * Uses the same font-sizing formulas as info_pane.ts rendering.
+ */
+export declare function estimateInfoPaneHeight(targetH: number, metaLineCount: number): number;
+export declare function formatInfoLines(sourceId: string, meta: MosaicMediaMetadata): {
+    title: string;
+    metadata: string;
+    metaLineCount: number;
+};
+/**
+ * Assemble the layout m0: an optional info-pane row on top of a gutterless
+ * grid that fills the canvas. Frame order is `[info-pane, tile, tile, …]` so
+ * the caller's source array maps positionally. The grid is gutterless (the
+ * compact `equalSplit` path) — the inter-tile gap is a per-tile inset on the
+ * media sources, so it costs no DSL tokens here.
+ *
+ * `gridM0` overrides the generated `rows × cols` grid with a caller-supplied
+ * layout (the custom-grid escape hatch); the timestamp overlay + info-pane
+ * wrapping still apply on top.
+ *
+ * `paneHeightPx` / `gridH` are pixel heights summing to the canvas height, so
+ * the `[pane, grid]` split lands the grid on exactly `gridH`.
+ */
+export declare function assembleScreencapM0(args: {
+    rows: number;
+    cols: number;
+    /** Info-pane pixel height. 0 → no info pane. */
+    paneHeightPx: number;
+    /** Grid region pixel height (canvas height minus the info pane). */
+    gridH: number;
+    withTileTimestamp: boolean;
+    /** Custom grid m0 (escape hatch). When set, replaces the generated grid. */
+    gridM0?: string;
+}): string;
+/**
+ * Compute deterministic seek timestamps for N grid tiles.
+ * Returns timestamps in ms, strictly in (0, durationMs).
+ */
+export declare function computeTimestamps(n: number, durationMs: number): number[];
+/**
+ * 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 renderScreencapGrid(props: ScreencapGridProps, ctx: MosaicEngineContext): Promise<MosaicRenderableFile>;
+export declare const ScreencapGrid: MosaicTemplate<ScreencapGridProps>;