autokap 1.0.5 → 1.0.7

package/dist/capture-request-plan.js

@@ -0,0 +1,216 @@
+import { resolveDeviceFrameDescriptor, } from "./mockup.js";
+import { buildScreenshotVariantPlan, } from "./capture-run-optimizer.js";
+import { findVariantPageDefinitionIssues } from "./capture-page-identity.js";
+function normalizeViewportDimension(value) {
+    if (!Number.isFinite(value))
+        return 1;
+    return Math.max(1, Math.round(value));
+}
+function getRequestedOrientation(target) {
+    const orientation = target.mockupOptions?.orientation;
+    return orientation === "portrait" || orientation === "landscape"
+        ? orientation
+        : undefined;
+}
+async function resolveDeviceViewport(deviceId, orientation) {
+    const descriptor = await resolveDeviceFrameDescriptor(deviceId, {
+        orientation,
+    });
+    if (!descriptor)
+        return null;
+    return {
+        label: descriptor.name,
+        viewport: {
+            width: normalizeViewportDimension(descriptor.screen.logicalWidth
+                - (descriptor.safeArea.left ?? 0)
+                - (descriptor.safeArea.right ?? 0)),
+            height: normalizeViewportDimension(descriptor.screen.logicalHeight
+                - descriptor.safeArea.top
+                - descriptor.safeArea.bottom),
+        },
+    };
+}
+export function hasNonEmptyCapturePrompt(prompt) {
+    return typeof prompt === "string" && prompt.trim().length > 0;
+}
+export function getCapturePromptValidationError(input) {
+    const hasLegacyPrompt = hasNonEmptyCapturePrompt(input.prompt);
+    const hasNamedPages = Array.isArray(input.pages) && input.pages.length > 0;
+    const hasInvalidNamedPage = hasNamedPages
+        && input.pages.some((page) => !hasNonEmptyCapturePrompt(page.prompt));
+    if (!input.url || (!hasLegacyPrompt && !hasNamedPages)) {
+        return "url and either a prompt or named capture pages are required";
+    }
+    if (hasInvalidNamedPage) {
+        return "each named capture page requires a prompt";
+    }
+    return null;
+}
+export function normalizeOutputScale(scale) {
+    if (!Number.isFinite(scale))
+        return 2;
+    return Math.max(0.5, Math.min(4, Number(scale)));
+}
+export function resolveCaptureLangs(raw) {
+    const langs = Array.isArray(raw)
+        ? raw.filter((value) => typeof value === "string" && value.trim().length > 0)
+        : [];
+    return langs.length > 0 ? langs : ["en"];
+}
+export function resolveCaptureThemes(raw) {
+    const themes = Array.isArray(raw)
+        ? raw.filter((value) => value === "light" || value === "dark")
+        : [];
+    return themes.length > 0 ? themes : ["light"];
+}
+export function buildCapturePageRuns(input) {
+    const pages = input.pages ?? [];
+    if (pages.length === 0) {
+        return [
+            {
+                url: input.url,
+                prompt: String(input.prompt ?? "").trim(),
+                pageId: null,
+            },
+        ];
+    }
+    return pages.map((page) => ({
+        url: page.url
+            ? page.url.startsWith("http")
+                ? page.url
+                : new URL(page.url, input.url).href
+            : input.url,
+        prompt: String(page.prompt ?? "").trim(),
+        pageId: page.id ?? null,
+    }));
+}
+export async function normalizeCaptureTargets(input) {
+    let targets;
+    if (input.targets?.length) {
+        targets = input.targets.map((target) => ({
+            ...target,
+            viewport: { ...target.viewport },
+        }));
+    }
+    else if (input.deviceFrame) {
+        const resolved = await resolveDeviceViewport(input.deviceFrame, getRequestedOrientation({ mockupOptions: input.mockupOptions }));
+        targets = [
+            {
+                id: input.deviceFrame,
+                label: resolved?.label ?? input.deviceFrame,
+                viewport: resolved?.viewport ?? { width: 1440, height: 900 },
+                deviceFrame: input.deviceFrame,
+                mockupOptions: input.mockupOptions ?? null,
+            },
+        ];
+    }
+    else if (input.viewports?.length) {
+        targets = input.viewports.map((viewport) => ({
+            id: `custom-${viewport.width}x${viewport.height}`,
+            label: `${viewport.width}×${viewport.height}`,
+            viewport: { ...viewport },
+        }));
+    }
+    else {
+        targets = [
+            {
+                id: "desktop-1440x900",
+                label: "1440×900",
+                viewport: { width: 1440, height: 900 },
+            },
+        ];
+    }
+    const deviceViewportCache = new Map();
+    const resolvedTargets = await Promise.all(targets.map(async (target) => {
+        if (!target.deviceFrame)
+            return target;
+        const orientation = getRequestedOrientation(target);
+        const cacheKey = `${target.deviceFrame}:${orientation ?? "default"}`;
+        let pending = deviceViewportCache.get(cacheKey);
+        if (!pending) {
+            pending = resolveDeviceViewport(target.deviceFrame, orientation);
+            deviceViewportCache.set(cacheKey, pending);
+        }
+        const resolved = await pending;
+        if (!resolved)
+            return target;
+        return {
+            ...target,
+            viewport: resolved.viewport,
+        };
+    }));
+    return resolvedTargets;
+}
+export function sanitizeStorageSegment(value) {
+    const normalized = (value ?? "main")
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return normalized || "main";
+}
+export function getCaptureUrlHostname(value) {
+    if (!value)
+        return "unknown";
+    try {
+        return new URL(value).hostname;
+    }
+    catch {
+        return value;
+    }
+}
+export function normalizeComparableUrl(value) {
+    if (!value)
+        return "";
+    try {
+        const url = new URL(value);
+        url.hash = "";
+        if ((url.protocol === "https:" && url.port === "443")
+            || (url.protocol === "http:" && url.port === "80")) {
+            url.port = "";
+        }
+        const normalizedPath = url.pathname.replace(/\/+$/, "") || "/";
+        const queryEntries = [...url.searchParams.entries()].sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey === rightKey
+            ? leftValue.localeCompare(rightValue)
+            : leftKey.localeCompare(rightKey));
+        url.search = "";
+        for (const [key, queryValue] of queryEntries) {
+            url.searchParams.append(key, queryValue);
+        }
+        return `${url.origin}${normalizedPath}${url.search}`;
+    }
+    catch {
+        return value;
+    }
+}
+export function urlsPointToSameCaptureState(left, right) {
+    return normalizeComparableUrl(left) === normalizeComparableUrl(right);
+}
+export async function resolveCaptureRequestPlan(input) {
+    const targets = await normalizeCaptureTargets(input);
+    const outputScale = normalizeOutputScale(input.outputScale);
+    const langs = resolveCaptureLangs(input.langs);
+    const themes = resolveCaptureThemes(input.themes);
+    const elements = input.elements ?? [];
+    const pageRuns = buildCapturePageRuns(input);
+    const variantPlan = buildScreenshotVariantPlan({
+        langs,
+        themes,
+        pages: pageRuns,
+    });
+    const pageDefinitionIssues = findVariantPageDefinitionIssues(pageRuns);
+    const requestedCaptureCount = pageRuns.length * targets.length * langs.length * themes.length
+        + elements.length * langs.length * themes.length;
+    return {
+        targets,
+        outputScale,
+        langs,
+        themes,
+        elements,
+        pageRuns,
+        variantPlan,
+        pageDefinitionIssues,
+        requestedCaptureCount,
+        totalCaptures: requestedCaptureCount,
+    };
+}
+//# sourceMappingURL=capture-request-plan.js.map

package/dist/capture-run-optimizer.d.ts

@@ -0,0 +1,139 @@
+import type { CaptureCheckpoint, CapturePageIdentity, InteractiveElement, IsolatedElement, ValidatedSessionProfile } from "./types.js";
+export interface ScreenshotPageRunInput {
+    url: string;
+    prompt: string;
+    pageId: string | null;
+}
+export interface ScreenshotVariantExecution {
+    key: string;
+    lang: string;
+    theme: "light" | "dark";
+    pages: ScreenshotPageRunInput[];
+}
+export interface DeterministicNavigationCandidate {
+    description: string;
+    selectors: string[];
+}
+export interface SelectorMemoryScopeContext {
+    pageId?: string | null;
+    pageIdentity?: CapturePageIdentity | null;
+    pageUrl?: string | null;
+}
+export declare function getUrlOrigin(value: string | null | undefined): string | null;
+export declare function urlMatchesCaptureTarget(currentUrl: string | null | undefined, targetUrl: string): boolean;
+export declare function urlsShareOrigin(left: string | null | undefined, right: string | null | undefined): boolean;
+export declare function resolveCaptureResumeUrl(params: {
+    pageIndex: number;
+    currentUrl?: string | null;
+    cursorResumeUrl?: string | null;
+    checkpoints: Array<Pick<CaptureCheckpoint, "pageId" | "resumeUrl" | "url" | "canonicalUrl">>;
+    pageId: string | null;
+    pageUrl: string;
+    sessionProfile?: ValidatedSessionProfile;
+}): string;
+export declare function shouldNormalizeDialogsBeforeTargetReuse(params: {
+    currentDialogCount: number | null | undefined;
+    pageIdentity?: Pick<CapturePageIdentity, "dialogTarget"> | null;
+}): boolean;
+export declare function buildScreenshotVariantPlan(params: {
+    langs: string[];
+    themes: Array<"light" | "dark">;
+    pages: ScreenshotPageRunInput[];
+}): ScreenshotVariantExecution[];
+export interface ResolvedIsolatedElementAssignment {
+    element: IsolatedElement;
+    pageId: string;
+    explicit: boolean;
+    score: number;
+}
+export declare function resolveIsolatedElementAssignments(params: {
+    elements: IsolatedElement[];
+    pageRuns: ScreenshotPageRunInput[];
+}): ResolvedIsolatedElementAssignment[];
+export declare function describeScreenshotVariantPlan(plan: ScreenshotVariantExecution[]): string;
+export declare function shouldReuseLivePageState(params: {
+    pageIndex: number;
+    presetRootUrl: string;
+    pageUrl: string;
+    currentUrl?: string | null;
+    isAuthenticated: boolean;
+}): boolean;
+export declare function shouldUseSequentialPageHandoff(params: {
+    pageIndex: number;
+    currentUrl?: string | null;
+    pageUrl: string;
+    previousPageId?: string | null;
+    pageId?: string | null;
+    previousPrompt?: string;
+    pagePrompt: string;
+}): boolean;
+export declare function buildSequentialHandoffArtifacts(actions: Array<{
+    action: string;
+    success: boolean;
+    stateChanged?: boolean;
+    params: Record<string, unknown>;
+}>): {
+    selectorHints: string[];
+    selectorMemory: Record<string, string[]>;
+};
+export declare function buildTargetNavigationArtifacts(params: {
+    selectorMemory?: Record<string, string[]>;
+    pageUrl: string;
+    pageId?: string | null;
+    prompt: string;
+}): {
+    navigationHints: string[];
+    selectorMemory: Record<string, string[]>;
+};
+export declare function buildDeterministicNavigationPlan(params: {
+    selectorMemory?: Record<string, string[]>;
+    pageUrl: string;
+    pageId?: string | null;
+    prompt: string;
+}): DeterministicNavigationCandidate[];
+export declare function buildVisibleControlNavigationPlan(params: {
+    interactiveElements?: InteractiveElement[];
+    pageId?: string | null;
+    prompt: string;
+}): DeterministicNavigationCandidate[];
+export declare function shouldAttemptSequentialReadyCheck(params: {
+    currentUrl?: string | null;
+    pageUrl: string;
+    previousPageId?: string | null;
+    pageId?: string | null;
+    previousPrompt?: string;
+    pagePrompt: string;
+}): boolean;
+export declare function shouldUseLiveStateFastPath(params: {
+    bootstrapMode: "reused_live_state" | "fresh_navigation" | "sequential_handoff";
+    currentUrl?: string | null;
+    pageUrl: string;
+    previousPageId?: string | null;
+    pageId?: string | null;
+    previousPrompt?: string;
+    pagePrompt: string;
+}): boolean;
+export declare function deriveRunSharedAuthProfile(profile: ValidatedSessionProfile | undefined): ValidatedSessionProfile | undefined;
+export declare function buildSessionBootstrapProfile(params: {
+    runAuthProfile?: ValidatedSessionProfile;
+    persistedVariantProfile?: ValidatedSessionProfile;
+    requestedLang: string;
+    requestedTheme: "light" | "dark";
+    startUrl?: string;
+}): {
+    profile?: ValidatedSessionProfile;
+    source: "run_shared_auth" | "persisted_variant" | "none";
+};
+export declare function buildSelectorMemoryScopeKeys(context?: SelectorMemoryScopeContext): string[];
+export declare function scopeSelectorMemoryUpdates<T extends {
+    stepSignature: string;
+    selector: string;
+    success: boolean;
+}>(updates: T[], context?: SelectorMemoryScopeContext): T[];
+export declare function resolveScopedSelectorMemory(memory: Record<string, string[]> | undefined, context?: SelectorMemoryScopeContext): Record<string, string[]>;
+export declare function mergeSelectorMemory(...sources: Array<Record<string, string[]> | undefined>): Record<string, string[]>;
+export declare function applySelectorMemoryUpdates(current: Record<string, string[]>, updates: Array<{
+    stepSignature: string;
+    selector: string;
+    success: boolean;
+}>): Record<string, string[]>;