mechanica 2.1.0 → 2.2.0

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,116 @@
+/**
+ * `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: Edge or Chrome from their usual install paths. */
+    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. */
+    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`. Throws when none 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';
+    ids: string[];
+} | {
+    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,19 +10,34 @@ 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>;

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

@@ -11,26 +11,123 @@ 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. 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.0",
   "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.0",
     "@vue/compiler-sfc": "^3.5.38",
     "compact-json-schema": "^0.1.5",
     "estree-walker": "^3.0.3",