libretto 0.5.0 → 0.5.1

package/dist/shared/instrumentation/instrument.js

@@ -25,6 +25,7 @@ const LOCATOR_ACTIONS = [
 ];
 const NAV_ACTIONS = ["goto", "reload", "goBack", "goForward"];
 const POINTER_ACTIONS = /* @__PURE__ */ new Set(["click", "dblclick", "hover"]);
+const instrumentedTargets = /* @__PURE__ */ new WeakSet();
 const pageQueues = /* @__PURE__ */ new WeakMap();
 function enqueue(page, fn) {
   const prev = pageQueues.get(page) ?? Promise.resolve();
@@ -96,11 +97,93 @@ function wrapLocatorActions(locator, page, opts) {
     };
   }
 }
+const LOCATOR_FACTORY_METHODS = [
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "filter",
+  "and",
+  "or",
+  "first",
+  "last",
+  "nth"
+];
+const FRAME_LOCATOR_FACTORY_METHODS = [
+  "locator",
+  "getByRole",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "getByTestId",
+  "owner",
+  "first",
+  "last",
+  "nth"
+];
+function instrumentLocator(locator, page, opts) {
+  const target = locator;
+  if (instrumentedTargets.has(target)) {
+    return locator;
+  }
+  instrumentedTargets.add(target);
+  wrapLocatorActions(locator, page, opts);
+  for (const method of LOCATOR_FACTORY_METHODS) {
+    if (typeof locator[method] !== "function") continue;
+    const orig = locator[method].bind(locator);
+    locator[method] = (...args) => {
+      const nextLocator = orig(...args);
+      return instrumentLocator(nextLocator, page, opts);
+    };
+  }
+  if (typeof locator.contentFrame === "function") {
+    const origContentFrame = locator.contentFrame.bind(locator);
+    locator.contentFrame = (...args) => {
+      const frameLocator = origContentFrame(...args);
+      return instrumentFrameLocator(frameLocator, page, opts);
+    };
+  }
+  return locator;
+}
+function instrumentFrameLocator(frameLocator, page, opts) {
+  const target = frameLocator;
+  if (instrumentedTargets.has(target)) {
+    return frameLocator;
+  }
+  instrumentedTargets.add(target);
+  for (const method of FRAME_LOCATOR_FACTORY_METHODS) {
+    if (typeof frameLocator[method] !== "function") continue;
+    const orig = frameLocator[method].bind(frameLocator);
+    frameLocator[method] = (...args) => {
+      const result = orig(...args);
+      if (method === "first" || method === "last" || method === "nth") {
+        return instrumentFrameLocator(result, page, opts);
+      }
+      return instrumentLocator(result, page, opts);
+    };
+  }
+  if (typeof frameLocator.frameLocator === "function") {
+    const origFrameLocator = frameLocator.frameLocator.bind(
+      frameLocator
+    );
+    frameLocator.frameLocator = (...args) => {
+      const nestedFrameLocator = origFrameLocator(...args);
+      return instrumentFrameLocator(nestedFrameLocator, page, opts);
+    };
+  }
+  return frameLocator;
+}
 function isTimeoutError(err) {
   if (!err || typeof err.message !== "string") return false;
   return err.message.includes("Timeout") || err.message.includes("timeout") || err.name === "TimeoutError";
 }
-const LOCATOR_FACTORIES = [
+const PAGE_LOCATOR_FACTORIES = [
   "locator",
   "getByRole",
   "getByText",
@@ -110,6 +193,7 @@ const LOCATOR_FACTORIES = [
   "getByTitle",
   "getByTestId"
 ];
+const PAGE_FRAME_LOCATOR_FACTORIES = ["frameLocator"];
 async function installInstrumentation(page, options) {
   if (page.__librettoInstrumented) return;
   page.__librettoInstrumented = true;
@@ -129,7 +213,12 @@ async function installInstrumentation(page, options) {
           try {
             const loc = page.locator(args[0]);
             const box = await loc.boundingBox();
-            await visualizeBeforeAction(page, box, method, highlightBeforeActionMs);
+            await visualizeBeforeAction(
+              page,
+              box,
+              method,
+              highlightBeforeActionMs
+            );
           } catch {
           }
         });
@@ -161,13 +250,20 @@ async function installInstrumentation(page, options) {
       return orig(...args);
     };
   }
-  for (const factory of LOCATOR_FACTORIES) {
+  for (const factory of PAGE_LOCATOR_FACTORIES) {
     if (typeof page[factory] !== "function") continue;
     const origFactory = page[factory].bind(page);
     page[factory] = (...factoryArgs) => {
       const locator = origFactory(...factoryArgs);
-      wrapLocatorActions(locator, page, mergedOpts);
-      return locator;
+      return instrumentLocator(locator, page, mergedOpts);
+    };
+  }
+  for (const factory of PAGE_FRAME_LOCATOR_FACTORIES) {
+    if (typeof page[factory] !== "function") continue;
+    const origFactory = page[factory].bind(page);
+    page[factory] = (...factoryArgs) => {
+      const frameLocator = origFactory(...factoryArgs);
+      return instrumentFrameLocator(frameLocator, page, mergedOpts);
     };
   }
 }

package/dist/shared/llm/ai-sdk-adapter.js

@@ -18,7 +18,9 @@ function createLLMClientFromModel(model) {
         if (msg.role === "assistant") {
           return {
             role: "assistant",
-            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+            content: msg.content.filter(
+              (part) => part.type === "text"
+            ).map((part) => ({ type: "text", text: part.text }))
           };
         }
         return {

package/dist/shared/llm/client.js

@@ -121,7 +121,9 @@ function convertUserContentParts(parts) {
   });
 }
 function convertAssistantContentParts(parts) {
-  return parts.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }));
+  return parts.filter(
+    (part) => part.type === "text"
+  ).map((part) => ({ type: "text", text: part.text }));
 }
 function convertMessages(messages) {
   return messages.map((msg) => {

package/dist/shared/logger/index.js

@@ -1,4 +1,7 @@
-import { Logger, defaultLogger } from "./logger.js";
+import {
+  Logger,
+  defaultLogger
+} from "./logger.js";
 import {
   createFileLogSink,
   prettyConsoleSink,

package/dist/shared/run/api.js

@@ -1,4 +1,6 @@
-import { launchBrowser } from "./browser.js";
+import {
+  launchBrowser
+} from "./browser.js";
 export {
   launchBrowser
 };

package/dist/shared/run/browser.js

@@ -1,8 +1,13 @@
-import { chromium } from "playwright";
+import {
+  chromium
+} from "playwright";
 import { createServer } from "node:net";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { ensureLibrettoSessionStatePath } from "../paths/paths.js";
-import { SESSION_STATE_VERSION, SessionStateFileSchema } from "../state/session-state.js";
+import {
+  SESSION_STATE_VERSION,
+  SessionStateFileSchema
+} from "../state/session-state.js";
 async function pickFreePort() {
   return await new Promise((resolve, reject) => {
     const server = createServer();

package/dist/shared/state/session-state.d.ts

@@ -15,7 +15,8 @@ declare const SessionViewportSchema: z.ZodObject<{
 declare const SessionStateFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     port: z.ZodNumber;
-    pid: z.ZodNumber;
+    pid: z.ZodOptional<z.ZodNumber>;
+    cdpEndpoint: z.ZodOptional<z.ZodString>;
     session: z.ZodString;
     startedAt: z.ZodString;
     status: z.ZodOptional<z.ZodEnum<{

package/dist/shared/state/session-state.js

@@ -14,7 +14,8 @@ const SessionViewportSchema = z.object({
 const SessionStateFileSchema = z.object({
   version: z.literal(SESSION_STATE_VERSION),
   port: z.number().int().min(0).max(65535),
-  pid: z.number().int(),
+  pid: z.number().int().optional(),
+  cdpEndpoint: z.string().url().optional(),
   session: z.string().min(1),
   startedAt: z.string().datetime({ offset: true }),
   status: SessionStatusSchema.optional(),
@@ -29,7 +30,9 @@ function formatIssues(error) {
 function parseSessionStateData(rawState, source) {
   const parsed = SessionStateFileSchema.safeParse(rawState);
   if (!parsed.success) {
-    throw new Error(`Session state at ${source} is invalid: ${formatIssues(parsed.error)}`);
+    throw new Error(
+      `Session state at ${source} is invalid: ${formatIssues(parsed.error)}`
+    );
   }
   const { version: _version, ...state } = parsed.data;
   return state;

package/dist/shared/visualization/ghost-cursor.js

@@ -64,7 +64,13 @@ async function moveGhostCursor(page, target) {
         el.style.transition = `transform ${duration}ms ${easing}`;
         el.style.transform = `translate3d(${x}px, ${y}px, 0)`;
       },
-      { id: CURSOR_ID, x: target.x, y: target.y, duration: durationMs, easing: opts.easing }
+      {
+        id: CURSOR_ID,
+        x: target.x,
+        y: target.y,
+        duration: durationMs,
+        easing: opts.easing
+      }
     );
     await page.waitForTimeout(durationMs);
   } catch {
@@ -122,15 +128,18 @@ async function hideGhostCursor(page) {
 }
 async function getGhostCursorPosition(page) {
   try {
-    return await page.evaluate(({ id }) => {
-      const el = document.getElementById(id);
-      if (!el) return null;
-      const match = el.style.transform.match(
-        /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
-      );
-      if (!match) return null;
-      return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
-    }, { id: CURSOR_ID });
+    return await page.evaluate(
+      ({ id }) => {
+        const el = document.getElementById(id);
+        if (!el) return null;
+        const match = el.style.transform.match(
+          /translate3d\(\s*([\d.-]+)px\s*,\s*([\d.-]+)px/
+        );
+        if (!match) return null;
+        return { x: parseFloat(match[1]), y: parseFloat(match[2]) };
+      },
+      { id: CURSOR_ID }
+    );
   } catch {
     return null;
   }

package/dist/shared/visualization/highlight.js

@@ -92,12 +92,15 @@ async function showHighlight(page, params) {
 }
 async function clearHighlights(page) {
   try {
-    await page.evaluate(({ layerId }) => {
-      const layer = document.getElementById(layerId);
-      if (!layer) return;
-      const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
-      rects.forEach((r) => r.remove());
-    }, { layerId: LAYER_ID });
+    await page.evaluate(
+      ({ layerId }) => {
+        const layer = document.getElementById(layerId);
+        if (!layer) return;
+        const rects = layer.querySelectorAll(".__libretto_highlight_rect__");
+        rects.forEach((r) => r.remove());
+      },
+      { layerId: LAYER_ID }
+    );
   } catch {
   }
 }

package/dist/shared/workflow/workflow.d.ts

@@ -2,8 +2,8 @@ import { Page } from 'playwright';
 import { MinimalLogger } from '../logger/logger.js';
 
 declare const LIBRETTO_WORKFLOW_BRAND: unique symbol;
-type LibrettoWorkflowMetadata = {};
 type LibrettoWorkflowContext<S = {}> = {
+    session: string;
     page: Page;
     logger: MinimalLogger;
     services: S;
@@ -11,11 +11,10 @@ type LibrettoWorkflowContext<S = {}> = {
 type LibrettoWorkflowHandler<Input = unknown, Output = unknown, S = {}> = (ctx: LibrettoWorkflowContext<S>, input: Input) => Promise<Output>;
 declare class LibrettoWorkflow<Input = unknown, Output = unknown, S = {}> {
     readonly [LIBRETTO_WORKFLOW_BRAND] = true;
-    readonly metadata: LibrettoWorkflowMetadata;
     private readonly handler;
-    constructor(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>);
+    constructor(handler: LibrettoWorkflowHandler<Input, Output, S>);
     run(ctx: LibrettoWorkflowContext<S>, input: Input): Promise<Output>;
 }
-declare function workflow<Input = unknown, Output = unknown, S = {}>(metadata: LibrettoWorkflowMetadata, handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
+declare function workflow<Input = unknown, Output = unknown, S = {}>(handler: LibrettoWorkflowHandler<Input, Output, S>): LibrettoWorkflow<Input, Output, S>;
 
-export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, type LibrettoWorkflowMetadata, workflow };
+export { LIBRETTO_WORKFLOW_BRAND, LibrettoWorkflow, type LibrettoWorkflowContext, type LibrettoWorkflowHandler, workflow };

package/dist/shared/workflow/workflow.js

@@ -1,18 +1,16 @@
 const LIBRETTO_WORKFLOW_BRAND = /* @__PURE__ */ Symbol.for("libretto.workflow");
 class LibrettoWorkflow {
   [LIBRETTO_WORKFLOW_BRAND] = true;
-  metadata;
   handler;
-  constructor(metadata, handler) {
-    this.metadata = metadata;
+  constructor(handler) {
     this.handler = handler;
   }
   async run(ctx, input) {
     return this.handler(ctx, input);
   }
 }
-function workflow(metadata, handler) {
-  return new LibrettoWorkflow(metadata, handler);
+function workflow(handler) {
+  return new LibrettoWorkflow(handler);
 }
 export {
   LIBRETTO_WORKFLOW_BRAND,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libretto",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "AI-powered browser automation library and CLI built on Playwright",
   "license": "MIT",
   "repository": {
@@ -31,6 +31,8 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
+    "sync-skills": "node scripts/sync-skills.mjs",
+    "check:skills": "node scripts/check-skills-sync.mjs",
     "build": "tsup --config tsup.config.ts",
     "type-check": "tsc --noEmit",
     "test": "pnpm run build && vitest run",
@@ -38,6 +40,7 @@
     "benchmark": "pnpm run build && tsx benchmarks/run.ts",
     "test:watch": "vitest",
     "cli": "node dist/index.js",
+    "prepare-release": "bash ./scripts/prepare-release.sh",
     "prepack": "pnpm run build"
   },
   "peerDependencies": {
@@ -61,12 +64,13 @@
     }
   },
   "devDependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@ai-sdk/anthropic": "^3.0.58",
     "@ai-sdk/google": "^3.0.51",
     "@ai-sdk/google-vertex": "^4.0.80",
     "@ai-sdk/openai": "^3.0.41",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.75",
     "@types/node": "^25.5.0",
+    "glimpseui": "^0.5.1",
     "openai": "^6.29.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",

package/scripts/check-skills-sync.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareSkillDirs, SKILL_DIRS } from "./skills-libretto.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, "..");
+const result = compareSkillDirs(repoRoot);
+
+if (result.ok) {
+  console.log(
+    `libretto: verified identical skill mirrors across ${SKILL_DIRS.join(", ")}`,
+  );
+  process.exit(0);
+}
+
+console.error("libretto: skill directories must be identical:");
+for (const issue of result.issues) {
+  console.error(`- ${issue}`);
+}
+console.error("");
+console.error("Run `pnpm i` to resync the mirrors in this repository.");
+process.exit(1);

package/scripts/compare-eval-summary.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+function usage() {
+  console.error(
+    "Usage: node scripts/compare-eval-summary.mjs <baseline-summary.json> <current-summary.json> [threshold-percent]",
+  );
+}
+
+const [, , baselineArg, currentArg, thresholdArg] = process.argv;
+
+if (!baselineArg || !currentArg) {
+  usage();
+  process.exit(1);
+}
+
+const baseline = JSON.parse(readFileSync(resolve(baselineArg), "utf8"));
+const current = JSON.parse(readFileSync(resolve(currentArg), "utf8"));
+const threshold = thresholdArg ? Number(thresholdArg) : 5;
+
+if (!Number.isFinite(threshold) || threshold < 0) {
+  console.error(`Invalid threshold percent: ${thresholdArg}`);
+  process.exit(1);
+}
+
+const delta = Number((current.percent - baseline.percent).toFixed(2));
+const withinThreshold = Math.abs(delta) <= threshold;
+
+const lines = [
+  "# Eval Baseline Comparison",
+  "",
+  `- Baseline score: \`${baseline.percent}%\``,
+  `- Current score: \`${current.percent}%\``,
+  `- Delta: \`${delta > 0 ? "+" : ""}${delta}%\``,
+  `- Allowed range: \`+/-${threshold}%\``,
+];
+
+process.stdout.write(`${lines.join("\n")}\n`);
+
+if (!withinThreshold) {
+  console.error(
+    `Eval score delta ${delta > 0 ? "+" : ""}${delta}% is outside the allowed +/-${threshold}% range.`,
+  );
+  process.exit(1);
+}

package/scripts/postinstall.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { SKILL_DIRS, syncSkillDir } from "./skills-libretto.mjs";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
 
@@ -29,22 +31,20 @@ const gitResult = spawnSync("git", ["rev-parse", "--show-toplevel"], {
   encoding: "utf-8",
   stdio: ["pipe", "pipe", "pipe"],
 });
-const repoRoot = gitResult.status === 0 && gitResult.stdout
-  ? gitResult.stdout.trim()
-  : installCwd;
+const repoRoot =
+  gitResult.status === 0 && gitResult.stdout
+    ? gitResult.stdout.trim()
+    : installCwd;
 
-// Sync skills to any agent dirs at repo root
 const sourceDir = join(packageRoot, "skills", "libretto");
 if (!existsSync(sourceDir)) process.exit(0);
 
-const agentDirNames = [".agents", ".claude"];
-for (const name of agentDirNames) {
-  const agentDir = join(repoRoot, name);
-  if (!existsSync(agentDir)) continue;
-  const dest = join(agentDir, "skills", "libretto");
-  if (existsSync(dest)) rmSync(dest, { recursive: true });
-  mkdirSync(dirname(dest), { recursive: true });
-  cpSync(sourceDir, dest, { recursive: true });
-  const count = readdirSync(dest).length;
-  console.log(`libretto: synced ${count} skill files to ${dest}`);
+const syncMissingDirs = repoRoot === packageRoot;
+for (const dir of SKILL_DIRS.slice(1)) {
+  const rootName = dir.split("/")[0];
+  const rootDir = join(repoRoot, rootName);
+  if (!syncMissingDirs && !existsSync(rootDir)) continue;
+  const dest = join(repoRoot, dir);
+  syncSkillDir(sourceDir, dest);
+  console.log(`libretto: synced skills/libretto -> ${dest}`);
 }

package/scripts/prepare-release.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/prepare-release.sh [patch|minor|major]
+
+Creates a release PR branch from main, bumps package.json, pushes the branch,
+and opens a pull request targeting main.
+EOF
+}
+
+bump="${1:-patch}"
+
+case "$bump" in
+  patch|minor|major)
+    ;;
+  -h|--help|help)
+    usage
+    exit 0
+    ;;
+  *)
+    echo "Invalid bump type: $bump" >&2
+    usage >&2
+    exit 1
+    ;;
+esac
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "gh CLI is required." >&2
+  exit 1
+fi
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Working tree must be clean before preparing a release." >&2
+  exit 1
+fi
+
+current_branch="$(git branch --show-current)"
+if [ "$current_branch" != "main" ]; then
+  echo "Switching from $current_branch to main."
+fi
+
+git fetch origin
+git checkout main
+git pull --ff-only origin main
+
+pnpm install --frozen-lockfile
+pnpm type-check
+pnpm test
+
+current_version="$(node -p "require('./package.json').version")"
+next_version="$(node -e '
+const [major, minor, patch] = process.argv[1].split(".").map(Number)
+const bump = process.argv[2]
+
+let next
+if (bump === "major") next = [major + 1, 0, 0]
+else if (bump === "minor") next = [major, minor + 1, 0]
+else next = [major, minor, patch + 1]
+
+process.stdout.write(next.join("."))
+' "$current_version" "$bump")"
+branch_name="tk-release-v${next_version}"
+
+if git show-ref --verify --quiet "refs/heads/${branch_name}"; then
+  echo "Local branch ${branch_name} already exists." >&2
+  exit 1
+fi
+
+if git ls-remote --exit-code --heads origin "${branch_name}" >/dev/null 2>&1; then
+  echo "Remote branch ${branch_name} already exists." >&2
+  exit 1
+fi
+
+npm version "$next_version" --no-git-tag-version >/dev/null
+
+git checkout -b "$branch_name"
+git add package.json
+git commit -m "release: v${next_version}"
+git push -u origin "$branch_name"
+
+gh pr create \
+  --base main \
+  --head "$branch_name" \
+  --title "release: v${next_version}" \
+  --body "$(cat <<EOF
+## Summary
+
+- release libretto v${next_version}
+
+## Verification
+
+- pnpm type-check
+- pnpm test
+EOF
+)"