@docsxai/engine 0.2.0 → 0.2.1-rc.1

package/dist/doc-pack.js

@@ -207,9 +207,17 @@ export const FlowFile = z
 // ---------------------------------------------------------------------------
 // Annotations (`<flow>/annotations.json`)
 // ---------------------------------------------------------------------------
+/** A rectangle in screenshot pixels: finite position, finite non-negative size. */
 export const BoundingBox = z
-    .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+    .object({
+    x: z.number().finite(),
+    y: z.number().finite(),
+    width: z.number().finite().nonnegative(),
+    height: z.number().finite().nonnegative(),
+})
     .strict();
+/** Most `obstacles` one annotation record may carry (the writer keeps the nearest this many). */
+export const MAX_OBSTACLES = 40;
 export const AnnotationRecord = z
     .object({
     step: z.string().min(1),
@@ -219,6 +227,16 @@ export const AnnotationRecord = z
     arrow_style: ArrowStyle.optional(),
     /** Optional pixel offset applied to the callout + arrow at render time — see {@link NudgeOffset}. */
     nudge: NudgeOffset.optional(),
+    /**
+     * Optional boxes of page content (text, controls), in screenshot pixels, that the burner keeps this
+     * annotation's callout from covering. The target itself is not listed. `docsxai run` writes it when
+     * the workspace sets `annotations.obstacles`; a pipeline that knows the page layout may add it by
+     * hand. At most {@link MAX_OBSTACLES} boxes. The engine measures them right after the screenshot, so
+     * on a page that animates continuously they can differ slightly from what the image shows. Absent or
+     * empty: the callout goes next to the target. The structural mirror in `packages/viewer/src/annotations.ts`
+     * carries the same field.
+     */
+    obstacles: z.array(BoundingBox).max(MAX_OBSTACLES).optional(),
     /** 1-based index of this annotation *within its step's screenshot* — set only when the step has > 1 annotation, so the viewer can render a numbered badge. Absent → render as a plain (un-numbered) halo. */
     index: z.number().int().positive().optional(),
 })

package/dist/doctor-checks.js

@@ -42,14 +42,14 @@ async function readTextIfExists(p) {
 // ---------------------------------------------------------------------------
 export function checkNode(nodeVersion) {
     const major = Number(nodeVersion.split(".")[0]);
-    if (Number.isFinite(major) && major >= 20) {
-        return { name: "node", ok: true, detail: `v${nodeVersion} (>= 20 required)` };
+    if (Number.isFinite(major) && major >= 26) {
+        return { name: "node", ok: true, detail: `v${nodeVersion} (>= 26 required)` };
     }
     return {
         name: "node",
         ok: false,
-        detail: `v${nodeVersion} — the engine requires Node >= 20`,
-        fix: "upgrade Node (https://nodejs.org); the engine's `engines` field pins >= 20",
+        detail: `v${nodeVersion} — the engine requires Node >= 26`,
+        fix: "upgrade Node (https://nodejs.org); the engine's `engines` field pins >= 26",
     };
 }
 export async function checkChromium(probe) {

package/dist/flow-file.d.ts

@@ -1,7 +1,7 @@
 import { FlowFile } from "./doc-pack.js";
 export declare class FlowFileError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 /** Parse + validate a flow-file from YAML text. Throws {@link FlowFileError} with a readable message on failure. */
 export declare function parseFlowFile(yamlText: string, source?: string): FlowFile;

package/dist/flow-runtime.d.ts

@@ -1,4 +1,5 @@
 import { type AnnotationsFile, type BoundingBox, type FlowFile, type RedactionRegion, type RedactionStyle, type Step } from "./doc-pack.js";
+import { type NearbyBoxes } from "./obstacles.js";
 /**
  * A redaction with its locator ref already resolved to a concrete selector. `selector` entries are
  * turned into bounding boxes by the driver at capture time (absent/zero-box selectors are skipped
@@ -39,6 +40,15 @@ export interface BrowserDriver {
     textOf(selector: string): Promise<string | null>;
     /** Bounding box of an element, in page pixels. Pass `timeoutMs` (default = driver default) so this fails fast when the target has vanished. Returns `null` on miss. */
     boundingBox(selector: string, timeoutMs?: number): Promise<BoundingBox | null>;
+    /**
+     * Boxes of the visible text and interactive elements within `radius` CSS px of `selector`, in
+     * the screenshot's pixel space (scaled by the device scale factor, like {@link boundingBox}).
+     * The target's own subtree and interactive elements containing it are left out. Order is the
+     * driver's; `selectObstacles` sorts, clips and caps. Returns `null` when the target isn't visible
+     * within `timeoutMs`; rejects if the scan itself runs past `timeoutMs`. The scan happens after the
+     * screenshot, so a continuously animating page can drift from the image. Only called when a workspace turns on `annotations.obstacles`.
+     */
+    nearbyBoxes(selector: string, radius: number, timeoutMs?: number): Promise<NearbyBoxes | null>;
     /** Capture a clean screenshot (no baked annotations), applying any `redactions` before it hits disk. */
     screenshot(relPath: string, redactions?: ResolvedRedaction[]): Promise<void>;
     /**
@@ -62,8 +72,8 @@ export interface BrowserDriver {
 export type ActionableState = "actionable" | "not-found" | "multiple-matches" | "detached" | "not-visible" | "off-screen" | "covered" | "disabled";
 export declare class FlowExecutionError extends Error {
     readonly stepId: string;
-    readonly cause?: unknown | undefined;
-    constructor(message: string, stepId: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, stepId: string, cause?: unknown);
 }
 /**
  * Best-effort 1-line cause extracted from a Playwright actionability log (or similar driver
@@ -89,6 +99,12 @@ export interface RunFlowOptions {
      * the caller is responsible for preserving the previous run's artifacts for them.
      */
     startFrom?: string;
+    /**
+     * Record the visible text and controls around each annotation's target as `obstacles` on its
+     * record (screenshot pixels, target excluded) so the burner keeps callouts off them. Default
+     * false: records are then exactly what they were before the field existed.
+     */
+    obstacles?: boolean;
 }
 export interface ExecutedStep {
     id: string;

package/dist/flow-runtime.js

@@ -8,6 +8,7 @@
 // The runtime is written against a thin {@link BrowserDriver} abstraction so it's testable
 // without a real browser; the Playwright-backed driver lives in a separate module.
 import { locatorRefName } from "./flow-file.js";
+import { OBSTACLE_RADIUS, selectObstacles } from "./obstacles.js";
 // ---------------------------------------------------------------------------
 // Errors
 // ---------------------------------------------------------------------------
@@ -72,6 +73,17 @@ export function resolveTarget(value, flow, resolver) {
     }
     return resolved;
 }
+/** Obstacles around `selector`, best-effort like the halo box: a failed scan leaves the field off. */
+async function obstaclesAround(driver, selector, target, stepId) {
+    try {
+        const scan = await driver.nearbyBoxes(selector, OBSTACLE_RADIUS, 2000);
+        return scan ? selectObstacles(scan, target) : [];
+    }
+    catch (e) {
+        process.stderr.write(`runFlow: step "${stepId}" — obstacle scan skipped (${e.message})\n`);
+        return [];
+    }
+}
 async function applyWait(driver, wait, resolve) {
     if (typeof wait === "string") {
         if (wait === "network_idle")
@@ -246,10 +258,14 @@ export async function runFlow(flow, driver, opts = {}) {
                     const ann = anns[i];
                     const annSelector = ann.target ? resolve(ann.target) : selector;
                     const bbox = annSelector ? await driver.boundingBox(annSelector, 2000) : null;
+                    const obstacles = opts.obstacles && annSelector && bbox
+                        ? await obstaclesAround(driver, annSelector, bbox, step.id)
+                        : [];
                     annotations.push({
                         step: step.id,
                         selector: annSelector ?? "",
                         ...(bbox ? { bounding_box: bbox } : {}),
+                        ...(obstacles.length > 0 ? { obstacles } : {}),
                         copy: ann.copy,
                         ...(ann.arrow ? { arrow_style: ann.arrow } : {}),
                         ...(ann.nudge ? { nudge: ann.nudge } : {}),

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./doc-pack.js";
 export * from "./doc-pack-io.js";
 export * from "./flow-file.js";
 export * from "./flow-runtime.js";
+export * from "./obstacles.js";
 export * from "./flow-lint.js";
 export * from "./flow-tree.js";
 export * from "./auth.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./doc-pack.js";
 export * from "./doc-pack-io.js";
 export * from "./flow-file.js";
 export * from "./flow-runtime.js";
+export * from "./obstacles.js";
 export * from "./flow-lint.js";
 export * from "./flow-tree.js";
 export * from "./auth.js";

package/dist/obstacles.d.ts

@@ -0,0 +1,33 @@
+import { type BoundingBox } from "./doc-pack.js";
+/** How far from the target (CSS px) page content still counts as an obstacle. */
+export declare const OBSTACLE_RADIUS = 320;
+/** The most obstacles one annotation records; the ones nearest the target win. */
+export declare const OBSTACLE_LIMIT = 40;
+/** What a driver reports about the content around a target. Every box is in screenshot pixels. */
+export interface NearbyBoxes {
+    /** Screenshot size (viewport × device scale factor). */
+    image: {
+        width: number;
+        height: number;
+    };
+    /** Device scale factor: screenshot pixels per CSS pixel. */
+    scale: number;
+    /** Boxes of visible text and interactive elements, the target and its subtree already left out. */
+    boxes: BoundingBox[];
+}
+export interface SelectOptions {
+    /** Distance cut-off in CSS px. Default {@link OBSTACLE_RADIUS}. */
+    radius?: number;
+    /** Cap on the number of boxes. Default {@link OBSTACLE_LIMIT}. */
+    limit?: number;
+}
+/**
+ * Pick the obstacles for one annotation. `target` is the annotation's own box (screenshot px).
+ *
+ * Boxes are rounded outward to whole pixels, clipped to the image, and dropped when empty, when
+ * farther than the radius from the target, when they sit entirely inside the target, or when
+ * another kept box already covers them (a label inside a button). Duplicates collapse to one. If
+ * more than the limit remain, the nearest to the target are kept. The result is sorted by y, x,
+ * width, height.
+ */
+export declare function selectObstacles(scan: NearbyBoxes, target: BoundingBox, options?: SelectOptions): BoundingBox[];

package/dist/obstacles.js

@@ -0,0 +1,72 @@
+// Obstacle selection — the pure half of `annotations.obstacles`.
+//
+// A driver reports the boxes of visible text and controls near an annotation's target
+// ({@link NearbyBoxes}). This module turns that raw scan into the `obstacles` array written on an
+// annotation record: boxes in screenshot pixels that a burned callout must not cover. No IO, no
+// browser: same scan in, same boxes out, so the doc pack stays byte-identical across runs.
+import { MAX_OBSTACLES } from "./doc-pack.js";
+/** How far from the target (CSS px) page content still counts as an obstacle. */
+export const OBSTACLE_RADIUS = 320;
+/** The most obstacles one annotation records; the ones nearest the target win. */
+export const OBSTACLE_LIMIT = MAX_OBSTACLES;
+const EPSILON = 1e-6;
+const edges = (b) => ({
+    left: b.x,
+    top: b.y,
+    right: b.x + b.width,
+    bottom: b.y + b.height,
+});
+/** Integer box that contains `b`, clipped to the image; `null` when nothing of it is left. */
+function clipOutward(b, image) {
+    const e = edges(b);
+    const left = Math.max(0, Math.floor(e.left + EPSILON));
+    const top = Math.max(0, Math.floor(e.top + EPSILON));
+    const right = Math.min(image.width, Math.ceil(e.right - EPSILON));
+    const bottom = Math.min(image.height, Math.ceil(e.bottom - EPSILON));
+    if (right <= left || bottom <= top)
+        return null;
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/** Straight-line gap between two boxes; 0 when they touch or overlap. */
+function gap(a, b) {
+    const ea = edges(a);
+    const eb = edges(b);
+    const dx = Math.max(0, ea.left - eb.right, eb.left - ea.right);
+    const dy = Math.max(0, ea.top - eb.bottom, eb.top - ea.bottom);
+    return Math.hypot(dx, dy);
+}
+/** True when `inner` lies entirely inside `outer` (equal boxes count). */
+function contains(outer, inner) {
+    const o = edges(outer);
+    const i = edges(inner);
+    return o.left <= i.left && o.top <= i.top && o.right >= i.right && o.bottom >= i.bottom;
+}
+const byPosition = (a, b) => a.y - b.y || a.x - b.x || a.width - b.width || a.height - b.height;
+/**
+ * Pick the obstacles for one annotation. `target` is the annotation's own box (screenshot px).
+ *
+ * Boxes are rounded outward to whole pixels, clipped to the image, and dropped when empty, when
+ * farther than the radius from the target, when they sit entirely inside the target, or when
+ * another kept box already covers them (a label inside a button). Duplicates collapse to one. If
+ * more than the limit remain, the nearest to the target are kept. The result is sorted by y, x,
+ * width, height.
+ */
+export function selectObstacles(scan, target, options = {}) {
+    const radius = (options.radius ?? OBSTACLE_RADIUS) * scan.scale;
+    const limit = options.limit ?? OBSTACLE_LIMIT;
+    const unique = new Map();
+    for (const raw of scan.boxes) {
+        const box = clipOutward(raw, scan.image);
+        if (!box || contains(target, box) || gap(box, target) > radius)
+            continue;
+        unique.set(`${box.x},${box.y},${box.width},${box.height}`, box);
+    }
+    const candidates = [...unique.values()];
+    const exposed = candidates.filter((box) => !candidates.some((other) => other !== box && contains(other, box)));
+    return exposed
+        .map((box) => ({ box, distance: gap(box, target) }))
+        .sort((a, b) => a.distance - b.distance || byPosition(a.box, b.box))
+        .slice(0, limit)
+        .map(({ box }) => box)
+        .sort(byPosition);
+}

package/dist/page-nearby-boxes.d.ts

@@ -0,0 +1,9 @@
+import { type NearbyBoxes } from "./obstacles.js";
+/**
+ * Boxes of the visible text and interactive elements within `radius` CSS px of `targetArg`, in
+ * screenshot pixels. Text is measured per rendered line (the text itself, not its block), so a
+ * paragraph beside the target contributes the lines that are there. Left out: anything inside the
+ * target, interactive elements that contain it, hidden or fully clipped content, scripts and styles.
+ * The result is in document order; `selectObstacles` sorts, clips and caps it.
+ */
+export declare function collectNearbyBoxes(targetArg: unknown, radius: number): NearbyBoxes;

package/dist/page-nearby-boxes.js

@@ -0,0 +1,92 @@
+// In-page scan behind `BrowserDriver.nearbyBoxes`.
+//
+// `collectNearbyBoxes` runs inside the page (Playwright serializes it with `locator.evaluate`), so
+// it must stay self-contained: no imports of values, no references to module scope. It imports no
+// Playwright either; the driver is the only module that does. The DOM lib isn't in this package's
+// TypeScript config, so the few DOM shapes it touches are declared locally.
+/**
+ * Boxes of the visible text and interactive elements within `radius` CSS px of `targetArg`, in
+ * screenshot pixels. Text is measured per rendered line (the text itself, not its block), so a
+ * paragraph beside the target contributes the lines that are there. Left out: anything inside the
+ * target, interactive elements that contain it, hidden or fully clipped content, scripts and styles.
+ * The result is in document order; `selectObstacles` sorts, clips and caps it.
+ */
+export function collectNearbyBoxes(targetArg, radius) {
+    const target = targetArg;
+    const doc = target.ownerDocument;
+    const view = doc.defaultView;
+    const dpr = view.devicePixelRatio || 1;
+    const t = target.getBoundingClientRect();
+    const near = {
+        left: t.left - radius,
+        top: t.top - radius,
+        right: t.right + radius,
+        bottom: t.bottom + radius,
+    };
+    const boxes = [];
+    // Add `r` (viewport CSS px) when `owner` renders it: visible, not clipped away by an ancestor's
+    // overflow, and inside the viewport. `clipSelf` lets the owner's own overflow clip text it holds.
+    const add = (r, owner, clipSelf) => {
+        let { left, top, right, bottom } = r;
+        left = Math.max(left, 0);
+        top = Math.max(top, 0);
+        right = Math.min(right, view.innerWidth);
+        bottom = Math.min(bottom, view.innerHeight);
+        for (let cur = owner; cur; cur = cur.parentElement) {
+            const cs = view.getComputedStyle(cur);
+            if (cs.display === "none" || cs.opacity === "0")
+                return;
+            if (cur === owner && cs.visibility !== "visible")
+                return;
+            const clips = cs.overflow !== "visible" || cs.overflowX !== "visible" || cs.overflowY !== "visible";
+            if (clips && (cur !== owner || clipSelf)) {
+                const cr = cur.getBoundingClientRect();
+                left = Math.max(left, cr.left);
+                top = Math.max(top, cr.top);
+                right = Math.min(right, cr.right);
+                bottom = Math.min(bottom, cr.bottom);
+            }
+        }
+        if (right <= left || bottom <= top)
+            return;
+        if (right < near.left || left > near.right || bottom < near.top || top > near.bottom)
+            return;
+        boxes.push({
+            x: left * dpr,
+            y: top * dpr,
+            width: (right - left) * dpr,
+            height: (bottom - top) * dpr,
+        });
+    };
+    const controls = doc.querySelectorAll('a[href], button, input:not([type="hidden"]), select, textarea, summary, ' +
+        '[role="button"], [role="link"], [role="checkbox"], [role="radio"], [role="switch"], ' +
+        '[role="tab"], [role="menuitem"], [role="combobox"], [role="option"], ' +
+        '[contenteditable=""], [contenteditable="true"], [tabindex]:not([tabindex^="-"])');
+    for (let i = 0; i < controls.length; i++) {
+        const el = controls[i];
+        if (el === target || target.contains(el) || el.contains(target))
+            continue;
+        add(el.getBoundingClientRect(), el, false);
+    }
+    if (doc.body) {
+        const range = doc.createRange();
+        const walker = doc.createTreeWalker(doc.body, 4); // NodeFilter.SHOW_TEXT
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            const text = n;
+            const owner = text.parentElement;
+            if (!owner || !/\S/.test(text.nodeValue ?? "") || target.contains(n))
+                continue;
+            if (/^(SCRIPT|STYLE|NOSCRIPT|TEMPLATE)$/.test(owner.tagName))
+                continue;
+            range.selectNodeContents(n);
+            const lines = range.getClientRects();
+            for (let i = 0; i < lines.length; i++)
+                add(lines[i], owner, true);
+        }
+    }
+    return {
+        image: { width: Math.round(view.innerWidth * dpr), height: Math.round(view.innerHeight * dpr) },
+        scale: dpr,
+        boxes,
+    };
+}

package/dist/playwright-driver.d.ts

@@ -2,6 +2,7 @@ import { type Browser, type BrowserContext, type Page } from "playwright-core";
 import { type BoundingBox, type EnvironmentSpec, type ViewportSize } from "./doc-pack.js";
 import { type ActionableState, type BrowserDriver, type ResolvedRedaction } from "./flow-runtime.js";
 import { type StorageState } from "./auth.js";
+import { type NearbyBoxes } from "./obstacles.js";
 /**
  * The cached Chromium binary path, or `undefined` when `playwright-core` has none installed.
  *
@@ -93,6 +94,7 @@ export declare class PlaywrightDriver implements BrowserDriver {
     count(selector: string): Promise<number>;
     textOf(selector: string): Promise<string | null>;
     boundingBox(selector: string, timeoutMs?: number): Promise<BoundingBox | null>;
+    nearbyBoxes(selector: string, radius: number, timeoutMs?: number): Promise<NearbyBoxes | null>;
     screenshot(relPath: string, redactions?: ResolvedRedaction[]): Promise<void>;
     /**
      * Resolve redactions to pixel rects in the screenshot's device-pixel space: selector entries via

package/dist/playwright-driver.js

@@ -11,6 +11,7 @@ import { existsSync, promises as fs } from "node:fs";
 import * as path from "node:path";
 import { chromium, } from "playwright-core";
 import { VIEWPORT_PRESETS, } from "./doc-pack.js";
+import { collectNearbyBoxes } from "./page-nearby-boxes.js";
 import { applyRedactions } from "./redact.js";
 import { resolveWorkspacePathReal } from "./workspace.js";
 /**
@@ -103,6 +104,16 @@ export async function launchPlaywrightSession(opts = {}) {
         },
     };
 }
+/** Rejects with a timeout error if `work` takes longer than `ms` (no limit when `ms` is undefined). */
+function withTimeout(work, ms) {
+    if (ms === undefined)
+        return work;
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([work, timeout]).finally(() => clearTimeout(timer));
+}
 export class PlaywrightDriver {
     page;
     docPackRoot;
@@ -256,6 +267,20 @@ export class PlaywrightDriver {
         })
             .catch(() => null);
     }
+    async nearbyBoxes(selector, radius, timeoutMs) {
+        const loc = this.page.locator(selector).first();
+        try {
+            await loc.waitFor({
+                state: "visible",
+                ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}),
+            });
+        }
+        catch {
+            return null;
+        }
+        // `evaluate` has no timeout of its own; a hung page must not stall the run.
+        return withTimeout(loc.evaluate(collectNearbyBoxes, radius), timeoutMs);
+    }
     async screenshot(relPath, redactions = []) {
         // relPath segments carry flow names + step ids from the flow-file — containment-checked
         // (symlink-aware) against the doc-pack root before writing.

package/dist/plugins/manifest.d.ts

@@ -20,35 +20,35 @@ declare const manifestSchema: z.ZodObject<{
         plugin: z.ZodString;
         version: z.ZodString;
     }, "strict", z.ZodTypeAny, {
-        version: string;
         plugin: string;
-    }, {
         version: string;
+    }, {
         plugin: string;
+        version: string;
     }>, "many">>;
     trust: z.ZodDefault<z.ZodEnum<["kalebtec", "community", "local"]>>;
 }, "strict", z.ZodTypeAny, {
-    capabilities: string[];
     apiVersion: string;
     namespace: string;
     register: string;
-    kinds: ("publisher" | "renderer" | "lint-rules" | "auth-strategy")[];
+    kinds: ("auth-strategy" | "lint-rules" | "publisher" | "renderer")[];
+    capabilities: string[];
     dependsOn: {
-        version: string;
         plugin: string;
+        version: string;
     }[];
-    trust: "local" | "kalebtec" | "community";
+    trust: "community" | "kalebtec" | "local";
 }, {
     apiVersion: string;
     namespace: string;
     register: string;
-    kinds: ("publisher" | "renderer" | "lint-rules" | "auth-strategy")[];
+    kinds: ("auth-strategy" | "lint-rules" | "publisher" | "renderer")[];
     capabilities?: string[] | undefined;
     dependsOn?: {
-        version: string;
         plugin: string;
+        version: string;
     }[] | undefined;
-    trust?: "local" | "kalebtec" | "community" | undefined;
+    trust?: "community" | "kalebtec" | "local" | undefined;
 }>;
 export type PluginManifest = z.infer<typeof manifestSchema>;
 export declare class PluginManifestError extends Error {

package/dist/style.d.ts

@@ -1,7 +1,7 @@
 import { StyleArtifact } from "./doc-pack.js";
 export declare class StyleError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 /** The seed style every workspace starts with — overwritable by the agent during calibration. */
 export declare const DEFAULT_STYLE: StyleArtifact;

package/dist/workspace.d.ts

@@ -22,6 +22,14 @@ export interface WorkspaceConfig {
     ignore_https_errors?: boolean;
     /** Backend stub/service URL for `push`/`pull` (e.g. `http://localhost:4477`). Optional — workspaces operate fully locally without it. */
     backend_url?: string;
+    /** How `run` records annotations. Absent keys keep today's output. */
+    annotations?: {
+        /**
+         * Write per-annotation `obstacles` (boxes of nearby text and controls, screenshot pixels, the
+         * target excluded) so the burner keeps callouts off page content. Default false.
+         */
+        obstacles?: boolean;
+    };
     /** Backend workspace ID, set by `push` after first round-trip. */
     backend_workspace_id?: string;
     /** Backend project ID, set by `push` after first round-trip. */

package/dist/zip.d.ts

@@ -11,7 +11,7 @@ export interface ZipResult {
     entries: string[];
 }
 export declare class ZipError extends Error {
-    readonly cause?: unknown | undefined;
-    constructor(message: string, cause?: unknown | undefined);
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
 }
 export declare function zipDocPack(opts: ZipOptions): Promise<ZipResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsxai/engine",
-  "version": "0.2.0",
+  "version": "0.2.1-rc.1",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -41,20 +41,20 @@
   },
   "dependencies": {
     "fflate": "^0.8.3",
-    "playwright-core": "^1.61.0",
+    "playwright-core": "^1.63.0",
     "pngjs": "^7.0.0",
-    "yaml": "^2.5.0",
+    "yaml": "^2.9.1",
     "zod": "^3.23.0"
   },
   "devDependencies": {
-    "@types/node": "^20.14.0",
+    "@types/node": "^20.19.43",
     "@types/pngjs": "^6.0.5",
     "vitest": "^2.0.0",
-    "@docsxai/backend": "0.2.0"
+    "@docsxai/backend": "0.2.1-rc.1"
   },
   "author": "Kalebtec <security@kalebtec.com>",
   "engines": {
-    "node": ">=20"
+    "node": ">=26"
   },
   "scripts": {
     "build": "node ../../scripts/clean-dist.mjs && tsc -b tsconfig.build.json",