autokap 1.0.6 → 1.0.8

package/dist/capture-studio-sync.js

@@ -0,0 +1,172 @@
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getNullableString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : null;
+}
+function mergeStudioMockupConfig(existingConfig, deviceFrame, orientation, browserBar, rawScreenshotUrl) {
+    const normalizedBrowserBar = browserBar && Object.keys(browserBar).length > 0
+        ? {
+            ...(browserBar.url ? { url: browserBar.url } : {}),
+            ...(browserBar.pageTitle ? { pageTitle: browserBar.pageTitle } : {}),
+            ...(browserBar.tabIconUrl ? { tabIconUrl: browserBar.tabIconUrl } : {}),
+        }
+        : null;
+    const normalizedFrame = deviceFrame ?? null;
+    const normalizedOrientation = orientation === 'portrait' || orientation === 'landscape'
+        ? orientation
+        : null;
+    const normalizedRawUrl = rawScreenshotUrl ?? null;
+    const base = isRecord(existingConfig) ? { ...existingConfig } : {};
+    if (normalizedFrame) {
+        base.deviceFrame = normalizedFrame;
+    }
+    else {
+        delete base.deviceFrame;
+    }
+    if (normalizedOrientation) {
+        base.orientation = normalizedOrientation;
+    }
+    if (normalizedRawUrl) {
+        base.rawScreenshotUrl = normalizedRawUrl;
+    }
+    else {
+        delete base.rawScreenshotUrl;
+    }
+    if (normalizedBrowserBar) {
+        base.browserBar = normalizedBrowserBar;
+    }
+    else {
+        delete base.browserBar;
+    }
+    return Object.keys(base).length > 0 ? base : null;
+}
+export async function syncStudioVariantAfterCapture(params) {
+    const { supabase, projectId, presetId, targetId = null, lang, theme, elementName, captureId, screenshotUrl, rawScreenshotUrl = null, deviceFrame = null, orientation = null, browserBar, matchTargetId = true, } = params;
+    if (!projectId || !presetId || !screenshotUrl) {
+        return;
+    }
+    let linkSelect = supabase
+        .from('screenshot_links')
+        .select('id, latest_capture:captures!latest_capture_id(screenshot_url, raw_screenshot_url)')
+        .eq('preset_id', presetId)
+        .eq('lang', lang)
+        .eq('theme', theme);
+    if (matchTargetId && targetId) {
+        linkSelect = linkSelect.eq('target_id', targetId);
+    }
+    if (elementName !== null) {
+        linkSelect = linkSelect.eq('element_name', elementName);
+    }
+    else {
+        linkSelect = linkSelect.is('element_name', null);
+    }
+    const { data: existingLinks, error: linkSelectError } = await linkSelect;
+    if (linkSelectError) {
+        console.error('[capture] failed to load screenshot links for studio sync:', linkSelectError.message);
+        return;
+    }
+    let linkUpdate = supabase
+        .from('screenshot_links')
+        .update({ latest_capture_id: captureId })
+        .eq('preset_id', presetId)
+        .eq('lang', lang)
+        .eq('theme', theme);
+    if (matchTargetId && targetId) {
+        linkUpdate = linkUpdate.eq('target_id', targetId);
+    }
+    if (elementName !== null) {
+        linkUpdate = linkUpdate.eq('element_name', elementName);
+    }
+    else {
+        linkUpdate = linkUpdate.is('element_name', null);
+    }
+    const { error: linkUpdateError } = await linkUpdate;
+    if (linkUpdateError) {
+        console.error('[capture] failed to update screenshot links:', linkUpdateError.message);
+        return;
+    }
+    const previousUrls = new Set();
+    for (const link of existingLinks ?? []) {
+        const latestCapture = isRecord(link.latest_capture) ? link.latest_capture : null;
+        const previousScreenshotUrl = getNullableString(latestCapture?.screenshot_url);
+        const previousRawScreenshotUrl = getNullableString(latestCapture?.raw_screenshot_url);
+        if (previousScreenshotUrl)
+            previousUrls.add(previousScreenshotUrl);
+        if (previousRawScreenshotUrl)
+            previousUrls.add(previousRawScreenshotUrl);
+    }
+    const { data: compositions, error: compositionsError } = await supabase
+        .from('compositions')
+        .select('id, pages')
+        .eq('project_id', projectId);
+    if (compositionsError) {
+        console.error('[capture] failed to load compositions for studio sync:', compositionsError.message);
+        return;
+    }
+    for (const composition of compositions ?? []) {
+        const pages = Array.isArray(composition.pages) ? composition.pages : [];
+        let changed = false;
+        const nextPages = pages.map((page) => {
+            if (!isRecord(page) || !isRecord(page.screenshot)) {
+                return page;
+            }
+            const screenshot = page.screenshot;
+            if (getNullableString(screenshot.presetId) !== presetId) {
+                return page;
+            }
+            const currentTargetId = getNullableString(screenshot.targetId);
+            const currentLang = getNullableString(screenshot.lang);
+            const currentTheme = getNullableString(screenshot.theme);
+            const currentElementName = getNullableString(screenshot.elementName);
+            const currentScreenshotUrl = getNullableString(screenshot.screenshotUrl);
+            const currentRawScreenshotUrl = getNullableString(screenshot.rawScreenshotUrl);
+            const targetMatches = !matchTargetId || !targetId || currentTargetId === targetId;
+            const exactMatch = targetMatches
+                && currentLang === lang
+                && currentTheme === theme
+                && currentElementName === elementName;
+            const legacyMatch = (!currentTargetId || !currentLang || !currentTheme)
+                && (currentElementName === null || currentElementName === elementName)
+                && ((currentScreenshotUrl !== null && previousUrls.has(currentScreenshotUrl))
+                    || (currentRawScreenshotUrl !== null && previousUrls.has(currentRawScreenshotUrl)));
+            if (!exactMatch && !legacyMatch) {
+                return page;
+            }
+            const nextMockupConfig = mergeStudioMockupConfig(screenshot.mockupConfig, deviceFrame, orientation, browserBar, rawScreenshotUrl);
+            const nextScreenshot = {
+                ...screenshot,
+                presetId,
+                captureId,
+                targetId: targetId ?? currentTargetId,
+                lang,
+                theme,
+                elementName,
+                screenshotUrl,
+                rawScreenshotUrl,
+            };
+            if (nextMockupConfig) {
+                nextScreenshot.mockupConfig = nextMockupConfig;
+            }
+            if (JSON.stringify(nextScreenshot) === JSON.stringify(screenshot)) {
+                return page;
+            }
+            changed = true;
+            return {
+                ...page,
+                screenshot: nextScreenshot,
+            };
+        });
+        if (!changed) {
+            continue;
+        }
+        const { error: compositionUpdateError } = await supabase
+            .from('compositions')
+            .update({ pages: nextPages })
+            .eq('id', composition.id);
+        if (compositionUpdateError) {
+            console.error(`[capture] failed to sync composition ${composition.id} with latest capture:`, compositionUpdateError.message);
+        }
+    }
+}
+//# sourceMappingURL=capture-studio-sync.js.map

package/dist/capture-surface-contract.d.ts

@@ -0,0 +1,36 @@
+import type { BrowserObservation } from "./browser.js";
+import type { CapturePageContract, CapturePageIdentity, VideoPageSignals } from "./types.js";
+export interface ObservedSurfaceEvidence {
+    currentUrl: string;
+    routeText: string;
+    mainText: string;
+    chromeText: string;
+    overlayText: string;
+    dialogText: string;
+    strongTargetTokens: string[];
+    mainTokenMatches: string[];
+    chromeTokenMatches: string[];
+    overlayTokenMatches: string[];
+    dialogTokenMatches: string[];
+    routeTokenMatches: string[];
+    hasMainSurface: boolean;
+    hasOverlaySurface: boolean;
+    hasConfigurationSurface: boolean;
+}
+export declare function buildObservedSurfaceEvidence(params: {
+    currentUrl?: string | null;
+    observation: BrowserObservation;
+    pageSignals?: VideoPageSignals | null;
+    pageIdentity?: CapturePageIdentity | null;
+}): ObservedSurfaceEvidence;
+export declare function evaluateSurfaceContract(params: {
+    contract: CapturePageContract;
+    currentUrl?: string | null;
+    observation: BrowserObservation;
+    pageSignals?: VideoPageSignals | null;
+    pageIdentity?: CapturePageIdentity | null;
+}): {
+    matched: boolean;
+    reason?: string;
+    evidence: ObservedSurfaceEvidence;
+};

package/dist/capture-surface-contract.js

@@ -0,0 +1,299 @@
+const WEAK_TARGET_TOKENS = new Set([
+    "page",
+    "pages",
+    "screen",
+    "view",
+    "views",
+    "section",
+    "content",
+    "main",
+    "current",
+    "currently",
+    "open",
+    "opened",
+    "screenshot",
+    "screenshots",
+    "state",
+    "target",
+    "ready",
+    "modal",
+    "dialog",
+    "popup",
+    "overlay",
+    "drawer",
+    "panel",
+    "route",
+    "routes",
+    "editor",
+    "form",
+    "configuration",
+    "config",
+    "selection",
+    "select",
+    "choose",
+    "picker",
+    "workflow",
+    "step",
+    "steps",
+    "app",
+    "site",
+    "web",
+]);
+function normalizeText(value) {
+    return (value ?? "")
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, " ")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function joinText(values) {
+    return values
+        .map((value) => normalizeText(value))
+        .filter(Boolean)
+        .join(" ");
+}
+function tokenize(value) {
+    return normalizeText(value)
+        .split(/\s+/g)
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 3);
+}
+function unique(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 buildStrongTargetTokens(pageIdentity) {
+    return unique((pageIdentity?.subjectTokens ?? [])
+        .map((token) => normalizeText(token))
+        .filter((token) => token.length >= 4 && !WEAK_TARGET_TOKENS.has(token)));
+}
+function countTokenMatches(tokens, haystack) {
+    if (tokens.length === 0 || !haystack)
+        return [];
+    const haystackTokens = new Set(tokenize(haystack));
+    return tokens.filter((token) => haystackTokens.has(token));
+}
+function requiredTokenEvidenceCount(tokenCount) {
+    return tokenCount <= 1 ? 1 : 2;
+}
+function hasSufficientSurfaceEvidence(params) {
+    if (params.totalTokenCount <= 0)
+        return false;
+    const minimum = requiredTokenEvidenceCount(params.totalTokenCount);
+    if (params.matchedCount >= minimum)
+        return true;
+    if (minimum >= 2 && params.matchedCount >= 1 && params.routeMatchedCount >= 1) {
+        return true;
+    }
+    return false;
+}
+function hasMeaningfulMainSurface(observation, pageSignals) {
+    return !!(normalizeText(observation.primarySurface)
+        || normalizeText(observation.configurationSurface)
+        || normalizeText(pageSignals?.title ?? observation.title)
+        || (pageSignals?.headings.length ?? 0) > 0
+        || normalizeText(pageSignals?.visibleText));
+}
+export function buildObservedSurfaceEvidence(params) {
+    const currentUrl = normalizeText(params.currentUrl ?? params.observation.url ?? "");
+    const routeText = joinText([
+        currentUrl,
+        params.pageSignals?.canonicalUrl ?? "",
+    ]);
+    const mainText = joinText([
+        params.pageSignals?.title ?? params.observation.title,
+        ...(params.pageSignals?.headings ?? []),
+        ...(params.pageSignals?.breadcrumbLabels ?? []),
+        params.observation.primarySurface,
+        params.observation.configurationSurface,
+        params.pageSignals?.visibleText ?? "",
+        params.observation.textSample,
+    ]);
+    const chromeText = joinText([
+        ...(params.pageSignals?.navLabels ?? []),
+        params.observation.navigationSurface,
+    ]);
+    const overlayText = joinText([
+        params.observation.overlaySurface,
+    ]);
+    const dialogText = joinText([
+        params.observation.overlaySurface,
+        params.observation.configurationSurface,
+        params.pageSignals?.title ?? params.observation.title,
+        ...(params.pageSignals?.headings ?? []),
+    ]);
+    const strongTargetTokens = buildStrongTargetTokens(params.pageIdentity ?? null);
+    return {
+        currentUrl,
+        routeText,
+        mainText,
+        chromeText,
+        overlayText,
+        dialogText,
+        strongTargetTokens,
+        mainTokenMatches: countTokenMatches(strongTargetTokens, mainText),
+        chromeTokenMatches: countTokenMatches(strongTargetTokens, chromeText),
+        overlayTokenMatches: countTokenMatches(strongTargetTokens, overlayText),
+        dialogTokenMatches: countTokenMatches(strongTargetTokens, dialogText),
+        routeTokenMatches: countTokenMatches(strongTargetTokens, routeText),
+        hasMainSurface: hasMeaningfulMainSurface(params.observation, params.pageSignals ?? null),
+        hasOverlaySurface: overlayText.length > 0,
+        hasConfigurationSurface: normalizeText(params.observation.configurationSurface).length > 0,
+    };
+}
+function resolveExpectedSurfaceLabel(contract) {
+    switch (contract.expectedSurfaceKind) {
+        case "dialog_configuration":
+        case "dialog_selection":
+            return "dialog/modal capture target";
+        case "editor_route":
+        case "detail_route":
+            return "requested page state";
+        default:
+            return "requested capture target";
+    }
+}
+function formatSurfaceReason(params) {
+    const expectedTokens = params.evidence.strongTargetTokens.slice(0, 5).join(", ");
+    const observedSurfaces = [
+        params.observation.overlaySurface ? `overlay="${params.observation.overlaySurface.slice(0, 80)}"` : "",
+        params.observation.configurationSurface ? `configuration="${params.observation.configurationSurface.slice(0, 80)}"` : "",
+        params.observation.primarySurface ? `main="${params.observation.primarySurface.slice(0, 80)}"` : "",
+    ]
+        .filter(Boolean)
+        .join("; ");
+    const details = [
+        params.pageIdentity?.summary ? `identity=${params.pageIdentity.summary}` : "",
+        expectedTokens ? `expected_tokens=${expectedTokens}` : "",
+        `dialogs=${params.observation.dialogCount}`,
+        observedSurfaces,
+    ]
+        .filter(Boolean)
+        .join("; ");
+    return details ? `${params.base} [${details}]` : params.base;
+}
+export function evaluateSurfaceContract(params) {
+    const evidence = buildObservedSurfaceEvidence(params);
+    const expectedLabel = resolveExpectedSurfaceLabel(params.contract);
+    const targetSeenInMain = hasSufficientSurfaceEvidence({
+        matchedCount: evidence.mainTokenMatches.length,
+        routeMatchedCount: evidence.routeTokenMatches.length,
+        totalTokenCount: evidence.strongTargetTokens.length,
+    });
+    const targetSeenInOverlay = hasSufficientSurfaceEvidence({
+        matchedCount: evidence.overlayTokenMatches.length,
+        routeMatchedCount: evidence.routeTokenMatches.length,
+        totalTokenCount: evidence.strongTargetTokens.length,
+    });
+    const targetSeenInRoute = evidence.routeTokenMatches.length >= requiredTokenEvidenceCount(evidence.strongTargetTokens.length);
+    const targetSeenOnlyInChrome = evidence.chromeTokenMatches.length > 0
+        && !targetSeenInMain
+        && !targetSeenInOverlay
+        && !targetSeenInRoute;
+    const structuralDialogVisible = params.contract.dialogPolicy === "must_be_open"
+        && params.observation.dialogCount > 0
+        && (evidence.hasOverlaySurface || evidence.hasConfigurationSurface || evidence.dialogText.length > 0);
+    const dialogCueMatches = unique([
+        ...evidence.overlayTokenMatches,
+        ...evidence.dialogTokenMatches,
+        ...evidence.mainTokenMatches,
+    ]);
+    if (params.contract.dialogPolicy === "must_be_open" && params.observation.dialogCount === 0) {
+        return {
+            matched: false,
+            reason: formatSurfaceReason({
+                base: `Expected a ${expectedLabel}, but no dialog is currently open.`,
+                evidence,
+                observation: params.observation,
+                pageIdentity: params.pageIdentity ?? null,
+            }),
+            evidence,
+        };
+    }
+    if (params.contract.dialogPolicy === "must_be_closed" && params.observation.dialogCount > 0) {
+        return {
+            matched: false,
+            reason: formatSurfaceReason({
+                base: `Expected the ${expectedLabel}, but a dialog/modal is still open on top of the page.`,
+                evidence,
+                observation: params.observation,
+                pageIdentity: params.pageIdentity ?? null,
+            }),
+            evidence,
+        };
+    }
+    if (evidence.strongTargetTokens.length > 0) {
+        const hasTargetEvidence = targetSeenInMain
+            || targetSeenInOverlay
+            || targetSeenInRoute;
+        if (hasTargetEvidence) {
+            return { matched: true, evidence };
+        }
+        if (structuralDialogVisible && dialogCueMatches.length >= 1) {
+            return { matched: true, evidence };
+        }
+        if (targetSeenOnlyInChrome) {
+            return {
+                matched: false,
+                reason: formatSurfaceReason({
+                    base: `Expected the ${expectedLabel}, but matching cues appear only in the navigation/chrome, not in the main page content.`,
+                    evidence,
+                    observation: params.observation,
+                    pageIdentity: params.pageIdentity ?? null,
+                }),
+                evidence,
+            };
+        }
+        return {
+            matched: false,
+            reason: formatSurfaceReason({
+                base: structuralDialogVisible
+                    ? `Expected the ${expectedLabel}, but the visible dialog still lacks enough target-specific cues.`
+                    : `Expected the ${expectedLabel}, but the main page content does not yet show the requested target.`,
+                evidence,
+                observation: params.observation,
+                pageIdentity: params.pageIdentity ?? null,
+            }),
+            evidence,
+        };
+    }
+    if (structuralDialogVisible && evidence.hasConfigurationSurface) {
+        return { matched: true, evidence };
+    }
+    if ((params.contract.expectedSurfaceKind === "dialog_configuration" || params.contract.expectedSurfaceKind === "dialog_selection")
+        && !evidence.hasOverlaySurface
+        && !evidence.hasConfigurationSurface) {
+        return {
+            matched: false,
+            reason: formatSurfaceReason({
+                base: `Expected a ${expectedLabel}, but the open dialog does not expose enough visible content yet.`,
+                evidence,
+                observation: params.observation,
+                pageIdentity: params.pageIdentity ?? null,
+            }),
+            evidence,
+        };
+    }
+    if (!evidence.hasMainSurface && params.contract.dialogPolicy !== "must_be_open") {
+        return {
+            matched: false,
+            reason: formatSurfaceReason({
+                base: `Expected the ${expectedLabel}, but the current page surface is too weakly identified.`,
+                evidence,
+                observation: params.observation,
+                pageIdentity: params.pageIdentity ?? null,
+            }),
+            evidence,
+        };
+    }
+    return { matched: true, evidence };
+}
+//# sourceMappingURL=capture-surface-contract.js.map

package/dist/capture-transition-engine.d.ts

@@ -0,0 +1,28 @@
+import type { BrowserObservation } from "./browser.js";
+import type { CaptureBaselineResult, CaptureHandoffContext, CapturePageContract, CapturePageIdentity, CaptureTransitionDecision, ValidatedSessionProfile, VideoPageSignals } from "./types.js";
+export declare function deriveCapturePageContract(params: {
+    pageIdentity?: CapturePageIdentity | null;
+}): CapturePageContract;
+export declare function buildCaptureCheckpointEvidence(params: {
+    currentUrl?: string | null;
+    targetUrl: string;
+    pageIdentity?: CapturePageIdentity | null;
+    observation: BrowserObservation;
+    pageSignals?: VideoPageSignals | null;
+    profile?: ValidatedSessionProfile;
+    requestedLang?: string;
+    requestedTheme?: "light" | "dark";
+}): CaptureTransitionDecision;
+export declare function decideCaptureTransition(params: {
+    pageIndex: number;
+    currentUrl?: string | null;
+    targetUrl: string;
+    resumeUrl?: string | null;
+    pageIdentity?: CapturePageIdentity | null;
+    observation: BrowserObservation | null;
+    pageSignals?: VideoPageSignals | null;
+    profile?: ValidatedSessionProfile;
+    handoffContext?: CaptureHandoffContext;
+    requestedLang?: string;
+    requestedTheme?: "light" | "dark";
+}): CaptureBaselineResult;