@ingcreators/annot-mcp 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # @ingcreators/annot-mcp
 
+## 0.3.0
+
+### Minor Changes
+
+- 806badc: Retire the `@ingcreators/annot-imagequant` (GPL-3.0) dynamic-import
+  boundary that gated PNG-8 output in the headless annotator and the
+  MCP server. `Annotator.toEncoded()`'s smart mode now routes PNG-8
+  through the pure-TS Median Cut + Floyd–Steinberg dither at
+  `@ingcreators/annot-core/encode/quantize-median-cut` directly.
+
+  ### Removed public API
+  - `isImagequantAvailable()` is no longer exported from
+    `@ingcreators/annot-annotator`. PNG-8 is now unconditionally
+    available — callers that previously gated `format: "smart"` on
+    this can drop the check.
+  - `Annotator.toEncoded()` no longer emits
+    `EncodeResult.reason === "imagequant-missing"`. The
+    graceful-PNG-32-fallback path that produced this reason is
+    unreachable.
+
+  ### Removed dependency
+  - `@ingcreators/annot-imagequant` is dropped from
+    `@ingcreators/annot-annotator`'s `dependencies`. Consumers
+    that previously installed it as a side-effect of installing
+    `annot-annotator` will save the WASM payload from their
+    `node_modules`. `annot-mcp` inherits the removal transitively.
+
+  Phase 3 of `docs/plans/replace-libimagequant-with-median-cut.md`.
+  Phase 4 deletes the `@ingcreators/annot-imagequant` workspace
+  package and deprecates the published 0.1.0 on npm.
+
+### Patch Changes
+
+- Updated dependencies [806badc]
+- Updated dependencies [df1a429]
+- Updated dependencies [2e92c97]
+- Updated dependencies [657a685]
+  - @ingcreators/annot-annotator@0.5.0
+  - @ingcreators/annot-product-docs@0.2.0
+
+## 0.2.0
+
+### Minor Changes
+
+- b3e8e53: Both packages now accept an optional `encode` option that flows through to `@ingcreators/annot-annotator@0.3.0`'s `toEncoded()` / `decodeAndEncodeImage()` pipeline. Achieves feature parity with the Chrome extension's "Save size" + "Format smart" capture settings for AI-agent (`annot-mcp`) and Playwright-test (`annot-playwright`) flows.
+
+  ## `annot-playwright`
+
+  ```ts
+  await annotator.annotateScreenshot(page, {
+    annotations: [...],
+    encode: { format: "smart", saveSizePreset: "standard" },
+  });
+  ```
+
+  Returned bytes shrink to PNG-8 / JPEG / resized PNG-32 per the smart heuristic; default behaviour when `encode` is omitted matches v0.2.x (raw PNG-32 from the annotator).
+
+  ## `annot-mcp`
+
+  All five tools (`annot_annotate_screenshot`, `annot_annotate_url`, `annot_redact_screenshot`, `annot_redact_url`, `annot_compare_screenshots`) accept the same `encode` shape on their MCP `inputSchema`. Agents can specify any subset:
+
+  ```jsonc
+  {
+    "url": "https://...",
+    "annotations": [...],
+    "encode": {
+      "format": "smart",
+      "saveSizePreset": "light",
+      "smartFallback": "jpeg"
+    }
+  }
+  ```
+
+  `format`: `"smart"` (default — PNG-8 for UI / PNG / JPEG for photos) / `"png"` / `"jpeg"`.
+  `saveSizePreset`: `"light"` 1280px / `"standard"` 1920px / `"highQuality"` 2560px / `"original"` no resize.
+  `smartFallback`, `smartColorThreshold`, `jpegPercent` all configurable.
+
+  Output `mimeType` flips to `image/jpeg` when the chosen path emits JPEG, so MCP clients render inline correctly. The text confirmation when `output` is set now includes the chosen format and any `reason` (`png-8` / `photo-fallback-jpeg` / `imagequant-missing` / …) for observability.
+
+  Backwards-compatible: when `encode` is omitted, all tools emit PNG-32 bytes verbatim (no decode/encode round-trip, same as v0.1.x / v0.2.x).
+
+### Patch Changes
+
+- Updated dependencies [86d0853]
+  - @ingcreators/annot-annotator@0.3.0
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -129,6 +129,43 @@ highlighted as `warning`-intent rects.
   content block listing the changed-region bboxes.
 - `output` (optional).
 
+### `annot_aria_snapshot`
+
+Open a URL and return Playwright's AI-mode aria-snapshot
+(YAML format with `[ref=eN]` markers). The same primitive
+`playwright-mcp` and `playwright-cli` use. Foundational
+input for the product-docs workflow (see
+[`docs/plans/_done/living-product-docs.md`](../../docs/plans/_done/living-product-docs.md)).
+
+**Inputs:**
+- `url` — page URL to snapshot.
+- `viewport` (optional) — `{ width, height, deviceScaleFactor }`.
+- `waitFor` (optional) — `"load"` / `"domcontentloaded"` /
+  `"networkidle"`. Default `"load"`.
+- `rootSelector` (optional, default `"body"`) — locator
+  selector whose subtree is snapshotted. Narrow to e.g.
+  `"main"` or `'[data-testid="login-form"]'` when only part
+  of the page is relevant.
+- `timeout` (optional) — forwarded to
+  `locator.ariaSnapshot({ timeout })`. Default 30 s.
+- `output` (optional, absolute path) — when set, the YAML is
+  written here and the tool returns a text confirmation;
+  otherwise the YAML is returned inline.
+
+**Important:** refs (`eN`) are session-local. They identify
+elements within THIS snapshot only. Do NOT persist refs
+across sessions or runs. Persistent identifiers should use
+`role + name` (with tree-path disambiguation for duplicates).
+
+**Example output:**
+
+```yaml
+- textbox "Email" [ref=e3]
+- textbox "Password" [ref=e5]
+- checkbox "Remember me" [ref=e7]
+- button "Sign in" [ref=e9]
+```
+
 ## The annotation DSL
 
 Two flavours. `BboxAnnotation` (used by `_screenshot` tools)
@@ -285,6 +322,7 @@ is the composable primitive.
 | `src/tools/redact-screenshot.ts` | `annot_redact_screenshot` |
 | `src/tools/redact-url.ts` | `annot_redact_url` |
 | `src/tools/compare-screenshots.ts` | `annot_compare_screenshots` |
+| `src/tools/aria-snapshot.ts` | `annot_aria_snapshot` |
 
 ## Runtime dependencies
 

package/dist/browser/aria-snapshot.d.ts

@@ -0,0 +1,37 @@
+import { BrowserPool } from './pool.js';
+export interface AriaSnapshotOptions {
+    url: string;
+    viewport?: {
+        width: number;
+        height: number;
+        deviceScaleFactor?: number;
+    };
+    waitFor?: "load" | "domcontentloaded" | "networkidle";
+    /**
+     * Selector for the locator whose subtree is snapshotted.
+     * Defaults to `"body"` (whole page).
+     */
+    rootSelector?: string;
+    /**
+     * Pass-through to Playwright's `ariaSnapshot({ timeout })`.
+     * Defaults to Playwright's own default (30 s).
+     */
+    timeout?: number;
+}
+export interface AriaSnapshotResult {
+    /**
+     * YAML-formatted accessibility tree. When `mode: "ai"` is used
+     * (which `captureAriaSnapshot` always does), each interactive
+     * element carries a `[ref=eN]` marker.
+     */
+    yaml: string;
+}
+/**
+ * Acquire a browser, open a context + page, navigate to the URL,
+ * take an AI-mode aria-snapshot of the root locator's subtree,
+ * and close everything.
+ *
+ * On any error after browser acquisition, the page + context are
+ * closed and the browser is released before the error propagates.
+ */
+export declare function captureAriaSnapshot(pool: BrowserPool, options: AriaSnapshotOptions): Promise<AriaSnapshotResult>;

package/dist/dsl/schema.d.ts

@@ -270,6 +270,38 @@ export declare const LOCATOR_ANNOTATION_SCHEMA: {
         };
     })[];
 };
+export declare const ENCODE_OPTIONS_SCHEMA: {
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        format: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        saveSizePreset: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        smartFallback: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        smartColorThreshold: {
+            type: string;
+            minimum: number;
+            description: string;
+        };
+        jpegPercent: {
+            type: string;
+            minimum: number;
+            maximum: number;
+            description: string;
+        };
+    };
+};
 export declare const LOCATOR_REDACT_REGION_SCHEMA: {
     type: string;
     additionalProperties: boolean;