autokap 1.0.6 → 1.0.7

package/dist/capture-llm-page-identity.js

@@ -0,0 +1,116 @@
+import { inferCapturePageIdentity } from "./capture-page-identity.js";
+/**
+ * Use a cheap LLM call to classify all pages in a capture run.
+ * Falls back to regex heuristics if the LLM call fails.
+ */
+export async function inferPageIdentitiesWithLLM(pageRuns, model, apiKey, providerPrefs) {
+    // Regex fallback for all pages
+    const regexFallback = Object.fromEntries(pageRuns.map((pr) => [pr.pageId ?? "main", inferCapturePageIdentity(pr)]));
+    if (pageRuns.length === 0) {
+        return { identities: regexFallback, usage: null };
+    }
+    const pagesDescription = pageRuns.map((pr, i) => {
+        const pageId = pr.pageId ?? "main";
+        return `${i + 1}. pageId="${pageId}" | url="${pr.url}" | prompt="${pr.prompt}"`;
+    }).join("\n");
+    const systemPrompt = `You classify web page capture targets for a screenshot automation tool.
+
+IMPORTANT: The "pageId" is a user-defined identifier — it is NOT a technical description. Do NOT infer the page type from the pageId name alone. A page named "preset_creation_modal" might actually be a sidebar panel, not a DOM dialog. Base your classification on the PROMPT text and URL, not the pageId.
+
+For each page, determine:
+- "kind": one of "gallery", "modal_selection", "modal_configuration", "editor_route", "detail_route", "unknown"
+  - "gallery": a grid/list overview of screenshots, captures, or presets
+  - "modal_selection": the prompt explicitly describes opening a dialog/modal/popup to pick or select something
+  - "modal_configuration": the prompt explicitly describes opening a dialog/modal/popup to configure/edit something
+  - "editor_route": a dedicated full-page editor (e.g., /presets/abc-123/edit)
+  - "detail_route": a dedicated detail page that is NOT a modal
+  - "unknown": none of the above
+- "dialogTarget": true ONLY if the prompt explicitly says to open an actual DOM dialog, modal, or popup overlay. Set to FALSE for: sidebar panels, drawers, slide-over panels, full pages, dropdown menus, popovers, or any UI that is part of the main page layout. When in doubt, set to false.
+- "dedicatedRoute": true if the capture target has its own URL route (not just a modal on top of another page)
+
+Respond with a JSON array of objects: [{ "pageId": "...", "kind": "...", "dialogTarget": true/false, "dedicatedRoute": true/false }]
+Output ONLY valid JSON, nothing else.`;
+    try {
+        const providerBody = { provider: { ...providerPrefs?.[model], zdr: true } };
+        const res = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+                "HTTP-Referer": "https://autokap.app",
+                "X-Title": "Screenshot Agent",
+            },
+            body: JSON.stringify({
+                model,
+                max_tokens: 512,
+                stream: false,
+                response_format: { type: "json_object" },
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: `Classify these ${pageRuns.length} page capture targets:\n\n${pagesDescription}` },
+                ],
+                ...providerBody,
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+            console.warn(`[llm-page-identity] LLM call failed: HTTP ${res.status}`);
+            return { identities: regexFallback, usage: null };
+        }
+        const json = await res.json();
+        const content = json.choices?.[0]?.message?.content?.trim();
+        const usage = {
+            stepNumber: 0,
+            stepType: "page_identity_classification",
+            generationId: json.id ?? null,
+            modelRequested: model,
+            modelUsed: json.model ?? null,
+            promptTokens: json.usage?.prompt_tokens ?? null,
+            completionTokens: json.usage?.completion_tokens ?? null,
+            totalTokens: json.usage?.total_tokens ?? null,
+            imagesInPrompt: 0,
+        };
+        if (!content)
+            return { identities: regexFallback, usage };
+        // Parse — handle both array and { pages: [...] } wrapper
+        let classifications;
+        const parsed = JSON.parse(content);
+        if (Array.isArray(parsed)) {
+            classifications = parsed;
+        }
+        else if (Array.isArray(parsed.pages)) {
+            classifications = parsed.pages;
+        }
+        else if (Array.isArray(parsed.classifications)) {
+            classifications = parsed.classifications;
+        }
+        else {
+            console.warn("[llm-page-identity] Unexpected LLM response shape:", content.slice(0, 200));
+            return { identities: regexFallback, usage };
+        }
+        // Merge LLM results with regex fallback (LLM wins, regex fills gaps)
+        const result = { ...regexFallback };
+        for (const cls of classifications) {
+            const pageId = cls.pageId;
+            if (!pageId || !result[pageId])
+                continue;
+            const validKinds = [
+                "gallery", "modal_selection", "modal_configuration", "editor_route", "detail_route", "unknown",
+            ];
+            const kind = validKinds.includes(cls.kind) ? cls.kind : result[pageId].kind;
+            result[pageId] = {
+                ...result[pageId],
+                kind,
+                dialogTarget: typeof cls.dialogTarget === "boolean" ? cls.dialogTarget : result[pageId].dialogTarget,
+                dedicatedRoute: typeof cls.dedicatedRoute === "boolean" ? cls.dedicatedRoute : result[pageId].dedicatedRoute,
+                summary: `${kind}:${result[pageId].subjectTokens.slice(0, 4).join(",")}@llm`,
+            };
+        }
+        return { identities: result, usage };
+    }
+    catch (err) {
+        console.warn(`[llm-page-identity] LLM classification failed, using regex fallback:`, err instanceof Error ? err.message : err);
+        return { identities: regexFallback, usage: null };
+    }
+}
+//# sourceMappingURL=capture-llm-page-identity.js.map

package/dist/capture-model-resolution.d.ts

@@ -0,0 +1,9 @@
+export declare function resolveRunModels(params: {
+    requestModel?: string | null;
+    defaultModel?: string | null;
+    fallbackModel?: string | null;
+    presetId?: string | null;
+}): {
+    model: string;
+    fallbackModel?: string;
+};

package/dist/capture-model-resolution.js

@@ -0,0 +1,21 @@
+function normalizeModelId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+export function resolveRunModels(params) {
+    const requestModel = normalizeModelId(params.requestModel);
+    const defaultModel = normalizeModelId(params.defaultModel);
+    const fallbackModel = normalizeModelId(params.fallbackModel);
+    const preferAdminModel = Boolean(params.presetId && (defaultModel || fallbackModel));
+    const model = (preferAdminModel
+        ? defaultModel ?? fallbackModel ?? requestModel
+        : requestModel ?? defaultModel ?? fallbackModel)
+        ?? '';
+    return {
+        model,
+        fallbackModel: fallbackModel && fallbackModel !== model ? fallbackModel : undefined,
+    };
+}
+//# sourceMappingURL=capture-model-resolution.js.map

package/dist/capture-page-identity.d.ts

@@ -0,0 +1,9 @@
+import type { CapturePageIdentity } from "./types.js";
+import type { ScreenshotPageRunInput } from "./capture-run-optimizer.js";
+export declare function inferCapturePageIdentity(pageRun: ScreenshotPageRunInput): CapturePageIdentity;
+export interface VariantPageDefinitionIssue {
+    pageId: string;
+    duplicateOfPageId: string;
+    reason: string;
+}
+export declare function findVariantPageDefinitionIssues(pageRuns: ScreenshotPageRunInput[]): VariantPageDefinitionIssue[];

package/dist/capture-page-identity.js

@@ -0,0 +1,219 @@
+const TOKEN_STOP_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "that",
+    "this",
+    "your",
+    "into",
+    "onto",
+    "page",
+    "pages",
+    "state",
+    "screen",
+    "capture",
+    "captures",
+    "screenshot",
+    "screenshots",
+    "open",
+    "opened",
+    "currently",
+    "current",
+    "already",
+    "visible",
+    "show",
+    "showing",
+    "display",
+    "displayed",
+    "view",
+    "interface",
+    "workflow",
+    "project",
+    "projects",
+    "user",
+    "step",
+    "steps",
+    "then",
+    "after",
+    "before",
+    "dans",
+    "pour",
+    "avec",
+    "page",
+    "pages",
+    "etat",
+    "état",
+    "capture",
+    "captures",
+    "ecran",
+    "écran",
+    "ouverte",
+    "ouvert",
+    "affiche",
+    "affiché",
+    "affichee",
+    "affichée",
+    "courante",
+    "actuelle",
+    "deja",
+    "déjà",
+    "interface",
+    "etape",
+    "étape",
+]);
+const GALLERY_RE = /\b(gallery|screenshots|captures|overview|dashboard|list|galerie)\b/i;
+const MODAL_RE = /\b(modal|dialog|popup|drawer|overlay)\b/i;
+const TEMPLATE_RE = /\b(template|templates|picker|selection|select|choose|search templates|start from scratch|new preset|nouveau preset)\b/i;
+const CONFIGURATION_RE = /\b(edit|editor|editing|config|configuration|configure|settings|details|detail|instructions|textarea|form|modifier|modification|modifier|edition)\b/i;
+const STRONG_ROUTE_PROMPT_RE = /\b(route|dedicated page|full page|editor page|edit page|preset editor|preset edit page|page d[‘’]edition du preset|page de preset)\b/i;
+const PASSIVE_STATE_RE = /\b(currently open|already open|currently displayed|already displayed|without launching|ne la lance pas|sans la lancer|deja ouverte|ouverte actuellement)\b/i;
+const DISTINCT_TRANSITION_RE = /\b(save|saved|submitted|created|results|preview|confirmation|pricing|homepage|hero|scratch|blank|empty|different|another|autre|resultat|apercu|confirmation|vide)\b/i;
+function uniqueInOrder(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+function tokenize(value) {
+    return value
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .split(/[^a-z0-9]+/g)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 3 && !TOKEN_STOP_WORDS.has(part));
+}
+function normalizeUrlPath(rawUrl) {
+    try {
+        return new URL(rawUrl).pathname.toLowerCase();
+    }
+    catch {
+        return rawUrl.toLowerCase();
+    }
+}
+function summarizeIdentity(kind, tokens, urlPath) {
+    const tokenSummary = tokens.slice(0, 4).join(",");
+    const pathSummary = urlPath.replace(/\/+/g, "/").slice(0, 80) || "/";
+    return `${kind}:${tokenSummary || "none"}@${pathSummary}`;
+}
+function normalizeForMatching(value) {
+    return value
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase();
+}
+export function inferCapturePageIdentity(pageRun) {
+    const rawPrompt = pageRun.prompt.trim();
+    const prompt = normalizeForMatching(rawPrompt);
+    const pageId = pageRun.pageId ?? "main";
+    const urlPath = normalizeUrlPath(pageRun.url);
+    const context = normalizeForMatching(`${pageId} ${rawPrompt} ${urlPath}`);
+    // For dialog/modal detection, only use the prompt and URL — page IDs are user-defined
+    // identifiers that often contain "modal" or "dialog" as naming convention, not as DOM intent.
+    const promptAndUrl = normalizeForMatching(`${rawPrompt} ${urlPath}`);
+    const hasPresetRoute = /\/projects\/[^/]+\/presets\/[^/?#]+/i.test(pageRun.url) || /\/presets\/[^/?#]+/i.test(pageRun.url);
+    const mentionsGallery = GALLERY_RE.test(context);
+    const mentionsModal = MODAL_RE.test(promptAndUrl);
+    const mentionsTemplate = TEMPLATE_RE.test(promptAndUrl);
+    const mentionsConfiguration = CONFIGURATION_RE.test(context);
+    const passiveState = PASSIVE_STATE_RE.test(prompt);
+    const mentionsDedicatedRoute = hasPresetRoute || (STRONG_ROUTE_PROMPT_RE.test(prompt) && !passiveState);
+    let kind = "unknown";
+    if (mentionsGallery && !mentionsConfiguration && !mentionsModal && !mentionsTemplate) {
+        kind = "gallery";
+    }
+    else if (mentionsConfiguration && mentionsDedicatedRoute && !mentionsModal) {
+        kind = "editor_route";
+    }
+    else if (mentionsConfiguration && (mentionsModal || mentionsTemplate || passiveState)) {
+        kind = "modal_configuration";
+    }
+    else if (mentionsModal || mentionsTemplate) {
+        kind = "modal_selection";
+    }
+    else if (mentionsConfiguration) {
+        kind = "detail_route";
+    }
+    else if (mentionsGallery) {
+        kind = "gallery";
+    }
+    const subjectTokens = uniqueInOrder([
+        ...tokenize(pageId),
+        ...tokenize(prompt),
+        ...tokenize(urlPath),
+    ]).slice(0, 10);
+    return {
+        kind,
+        summary: summarizeIdentity(kind, subjectTokens, urlPath),
+        subjectTokens,
+        dialogTarget: kind === "modal_selection" || kind === "modal_configuration",
+        dedicatedRoute: kind === "editor_route" || (kind === "detail_route" && hasPresetRoute),
+    };
+}
+function countTokenOverlap(left, right) {
+    if (left.length === 0 || right.length === 0)
+        return 0;
+    const rightSet = new Set(right);
+    return left.filter((token) => rightSet.has(token)).length;
+}
+function urlsPointToSameState(leftUrl, rightUrl) {
+    try {
+        const left = new URL(leftUrl);
+        const right = new URL(rightUrl);
+        return left.origin === right.origin && left.pathname === right.pathname;
+    }
+    catch {
+        return leftUrl === rightUrl;
+    }
+}
+function promptDeclaresDistinctTransition(prompt) {
+    return DISTINCT_TRANSITION_RE.test(normalizeForMatching(prompt));
+}
+export function findVariantPageDefinitionIssues(pageRuns) {
+    const issues = [];
+    for (let index = 1; index < pageRuns.length; index += 1) {
+        const previous = pageRuns[index - 1];
+        const current = pageRuns[index];
+        const previousIdentity = inferCapturePageIdentity(previous);
+        const currentIdentity = inferCapturePageIdentity(current);
+        const sameUrl = urlsPointToSameState(previous.url, current.url);
+        const overlap = countTokenOverlap(previousIdentity.subjectTokens, currentIdentity.subjectTokens);
+        const sameKind = previousIdentity.kind === currentIdentity.kind;
+        const passiveState = PASSIVE_STATE_RE.test(normalizeForMatching(current.prompt));
+        const lacksDistinctTransition = !promptDeclaresDistinctTransition(current.prompt);
+        if (sameUrl
+            && sameKind
+            && previousIdentity.kind !== "unknown"
+            && currentIdentity.kind !== "unknown"
+            && (overlap >= 2 || passiveState)
+            && lacksDistinctTransition) {
+            issues.push({
+                pageId: current.pageId ?? "main",
+                duplicateOfPageId: previous.pageId ?? "main",
+                reason: `Named capture "${current.pageId ?? "main"}" is ambiguous with "${previous.pageId ?? "main"}": both target the same ${currentIdentity.kind.replace(/_/g, " ")} state at ${current.url}. ` +
+                    "Rewrite one prompt to describe a materially different state, or add a URL override for the later page.",
+            });
+            continue;
+        }
+        if (currentIdentity.dedicatedRoute
+            && previousIdentity.dialogTarget
+            && sameUrl
+            && !promptDeclaresDistinctTransition(current.prompt)) {
+            issues.push({
+                pageId: current.pageId ?? "main",
+                duplicateOfPageId: previous.pageId ?? "main",
+                reason: `Named capture "${current.pageId ?? "main"}" expects a dedicated editor/detail route, but it reuses the same URL/state as "${previous.pageId ?? "main"}" without any explicit navigation step. ` +
+                    "Add a distinct URL override or rewrite the prompt so the target route is unambiguous.",
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=capture-page-identity.js.map

package/dist/capture-preset-credentials.d.ts

@@ -0,0 +1,12 @@
+import { type EncryptedEnvelope } from './capture-encryption.js';
+export interface StoredPresetCredentials {
+    loginUrl?: string;
+    email?: string;
+    password?: string;
+}
+export declare function normalizePresetCredentials(credentials?: Partial<StoredPresetCredentials> | null): StoredPresetCredentials | undefined;
+export declare function hasStoredCredentials(raw: unknown): boolean;
+export declare function encryptPresetCredentials(credentials: StoredPresetCredentials): EncryptedEnvelope;
+export declare function decryptPresetCredentials(value: unknown): StoredPresetCredentials | undefined;
+export declare function preparePresetConfigForStorage<T extends Record<string, unknown>>(config: T): T;
+export declare function hydratePresetConfigFromStorage<T extends Record<string, unknown>>(raw: unknown): T;

package/dist/capture-preset-credentials.js

@@ -0,0 +1,57 @@
+import { decrypt, encrypt, isEncryptedEnvelope } from './capture-encryption.js';
+function getSecret() {
+    const secret = process.env.PRESET_CREDENTIALS_ENCRYPTION_SECRET;
+    if (!secret) {
+        throw new Error('Missing PRESET_CREDENTIALS_ENCRYPTION_SECRET for preset credential encryption');
+    }
+    return secret;
+}
+export function normalizePresetCredentials(credentials) {
+    if (!credentials)
+        return undefined;
+    const loginUrl = credentials.loginUrl?.trim() || undefined;
+    const email = credentials.email?.trim() || undefined;
+    const password = credentials.password || undefined;
+    if (!loginUrl && !email && !password)
+        return undefined;
+    return {
+        ...(loginUrl ? { loginUrl } : {}),
+        ...(email ? { email } : {}),
+        ...(password ? { password } : {}),
+    };
+}
+export function hasStoredCredentials(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    return raw.credentials != null;
+}
+export function encryptPresetCredentials(credentials) {
+    return encrypt(JSON.stringify(credentials), getSecret());
+}
+export function decryptPresetCredentials(value) {
+    if (!value)
+        return undefined;
+    if (isEncryptedEnvelope(value)) {
+        const decrypted = decrypt(value, getSecret());
+        return normalizePresetCredentials(JSON.parse(decrypted));
+    }
+    return normalizePresetCredentials(value);
+}
+export function preparePresetConfigForStorage(config) {
+    const credentials = normalizePresetCredentials(config.credentials);
+    return {
+        ...config,
+        ...(credentials
+            ? { credentials: encryptPresetCredentials(credentials) }
+            : { credentials: undefined }),
+    };
+}
+export function hydratePresetConfigFromStorage(raw) {
+    const config = (raw && typeof raw === 'object' ? raw : {});
+    const credentials = decryptPresetCredentials(config.credentials);
+    return {
+        ...config,
+        ...(credentials ? { credentials } : { credentials: undefined }),
+    };
+}
+//# sourceMappingURL=capture-preset-credentials.js.map

package/dist/capture-request-plan.d.ts

@@ -0,0 +1,58 @@
+import { type ScreenshotPageRunInput, type ScreenshotVariantExecution } from "./capture-run-optimizer.js";
+import { findVariantPageDefinitionIssues } from "./capture-page-identity.js";
+export type CaptureTheme = "light" | "dark";
+export interface CaptureViewport {
+    width: number;
+    height: number;
+}
+export interface CaptureTargetLike {
+    id: string;
+    label: string;
+    viewport: CaptureViewport;
+    deviceFrame?: string;
+    mockupOptions?: {
+        orientation?: "portrait" | "landscape" | string;
+    } | null;
+}
+export interface CapturePageDefinitionLike {
+    id?: string | null;
+    prompt?: string | null;
+    url?: string | null;
+}
+export interface CaptureRequestPlanInput<TTarget extends CaptureTargetLike = CaptureTargetLike, TElement = unknown> {
+    url: string;
+    prompt?: string | null;
+    targets?: TTarget[] | null;
+    viewports?: CaptureViewport[] | null;
+    deviceFrame?: string | null;
+    mockupOptions?: TTarget["mockupOptions"];
+    outputScale?: number | null;
+    langs?: string[] | null;
+    themes?: Array<CaptureTheme> | null;
+    elements?: TElement[] | null;
+    pages?: CapturePageDefinitionLike[] | null;
+}
+export interface CaptureRequestPlan<TTarget extends CaptureTargetLike = CaptureTargetLike, TElement = unknown> {
+    targets: TTarget[];
+    outputScale: number;
+    langs: string[];
+    themes: Array<CaptureTheme>;
+    elements: TElement[];
+    pageRuns: ScreenshotPageRunInput[];
+    variantPlan: ScreenshotVariantExecution[];
+    pageDefinitionIssues: ReturnType<typeof findVariantPageDefinitionIssues>;
+    requestedCaptureCount: number;
+    totalCaptures: number;
+}
+export declare function hasNonEmptyCapturePrompt(prompt: string | null | undefined): boolean;
+export declare function getCapturePromptValidationError(input: Pick<CaptureRequestPlanInput, "url" | "prompt" | "pages">): string | null;
+export declare function normalizeOutputScale(scale?: number | null): number;
+export declare function resolveCaptureLangs(raw: unknown): string[];
+export declare function resolveCaptureThemes(raw: unknown): Array<CaptureTheme>;
+export declare function buildCapturePageRuns(input: Pick<CaptureRequestPlanInput, "url" | "prompt" | "pages">): ScreenshotPageRunInput[];
+export declare function normalizeCaptureTargets<TTarget extends CaptureTargetLike = CaptureTargetLike>(input: Pick<CaptureRequestPlanInput<TTarget>, "targets" | "viewports" | "deviceFrame" | "mockupOptions">): Promise<TTarget[]>;
+export declare function sanitizeStorageSegment(value: string | null | undefined): string;
+export declare function getCaptureUrlHostname(value: string | null | undefined): string;
+export declare function normalizeComparableUrl(value: string | null | undefined): string;
+export declare function urlsPointToSameCaptureState(left: string | null | undefined, right: string | null | undefined): boolean;
+export declare function resolveCaptureRequestPlan<TTarget extends CaptureTargetLike = CaptureTargetLike, TElement = unknown>(input: CaptureRequestPlanInput<TTarget, TElement>): Promise<CaptureRequestPlan<TTarget, TElement>>;