mechanica 2.1.0 → 2.2.1

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

@@ -2,7 +2,18 @@ export interface ParsedArgs {
     command?: string;
     /** Positional arguments after the command (excluding `--flag` values). */
     args: string[];
+    /** Flag values; a flag given several times keeps its last value (see {@link flagValues}). */
     flags: Record<string, string | boolean>;
 }
+export interface ParseOptions {
+    /** Flags that never take a value, so `--full hero` keeps `hero` positional. */
+    booleans?: string[];
+}
 /** Parse `argv` (without node/script) into a command, positionals and a `--flag[=value]` map. */
-export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function parseArgs(argv: string[], options?: ParseOptions): ParsedArgs;
+/**
+ * Every value a repeatable flag was given, in order — `--section a --section b`
+ * → `['a', 'b']`; a bare `--section` contributes `true`. Takes the same `argv`
+ * as {@link parseArgs} (command first).
+ */
+export declare function flagValues(argv: string[], name: string, options?: ParseOptions): Array<string | boolean>;

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

@@ -0,0 +1,130 @@
+/**
+ * `mechanica/browser` — the headless browser behind `mechanica shot` and
+ * `mechanica thumbs`, for a site's own scripts: open a page (a dev-server URL,
+ * a design handoff's `file://` URL, any site), resize it, scroll it, measure it
+ * with `evaluate`, and screenshot it or one section of it.
+ *
+ * Drives a Chrome/Edge already installed on the machine over raw CDP
+ * (`headless.ts`), so there is nothing to download. Needs a global `WebSocket`
+ * (Node 22+ or Bun) and never imports Vite.
+ */
+import { type Clip } from './headless';
+export { findDevServer, MAX_SHOT_HEIGHT, type Clip } from './headless';
+/** Readiness of an ordinary page: the load event has fired. */
+export declare const PAGE_LOADED = "document.readyState === 'complete'";
+export interface GotoOptions {
+    /** JS expression polled until it is `true`. Default: {@link PAGE_LOADED}. */
+    ready?: string;
+    /** Then wait for web fonts and images (see {@link BrowserPage.settle}). Default `true`. */
+    settle?: boolean;
+    /** How long `ready` may take, in ms. Default 15 000. */
+    timeout?: number;
+}
+export interface OpenPageOptions extends GotoOptions {
+    /** Viewport width in CSS px. Default 1440. */
+    width?: number;
+    /** Viewport height in CSS px. Default 900. */
+    height?: number;
+    /**
+     * A Chromium-based executable. Default: the first installed browser that
+     * starts, from the usual install paths (on Windows Chrome, then Edge).
+     */
+    browser?: string;
+    /**
+     * Emulate `prefers-reduced-motion: reduce`, as `mechanica shot` does: pages
+     * that honor it skip their entrance animations. Default `true`.
+     */
+    reducedMotion?: boolean;
+}
+export interface ScreenshotOptions {
+    /** An explicit region in document coordinates. Wins over everything else. */
+    clip?: Clip;
+    /** A CSS selector: the bounding box of the first matching element (see {@link BrowserPage.sectionClip}). */
+    section?: string;
+    /** The whole document (height capped at {@link MAX_SHOT_HEIGHT}). */
+    full?: boolean;
+    /** Output scale: `0.5` writes a half-size PNG. Default 1. */
+    scale?: number;
+}
+/** `goto` could not open the URL at all (DNS, refused connection, missing file…). */
+export declare class NavigationError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    constructor(url: string, reason: string);
+}
+/** One headless tab in its own browser process. */
+export interface BrowserPage {
+    /** Console errors/warnings and uncaught exceptions, as `[console.error] …` / `[pageerror] …` lines. */
+    readonly messages: string[];
+    /** Navigate, then wait for `ready` and (by default) fonts + images. */
+    goto(url: string, options?: GotoOptions): Promise<void>;
+    /** Evaluate an expression in the page (promises are awaited) and return its JSON value. Throws on a page exception. */
+    evaluate<T = unknown>(expression: string): Promise<T>;
+    /** Poll `expression` until it is `true`. */
+    waitFor(expression: string, timeout?: number): Promise<void>;
+    /** Resize the viewport (height defaults to the current one). */
+    setViewport(width: number, height?: number): Promise<void>;
+    /** Scroll the window to `y` instantly (ignoring `scroll-behavior: smooth`), wait two frames, return the reached `scrollY`. */
+    scrollTo(y: number): Promise<number>;
+    /** Wait two animation frames: one full style → layout → paint cycle. */
+    nextFrame(): Promise<void>;
+    /** Wait for web fonts and images; lazy images are switched to eager. Gives up after 10 s. */
+    settle(): Promise<void>;
+    /** Turn off CSS animations and transitions (running transitions jump to their end). Idempotent. */
+    freezeAnimations(): Promise<void>;
+    /** Undo {@link freezeAnimations}. */
+    unfreezeAnimations(): Promise<void>;
+    /**
+     * The document-coordinate box of the first element matching `selector`.
+     * Looks in the document, then in every open shadow root (`host >>> inner`
+     * crosses into `host`'s shadow root explicitly). A bare `#name` or `name`
+     * that matches nothing falls back to `[data-block-id="name"]`, a Mechanica
+     * block. Throws when nothing matches or the box is empty.
+     */
+    sectionClip(selector: string): Promise<Clip>;
+    /**
+     * A PNG of the page: `clip`, else `section`, else `full`, else what is in
+     * the viewport right now (at the current scroll position).
+     */
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /** A raw CDP command on this tab's session, for anything not covered above. */
+    send(method: string, params?: object): Promise<any>;
+    /** Close the browser and remove its temporary profile. */
+    close(): Promise<void>;
+}
+/**
+ * Launch a headless browser with one tab, sized and media-emulated like
+ * `mechanica shot`, and open `url` in it (omit `url` for a blank tab to
+ * `goto` later). Always `close()` the page — it owns the browser process.
+ *
+ * ```ts
+ * import { openPage } from 'mechanica/browser'
+ *
+ * const page = await openPage('file:///…/design/index.html', { width: 390 })
+ * try {
+ *   const size = await page.evaluate<string>(`getComputedStyle(document.querySelector('h1')).fontSize`)
+ *   fs.writeFileSync('hero.png', await page.screenshot({ section: '#hero' }))
+ * } finally {
+ *   await page.close()
+ * }
+ * ```
+ */
+export declare function openPage(url?: string, options?: OpenPageOptions): Promise<BrowserPage>;
+type SectionBox = Clip | {
+    error: 'invalid';
+    message: string;
+} | {
+    error: 'missing';
+    /** Readable ids on the page (`#name`), shadow roots included. */
+    ids: string[];
+    /** `data-block-id` values on the page. */
+    blockIds?: string[];
+    /** The block-id selector that was tried as well. */
+    fallback?: string | null;
+} | {
+    error: 'empty';
+    width: number;
+    height: number;
+};
+/** The message for a `sectionClip` that found nothing usable. */
+export declare function describeSectionError(selector: string, box: Exclude<SectionBox, Clip>): string;

package/dist/types/cli/dev-server.d.ts

@@ -0,0 +1,13 @@
+export interface ResolvedServer {
+    origin: string;
+    close: () => Promise<void>;
+}
+/**
+ * Find a dev server to render against: an explicit origin, a running local
+ * Mechanica dev server, or an ephemeral one booted from the project's
+ * `vite.config.ts` and torn down afterwards.
+ *
+ * The only browser-side helper that needs Vite, kept out of `headless.ts` so
+ * the public `mechanica/browser` entry never pulls it in.
+ */
+export declare function resolveServer(flag?: string): Promise<ResolvedServer>;

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

@@ -1,13 +1,7 @@
-export interface ResolvedServer {
-    origin: string;
-    close: () => Promise<void>;
-}
-/**
- * Find a dev server to render against: an explicit origin, a running local
- * Mechanica dev server, or an ephemeral one booted from the project's
- * `vite.config.ts` and torn down afterwards.
- */
-export declare function resolveServer(flag?: string): Promise<ResolvedServer>;
+/** Where `mechanica shot`/`thumbs` look for a running dev server first. */
+export declare const DEV_SERVER_ORIGINS: string[];
+/** The origin of a running Mechanica dev server on the default port, or null. */
+export declare function findDevServer(origins?: string[]): Promise<string | null>;
 export declare function setViewport(cdp: CdpClient, sessionId: string, width: number, height?: number): Promise<void>;
 export declare function evaluateValue<T>(cdp: CdpClient, sessionId: string, expression: string): Promise<T>;
 /**
@@ -16,29 +10,86 @@ export declare function evaluateValue<T>(cdp: CdpClient, sessionId: string, expr
  * ready yet" rather than failing the wait.
  */
 export declare function waitForCondition(cdp: CdpClient, sessionId: string, expression: string, timeout: number): Promise<void>;
-/** Wait for web fonts and all images — normal pages have no injected ready flag. */
-export declare function settlePageMedia(cdp: CdpClient, sessionId: string): Promise<void>;
-/** Freeze animations/transitions so captures are deterministic across runs. */
+/** Upper bound for {@link settlePageMedia}: a stalled image must not hang a shot. */
+export declare const SETTLE_TIMEOUT = 10000;
+/**
+ * Wait for web fonts and all images — normal pages have no injected ready flag.
+ * Lazy images are switched to eager first: below the fold they would never
+ * start loading in a headless tab (the wait used to hang on them), and a
+ * full-page capture should show them anyway. Gives up after `timeout` ms.
+ */
+export declare function settlePageMedia(cdp: CdpClient, sessionId: string, timeout?: number): Promise<void>;
+/** Freeze animations/transitions so captures are deterministic across runs. Idempotent. */
 export declare function freezeAnimations(cdp: CdpClient, sessionId: string): Promise<void>;
+/** Undo {@link freezeAnimations}: transitions and animations run again. */
+export declare function unfreezeAnimations(cdp: CdpClient, sessionId: string): Promise<void>;
+/** Wait two animation frames: a full style → layout → paint cycle has run. */
+export declare function nextFrames(cdp: CdpClient, sessionId: string): Promise<void>;
 /** Chromium refuses to encode arbitrarily tall captures — cap and say so. */
 export declare const MAX_SHOT_HEIGHT = 12000;
-/** The full document size as a screenshot clip. */
-export declare function fullPageClip(cdp: CdpClient, sessionId: string): Promise<{
+/** A screenshot region in CSS pixels, relative to the document (not the viewport). */
+export interface Clip {
     x: number;
     y: number;
     width: number;
     height: number;
-}>;
+}
+/** The full document size as a screenshot clip. */
+export declare function fullPageClip(cdp: CdpClient, sessionId: string): Promise<Clip>;
+/** What is on screen right now (the visual viewport at its scroll offset), as a clip. */
+export declare function viewportClip(cdp: CdpClient, sessionId: string): Promise<Clip>;
 export interface LaunchedBrowser {
     client: CdpClient;
     close: () => Promise<void>;
 }
+/** A Chromium-based browser executable to try. */
+export interface BrowserExecutable {
+    label: string;
+    path: string;
+}
 /**
  * Spawn a headless Chromium-based browser with a DevTools endpoint and connect
- * to it. Prefers browsers already on the machine (Edge ships with Windows,
- * Chrome is everywhere), so nothing needs downloading.
+ * to it. With `explicitPath` (`--browser`) only that executable is tried.
+ * Otherwise the installed browsers of {@link platformBrowserCandidates} are
+ * tried in order until one starts — a browser already on the machine, so
+ * nothing needs downloading — and the error names each one that failed.
  */
 export declare function launchBrowser(explicitPath?: string): Promise<LaunchedBrowser>;
+/**
+ * Try `start` on each candidate in order and return the first browser that
+ * comes up. When none does, the error lists every candidate and why it failed.
+ */
+export declare function startFirstBrowser<T>(candidates: BrowserExecutable[], start: (candidate: BrowserExecutable) => Promise<T>): Promise<T>;
+/**
+ * Spawn one browser on a fresh temporary profile and connect to it. When it
+ * does not come up (exits early, never prints its endpoint, refuses the
+ * connection), everything it started is ended and the profile removed before
+ * the error is rethrown.
+ */
+export declare function startBrowser(executable: BrowserExecutable): Promise<LaunchedBrowser>;
+/**
+ * The environment a browser starts with. On Windows it leaves out
+ * `__COMPAT_LAYER` (Git Bash and some tool runners set it to `RunAsInvoker`):
+ * under a compatibility layer Edge relaunches itself without it and exits at
+ * once, so the process we spawned never prints its endpoint while the
+ * relaunched one keeps running.
+ */
+export declare function browserEnv(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/**
+ * The Windows commands that end a browser which failed to start, best effort:
+ * `taskkill /T /F` on its process tree while the spawned process still runs
+ * (`pid`), then — because a browser that relaunched itself has outlived the
+ * process we spawned — every process still running on its temporary profile,
+ * found by the profile's folder name in the command line.
+ */
+export declare function windowsKillCommands(pid: number | undefined, userDataDir: string): Array<[string, string[]]>;
+/**
+ * Known install locations of Chromium-based browsers, in the order they are
+ * tried. On Windows Chrome comes first: Edge ships with Windows, so it is the
+ * fallback, and it relaunches itself under a compatibility layer (see
+ * {@link browserEnv}).
+ */
+export declare function platformBrowserCandidates(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): BrowserExecutable[];
 type CdpEventListener = (method: string, params: any, sessionId?: string) => void;
 /**
  * A minimal Chrome DevTools Protocol client over the platform `WebSocket`

package/dist/types/cli/section-query.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Finding the element behind a section selector (`mechanica shot --section`,
+ * `BrowserPage.sectionClip`): the lookup that runs in the page, and the pure
+ * helpers that prepare its arguments.
+ *
+ * - **Shadow DOM.** Design handoffs render their sections inside custom
+ *   elements with open shadow roots, where `document.querySelector` sees
+ *   nothing. The lookup tries the document first, then every open shadow root
+ *   in tree order (depth first), matching the selector within each root.
+ *   Slotted content belongs to its host's tree, so that tree's query covers
+ *   it. `host >>> inner` crosses into the shadow root of `host` explicitly.
+ * - **Block ids.** Mechanica renders a block with `data-block-id="<node id>"`
+ *   and no `id`, so a bare `#hero` (or `hero`) that matches nothing falls back
+ *   to `[data-block-id="hero"]`.
+ */
+/** Crosses into the shadow root of the elements matched by the part before it. */
+export declare const SHADOW_COMBINATOR = ">>>";
+/**
+ * Split a selector at `>>>` into trimmed parts (one part when there is none).
+ * A `>>>` inside quotes, brackets or parentheses, or after a backslash, is
+ * part of the selector. Throws when a part is empty (`>>> .a`, `.a >>>`).
+ */
+export declare function splitShadowSelector(selector: string): string[];
+/**
+ * The block-id selector to try when a bare `#name` or `name` matches nothing:
+ * `[data-block-id="name"]`. Null for any other selector. A name that is not a
+ * valid CSS id (`#1hero`) still gets one, so block ids starting with a digit
+ * are reachable too.
+ */
+export declare function blockIdFallback(selector: string): string | null;
+/** Readable ids and block ids listed in a "no match" error, at most this many of each. */
+export declare const MAX_LISTED_IDS = 20;
+/**
+ * In-page source of `(parts, fallback) => result`, where `parts` is a selector
+ * split by {@link splitShadowSelector} and `fallback` is
+ * {@link blockIdFallback}'s result (or null). It finds the first element
+ * matching `parts`, else the first matching `fallback`, in the document and
+ * in every open shadow root, and returns:
+ *
+ * - `{ element }`;
+ * - `{ error: 'invalid', message }` when the selector does not parse (and the
+ *   fallback finds nothing);
+ * - `{ error: 'missing', ids, blockIds, fallback }`: the readable ids
+ *   (`#name`) and the `data-block-id` values on the page, shadow roots
+ *   included, for the error message.
+ *
+ * Plain JS with no outside references: it is sent to the page as text.
+ */
+export declare const FIND_SECTION_SOURCE: string;

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

@@ -11,26 +11,128 @@ export interface ShotOptions {
     server?: string;
     /** Explicit Chromium-based browser executable path. */
     browser?: string;
-    /** Screenshot the full page instead of clipping to the block element. */
+    /** Screenshot the full page instead of clipping to the block element (or to the viewport with `scroll`). */
     full?: boolean;
+    /**
+     * CSS selectors (`--section`, repeatable): one PNG each, clipped to the first
+     * match — in the document or an open shadow root (`host >>> inner` crosses
+     * one explicitly); a bare `#name` that matches nothing finds
+     * `[data-block-id="name"]`. Page/URL/file shots only.
+     */
+    section?: string[];
+    /** Scroll offset(s) in px, comma-separated: capture the viewport scrolled there. */
+    scroll?: string;
+    /** Leave CSS animations and transitions running (`--no-freeze`). */
+    noFreeze?: boolean;
 }
+/**
+ * What `mechanica shot` renders: a block through the preview route, a page of
+ * this project on the dev server, or a foreign document — any `http(s)://` URL
+ * or a local file (a design handoff's `index.html`) — opened as is.
+ */
+export type ShotTarget = {
+    kind: 'block';
+    blockId: string;
+} | {
+    kind: 'page';
+    path: string;
+} | {
+    kind: 'url';
+    url: string;
+}
+/** `file` is the path on disk when the URL maps to one (checked before launching). */
+ | {
+    kind: 'file';
+    url: string;
+    file?: string;
+};
+/** How one capture is framed. */
+export type CaptureMode = 'block' | 'section' | 'full' | 'viewport';
+/** Everything `runShot` needs, resolved and validated before any browser starts. */
+export interface ShotPlan {
+    target: ShotTarget;
+    /** Base output name (without section/scroll/width suffixes). */
+    name: string;
+    widths: number[];
+    /** Scroll offsets to capture at, in order; undefined = no scrolling. */
+    scrolls?: number[];
+    sections: Array<{
+        selector: string;
+        slug: string;
+    }>;
+    data?: Record<string, unknown>;
+    mode: CaptureMode;
+    freeze: boolean;
+}
+/** Readiness flag of the standalone block preview route. */
+export declare const PREVIEW_READY = "window.__MECHANICA_PREVIEW_READY__ === true";
 /** Parse a `--width` value into a list of positive integers. Defaults to `[1440]`. */
 export declare function parseWidths(value: string | undefined): number[];
+/** Parse a `--scroll` value (px from the top, comma-separated). Undefined when absent. */
+export declare function parseScrolls(value: string | undefined): number[] | undefined;
 /** Resolve `--data`: inline JSON or `@file`, validated to a JSON object. */
 export declare function resolveDataArg(value: string | undefined): Record<string, unknown> | undefined;
 /** Build the preview-route URL for a block on a given server origin. */
 export declare function previewUrl(origin: string, blockId: string, data?: Record<string, unknown>): string;
-/** Resolve the output PNG path for one width. */
-export declare function outputPath(out: string | undefined, name: string, width: number, multi: boolean): string;
+/**
+ * Resolve the output PNG path for one capture. `variant` (`-<section>`,
+ * `-y<scroll>`) is always part of the name; the `-w<width>` suffix only when
+ * shooting several widths. An `--out` ending in `.png` is a file name, any
+ * other value a directory.
+ */
+export declare function outputPath(out: string | undefined, name: string, width: number, multi: boolean, variant?: string): string;
+/** The name suffix of one capture: `-<section slug>` and/or `-y<scroll>`. */
+export declare function shotVariant(sectionSlug?: string, scroll?: number): string;
 /** `/` → `index`, `/docs/getting-started` → `docs-getting-started`. */
 export declare function pageSlug(path: string): string;
 /** Normalize a page path: leading slash, no trailing slash (except the root). */
 export declare function normalizePagePath(path: string): string;
+/** Lowercase letters and digits (any script) joined by single dashes. */
+export declare function slugify(value: string): string;
+/**
+ * One file-name slug per `--section` selector: `#hero` → `hero`,
+ * `.stage > .pin` → `stage-pin`. A selector with no letters or digits becomes
+ * `section`; repeats get `-2`, `-3`…
+ */
+export declare function sectionSlugs(selectors: string[]): string[];
+/**
+ * Classify a `shot` target, in this order:
+ * - `--page </path>` → that page;
+ * - `http://…` / `https://…` → a URL, opened as is;
+ * - `file://…`, a Windows drive path (`C:\…`), a `./` or `../` path, or any
+ *   path ending in `.html`/`.htm` → a local file (relative to `cwd`);
+ * - anything else starting with `/` → a page of this project;
+ * - anything else → a block id.
+ */
+export declare function classifyTarget(target: string | undefined, page?: string, cwd?: string): ShotTarget;
+/**
+ * Default output name of a URL or file shot:
+ * - a URL → its host (no `www.`, port appended) and path, extension dropped:
+ *   `https://example.com/business/evolve` → `example-com-business-evolve`;
+ * - a file → its path relative to `cwd` (or its last three path segments when
+ *   it lies outside), extension dropped: `design/evolve-level/index.html` →
+ *   `design-evolve-level-index`.
+ */
+export declare function foreignShotName(target: ShotTarget, cwd?: string): string;
+/**
+ * How each capture is framed: `--section` boxes, else `--full` (whole
+ * document), else the viewport when scrolling (so sticky/pinned states are
+ * what's in the picture), else the block element for block shots and the
+ * whole document for pages, URLs and files.
+ */
+export declare function captureMode(kind: ShotTarget['kind'], flags: {
+    section?: boolean;
+    full?: boolean;
+    scroll?: boolean;
+}): CaptureMode;
+/** Resolve and validate a `shot` invocation without touching a browser or a server. */
+export declare function planShot(target: string | undefined, options?: ShotOptions, cwd?: string): ShotPlan;
 /**
- * `mechanica shot <blockId>` / `mechanica shot /page/path` — render one block
- * through the dev preview route (or a whole page, editor overlay stripped) in
- * a headless Chromium and write PNG screenshot(s). Made for agent loops:
- * prints the image paths plus any console/render errors, and fails loudly when
- * the block or page failed to render.
+ * `mechanica shot <target>` — render one block through the dev preview route,
+ * a whole page (editor overlay stripped), or a foreign document (any URL, or
+ * a local `.html` file such as a design handoff) in a headless Chromium and
+ * write PNG screenshot(s): per width, per scroll offset, per `--section`.
+ * Made for agent loops: prints the image paths plus any console/render errors,
+ * and fails loudly when the block or page failed to render.
  */
 export declare function runShot(target: string | undefined, options?: ShotOptions): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mechanica",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Build Vue 3 websites with a visual block editor",
   "license": "MIT",
   "repository": {
@@ -45,6 +45,10 @@
       "types": "./dist/types/server/index.d.ts",
       "import": "./dist/server.js"
     },
+    "./browser": {
+      "types": "./dist/types/cli/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
     "./editor": {
       "import": "./dist/editor.js"
     },
@@ -66,7 +70,7 @@
     "prepublishOnly": "bun ../../scripts/ensure-bun-publish.js && bun run build"
   },
   "dependencies": {
-    "mechanica-shared": "2.1.0",
+    "mechanica-shared": "2.2.1",
     "@vue/compiler-sfc": "^3.5.38",
     "compact-json-schema": "^0.1.5",
     "estree-walker": "^3.0.3",