markswift 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,34 @@
+import type { Page } from "playwright-core";
+import type { FontFace as FontFaceRecord } from "../model/layout.ts";
+/**
+ * The page's `@font-face` rules, as the browser resolved them. Two sources, because neither is
+ * enough on its own: `document.styleSheets` carries the authored descriptors (`src` with its
+ * URLs and formats, `unicode-range`, the weight range of a variable face), while
+ * `document.fonts` is the only place that says whether a face actually loaded — i.e. whether
+ * the reference pixels are its glyphs or a fallback's. Runs after `settle`, so
+ * `document.fonts.ready` has already resolved.
+ *
+ * `@import`ed sheets are followed. A cross-origin sheet throws on `cssRules`; its rules are then
+ * parsed from `sheetText` (response bodies by request URL, kept by the capture) into a
+ * constructable sheet. A sheet with neither is returned in `unreadable`.
+ */
+export declare function collectFontFaces(page: Page, sheetText: Record<string, string>): Promise<{
+    faces: FontFaceRecord[];
+    unreadable: string[];
+}>;
+/**
+ * Reads the bytes behind every non-inline `@font-face` source and names each blob by content
+ * hash, mutating the faces to point at it: each returned `file` is exactly the value written to
+ * `src.file`, so the bytes are keyed by `FontFace.src[].file`; the conversion never writes them to disk. Runs
+ * in-process while the source's static server is still up: that server is the only thing that
+ * can answer its own ephemeral-port URL, and it stops when the conversion returns.
+ *
+ * Only `http:`/`https:` URLs are fetched (what the capture browser itself could request; never
+ * `file:`, `s3:`, `blob:`), and a response over 25 MB is skipped. `signal` aborts the fetch.
+ * A source that cannot be read keeps its `url` and gets no `file` — packaging reports it rather
+ * than guessing.
+ */
+export declare function readFontBytes(faces: FontFaceRecord[], allowRemote?: boolean, signal?: AbortSignal): Promise<Array<{
+    file: string;
+    bytes: Uint8Array;
+}>>;

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

@@ -0,0 +1,3 @@
+import type { LayoutNode } from "../model/layout.ts";
+/** Resolve images from resources the browser actually loaded; no second network fetch. */
+export declare function inlineCapturedImages(root: LayoutNode, baseURL: string, images: ReadonlyMap<string, string>): string[];

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

@@ -0,0 +1,132 @@
+/**
+ * Open-state pass: find what can open (discovery in the rest page), open each trigger for real in a fresh
+ * page, and keep the content that gained layout (LayoutDoc `layers`), the trigger's paint while open
+ * (`states.open`) and how the layer is dismissed. Nothing here emits Swift.
+ */
+import type { CDPSession, Page } from "playwright-core";
+import type { CaptureRequest, NodeIdentity, Trigger } from "../input/types.ts";
+import type { Layer, LayoutNode, Rect } from "../model/layout.ts";
+import type { Capture } from "./capture.ts";
+import { type DomSnapshot, type Raw } from "./snapshot.ts";
+/** Stamped through CDP on each layer root, valued by its paint-order index. */
+export declare const LAYER_MARK = "data-markswift-layer-root";
+/** Laid-out backend ids of a snapshot (layout.nodeIndex → nodes.backendNodeId). The content of a closed `<details>`
+ * (all but its first `<summary>`) has boxes in DOMSnapshot but paints nothing (`::details-content` is
+ * `content-visibility: hidden`), so it does not count. */
+export declare function laidOut(snap: DomSnapshot): Set<number>;
+/** Step 3 of the design: new roots in paint order, excluding `exclude` (the trigger subtree's backend ids), zero-area
+ * subtrees and opacity-0 roots. `snap` is taken with `ROOTS_ARGS`. */
+export declare function layerRoots(before: Set<number>, snap: DomSnapshot, exclude: Set<number>): number[];
+/** 2 px inside the first viewport corner (top-left, top-right, bottom-left, bottom-right) outside every rect; undefined when none. */
+export declare function outsidePoint(rects: Rect[], viewport: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+} | undefined;
+/** PAINT_KEYS of `open` that differ from `rest` (both `styles` records). */
+export declare function openDelta(rest: Record<string, string>, open: Record<string, string>): Record<string, string> | undefined;
+/** Layer ids: slug of each name (diacritics dropped, first 4 words, `layer` when empty), made unique with `-2`, `-3`…. */
+export declare function layerIds(names: string[]): string[];
+/** Triggers inside `root` (document order) and the hint values that were not understood. */
+export declare function findTriggers(page: Page, root: string): Promise<{
+    triggers: Array<Omit<Trigger, "trigger">>;
+    warnings: string[];
+}>;
+/**
+ * Scroll the trigger into view and activate it with the real mouse; false when it is not in the page. The animations
+ * the activation starts are recorded (066: a short enter finishes before the layer is read).
+ */
+export declare function activate(page: Page, root: string, trigger: Trigger): Promise<boolean>;
+/** The root, or an ancestor, is hidden from assistive technology (`aria-hidden`/`inert`). */
+export declare const rootHidden: (page: Page, root: string) => Promise<boolean>;
+/** An activated trigger in its open page. */
+export interface Opening {
+    /** Paint of every node laid out before activation, by backend id. */
+    rest: Map<number, Record<string, string>>;
+    /** The root (or an ancestor) was aria-hidden/inert before activation. */
+    hidden: boolean;
+    /** Backend ids of the layer roots in paint order (marked `LAYER_MARK="<i>"`); empty = nothing opened. */
+    roots: number[];
+    /** The step-3 diff is non-empty. */
+    isOpen(): Promise<boolean>;
+    /** Activate again when closed, then re-mark the roots. */
+    reopen(): Promise<void>;
+}
+/**
+ * Steps 2–3: snapshot, activate `trigger`, and mark the roots of what gained layout outside the trigger.
+ * `rootMark` is the attribute the capture root carries. Undefined when the trigger is not in the page.
+ */
+export declare function openLayer(page: Page, cdp: CDPSession, root: string, rootMark: string, trigger: Trigger): Promise<Opening | undefined>;
+/** A button of the layer the dismiss probe clicks: the `root`-th layer root, element `path` below it. */
+export interface DismissCandidate {
+    root: number;
+    path: string;
+    /** Its LayoutNode id. */
+    id: string;
+}
+/** `button, [role=button], [role^=menuitem], [role=option], a:not([href])` in roots order then document order. */
+export declare function dismissCandidates(roots: Raw[], paths: string[], identity: NodeIdentity): DismissCandidate[];
+/**
+ * Step 5: the layer from the marked raws of the open tree (`marked[i]` carries `LAYER_MARK="<i>"`, already
+ * removed from its attrs). `root` is the open tree's root LayoutNode; `rootRaw` its raw.
+ */
+export declare function assembleLayer(o: {
+    trigger: Trigger;
+    rootRaw: Raw;
+    root: LayoutNode;
+    marked: Raw[];
+    origin: {
+        x: number;
+        y: number;
+    };
+    identity: NodeIdentity;
+    /** Per root, from the open page: `:modal`, and CSS anchor positioning. */
+    info: Array<{
+        modal: boolean;
+        anchored: boolean;
+    }>;
+    /** The root (or an ancestor) became aria-hidden/inert on open. */
+    hiddenOnOpen: boolean;
+}): {
+    layer: Layer;
+    paths: string[];
+};
+/**
+ * Step 6: paint the trigger and its descendants show while the layer is open (by LayoutNode id), and how many of
+ * its elements appeared or disappeared (not reproduced).
+ */
+export declare function triggerPaint(rest: Map<number, Record<string, string>>, rootRaw: Raw, trigger: Trigger, identity: NodeIdentity): {
+    paint: Record<string, Record<string, string>>;
+    changed: number;
+};
+/** Step 7 after the Escape probe: outside click, then each candidate button. `escape` = the Escape probe closed it. */
+export declare function probeDismiss(page: Page, opening: Opening, o: {
+    root: string;
+    trigger: Trigger;
+    candidates: DismissCandidate[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    escape: boolean;
+    warn: (message: string) => void;
+}): Promise<Layer["dismiss"]>;
+/** What an `@open` capture needs: the open page's root-clipped screenshot (with `spec.screenshot`), root size, and the
+ * trigger that opened it (its enter frames reopen it, 066). */
+export type OpenShots = Record<string, {
+    png?: Uint8Array;
+    size: {
+        w: number;
+        h: number;
+    };
+    trigger: Trigger;
+}>;
+/**
+ * Step 8: open the first 12 of `rest.triggers`, each in a fresh page (`capture`), append the layers to
+ * `rest.layout.layers`, write `states.open` into `rest.layout.root`, and append warnings.
+ */
+export declare function captureLayers(capture: (spec: CaptureRequest) => Promise<Capture>, spec: CaptureRequest, rest: Capture, { probeDismiss }: {
+    probeDismiss: boolean;
+}): Promise<OpenShots>;

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

@@ -0,0 +1,44 @@
+/**
+ * Motion capture: CSS animations and transitions as Chrome's Web Animations objects report them
+ * (`CSSAnimation` / `CSSTransition`: `var()`-resolved keyframes, timing, per element). Read on the
+ * live page before `settle()` finishes them; nothing here changes what the snapshots see.
+ */
+import type { ElementHandle, Page } from "playwright-core";
+import type { Anim, Motion, Transition } from "../model/layout.ts";
+/** Key: element path as `readPreferredSizes` builds it ("0/2/1", "" = root), or `<path>::before|::after`. */
+export type MotionByPath = Record<string, Motion>;
+declare global {
+    interface Window {
+        /** CSS animations started since `recordAnimations` (overlay enter/exit, 066). */
+        __markswiftStarted?: Animation[];
+    }
+}
+/**
+ * CSS animations under `root` in both `prefers-reduced-motion` branches. Call before `settle()`: a finished
+ * CSSAnimation leaves `getAnimations()`. The context runs `reduce`; the page ends there again.
+ */
+export declare function readMotion(page: Page, root: string): Promise<{
+    motion: MotionByPath;
+    warnings: string[];
+    authorReduce: boolean;
+}>;
+/** CSSTransitions running under `root` (started by a forced state), keyed by element path; finishes them. */
+export declare function readTransitions(page: Page, root: string): Promise<Record<string, Transition[]>>;
+/**
+ * Starts (or restarts) the page's record of the CSS animations that start from now on, so a short overlay enter or
+ * exit can be read after it finished (`readElementAnimations`). Call right before the activation or dismissal.
+ * Each DOM mutation records the CSS animations it created, in the same task: `animationstart` alone misses one when
+ * a busy main thread delivers it with `animationend` (a 100 ms enter on a slow runner) — the finished, fill-none
+ * animation has already left `getAnimations()`. The listener still catches style-only starts (`:hover`, `:focus`).
+ */
+export declare function recordAnimations(page: Page): Promise<void>;
+/**
+ * CSS animations on each of `targets` (overlay layer roots) under `prefers-reduced-motion: no-preference`, so
+ * motion-safe-only animations are seen (the context runs `reduce` and is left there): the running ones and those
+ * `recordAnimations` kept. A target without its own takes its single animated descendant's; with several, none
+ * (warned). Nothing is finished.
+ */
+export declare function readElementAnimations(page: Page, targets: ElementHandle[]): Promise<{
+    lists: Anim[][];
+    warnings: string[];
+}>;

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

@@ -0,0 +1,27 @@
+import type { CDPSession, Page } from "playwright-core";
+/**
+ * Fonts loaded, animations finished, one frame painted.
+ * `content-visibility: auto` subtrees are forced to lay out (off-screen content
+ * would otherwise be missing from the snapshot); the contents of
+ * `content-visibility: hidden` elements (`hidden=until-found`) are removed from
+ * layout because DOMSnapshot still reports boxes for them while nothing paints. Lazy images
+ * are loaded eagerly so below-the-fold pixels exist.
+ * `at` (ms): every animation is paused at that time instead of finished (motion frame captures), including the ones
+ * `recordAnimations` kept that already finished (a 100 ms overlay enter, 066). Resolves to how many it paused.
+ */
+export declare function settle(page: Page, options?: {
+    at?: number;
+}): Promise<number>;
+/** Finish (or, for infinite ones, cancel) every running animation: the settled look `settle()` leaves. */
+export declare function finishAnimations(page: Page): Promise<void>;
+/**
+ * Runs `shot` with every indeterminate `<progress>` painted at its first frame. Blink draws one with a native
+ * appearance from the clock (`LayoutProgress::AnimationProgress()`: `(TimeTicks::Now() - start) % 2.5 s`, repainted
+ * every 125 ms), outside Web Animations, so `settle()` and reduced motion don't reach it. CDP virtual time, paused,
+ * freezes the renderer's clock; the bars are hidden before and shown after, so their new layout objects start at that
+ * instant and paint at progress 0. Pausing while a frame is in flight stalls every later frame (the screenshot never
+ * returns), so a 1 px screenshot first waits until the hidden bars' frame is presented. A page without such a bar is
+ * left alone; one with it keeps virtual time, set to `advance` (timers still fire) after `shot`. `shot` gets the
+ * timeout to pass to the screenshot.
+ */
+export declare function withFrozenProgress<T>(page: Page, cdp: CDPSession, shot: (timeout: number) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,10 @@
+/** Read cascaded sizing and pseudo-element styles DOMSnapshot omits, without mutating the page. */
+import type { Page } from "playwright-core";
+import type { LayoutNode, PreferredSize } from "../model/layout.ts";
+export type PreferredSizes = Record<string, PreferredSize>;
+export type PseudoStyles = Record<string, NonNullable<LayoutNode["pseudoStyles"]>>;
+/** DOM element paths match snapshot traversal; text and generated pseudo-elements do not count. */
+export declare function readPreferredSizes(page: Page, selector: string): Promise<{
+    sizes: PreferredSizes;
+    pseudoStyles: PseudoStyles;
+}>;

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

@@ -0,0 +1,155 @@
+/**
+ * CDP `DOMSnapshot.captureSnapshot` → LayoutNode tree.
+ * The snapshot is columnar (parallel arrays + string table); this rebuilds a
+ * tree, attaches whitelisted computed styles and document-relative bounds,
+ * materialises `::before`/`::after`/`::marker`, hoists `display: contents`
+ * children, then crops to the requested root and rebases coordinates to it.
+ */
+import type { LayoutNode, Rect } from "../model/layout.ts";
+import type { NodeIdentity } from "../input/types.ts";
+import type { PreferredSizes, PseudoStyles } from "./sizing.ts";
+import type { MotionByPath } from "./motion.ts";
+/** CDP `RareStringData`: sparse per-node strings (`value[k]` belongs to node `index[k]`). */
+interface RareStringData {
+    index: number[];
+    value: number[];
+}
+/** CDP `RareBooleanData`: the nodes for which the flag is true. */
+interface RareBooleanData {
+    index: number[];
+}
+/** Subset of the CDP response we read. */
+export interface DomSnapshot {
+    documents: Array<{
+        documentURL: number;
+        nodes: {
+            nodeType: number[];
+            nodeName: number[];
+            nodeValue: number[];
+            parentIndex: number[];
+            attributes: number[][];
+            /** `before` / `after` / `marker` / … for pseudo-element nodes. */
+            pseudoType?: RareStringData;
+            /** `img.currentSrc` (absolute URL) for every `<img>`. */
+            currentSourceURL?: RareStringData;
+            /** Stable per-node backend id (CDP always sends it); joins the rest and state snapshots. */
+            backendNodeId?: number[];
+            /** Live `value` of `<input>` / `<textarea>` (the attributes keep the markup's initial value). */
+            inputValue?: RareStringData;
+            textValue?: RareStringData;
+            /** Live `checked` / `selected` (the attributes keep the markup's defaults). */
+            inputChecked?: RareBooleanData;
+            optionSelected?: RareBooleanData;
+        };
+        layout: {
+            nodeIndex: number[];
+            styles: number[][];
+            bounds: number[][];
+            text: number[];
+            paintOrders?: number[];
+            /** `offsetLeft/Top/Width/Height` per laid-out node (`includeDOMRects`). */
+            offsetRects?: number[][];
+        };
+        textBoxes: {
+            layoutIndex: number[];
+            bounds: number[][];
+            start: number[];
+            length: number[];
+        };
+    }>;
+    strings: string[];
+}
+export interface Raw {
+    idx: number;
+    /** CDP `backendNodeId`: stable across snapshots of one page. */
+    backend?: number;
+    type: number;
+    name: string;
+    value: string;
+    attrs: Record<string, string>;
+    /** `<img>` only: see `LayoutNode.currentSrc`. */
+    currentSrc?: string;
+    styles: Record<string, string>;
+    preferredSize?: LayoutNode["preferredSize"];
+    /** Snapshot bounds: border box for elements, line-box union for inline/text, the generated text's box for pseudo-elements. */
+    bounds?: Rect;
+    /** CSSOM offset rect (relative to the offsetParent's padding edge). */
+    offset?: Rect;
+    /** `before` / `after` / `marker` for pseudo-element nodes. */
+    pseudo?: string;
+    /** Pseudo-elements only: border box derived from `offset` (see `pseudoBox`). */
+    box?: Rect;
+    /** Text nodes: measured line boxes (`textBoxes`), in layout order; `start`/`length` index `text`. */
+    lines?: Array<{
+        bounds: Rect;
+        start: number;
+        length: number;
+    }>;
+    text?: string;
+    paint?: number;
+    /** See `LayoutNode.states`. */
+    states?: LayoutNode["states"];
+    /** See `LayoutNode.pseudoStyles`. */
+    pseudoStyles?: LayoutNode["pseudoStyles"];
+    /** See `LayoutNode.motion`. */
+    motion?: LayoutNode["motion"];
+    /** Pseudo-elements only: every layout entry in snapshot order (the first is the container); bounds from snapshot B when present. */
+    parts?: Array<{
+        bounds: Rect;
+        text?: string;
+    }>;
+    parent?: Raw;
+    children: Raw[];
+}
+/** Element children that consume a path index (every DOM element child; text and generated pseudo-elements do not). */
+export declare const pathChildren: (raw: Raw) => Raw[];
+/** Join CSS size intent and pseudo-element styles while wrappers still exist, before display:contents is flattened. */
+export declare function attachPreferredSizes(root: Raw, sizes: PreferredSizes, pseudoStyles: PseudoStyles): void;
+/** Join captured motion (browser/motion.ts) by element path; `<path>::before|::after` lands on that pseudo child. */
+export declare function attachMotion(root: Raw, motion: MotionByPath): void;
+/** The descendant of `root` at element path `path` (`""` = `root`), counted as `attachPreferredSizes` counts. */
+export declare function rawAt(root: Raw, path: string): Raw | undefined;
+/** Inverse of `rawAt`: `raw`'s element path from `root`, or undefined when it is not `root` or below it. */
+export declare function pathOf(root: Raw, raw: Raw): string | undefined;
+/**
+ * @param snap     snapshot as painted (styles incl. transform matrices, paint order)
+ * @param boxes    optional snapshot taken with `transform: none` on every element;
+ *                 its bounds/offsets are the untransformed layout boxes and win over `snap`'s.
+ * @param states   paint deltas per `snap` node index under forced interaction states (`browser/states.ts`).
+ */
+export declare function snapshotToTree(snap: DomSnapshot, boxes?: DomSnapshot, states?: {
+    pressed: Map<number, Record<string, string>>;
+    focused: Map<number, Record<string, string>>;
+}): Raw;
+/** Candidate URLs of a `srcset` (HTML spec tokenisation: URLs are whitespace-free, descriptors run to the next comma). */
+export declare function srcsetUrls(srcset: string): string[];
+export declare function findByAttr(root: Raw, attr: string, value: string): Raw | undefined;
+/**
+ * Convert the capture root to a LayoutNode tree, dropping nodes without
+ * layout (display:none, <script>, comments, collapsed whitespace — a
+ * whitespace-only text node that renders as an inter-run space is kept) and
+ * rebasing bounds to `origin`. Element ids come from `identity`; `path` is the
+ * element-index path of `raw` from the capture root ("" for the root itself,
+ * then "0", "0/2", …) counting element children only.
+ *
+ * - `::before`/`::after`/`::marker` become element nodes with that tag, their
+ *   computed styles, the derived border box and `#text` children holding the
+ *   generated text (counters/quotes already resolved by the browser; consecutive
+ *   text parts merged into one), plus one
+ *   `img` child per image the browser laid out from `content: url()` /
+ *   `list-style-image` (`attrs.src`, its box), in layout order. `::after`
+ *   is placed after the element's real children, the others before. They do
+ *   not consume an element index; their path is `<parent path>/::before`.
+ *   Empty ones (`content: ""` without a box) are dropped.
+ * - An element without a layout box but with laid-out children
+ *   (`display: contents`) is spliced out: its children join the parent's list
+ *   in order; the element's own attrs and id are gone. It still counts as an
+ *   element in its children's paths so identity follows the DOM.
+ * - `visibility: hidden` elements keep their box and are emitted like any
+ *   other node; hiding is the inference pass's decision.
+ */
+export declare function toLayout(raw: Raw, origin: {
+    x: number;
+    y: number;
+}, identity: NodeIdentity, path?: string): LayoutNode | undefined;
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * Paint-only interaction states: force `:hover`+`:active` on every pressable element and
+ * `:focus`+`:focus-visible` on every text field of the capture root, take one DOM snapshot per state,
+ * and keep the paint properties that changed. Layout never comes from these snapshots.
+ * With `motion`, the CSSTransitions forcing and releasing each state starts are read too, under both
+ * `prefers-reduced-motion` values.
+ */
+import type { CDPSession, ElementHandle, Page } from "playwright-core";
+import { type Motion } from "../model/layout.ts";
+import type { DomSnapshot } from "./snapshot.ts";
+/** Properties that move paint, not layout (all are in STYLE_WHITELIST). */
+export declare const PAINT_KEYS: readonly ["background-color", "background-image", "color", "-webkit-text-fill-color", "border-top-color", "border-right-color", "border-bottom-color", "border-left-color", "box-shadow", "outline-color", "outline-style", "outline-width", "outline-offset", "opacity", "transform", "scale", "translate", "rotate", "filter", "text-decoration-color"];
+export type StateDeltas = Map<number, Record<string, string>>;
+export declare function forceStates(cdp: CDPSession, nodeIds: number[], classes: string[]): Promise<void>;
+/**
+ * Per rest-snapshot node index, the paint keys whose value differs in `state`. Nodes are joined by
+ * `backendNodeId` (index order when absent and the node counts match). A node whose offset box moved,
+ * or whose display/visibility changed, contributes nothing and is counted instead.
+ */
+export declare function diffStates(rest: DomSnapshot, state: DomSnapshot, ignoreAutoOutline: boolean): {
+    deltas: StateDeltas;
+    moved: number;
+    revealed: number;
+};
+export declare function captureStates(cdp: CDPSession, root: string, rest: DomSnapshot, motion?: {
+    page: Page;
+    sheet: ElementHandle;
+    root: string;
+    authorReduce: boolean;
+}): Promise<{
+    pressed: StateDeltas;
+    focused: StateDeltas;
+    /** Keyed by element path (see `MotionByPath`). */
+    transitions: Record<string, NonNullable<Motion["transitions"]>>;
+    warnings: string[];
+}>;

package/dist/types/cli/args.d.ts

@@ -0,0 +1,31 @@
+import type { ConvertOptions } from "../api/types.ts";
+export declare class UsageError extends Error {
+}
+export interface ConversionCommand {
+    kind: "convert";
+    source: {
+        file: string;
+    } | {
+        url: string;
+    } | {
+        stdin: true;
+    };
+    outDir: string;
+    cssPath?: string;
+    palettePath?: string;
+    update: boolean;
+    force: boolean;
+    options: Pick<ConvertOptions, "name" | "root" | "theme" | "darkClass" | "mode" | "viewport" | "breakpoints">;
+}
+export interface BuildCommand {
+    kind: "build";
+    configPath: string;
+    force: boolean;
+}
+export type Command = {
+    kind: "help";
+} | {
+    kind: "version";
+} | ConversionCommand | BuildCommand;
+export declare const HELP = "Markswift \u2014 convert rendered HTML and CSS to SwiftUI.\n\nUsage:\n  markswift convert <file.html|-> --out <directory> [options]\n  markswift convert --url <http(s)://...> --out <directory> [options]\n  markswift build [markswift.json] [--force]\n                    Build every component of the config into one Swift package\n                    (directory \"out\" of the config; replaces only files it wrote)\n  markswift --help | --version\n\nInputs:\n  <file.html>       HTML document or fragment; relative assets use its directory\n  -                 Read HTML from stdin (inline/data assets only)\n  --url <url>       Capture a running HTTP or HTTPS page\n  --css <file>      Optional compiled CSS file\n\nOptions:\n  --out <directory> Required. Must not exist yet, unless --update\n  --update          Regenerate into an existing --out written by Markswift: rewrites only the files\n                    listed in its .markswift.json, removes listed files no longer produced, never\n                    touches other files; refuses (exit 2) when a listed file was edited by hand\n  --force           With --update: overwrite hand-edited listed files\n  --name <Name>     Swift view name (default: ConvertedView)\n  --root <selector> Capture only this CSS selector\n  --width <px>      Viewport width (default: 390)\n  --height <px>     Viewport height (default: 844)\n  --theme <value>   adaptive, light or dark (default: adaptive). adaptive captures the page in\n                    light and dark (prefers-color-scheme) and emits one view that follows both\n  --dark-class <name>\n                    Class added to <html> for the dark capture (class-based themes, e.g. dark)\n  --mode <value>    app or fidelity (default: app)\n  --palette <file>  JSON map from CSS variables or hex colours to app colours\n                    (e.g. {\"--primary\": \"Color.accentColor\"})\n  --breakpoints <auto|W[xH],\u2026>  Capture one layout per CSS width band (auto: 390, 834x1210, 1210x834, 1376x1032) and emit one view that switches at the CSS thresholds\n  -h, --help        Show this help\n  -v, --version     Show version\n\nRequires Node.js 20+ (or Bun 1.4.2+) and Google Chrome; webfonts need python3 with fontTools and brotli. CSS must already be compiled; JavaScript behavior is not translated.\n";
+export declare function parseArgs(args: string[]): Command;

package/dist/types/cli/config.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import type { BuildOptions } from "../api/build.ts";
+import { type PaletteMap } from "../compiler/index.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+/** `markswift.json`: one library, its output directory, shared capture settings and the components (each may override them). */
+export declare const BuildConfig: z.ZodObject<{
+    components: z.ZodArray<z.ZodObject<{
+        root: z.ZodOptional<z.ZodString>;
+        viewport: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>;
+        theme: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+            adaptive: "adaptive";
+        }>>;
+        darkClass: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            app: "app";
+            fidelity: "fidelity";
+        }>>;
+        css: z.ZodOptional<z.ZodString>;
+        waitFor: z.ZodOptional<z.ZodString>;
+        breakpoints: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+            devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strict>>>;
+            max: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>]>>;
+        name: z.ZodString;
+        source: z.ZodString;
+    }, z.core.$strict>>;
+    root: z.ZodOptional<z.ZodString>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>>;
+    theme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        adaptive: "adaptive";
+    }>>;
+    darkClass: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        app: "app";
+        fidelity: "fidelity";
+    }>>;
+    css: z.ZodOptional<z.ZodString>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    breakpoints: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        devices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>>>;
+        max: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>]>>;
+    library: z.ZodString;
+    out: z.ZodString;
+    serve: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    palette: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** `--palette` / `palette` file: CSS variable or hex key → one-line Swift `Color` expression. */
+export declare const PaletteMapFile: z.ZodRecord<z.ZodString, z.ZodString>;
+/** Read and validate a palette map. A missing file is a plain `Error`; bad JSON or entries are `UsageError`s naming the key. */
+export declare function loadPalette(path: string): Promise<PaletteMap>;
+/**
+ * Read and validate a build config. Paths (`out`, `serve`, `css`, `source`, `palette`) are relative to the config file's
+ * directory; `serve` defaults to it. Config mistakes are `UsageError`s; a missing config, source, CSS or palette file is a
+ * plain `Error`.
+ */
+export declare function loadBuildConfig(path: string): Promise<{
+    out: string;
+    options: BuildOptions;
+    warnings: ConversionWarning[];
+}>;

package/dist/types/cli/css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Inline `url()`s of a compiled CSS file that are relative to that file, as data URLs. Returns the CSS and the references it could not read.
+ * `--css` is injected as a `<style>` into the page, where relative URLs would otherwise resolve against the HTML document.
+ * Untouched: `data:`, `#fragment`, root-relative `/…`, protocol-relative `//…` and any URL with a scheme. `@import` is not followed.
+ */
+export declare function inlineRelativeUrls(css: string, cssPath: string): Promise<{
+    css: string;
+    missing: string[];
+}>;

package/dist/types/cli/manifest.d.ts

@@ -0,0 +1,20 @@
+/** Records what a run wrote, so `convert --update` rewrites exactly those files. */
+export declare const MANIFEST = ".markswift.json";
+export interface Manifest {
+    tool: "markswift";
+    version: string;
+    /** POSIX relative path → lowercase hex SHA-256 of its bytes. */
+    files: Record<string, string>;
+}
+export declare class EditedFilesError extends Error {
+    readonly files: string[];
+    constructor(files: string[], message: string);
+}
+/** Absolute, backslashed, empty-segment, `.` or `..` paths could escape the output directory. */
+export declare function unsafePath(name: string): boolean;
+export declare function manifestFor(files: Record<string, string | Uint8Array>, version: string): Manifest;
+export declare function serializeManifest(manifest: Manifest): string;
+/** `undefined` when `dir` has no manifest; throws when it is malformed or written by another tool. */
+export declare function readManifest(dir: string): Promise<Manifest | undefined>;
+/** Listed files whose bytes no longer match; a missing listed file is not edited (it is simply recreated). */
+export declare function editedFiles(dir: string, manifest: Manifest): Promise<string[]>;

package/dist/types/cli/output.d.ts

@@ -0,0 +1,27 @@
+import type { ConversionResult } from "../api/types.ts";
+import type { ConversionWarning } from "../model/semantic.ts";
+import { type Manifest } from "./manifest.ts";
+type Bundle = Pick<ConversionResult, "files" | "assets">;
+export declare function ensureVacant(directory: string): Promise<void>;
+/**
+ * Pre-flight for `--update`: the manifest of the Markswift output in `directory`, `undefined` when it does not exist.
+ * Throws when the directory was not written by Markswift or, unless `force`, when a listed file was edited by hand.
+ */
+export declare function updatable(directory: string, force?: boolean): Promise<Manifest | undefined>;
+/** Write the complete conversion bundle and its manifest without replacing an existing directory. */
+export declare function writeBundle(result: Bundle, directory: string, options: {
+    version: string;
+}): Promise<string[]>;
+/**
+ * Regenerate a Markswift output in place: rewrite the files its manifest lists, delete listed files the new bundle no
+ * longer produces, never touch anything else. Every refusal happens before the first write.
+ */
+export declare function updateBundle(result: Bundle, directory: string, options: {
+    version: string;
+    force?: boolean;
+}): Promise<string[]>;
+/** A warning as one stderr line: `[<component>] <level> <feature>: <message>`; each prefix only when set. */
+export declare function formatWarning(w: ConversionWarning): string;
+/** One line per distinct (level, feature, message), unmapped first, naming the nodes it affects. */
+export declare function formatDiagnostics(report: ConversionResult["diagnostics"]): string[];
+export {};

package/dist/types/cli/run.d.ts

@@ -0,0 +1,4 @@
+import type { BuildCommand, ConversionCommand } from "./args.ts";
+/** `markswift build`: capture every component of the config and regenerate one Swift package in its `out`. */
+export declare function runBuild(command: BuildCommand): Promise<void>;
+export declare function runConversion(command: ConversionCommand): Promise<void>;

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};