markswift 0.0.0-stage → 2.0.0

package/dist/types/analysis/svg/context.d.ts

@@ -0,0 +1,31 @@
+/** Shared SVG traversal data contracts. */
+import { type BundledFamilies } from "../../model/fonts.ts";
+import { type LayoutNode, type Rect } from "../../model/layout.ts";
+import { type Diagnostic, type SvgPath, type SvgText } from "../../model/semantic.ts";
+/** Affine matrix in SVG order `[a, b, c, d, e, f]`. */
+export type SvgMatrix = [number, number, number, number, number, number];
+export interface SvgScope {
+    /** Inherited presentation attributes, nearest ancestor wins. */
+    attrs: Record<string, string>;
+    /** Accumulated transform from the viewBox down to this element. */
+    ctm: SvgMatrix;
+    /** Product of ancestor `opacity` values. */
+    opacity: number;
+    /** Computed `color` of the nearest `<use>`: instanced content resolves `currentColor` against it. */
+    useColor?: string;
+    /** `<use>` nesting depth (cycle guard). */
+    depth: number;
+    /** Inherited from an ancestor group (<g clip-path|mask>): applied to every shape below that has none of its own. */
+    clip?: SvgPath["clip"];
+    /** Inherited from an ancestor group (<g clip-path|mask>): applied to every shape below that has none of its own. */
+    mask?: SvgPath[];
+}
+export interface SvgContext {
+    bundledFamilies: BundledFamilies;
+    ids: Record<string, LayoutNode>;
+    diagnostics: Diagnostic[];
+    vb: [number, number, number, number];
+    frame: Rect;
+    paths: SvgPath[];
+    texts: SvgText[];
+}

package/dist/types/analysis/svg/geometry.d.ts

@@ -0,0 +1,11 @@
+/** Exact SVG path bounds and circular stroke geometry. */
+import { type PathSegment, type SvgPath } from "../../model/semantic.ts";
+import { type Rect } from "../../model/layout.ts";
+import { type SvgMatrix } from "./context.ts";
+export declare function ringOf(circle: {
+    cx: number;
+    cy: number;
+    r: number;
+}, dash: number[], phase: number, ctm: SvgMatrix, vb: [number, number, number, number]): SvgPath["ring"] | undefined;
+/** Bounding box of the path's geometry (exact for lines and Bézier curves). */
+export declare function pathBounds(path: PathSegment[]): Rect;

package/dist/types/analysis/svg/gradients.d.ts

@@ -0,0 +1,6 @@
+/** Resolve SVG gradient paint servers and inherited stops. */
+import { type Rect } from "../../model/layout.ts";
+import { type SvgGradient } from "../../model/semantic.ts";
+import { type SvgContext } from "./context.ts";
+/** `url(#id)` → gradient in user units, or undefined (reported) when the id is not a gradient. */
+export declare function gradientOf(raw: string, bbox: Rect, ctx: SvgContext): SvgGradient | undefined;

package/dist/types/analysis/svg/markup.d.ts

@@ -0,0 +1,23 @@
+/** Parse standalone SVG markup into layout data before SVG analysis. */
+import { type Rect } from "../../model/layout.ts";
+import { type SvgNode } from "../../model/semantic.ts";
+/**
+ * Standalone SVG markup (a `data:image/svg+xml` URL, an inline asset) → SvgNode drawn in
+ * `frame`. Attributes only — there is no computed style — so `currentColor`, CSS classes
+ * and `<style>` rules inside the markup are not resolved. Undefined when the root is not an
+ * `<svg>` or no viewBox can be derived (neither `viewBox` nor width/height).
+ */
+export declare function svgFromMarkup(markup: string, frame: Rect): SvgNode | undefined;
+/**
+ * A `data:image/svg+xml` URL → its vector (drawn in a zero frame; the emitter sizes it) and CSS
+ * natural size; `undefined` for any other URL. The payload is parsed once for both. The natural
+ * size is px `width`/`height`; one of them alone takes the other from the viewBox ratio. With
+ * neither (or `%`) the image has a ratio but no size: the caller fits the viewBox into its area.
+ */
+export declare function svgFromDataUrl(url: string): {
+    vector?: SvgNode;
+    intrinsic?: {
+        w: number;
+        h: number;
+    };
+} | undefined;

package/dist/types/analysis/svg/text.d.ts

@@ -0,0 +1,7 @@
+/** Resolve SVG labels and measured text placement. */
+import { type LayoutNode } from "../../model/layout.ts";
+import { type SvgScope, type SvgContext } from "./context.ts";
+export declare function collectText(el: LayoutNode, scope: SvgScope, pos: {
+    x: number;
+    y: number;
+}, ctx: SvgContext): void;

package/dist/types/analysis/svg/transforms.d.ts

@@ -0,0 +1,19 @@
+/** SVG affine transforms and path transformation. */
+import { type LayoutNode } from "../../model/layout.ts";
+import { type Diagnostic, type PathSegment } from "../../model/semantic.ts";
+import { type SvgMatrix } from "./context.ts";
+export declare const IDENTITY: SvgMatrix;
+export declare function multiply(m: SvgMatrix, n: SvgMatrix): SvgMatrix;
+export declare function isIdentity(m: SvgMatrix): boolean;
+/**
+ * The element's own transform: Chrome's computed `transform` (attribute and CSS alike, as a
+ * matrix) about its `transform-origin`, in user units. Falls back to the attribute when the
+ * snapshot carries no computed value.
+ */
+export declare function ownTransform(c: LayoutNode, diagnostics: Diagnostic[]): SvgMatrix;
+/** SVG transform list (`rotate(30 50 40) translate(…)`) → matrix; svgpath parses the list, three probe points recover it. */
+export declare function transformAttr(attr: string | undefined): SvgMatrix;
+export declare function bake(d: string, ctm: SvgMatrix): string;
+/** Path data → absolute segments, shorthands and arcs expanded: the IR's one path normalisation. */
+export declare function segments(d: string): PathSegment[];
+export declare function apply(m: SvgMatrix, x: number, y: number): [number, number];

package/dist/types/analysis/svg/traversal.d.ts

@@ -0,0 +1,4 @@
+/** Traverse SVG groups, instances and shapes with recursive clipping and masks. */
+import { type LayoutNode } from "../../model/layout.ts";
+import { type SvgScope, type SvgContext } from "./context.ts";
+export declare function visitChildren(el: LayoutNode, scope: SvgScope, ctx: SvgContext): void;

package/dist/types/analysis/table-borders.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The collapsing border model (CSS 2.1 §17.6.2) over a captured table. Chrome resolves every grid
+ * line to one border (hidden wins, then the widest, then the stronger style, then cell > row >
+ * row group > table, then the box further up/left), paints it centred on the line and lays each
+ * cell out with half of it inside on every side; the table's box holds the outer halves. Each
+ * box paints only its own computed border, so the resolved line is rewritten into the boxes'
+ * styles instead: half of it on each side of the line. A line that is the same along a whole
+ * row is painted by the row (a hugging cell can be shorter than its row), and its cells keep
+ * the half as padding; any other line is painted by the cells.
+ */
+import type { LayoutNode } from "../model/layout.ts";
+/** `table` with its collapsed borders rewritten into its own, its row groups', rows' and cells' styles. */
+export declare function collapseTableBorders(table: LayoutNode): LayoutNode;
+/**
+ * `empty-cells: hide` in the separated border model: an empty cell paints no background, border or shadow; its box
+ * keeps its place. Empty as Chrome decides it (probed): only collapsible whitespace inside — an empty `<span>` or
+ * `&nbsp;` still paints. Collapsed tables ignore the property.
+ */
+export declare function hideEmptyCells(table: LayoutNode): LayoutNode;

package/dist/types/analysis/table.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Admission of a captured CSS table into `MarkswiftTable` (plan 049): its HTML-table-model slot grid, checked against
+ * the captured boxes, and the `table-layout: fixed` column solver the runtime mirrors.
+ */
+import type { LayoutNode } from "../model/layout.ts";
+import type { GridPlacement, TableColumn } from "../model/semantic.ts";
+type Slot = Pick<GridPlacement, "rowStart" | "colStart" | "rowSpan" | "colSpan">;
+/** One slot-grid member of a captured table: its LayoutNode, its row (and row group), 1-based slot. */
+export interface TableMember extends Slot {
+    node: LayoutNode;
+    parent: LayoutNode;
+    group?: LayoutNode;
+}
+export interface TableSlots {
+    widths: number[];
+    heights: number[];
+    hSpacing: number;
+    vSpacing: number;
+    collapse: boolean;
+    /** `table-layout: fixed` on a table with a non-`auto` Typed-OM width (CSS applies the fixed algorithm). */
+    fixedRequested: boolean;
+    /** The table's Typed-OM width is `<n>px` (read from `t`): the offered width is the captured one, scaling is exact. */
+    widthFixed: boolean;
+    fixed?: TableColumn[];
+    /** Painting row groups then rows (collapsed tables only), each spanning every column. */
+    bands: Array<Slot & {
+        node: LayoutNode;
+    }>;
+    /** Cells in DOM row-major order. */
+    cells: TableMember[];
+}
+/** Column widths for a content width; mirrors MarkswiftTable.columns (runtime/table.swift). */
+export declare function solveTableColumns(width: number | undefined, widths: number[], spacing: number, fixed?: TableColumn[]): number[];
+/** The table's slot grid when every captured box sits on it (0.5 px); undefined keeps the measured-rows path. */
+export declare function tableSlots(t: LayoutNode): TableSlots | undefined;
+export {};

package/dist/types/analysis/text-layout.d.ts

@@ -0,0 +1,65 @@
+/** Inline gaps, fragments, line breaks and baseline placement. */
+import { type LayoutNode, type Rect } from "../model/layout.ts";
+import { type TextRun, type DiagnosticLevel } from "../model/semantic.ts";
+import { type BundledFamilies } from "../model/fonts.ts";
+import { type MeasuredTextRun } from "./context.ts";
+/**
+ * The horizontal padding and border of an inline element is advance the browser inserted around
+ * its text, but a native run carries no box — so it becomes a run that paints nothing and only
+ * advances the line. Nested inline elements contribute one gap each, at the point where their
+ * first (or last) run sits, so `<a><code>x</code></a>` opens both boxes before the same glyph.
+ */
+export declare function withInlineGaps(built: MeasuredTextRun[], host: LayoutNode): TextRun[];
+/**
+ * The collapsed space between two inline elements, as a run of the host's own text: its style,
+ * and a text node of its own so the browser's measured line boxes — which belong to the real
+ * text nodes — are not read twice.
+ */
+export declare function hostSpace(host: LayoutNode, families: BundledFamilies): MeasuredTextRun;
+/** The inline elements from `host` (exclusive) down to `el` (inclusive), outermost first. */
+export declare function inlineChain(host: LayoutNode, el: LayoutNode): LayoutNode[];
+/**
+ * The boxes a wrapped inline element was painted in: one per line it spans. The measured text
+ * fragments inside it are the content areas, so each line's box is their union grown by the
+ * element's padding and border — vertically on every line, horizontally only where the box
+ * actually opens and closes (`box-decoration-break: slice`, the CSS default).
+ */
+export declare function inlineFragments(el: LayoutNode): Rect[];
+/** Drops the whitespace `edge` matches from a run, keeping its source map aligned. */
+export declare function trimRun(b: MeasuredTextRun, edge: RegExp): void;
+/**
+ * Computed `unicode-bidi` as Unicode controls around each element's runs: SwiftUI has no
+ * per-run direction, and Core Text runs UAX #9 over the controls (LRI/RLI…PDI, LRO/RLO…PDF). The
+ * direction is the computed one, which Chrome already resolved for `dir=auto` from the content.
+ * Call after trimming and before `markLineBreaks`; the controls map to no source index.
+ */
+export declare function markBidi(built: MeasuredTextRun[], host: LayoutNode): void;
+/** What closes each UAX #9 explicit opener (LRE/RLE/LRO/RLO, LRI/RLI/FSI): PDF, or PDI for an isolate. */
+export declare const BIDI_CLOSER: Record<string, string>;
+/**
+ * The bidi controls (`markBidi`) still open after `text`, outermost first. A PDI closes the innermost isolate and every
+ * embedding opened inside it; a PDF closes an embedding only inside the current isolate's scope; a "\n" is a
+ * paragraph separator and ends them all (UAX #9 X6a, X7, X8). Unmatched terminators do nothing.
+ */
+export declare function openBidi(text: string): string[];
+/**
+ * The browser's line division, re-expressed as offsets into each run's laid-out text.
+ *
+ * A measured box is an inline *fragment*, not a line: Blink splits one at every collapsed
+ * whitespace run that came from a source newline, so several boxes routinely share a line.
+ * Fragments are grouped by their top edge; the first fragment of each line after the first is
+ * a break, and the first output character at or after its raw index is where it goes. Only
+ * fidelity bakes the breaks into the output; its emitter reports that.
+ *
+ * A wrap can also fall exactly at a run boundary (before an `<a>` or `<strong>`): that run's own
+ * boxes hold no break, and CDP omits `lines` for a single-line node. Its first baseline is then
+ * below the previous run's last one — baselines, because top edges differ on a shared line when
+ * font sizes do; a `vertical-align` shift is added back first, so call after `markBaselineShifts`.
+ */
+export declare function markLineBreaks(built: MeasuredTextRun[]): void;
+/**
+ * `vertical-align` on an inline run (`<sub>`, `<sup>`, `vertical-align: super`) as a baseline
+ * offset in px. The shift is measured against the nearest run on the same line that sits on the
+ * host's own baseline, so a UA-defined keyword needs no table.
+ */
+export declare function markBaselineShifts(built: MeasuredTextRun[], host: LayoutNode, note: (level: DiagnosticLevel, feature: string, message: string) => void): void;

package/dist/types/analysis/text-runs.d.ts

@@ -0,0 +1,30 @@
+/** Inline run collection, whitespace normalization and text decoration. */
+import { type LayoutNode } from "../model/layout.ts";
+import type { Color } from "../model/values.ts";
+import { type TextDecoration } from "../model/semantic.ts";
+import { type SourceTextRun } from "./context.ts";
+/** Inline (non-atomic) element whose subtree is nothing but text (and a pseudo's captured images): merged into the parent's runs. */
+export declare function isInlineText(c: LayoutNode): boolean;
+export declare function collectRuns(el: LayoutNode, runs: SourceTextRun[]): void;
+/** Split runs into groups separated by flow children (by document order → measured y/x proximity). */
+export declare function groupRuns(host: LayoutNode, runs: SourceTextRun[]): SourceTextRun[][];
+export declare function contains(a: LayoutNode, b: LayoutNode): boolean;
+export type Collapse = "collapse" | "preserve" | "preserve-breaks";
+/** Computed `white-space-collapse`; a hand-built tree without it gets the initial `collapse`. */
+export declare function collapseOf(s: Record<string, string>): Collapse;
+/**
+ * Whitespace as the browser laid it out — collapsed to single spaces, or kept (breaks only, or
+ * all) — plus a source map: `src[i]` is the index in `text` of the character that produced
+ * output character `i`, a collapsed run mapping to its first character. The map is what lets
+ * the browser's measured line division, which indexes the raw text, be re-expressed as offsets
+ * into the laid-out run text.
+ */
+export declare function normalizeWhitespace(text: string, mode: Collapse): {
+    text: string;
+    src: number[];
+};
+/** The colour glyphs paint in: `-webkit-text-fill-color` overrides `color`; black when neither parses. */
+export declare function textColorOf(s: Record<string, string>): Color;
+/** Concatenated text of an element's subtree, as the snapshot laid it out. */
+export declare function textContent(el: LayoutNode | undefined): string;
+export declare function decorationOf(s: Record<string, string>, color: Color): TextDecoration | undefined;

package/dist/types/analysis/text.d.ts

@@ -0,0 +1,9 @@
+/** Construct semantic text nodes from measured inline runs. */
+import { type LayoutNode } from "../model/layout.ts";
+import { type TextNode } from "../model/semantic.ts";
+import { type SourceTextRun, type InferenceContext } from "./context.ts";
+/**
+ * @param leaf  the host holds nothing but this text → its box is the CSS line box (text-node
+ *              boxes from DOMSnapshot are glyph areas and overshoot tight line-heights).
+ */
+export declare function buildText(host: LayoutNode, runs: SourceTextRun[], ctx: InferenceContext, leaf?: boolean): TextNode;

package/dist/types/analysis/tooltips.d.ts

@@ -0,0 +1,16 @@
+/** Tooltips (D-HOVER): `title` and captured tooltip layers become `SemBase.tooltip` — `.help` plus an accessibility hint, never drawn. */
+import type { Layer, LayoutDoc, LayoutNode } from "../model/layout.ts";
+import { type SemBase, type SemNode } from "../model/semantic.ts";
+/** An element's `title` as tooltip text; an iframe's title is its name, not a tooltip. */
+export declare function titleOf(n: LayoutNode): string;
+/** Appends `text` to `base.tooltip` unless blank or already there; parts join with "; ". */
+export declare function addTooltip(base: SemBase, text: string): void;
+/**
+ * A layer that only describes its trigger: tooltip content (`role=tooltip`, shadcn's `tooltip-content` slot), an
+ * `aria-describedby`/`interestfor` relation, or a hover layer of a shadcn tooltip trigger (`root` resolves the trigger;
+ * without it that last rule cannot fire). 060 skips these layers.
+ */
+export declare function isTooltipLayer(layer: Layer, root?: LayoutNode): boolean;
+/** Each tooltip layer's text becomes its trigger's `tooltip`: the `role=tooltip` element's (Radix pairs its visible
+ * content with a visually hidden copy that carries the role), else the whole layer's. */
+export declare function applyTooltips(root: SemNode, doc: LayoutDoc): void;

package/dist/types/analysis/typography.d.ts

@@ -0,0 +1,21 @@
+/** Computed font selection with conversion-scoped bundled families. */
+import { type BundledFamilies } from "../model/fonts.ts";
+import { type FontSpec } from "../model/semantic.ts";
+/**
+ * Lower-case family name → the SwiftUI system design that carries it: the CSS generic families,
+ * the `ui-*` keywords, the Apple system stacks (`-apple-system`, `BlinkMacSystemFont`) and the
+ * concrete faces a design names next to a generic (`Menlo`, `Georgia`, …). `cursive`/`fantasy`
+ * have no system design and resolve to the default one, which `buildText` reports.
+ */
+export declare const SYSTEM_DESIGNS: Record<string, "default" | "rounded" | "monospaced" | "serif">;
+/**
+ * Font of a computed style: family, size, weight, line-height. The computed `font-family` is the
+ * authored list, not the family the browser picked, so it is walked in order and the first entry
+ * that resolves decides — a family the run bundled becomes `custom` (with `opsz` clamped into
+ * the axis range its file declares), a generic or an Apple system stack becomes the matching
+ * system design. An unresolvable list falls back to the default design, which `buildText`
+ * reports by name. `font-variation-settings` applies last and wins per axis (CSS Fonts 4 §7):
+ * `wght` → weight, `opsz` → opsz, other axes the bundled file declares (`wdth` also from
+ * `font-stretch`) → `axes`; a system family keeps `font-stretch`/`wdth` as `stretch`.
+ */
+export declare function fontOf(s: Record<string, string>, families?: BundledFamilies): FontSpec;

package/dist/types/analysis/wrapping.d.ts

@@ -0,0 +1,5 @@
+/** Bounded native row reflow; unsupported flex algorithms retain captured positions. */
+import type { LayoutNode } from "../model/layout.ts";
+import { type Axis, type CrossAlign, type Distribution, type SemBase, type StackNode } from "../model/semantic.ts";
+import type { AnalyzedChild } from "./context.ts";
+export declare function buildWrapping(n: LayoutNode, base: SemBase, all: AnalyzedChild[], axis: Axis, align: CrossAlign, distribution: Distribution): StackNode;

package/dist/types/api/bands.d.ts

@@ -0,0 +1,58 @@
+/** The browser captures of one conversion: per theme, and per width band. */
+import type { Page } from "playwright-core";
+import type { BrowserCapture, Capture } from "../browser/capture.ts";
+import { type BandPlan } from "../compiler/index.ts";
+import type { LayoutCondition, Theme } from "../model/layout.ts";
+import type { ConvertOptions } from "./types.ts";
+/** Throws unless `bp` is unset, `true` or `{ devices?, max? }` with positive integer sizes and an integer max ≥ 320. */
+export declare function validateBreakpoints(bp: ConvertOptions["breakpoints"], prefix?: string): void;
+/** The band plan of `bp` for a page whose first capture is `first` and reports `conditions`. */
+export declare function planFor(bp: NonNullable<ConvertOptions["breakpoints"]>, conditions: LayoutCondition[], first: {
+    width: number;
+    height: number;
+}): BandPlan;
+/**
+ * Capture one page in its theme(s), each raced against `timedOut`. Adaptive: two captures in one browser session;
+ * the light one is emitted, the dark one pairs its colours. `layers`: also run the open-state pass on each theme
+ * (the primary one probes dismissal; dark copies it by layer id).
+ */
+export declare function captureThemes(renderer: BrowserCapture, req: {
+    name: string;
+    url: string;
+    html?: string;
+    label: string;
+    root: string;
+    theme: Theme | "adaptive";
+    css?: string;
+    darkClass?: string;
+    waitFor?: string;
+    prepare?: (page: Page) => Promise<void>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    layers?: boolean;
+    breakpoints?: boolean;
+}, timedOut: Promise<never>): Promise<{
+    primary: Capture;
+    dark?: Capture;
+}>;
+/** One capture of a breakpoint conversion; `extra`: a container-query capture (`BandPlan.extra`). */
+export interface BandCapture {
+    primary: Capture;
+    dark?: Capture;
+    extra?: true;
+}
+/** The capture of every band of `plan`, reusing `first` for the band it belongs to, then its `extra` captures; one
+ * browser, in order, returned ascending by width (`extra: true` on the extras). Only band 0 runs the open-state pass
+ * (`req.layers`): its layers are applied once on the merged screen. */
+export declare function captureBands(renderer: BrowserCapture, req: Parameters<typeof captureThemes>[1], first: {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    captured: {
+        primary: Capture;
+        dark?: Capture;
+    };
+}, plan: BandPlan, timedOut: Promise<never>): Promise<BandCapture[]>;

package/dist/types/api/build.d.ts

@@ -0,0 +1,51 @@
+import { type CompileResult, type EmitMode, type PaletteMap } from "../compiler/index.ts";
+import type { Theme } from "../model/layout.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+import type { ConvertOptions } from "./types.ts";
+export interface BuildComponent {
+    /** Swift view name, e.g. `AccordionView`. */
+    name: string;
+    /** `file`: path inside `serveRoot`; `url`: a running http(s) page. */
+    source: {
+        file: string;
+    } | {
+        url: string;
+    };
+    root?: string;
+    theme?: Theme | "adaptive";
+    darkClass?: string;
+    /** Already compiled CSS injected into the page. */
+    css?: string;
+    waitFor?: string;
+    mode?: EmitMode;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Capture every CSS width band and emit one view across them, as `convert`'s `breakpoints`. */
+    breakpoints?: ConvertOptions["breakpoints"];
+}
+export interface BuildOptions {
+    /** Swift package, product, target and module name. */
+    library: string;
+    components: BuildComponent[];
+    /** Directory served at http://127.0.0.1:<port>/ for every `file` source (relative URLs such as `../assets/x.woff2` resolve inside it). */
+    serveRoot?: string;
+    /** Whole-build deadline in ms. Default 600000. */
+    timeoutMs?: number;
+    /** App colours for the library's `Palette` tokens; unmapped tokens and unused keys become warnings. */
+    palette?: PaletteMap;
+}
+export interface BuildResult {
+    /** Package files relative to the package root (`Package.swift`, `Sources/<library>/…`). */
+    files: Record<string, string>;
+    assets: Record<string, Uint8Array>;
+    /** Page and compile warnings carry `component`; font notes and config-level (`source: "build"`) ones may not. */
+    warnings: ConversionWarning[];
+    diagnostics: Record<string, CompileResult["diagnostics"]>;
+}
+/**
+ * Capture every component in one browser session per viewport and emit ONE local SwiftPM package: a module-level
+ * `Palette`, one copy of each shape, font and image, one runtime, public views.
+ */
+export declare function buildLibrary(options: BuildOptions): Promise<BuildResult>;

package/dist/types/api/convert.d.ts

@@ -0,0 +1,13 @@
+import type { HtmlSource } from "../input/types.ts";
+import type { FontFace } from "../model/layout.ts";
+import type { ConvertOptions, ConversionResult } from "./types.ts";
+/** Convert a document, fragment, HTML file or rendered URL through the same measured pipeline. */
+export declare function convert(source: HtmlSource, options?: ConvertOptions): Promise<ConversionResult>;
+/**
+
+ * Faces of several captures: the first list, plus faces only a later one declared. A face several
+ * declared is one face, loaded if any capture loaded it. Identical lists come back as the first.
+ */
+export declare function unionFaces(lists: FontFace[][]): FontFace[];
+/** Convenience entry point for pasted HTML. */
+export declare function convertHtml(html: string, options?: ConvertOptions): Promise<ConversionResult>;

package/dist/types/api/types.d.ts

@@ -0,0 +1,69 @@
+import type { Page } from "playwright-core";
+import type { CompileOptions, CompileResult } from "../compiler/index.ts";
+import type { LayoutDoc, Theme } from "../model/layout.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+export type { HtmlSource } from "../input/types.ts";
+export interface ConvertOptions extends Pick<CompileOptions, "name" | "mode" | "palette"> {
+    /** Already compiled CSS. Utility and CSS Modules selectors work exactly like normal CSS. */
+    css?: string;
+    root?: string;
+    /**
+     * `adaptive` (default) captures the page with `prefers-color-scheme: light`, then `dark`, and
+     * emits one view whose colours follow the colour scheme. `light`/`dark` capture one theme.
+     */
+    theme?: Theme | "adaptive";
+    /** Class added to `<html>` for the dark capture, for class-based themes such as `.dark`. */
+    darkClass?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Default true: when the capture contains a grid or flex row that a runtime Layout would reflow, a second capture
+     * at 320px (390px when the viewport is ≤ 320px) must agree, or the layout stays pinned.
+     */
+    probe?: boolean;
+    dpr?: number;
+    /** Installed Playwright browser channel; defaults to chrome. */
+    browserChannel?: string;
+    /** For publicly submitted pasted markup: block page scripts and outbound resource requests. */
+    untrustedInput?: boolean;
+    /** Mounted selector to await before capture. */
+    waitFor?: string;
+    /** Optional application-specific setup, such as opening a menu; runs before every capture, including each open-state capture. */
+    prepare?: (page: Page) => Promise<void>;
+    /** Upper bound for the whole conversion (browser, network, font conversion), in ms. Default 120000. */
+    timeoutMs?: number;
+    /**
+     * Capture one layout per CSS width band (`@media` width thresholds) instead of one viewport. `true`: devices
+     * 390×844, 834×1210, 1210×834, 1376×1032 up to `max` (default 1376); a band without a device is captured at its
+     * lower bound with `viewport.height`; the configured `viewport` is the capture of its own band. Thresholds below
+     * 320 px or above `max`, and beyond six bands, are reported. The view emits every element whose authored inputs are
+     * equal in all bands once and switches the others at the CSS thresholds (`MarkswiftBands`, at the width offered to
+     * the view); a root that does not follow the viewport width keeps the first band's layout, with a warning. A query
+     * container (`container-type`) that is a stack or grid switches its content at the width offered to its content box
+     * on width `@container` queries; such pages add one capture at the top of each band, then capture each band but
+     * band 0 and the configured `viewport`'s at its lower bound, keeping its device as one more capture (within the six).
+     */
+    breakpoints?: true | {
+        devices?: Array<{
+            width: number;
+            height: number;
+        }>;
+        max?: number;
+    };
+}
+export interface ConversionResult extends CompileResult {
+    /** Font packaging limitations, browser resource/page errors, viewport-dependent CSS and light/dark pairing limitations. */
+    warnings: ConversionWarning[];
+    /** The emitted capture: the light one for `adaptive`. */
+    layout: LayoutDoc;
+    /** The dark capture of an `adaptive` conversion. */
+    darkLayout?: LayoutDoc;
+    /** Every capture (`breakpoints`), ascending by width: one per width band plus, on pages with width `@container`
+     * queries, the extra captures of each band (its top, its device); `bands[0].layout` is `layout`. */
+    bands?: Array<{
+        layout: LayoutDoc;
+        darkLayout?: LayoutDoc;
+    }>;
+}

package/dist/types/browser/capture.d.ts

@@ -0,0 +1,89 @@
+import { type Layer, type LayoutDoc } from "../model/layout.ts";
+import type { NodeIdentity, CaptureRequest, Trigger } from "../input/types.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+export interface Capture {
+    /** Resource failures, page errors and viewport-dependent CSS observed while preparing this capture. */
+    warnings: ConversionWarning[];
+    layout: LayoutDoc;
+    /** Set only when `CaptureRequest.screenshot` is true. */
+    png?: Uint8Array;
+    /**
+     * Bytes of every `@font-face` source that was not already inline, keyed by `file`: exactly
+     * the `LayoutDoc.fonts[].src[].file` value (`_fonts/<content hash>.<ext>`) that points at
+     * them. Packaging reads them from here; the conversion never writes them to disk. Identical
+     * faces collapse onto one entry.
+     */
+    fontFiles: Array<{
+        file: string;
+        bytes: Uint8Array;
+    }>;
+    /** Rest captures: what the open-state pass activates (`browser/layers.ts`), in document order. */
+    triggers?: Trigger[];
+    /** `spec.open` captures whose trigger opened something: the layer, the open root size, and the trigger-subtree
+     * paint while open (LayoutNode id → delta). */
+    opened?: {
+        layer: Layer;
+        size: {
+            w: number;
+            h: number;
+        };
+        openPaint: Record<string, Record<string, string>>;
+    };
+}
+export interface CaptureOptions {
+    dpr: number;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    channel?: string;
+    restricted?: boolean;
+    signal?: AbortSignal;
+}
+export declare class BrowserCapture {
+    private browser;
+    private context;
+    private stopping?;
+    private readonly opts;
+    constructor(opts: CaptureOptions);
+    start(): Promise<void>;
+    /** Version of the launched browser (e.g. `153.0.8010.12`). */
+    get version(): string;
+    /**
+     * Safe to call more than once and concurrently (the conversion deadline and its cleanup both
+     * call it): one close runs. Before `start` has a browser it does nothing, so a later call still closes it.
+     */
+    stop(): Promise<void>;
+    /**
+     * Capture one screen. `identity` names layout nodes; `source` is the
+     * LayoutDoc.source label. The page's `prefers-color-scheme` follows `spec.theme`.
+     */
+    capture(spec: CaptureRequest, identity: NodeIdentity, source: string): Promise<Capture>;
+    /** Viewport, colour scheme, routes, navigation, `waitFor` and `prepare` of one capture request. */
+    private load;
+    /**
+     * Motion frame: the same page with every animation paused `frame.t` ms in (`reduced`: under
+     * `prefers-reduced-motion: reduce`, else `no-preference`), screenshotted at `clip` — the rest capture's root box.
+     * Throws when no animation was paused: the frame would silently be the settled look.
+     */
+    captureFrame(spec: CaptureRequest, frame: {
+        t: number;
+        reduced: boolean;
+    }, clip: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<Uint8Array>;
+    /**
+     * `@open:<layer>@t:<ms>` enter frame (066): a fresh page opened like the `@open` capture (058's `openLayer`), the
+     * focus ring it took dropped, every animation paused `t` ms in under `no-preference`, screenshotted at `clip`.
+     * Throws when no animation was paused (as `captureFrame`).
+     */
+    captureLayerFrame(spec: CaptureRequest, trigger: Trigger, t: number, clip: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Promise<Uint8Array>;
+}

package/dist/types/browser/conditions.d.ts

@@ -0,0 +1,25 @@
+/** CSS the capture resolved for one viewport and one validation state, reported instead of silently baked in. */
+import type { Page } from "playwright-core";
+import { type LayoutCondition, type LayoutNode } from "../model/layout.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+/** A size condition whose rules hit captured elements; `container`: the serial stamped on the query container. */
+export interface FoundCondition {
+    kind: "media" | "container";
+    query: string;
+    matches?: boolean;
+    container?: number;
+}
+/**
+ * Walks every readable stylesheet (nested rules included). For `@media`/`@container` rules with a
+ * size condition, collects the selectors inside that match the captured root or its descendants
+ * (whether or not the condition holds now) and stamps the matching elements with CONDITIONAL_MARK
+ * (their query container with CONTAINER_MARK); marks elements an author rule styles through
+ * `:valid`/`:invalid` with VALIDATION_MARK. Call before DOMSnapshot A so the marks land in `attrs`.
+ * `breakpoints`: the conversion reconstructs width media queries, so they are not reported as losses.
+ */
+export declare function readConditionalRules(page: Page, selector: string, viewportWidth: number, breakpoints?: boolean): Promise<{
+    warnings: ConversionWarning[];
+    found: FoundCondition[];
+}>;
+/** Moves the stamped marks into `conditional` and resolves container entries to node ids and `matches`. */
+export declare function applyConditionMarks(root: LayoutNode, found: FoundCondition[]): LayoutCondition[];