@dynamicagents/plugins 0.12.0 → 0.14.0

package/dist/arc-agi/analysis.d.ts

@@ -1,322 +0,0 @@
-/**
- * Pure grid-analysis helpers for ARC-AGI-3 frames. No I/O — every function is a
- * deterministic transform of a 64×64 grid (color values 0–15), unit-tested in
- * isolation. The tool family calls these to render compact observations for the
- * model instead of dumping raw grids into context.
- *
- * Two rendering registers, deliberately kept apart:
- *
- * - **Prose** (diffs, shapes, histogram) names its colors: `blue->white` carries
- *   structure a bare `9->0` hides, and no tool input ever takes a color, so the
- *   index is never needed as an argument.
- * - **Grids** ({@link renderGrid}, {@link renderRegion}) stay one character per
- *   cell and carry a {@link renderLegend} instead. One char per cell is the only
- *   reason a 64×64 board is legible at all; a named cell would be unreadable and
- *   cost ~50× the tokens.
- */
-/**
- * The ARC-AGI-3 16-color palette, index → name.
- *
- * Source: `agents/templates/multimodal.py` in `arcprize/ARC-AGI-3-Agents` (ARC
- * Prize's own agent template), which maps these indices to RGBA for multimodal
- * play. Taken from there rather than assumed, because **ARC-AGI-3's palette is
- * unrelated to ARC-AGI-1's**: here 0 is *white* and 1–5 are a greyscale ramp,
- * where the familiar ARC-AGI-1 mapping would say 0=black, 1=blue, 2=red. Note
- * that same repo carries a second, contradictory `COLOR_PALETTE` in
- * `langgraph_thinking/vision.py` — that one is incomplete and does not match the
- * engine; do not use it.
- *
- * The pairs matter to a player: 6/7 and 9/10 and 2/3 are related shades, which
- * the names convey and the indices do not.
- */
-export declare const COLOR_NAMES: readonly ["white", "off-white", "neutral-light", "neutral", "off-black", "black", "magenta", "magenta-light", "red", "blue", "blue-light", "yellow", "orange", "maroon", "green", "purple"];
-/** Color 0 (white) — treated as background by {@link locateComponents}. */
-export declare const BACKGROUND_COLOR = 0;
-/**
- * Name of a color index. An out-of-range value renders as `color <n>` rather
- * than throwing: a malformed frame should degrade the wording, not fail the turn.
- */
-export declare function colorName(color: number): string;
-/** The current board: the LAST grid of a frame response's grid array. */
-export declare function lastGrid(frame: number[][][]): number[][];
-/**
- * Bare hex rows, one char per cell, no labels — the round-trippable **storage**
- * form, paired with {@link parseGrid}. Deliberately distinct from
- * {@link renderGrid}, which adds a legend, rulers and row collapsing and so
- * cannot be parsed back.
- */
-export declare function serializeGrid(grid: number[][]): string;
-/** Inverse of {@link serializeGrid}. */
-export declare function parseGrid(hex: string): number[][];
-export interface CellChange {
-    row: number;
-    col: number;
-    from: number;
-    to: number;
-}
-/** The rectangle enclosing a set of cells. */
-export interface Box {
-    top: number;
-    left: number;
-    bottom: number;
-    right: number;
-}
-export interface GridDiff {
-    changed: number;
-    /** Up to `cap` changed cells (for a compact summary of a large change). */
-    cells: CellChange[];
-    /** Rectangle enclosing ALL changed cells (not just the capped ones). */
-    box: Box | null;
-}
-/** Cell-by-cell diff of two grids. `cap` bounds the returned cell list. */
-export declare function diffGrids(a: number[][] | null, b: number[][], cap?: number): GridDiff;
-/** `rows 3-5, cols 10-12` — or a single row/col rendered without the range. */
-export declare function describeBox(box: Box): string;
-/** `(3,10) blue->white` — one changed cell, colors named. */
-export declare function describeCell(cell: CellChange): string;
-/** Count of each color present, descending by count. */
-export declare function colorHistogram(grid: number[][]): Array<{
-    color: number;
-    count: number;
-}>;
-/** One 4-connected same-color region, with where it sits and how big it is. */
-export interface Component extends Box {
-    color: number;
-    size: number;
-}
-/**
- * Every 4-connected same-color region, with its bounding box, largest first.
- * Skips {@link BACKGROUND_COLOR}.
- *
- * The bounding boxes are the point: a rollup of counts alone tells the model
- * *that* there are three shapes and never *where* they are, which leaves dumping
- * the whole 64×64 grid as the only way to locate anything. The flood fill has to
- * visit every cell regardless, so tracking min/max row/col is free.
- */
-export declare function locateComponents(grid: number[][]): Component[];
-/**
- * How much of its bounding box a region actually occupies, 0–1.
- *
- * Every caller passes a {@link Component} from {@link locateComponents} or a
- * {@link unionBox} of those, and a flood fill cannot produce `bottom < top`, so
- * `area` is at least 1 and there is nothing to guard against dividing by.
- *
- * The result is deliberately **not** clamped into 0–1. An out-of-range value here
- * could only mean a caller broke that invariant, and the way to learn that is a
- * region classified absurdly, not a number quietly corrected into looking sane.
- */
-export declare function fillRatio(box: Box, size: number): number;
-/**
- * A band of consecutive rows in which one color occupies exactly the same
- * columns, and the column runs it occupies there.
- */
-export interface SpanBand extends Pick<Box, "top" | "bottom"> {
-    /** Inclusive `[first, last]` column runs, left to right. */
-    cols: Array<[number, number]>;
-    /** Runs the cap dropped, so a truncated band never reads as a complete one. */
-    hidden: number;
-}
-/**
- * Where one color sits, row band by row band — the view a bounding box cannot
- * give for a maze, a frame, or any other structure that is mostly holes.
- *
- * Keyed by **color rather than component** on purpose. A wall that a doorway
- * splits into three components is one thing to a player, and three boxes describe
- * it worse than one span list does; the flood fill's notion of connectedness is an
- * implementation detail here, not something the model should have to reassemble.
- *
- * Rows whose runs are identical collapse into one band, the same trick
- * {@link renderGrid} uses — and for the same reason, since ARC boards are banded.
- * On a real 64×64 maze it turns 64 rows into ~20 bands.
- */
-export declare function colorSpans(grid: number[][], color: number): SpanBand[];
-/**
- * Runs named per band, one line each. Both caps exist to bound the render on a
- * board this encoding suits badly — a checkerboard is 32 runs in every one of 64
- * rows — and both announce themselves, so a clipped view is never mistaken for
- * the whole of one.
- */
-export declare function renderSpans(bands: SpanBand[]): string;
-/**
- * Named regions with their positions, largest first — the locational view.
- *
- * A bounding box describes a region only when the region roughly fills it. That
- * holds for the movable pieces and fails for exactly the two things a route
- * depends on: on a real `ls20` board the maze boxes as `off-black: rows 0-63,
- * cols 0-63 (2129 cells)` and the floor as `neutral: rows 5-54, cols 9-58 (1354
- * cells)`, both a shade over half-filled. The first says nothing; the second is
- * worse, asserting a 50×50 open arena of which 46% is wall — and a play reading
- * its route off those boxes walks into walls, then spends a dozen turns
- * rebuilding the maze through 11×11 `region` peepholes.
- *
- * So a region that sprawls is rendered as {@link colorSpans} instead — every row
- * band and the columns it occupies, which is the same fact at a resolution that
- * can be acted on. Sprawl is judged per color and the whole color is then spanned
- * at once, so a wall and the doorway splitting it read as one terrain layer rather
- * than as two boxes that overlap everything.
- *
- * `cap` bounds the boxed list; anything beyond it is reported as a count so the
- * model knows the view is truncated rather than complete.
- */
-export declare function renderShapes(grid: number[][], cap?: number): string;
-/**
- * What became of one shape between two frames.
- *
- * The four cases are kept apart because only **one** of them answers the question
- * an action asks — did anything move? Folding a counter ticking down into the
- * same bucket as a step taken is exactly the mistake {@link diffGrids} cannot
- * help making: in `ls20` every action shrinks a fuel bar by four cells, so a move
- * into a wall reports "4 cells changed" and reads, to a model told that `0 cells
- * changed` means blocked, as a move that worked. It spent eleven actions on that
- * misreading. A wall is `moved: []` here, whatever else on the board ticked.
- */
-export type ShapeChange = {
-    kind: "moved";
-    /** Where it was, with its color and cell count. */
-    from: Component;
-    /** Where it is now — same color and same cell count, by construction. */
-    to: Box;
-    dRow: number;
-    dCol: number;
-}
-/** Same color, still overlapping, different cell count — a bar, a trail, a fill. */
- | {
-    kind: "resized";
-    from: Component;
-    to: Component;
-}
-/**
- * Same footprint and same cell count, a different color — a repaint in place,
- * which is what a click game does instead of moving anything.
- */
- | {
-    kind: "recolored";
-    from: Component;
-    to: Component;
-} | {
-    kind: "appeared";
-    shape: Component;
-} | {
-    kind: "gone";
-    shape: Component;
-};
-export type MovedShape = Extract<ShapeChange, {
-    kind: "moved";
-}>;
-/**
- * Two frames' shapes, matched. Split rather than one list because both consumers
- * want the split: the renderer leads with movement, and a caller summing a batch
- * accumulates only the moves.
- */
-export interface ShapeDelta {
-    /** Every shape that travelled, largest first. */
-    moved: MovedShape[];
-    /** Resized, appeared and disappeared shapes, largest first. */
-    other: ShapeChange[];
-}
-/**
- * Above this many changed shapes, a frame is a repaint (a level change, a
- * transform) rather than a board where things moved, and naming twenty shapes
- * that all "appeared" says less than the cell diff does. {@link renderShapeDelta}
- * declines, and its caller falls back.
- */
-export declare const MAX_SHAPE_CHANGES = 10;
-/**
- * Match the shapes of two frames: what moved, what changed size, what came and
- * went. Null when there is no earlier frame to compare against.
- *
- * Three passes, and the order is the whole design. Color **and** cell count
- * first, because a rigid object that travelled keeps both — that pass is what
- * finds a move, and its pairs are never reconsidered. Color alone second, over
- * what is left, which is what a bar losing cells or a trail growing looks like.
- * **Footprint** alone last, over what neither pass claimed, which is a shape that
- * changed color without moving — see {@link matchRepaints}.
- */
-export declare function diffShapes(before: number[][] | null, after: number[][]): ShapeDelta | null;
-/** {@link diffShapes} over already-located components. Exported for tests. */
-export declare function matchShapes(before: Component[], after: Component[]): ShapeDelta;
-/** `down 5, left 10` — a displacement in board directions, zero terms dropped. */
-export declare function describeShift(dRow: number, dCol: number): string;
-/**
- * One action's effect as movement: `nothing moved` when the board's objects
- * stayed put, whatever a counter did alongside them.
- *
- * That phrase is spent carefully, because the soul teaches it as the signal for
- * *blocked or refused*: it leads a step only when everything else the delta holds
- * is a {@link ShapeChange} of kind `resized`, which is a counter or a bar doing
- * its own bookkeeping. A step that repainted a block, or made one appear, changed
- * the board — no object travelled, and reporting that as `nothing moved` tells a
- * click game that twenty clicks which each toggled a 36-cell block were refused.
- *
- * Null means *this view has nothing to say* — either no shape can be paired
- * across the frames, or so many changed that they are a repaint
- * ({@link MAX_SHAPE_CHANGES}). Both leave the cell diff as the better witness, so
- * the caller renders that instead rather than printing a confident "nothing
- * moved" over a board that changed completely.
- */
-export declare function renderShapeDelta(delta: ShapeDelta, cap?: number): string | null;
-/** Where one shape ended up over a whole batch, and how many steps took it there. */
-export interface ShapeTravel {
-    shape: Component;
-    dRow: number;
-    dCol: number;
-    /** Steps in which this shape moved at all. */
-    moves: number;
-}
-/**
- * Fold one step's moves into a batch's running totals.
- *
- * Identity is *position*, not appearance. Boards carrying two identical shapes
- * are the ordinary case, not the contrived one — a pair of blocks, a player and
- * its twin — and summing them under one color-and-size key reports two shapes
- * that passed each other as one shape that never moved, which is the single
- * worst thing this line could say.
- *
- * Each entry is re-keyed to where its shape landed, which is exactly where the
- * next step's diff will find it: the frames chain, step N's board being step
- * N+1's starting board, so a position is a stable handle for as long as the
- * shape keeps its color and size. Sources are cleared before any destination is
- * written, so a shape sliding into the cell another just vacated inherits its
- * own history rather than the vacater's.
- */
-export declare function trackTravel(travels: Map<string, ShapeTravel>, moved: MovedShape[]): void;
-/**
- * A shape's net travel over a batch, counted in **moves** rather than cells.
- *
- * Cells are the misleading unit for a sequence: two presses that each slide a
- * selector five cells are not "ten cells down", they are two moves of five, and a
- * model reading the former will place itself ten cells from where it is. So the
- * per-move stride is stated whenever the total divides by the moves that produced
- * it — observed from the steps, never assumed.
- */
-export declare function renderTravel(travel: ShapeTravel): string;
-/** `0=white 9=blue b=yellow` — maps grid characters to names, present colors only. */
-export declare function renderLegend(grid: number[][]): string;
-/**
- * The full board: a legend, a column ruler, then one labeled line per row —
- * with **runs of identical rows collapsed** into a single `12-31 |` band.
- *
- * Labels exist because a model cannot reliably count to column 37 across 64
- * undelimited characters; miscounting there costs a wrong click and two more
- * turns. Collapsing exploits how banded ARC boards are without run-length
- * encoding *within* a row, which would destroy the 2-D structure that this view
- * exists to convey.
- */
-export declare function renderGrid(grid: number[][]): string;
-/**
- * A localized view: a `radius`-cell square around (centerRow, centerCol), with
- * **absolute** row and column labels. The labels are what make the view usable —
- * an unlabeled block cannot be mapped back to a coordinate to click.
- *
- * The window is **clipped** on every side, never padded, which is what makes the
- * header's `cols` anchor true: character `i` of a body line is column
- * `firstCol + i`. Padding off-grid columns with spaces instead would shift that
- * mapping by up to `radius` near the left edge.
- *
- * **The window is ruled, not just headed.** A model asked to place a cell in an
- * 11-wide window counts the characters by hand and gets them wrong, then reasons
- * on the columns it miscounted — so narrow is exactly where the ruler is needed.
- * It steps at {@link REGION_RULER_STEP} rather than {@link renderGrid}'s tens,
- * which a window this size can miss entirely.
- */
-export declare function renderRegion(grid: number[][], centerRow: number, centerCol: number, radius?: number): string;