libretto 0.5.0 → 0.5.2

package/dist/cli/commands/shared.js

@@ -1,26 +1,15 @@
 import { z } from "zod";
+import { createLoggerForSession } from "../core/context.js";
 import {
-  SESSION_DEFAULT,
+  generateSessionName,
   readSessionStateOrThrow,
   validateSessionName
 } from "../core/session.js";
 import {
   SimpleCLI
 } from "../framework/simple-cli.js";
-function createSessionSchema() {
-  return z.string().default(SESSION_DEFAULT).superRefine((value, ctx) => {
-    try {
-      validateSessionName(value);
-    } catch (err) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: err instanceof Error ? err.message : String(err)
-      });
-    }
-  });
-}
-function sessionOption(help = "Use a named session") {
-  return SimpleCLI.option(createSessionSchema(), { help });
+function sessionOption(help = "Session name") {
+  return SimpleCLI.option(z.string().optional(), { help });
 }
 function pageOption(help = "Target a specific page id") {
   return SimpleCLI.option(z.string().optional(), { help });
@@ -28,23 +17,35 @@ function pageOption(help = "Target a specific page id") {
 function integerOption(help) {
   return SimpleCLI.option(z.coerce.number().int().optional(), { help });
 }
-const resolveSessionMiddleware = async ({ input, ctx }) => {
-  return {
-    ...ctx,
-    session: input.session
+function withRequiredSession() {
+  return async ({ input, ctx }) => {
+    if (!input.session) {
+      throw new Error("Missing required option --session.");
+    }
+    validateSessionName(input.session);
+    const logger = createLoggerForSession(input.session);
+    return {
+      ...ctx,
+      session: input.session,
+      logger,
+      sessionState: readSessionStateOrThrow(input.session)
+    };
   };
-};
-const loadSessionStateMiddleware = async ({ ctx }) => {
-  return {
-    ...ctx,
-    sessionState: readSessionStateOrThrow(ctx.session)
+}
+function withAutoSession() {
+  return async ({ input, ctx }) => {
+    const session = input.session ?? generateSessionName();
+    if (input.session) {
+      validateSessionName(input.session);
+    }
+    const logger = createLoggerForSession(session);
+    return { ...ctx, session, logger };
   };
-};
+}
 export {
-  createSessionSchema,
   integerOption,
-  loadSessionStateMiddleware,
   pageOption,
-  resolveSessionMiddleware,
-  sessionOption
+  sessionOption,
+  withAutoSession,
+  withRequiredSession
 };

package/dist/cli/commands/snapshot.js

@@ -5,16 +5,10 @@ import { getSessionSnapshotRunDir } from "../core/context.js";
 import { condenseDom } from "../../shared/condense-dom/condense-dom.js";
 import { readSessionState } from "../core/session.js";
 import { SimpleCLI } from "../framework/simple-cli.js";
-import {
-  loadSessionStateMiddleware,
-  pageOption,
-  resolveSessionMiddleware,
-  sessionOption
-} from "./shared.js";
+import { pageOption, sessionOption, withRequiredSession } from "./shared.js";
 import { runApiInterpret } from "../core/api-snapshot-analyzer.js";
 import { readAiConfig } from "../core/ai-config.js";
 import { resolveSnapshotApiModelOrThrow } from "../core/snapshot-api-config.js";
-const DEFAULT_SNAPSHOT_CONTEXT = "No additional user context provided.";
 const FALLBACK_SNAPSHOT_VIEWPORT = { width: 1280, height: 800 };
 function generateSnapshotRunId() {
   return `snapshot-${Date.now()}`;
@@ -106,6 +100,12 @@ async function captureScreenshot(session, logger, pageId) {
     const pngPath = `${snapshotRunDir}/page.png`;
     const htmlPath = `${snapshotRunDir}/page.html`;
     const condensedHtmlPath = `${snapshotRunDir}/page.condensed.html`;
+    const RENDER_SETTLE_TIMEOUT_MS = 1e4;
+    await Promise.race([
+      page.waitForLoadState("networkidle").catch(() => {
+      }),
+      new Promise((resolve) => setTimeout(resolve, RENDER_SETTLE_TIMEOUT_MS))
+    ]);
     const restoreViewport = resolveSnapshotViewport(session, logger);
     const viewportMetrics = await readSnapshotViewportMetrics(page);
     logger.info("screenshot-viewport-metrics", {
@@ -185,17 +185,10 @@ async function captureScreenshot(session, logger, pageId) {
   }
 }
 async function runSnapshot(session, logger, pageId, objective, context) {
-  const normalizedObjective = objective?.trim();
-  const normalizedContext = context?.trim();
-  if (!normalizedObjective && normalizedContext) {
-    throw new Error(
-      "Couldn't run analysis: --objective is required when providing --context."
-    );
-  }
-  const configuredAi = normalizedObjective ? readAiConfig() : null;
-  if (normalizedObjective) {
-    resolveSnapshotApiModelOrThrow(configuredAi);
-  }
+  const normalizedObjective = objective.trim();
+  const normalizedContext = context.trim();
+  const configuredAi = readAiConfig();
+  resolveSnapshotApiModelOrThrow(configuredAi);
   const { pngPath, htmlPath, condensedHtmlPath } = await captureScreenshot(
     session,
     logger,
@@ -205,14 +198,10 @@ async function runSnapshot(session, logger, pageId, objective, context) {
   console.log(`  PNG:             ${pngPath}`);
   console.log(`  HTML:            ${htmlPath}`);
   console.log(`  Condensed HTML:  ${condensedHtmlPath}`);
-  if (!normalizedObjective) {
-    console.log("Use --objective flag to analyze snapshots.");
-    return;
-  }
   const interpretArgs = {
     objective: normalizedObjective,
     session,
-    context: normalizedContext ?? DEFAULT_SNAPSHOT_CONTEXT,
+    context: normalizedContext,
     pngPath,
     htmlPath,
     condensedHtmlPath
@@ -224,24 +213,22 @@ const snapshotInput = SimpleCLI.input({
   named: {
     session: sessionOption(),
     page: pageOption(),
-    objective: SimpleCLI.option(z.string().optional()),
-    context: SimpleCLI.option(z.string().optional())
+    objective: SimpleCLI.option(z.string()),
+    context: SimpleCLI.option(z.string())
   }
 });
-function createSnapshotCommand(logger) {
-  return SimpleCLI.command({
-    description: "Capture PNG + HTML; analyze when --objective is provided (--context optional)"
-  }).input(snapshotInput).use(resolveSessionMiddleware).use(loadSessionStateMiddleware).handle(async ({ input, ctx }) => {
-    await runSnapshot(
-      ctx.session,
-      logger,
-      input.page,
-      input.objective,
-      input.context
-    );
-  });
-}
+const snapshotCommand = SimpleCLI.command({
+  description: "Capture PNG + HTML and analyze with --objective and --context"
+}).input(snapshotInput).use(withRequiredSession()).handle(async ({ input, ctx }) => {
+  await runSnapshot(
+    ctx.session,
+    ctx.logger,
+    input.page,
+    input.objective,
+    input.context
+  );
+});
 export {
-  createSnapshotCommand,
+  snapshotCommand,
   snapshotInput
 };

package/dist/cli/core/ai-config.js

@@ -11,10 +11,15 @@ const ViewportConfigSchema = z.object({
   width: z.number().int().min(1),
   height: z.number().int().min(1)
 });
+const WindowPositionConfigSchema = z.object({
+  x: z.number().int(),
+  y: z.number().int()
+});
 const LibrettoConfigSchema = z.object({
   version: z.literal(CURRENT_CONFIG_VERSION),
   ai: AiConfigSchema.optional(),
-  viewport: ViewportConfigSchema.optional()
+  viewport: ViewportConfigSchema.optional(),
+  windowPosition: WindowPositionConfigSchema.optional()
 }).passthrough();
 const DEFAULT_MODELS = {
   openai: "openai/gpt-5.4",
@@ -26,7 +31,12 @@ const PROVIDER_ALIASES = {
   claude: DEFAULT_MODELS.anthropic,
   google: DEFAULT_MODELS.gemini
 };
-const CONFIGURE_PROVIDERS = ["openai", "anthropic", "gemini", "vertex"];
+const CONFIGURE_PROVIDERS = [
+  "openai",
+  "anthropic",
+  "gemini",
+  "vertex"
+];
 function formatConfigureProviders(separator = " | ") {
   return CONFIGURE_PROVIDERS.join(separator);
 }
@@ -44,6 +54,10 @@ function formatExpectedConfigExample() {
       viewport: {
         width: 1280,
         height: 800
+      },
+      windowPosition: {
+        x: 1600,
+        y: 120
       }
     },
     null,
@@ -59,7 +73,7 @@ ${detail}` : null,
       "Expected config example:",
       formatExpectedConfigExample(),
       "Notes:",
-      '  - "ai" and "viewport" are optional.',
+      '  - "ai", "viewport", and "windowPosition" are optional.',
       '  - "ai.model" must be a provider/model string like "openai/gpt-5.4" or "anthropic/claude-sonnet-4-6".',
       "Fix the file to match this shape, or delete it and rerun:",
       `  npx libretto ai configure ${formatConfigureProviders()}`
@@ -147,7 +161,9 @@ function runAiConfigure(input, options = {}) {
       console.log(
         `No AI config set. Choose a default model: ${configureCommandName} ${formatConfigureProviders()}`
       );
-      console.log("Provider credentials still come from your shell or .env file.");
+      console.log(
+        "Provider credentials still come from your shell or .env file."
+      );
       return;
     }
     printAiConfig(config2, configPath);
@@ -182,6 +198,7 @@ export {
   CURRENT_CONFIG_VERSION,
   LibrettoConfigSchema,
   ViewportConfigSchema,
+  WindowPositionConfigSchema,
   clearAiConfig,
   readAiConfig,
   readLibrettoConfig,

package/dist/cli/core/api-snapshot-analyzer.js

@@ -1,16 +1,13 @@
 import { readFileSync } from "node:fs";
 import { createLLMClient } from "../../shared/llm/client.js";
 import {
-  formatInterpretationOutput,
   InterpretResultSchema,
   buildInlinePromptSelection,
   getMimeType,
   readFileAsBase64
 } from "./snapshot-analyzer.js";
 import { readAiConfig } from "./ai-config.js";
-import {
-  resolveSnapshotApiModelOrThrow
-} from "./snapshot-api-config.js";
+import { resolveSnapshotApiModelOrThrow } from "./snapshot-api-config.js";
 async function runApiInterpret(args, logger, configuredAi = readAiConfig()) {
   const selection = resolveSnapshotApiModelOrThrow(configuredAi);
   logger.info("api-interpret-start", {
@@ -67,7 +64,20 @@ async function runApiInterpret(args, logger, configuredAi = readAiConfig()) {
     selectorCount: parsed.selectors.length,
     answer: parsed.answer.slice(0, 200)
   });
-  console.log(formatInterpretationOutput(parsed, "Interpretation (via API):"));
+  console.log("");
+  console.log("Analysis:");
+  console.log(parsed.answer);
+  if (parsed.selectors.length > 0) {
+    console.log("");
+    console.log("Selectors:");
+    parsed.selectors.forEach((selector, index) => {
+      console.log(`  ${index + 1}. ${selector.label}: ${selector.selector}`);
+    });
+  }
+  if (parsed.notes?.trim()) {
+    console.log("");
+    console.log(`Notes: ${parsed.notes.trim()}`);
+  }
 }
 export {
   runApiInterpret