codex-chatgpt-control 0.1.0-alpha.1 → 0.2.0-alpha.1

package/dist/src/scripts/capture-intelligence-locales.js

@@ -0,0 +1,669 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { attachChatGPTBrowser } from "../browser/attach.js";
+import { BROWSER_BRIDGE_REMEDIATION, BROWSER_BRIDGE_UNAVAILABLE_MESSAGE } from "../errors.js";
+import { localeLabels } from "../dom/locale-labels.js";
+import { nonEnglishLanguages, readLanguageCoverage } from "./locale-capture/language-coverage.js";
+const SCHEMA_VERSION = "chatgpt.browser_control.intelligence_locale_capture.v1";
+const CHATGPT_HOME = "https://chatgpt.com/";
+const DEFAULT_SWITCH_TIMEOUT_MS = 15_000;
+const DEFAULT_SETTLE_MS = 1_500;
+const DEFAULT_LIMIT = 25;
+class CaptureUsageError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "CaptureUsageError";
+    }
+}
+const USAGE = [
+    "Usage:",
+    "  npm run capture:intelligence-locales:queue",
+    "  npm run capture:intelligence-locales -- --locale de --native Deutsch --out ../../outputs/intelligence-locale-captures/2026-06-10-intelligence-picker.jsonl",
+    "  npm run capture:intelligence-locales -- --auto-switch --limit 25",
+    "  npm run capture:intelligence-locales -- --auto-switch --all --if-missing open",
+    "  npm run capture:intelligence-locales -- --auto-switch --locales de,fr-FR,pt-BR",
+    "",
+    "Options:",
+    "  --print-queue                  Print the language queue from references/language-coverage.md.",
+    "  --locale                       BCP47 locale id for a one-shot capture.",
+    "  --native                       Exact Settings language option text for a one-shot capture.",
+    "  --out                          JSONL output path. Defaults to ../../outputs/intelligence-locale-captures/<today>-intelligence-picker.jsonl.",
+    "  --auto-switch                  Change ChatGPT Settings -> General -> Language before each capture.",
+    "  --all                          Sweep every non-English language from references/language-coverage.md.",
+    "  --limit                        Number of non-English languages to sweep. Default: 25 with --auto-switch.",
+    "  --locales                      Comma-separated BCP47 ids to sweep instead of first --limit languages.",
+    "  --open-version-submenu         Capture GPT-* model version submenu labels. Default: true.",
+    "  --no-open-version-submenu      Do not open the model-version submenu.",
+    "  --restore                      Restore the initially selected language after a sweep. Default with --auto-switch.",
+    "  --no-restore                   Leave ChatGPT on the last swept language.",
+    "  --settle-ms                    Wait after language switches and menu opens. Default: 1500.",
+    "  --switch-timeout-ms            Wait for rendered html lang after a language switch. Default: 15000.",
+    "  --if-missing                   block|open|create. Default: open with --auto-switch, otherwise block.",
+    "  --tab-id                       Claim an exact ChatGPT tab id instead of the selected ChatGPT tab.",
+    "  --coverage-path                Path to language-coverage.md."
+].join("\n");
+export async function main(argv = process.argv.slice(2), runtime = globalThis) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof CaptureUsageError) {
+            console.log(error.message);
+            return error.exitCode;
+        }
+        throw error;
+    }
+    const languages = await readLanguageCoverage(options.coveragePath);
+    if (options.printQueue) {
+        printQueue(nonEnglishLanguages(languages));
+        return 0;
+    }
+    if ((runtime.agent === undefined || runtime.agent === null) && runtime.browser === undefined) {
+        console.log(JSON.stringify({
+            ok: false,
+            status: "blocked",
+            blocker: {
+                kind: "browser_bridge_unavailable",
+                code: "codex_chrome_bridge_unavailable",
+                message: BROWSER_BRIDGE_UNAVAILABLE_MESSAGE,
+                remediation: BROWSER_BRIDGE_REMEDIATION
+            }
+        }, null, 2));
+        return 2;
+    }
+    const initialLanguage = options.autoSwitch
+        ? await attachCapturePage(runtime, options).then(page => readSelectedLanguage(page)).catch(() => undefined)
+        : undefined;
+    const sweepLanguages = resolveSweepLanguages(options, languages);
+    const records = [];
+    try {
+        for (const language of sweepLanguages) {
+            const page = await attachCapturePage(runtime, options);
+            const record = await captureOne(page, language, options);
+            records.push(record);
+            await appendRecord(options.out, record);
+            printCaptureRecord(record, options.out);
+            const recentRecords = records.slice(-3);
+            if (recentRecords.length === 3 && recentRecords.every(previous => previous.status === "blocked")) {
+                console.error("Stopping after three consecutive blocked locale captures.");
+                return 1;
+            }
+        }
+    }
+    finally {
+        if (options.autoSwitch && options.restore && initialLanguage !== undefined) {
+            await attachCapturePage(runtime, options).then(page => restoreLanguage(page, initialLanguage, options)).catch(error => {
+                console.error(`Unable to restore initial language ${initialLanguage}: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    }
+    return records.some(record => record.status === "blocked") ? 1 : 0;
+}
+export function parseArgs(argv) {
+    let locale;
+    let nativeName;
+    let out;
+    let printQueue = false;
+    let autoSwitch = false;
+    let all = false;
+    let limit;
+    let locales;
+    let openVersionSubmenu = true;
+    let restore;
+    let settleMs = DEFAULT_SETTLE_MS;
+    let switchTimeoutMs = DEFAULT_SWITCH_TIMEOUT_MS;
+    let coveragePath;
+    let ifMissing;
+    let tabId;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined)
+            continue;
+        switch (arg) {
+            case "--help":
+            case "-h":
+                throw new CaptureUsageError(USAGE, 0);
+            case "--print-queue":
+                printQueue = true;
+                break;
+            case "--locale":
+                locale = requiredValue(argv, ++index, arg);
+                break;
+            case "--native":
+                nativeName = requiredValue(argv, ++index, arg);
+                break;
+            case "--out":
+                out = requiredValue(argv, ++index, arg);
+                break;
+            case "--auto-switch":
+                autoSwitch = true;
+                break;
+            case "--all":
+                all = true;
+                break;
+            case "--limit":
+                limit = parsePositiveInteger(requiredValue(argv, ++index, arg), arg);
+                break;
+            case "--locales":
+                locales = requiredValue(argv, ++index, arg).split(",").map(value => value.trim()).filter(Boolean);
+                break;
+            case "--open-version-submenu":
+                openVersionSubmenu = true;
+                break;
+            case "--no-open-version-submenu":
+                openVersionSubmenu = false;
+                break;
+            case "--restore":
+                restore = true;
+                break;
+            case "--no-restore":
+                restore = false;
+                break;
+            case "--settle-ms":
+                settleMs = parsePositiveInteger(requiredValue(argv, ++index, arg), arg);
+                break;
+            case "--switch-timeout-ms":
+                switchTimeoutMs = parsePositiveInteger(requiredValue(argv, ++index, arg), arg);
+                break;
+            case "--if-missing":
+                ifMissing = parseIfMissing(requiredValue(argv, ++index, arg));
+                break;
+            case "--tab-id":
+                tabId = requiredValue(argv, ++index, arg);
+                break;
+            case "--coverage-path":
+                coveragePath = requiredValue(argv, ++index, arg);
+                break;
+            default:
+                throw new CaptureUsageError(`Unknown option: ${arg}\n\n${USAGE}`);
+        }
+    }
+    if (!printQueue && !autoSwitch && (locale === undefined || nativeName === undefined)) {
+        throw new CaptureUsageError(`One-shot capture requires --locale and --native unless --auto-switch is used.\n\n${USAGE}`);
+    }
+    const root = packageRoot();
+    return {
+        locale,
+        nativeName,
+        out: resolve(root, out ?? defaultOutputPath()),
+        printQueue,
+        autoSwitch,
+        all,
+        limit,
+        locales,
+        openVersionSubmenu,
+        restore: restore ?? autoSwitch,
+        settleMs,
+        switchTimeoutMs,
+        coveragePath: resolve(root, coveragePath ?? "references/language-coverage.md"),
+        ifMissing: ifMissing ?? (autoSwitch ? "open" : "block"),
+        tabId
+    };
+}
+async function attachCapturePage(runtime, options) {
+    const runtimeEnv = {};
+    if (runtime.agent !== undefined && runtime.agent !== null)
+        runtimeEnv.agent = runtime.agent;
+    if (runtime.browser !== undefined)
+        runtimeEnv.browser = runtime.browser;
+    const attached = await attachChatGPTBrowser(runtimeEnv, {
+        existingTab: {
+            target: options.tabId === undefined
+                ? { type: "selected", host: "chatgpt" }
+                : { type: "tabId", tabId: options.tabId },
+            ifMissing: options.ifMissing,
+            ifMultiple: "first",
+            requireChatGPT: true
+        },
+        url: CHATGPT_HOME
+    });
+    return attached.page;
+}
+function resolveSweepLanguages(options, languages) {
+    if (options.autoSwitch) {
+        const nonEnglish = nonEnglishLanguages(languages);
+        if (options.locales !== undefined) {
+            return options.locales.map(locale => {
+                const language = languages.find(candidate => candidate.bcp47.toLowerCase() === locale.toLowerCase());
+                if (language === undefined) {
+                    throw new CaptureUsageError(`Locale ${locale} was not found in language coverage.`);
+                }
+                return language;
+            });
+        }
+        if (options.all) {
+            return nonEnglish;
+        }
+        return nonEnglish.slice(0, options.limit ?? DEFAULT_LIMIT);
+    }
+    return [{
+            language: options.locale,
+            nativeName: options.nativeName,
+            bcp47: options.locale,
+            speakers: "",
+            status: ""
+        }];
+}
+async function captureOne(page, language, options) {
+    const warnings = [];
+    try {
+        if (options.autoSwitch) {
+            await switchLanguage(page, language, options);
+            const proof = await renderedProof(page);
+            if (!htmlLangMatches(proof.htmlLang, language.bcp47)) {
+                return blockedRecord(language, proof, warnings, "rendered_locale_mismatch", `Rendered html lang ${proof.htmlLang || "unknown"} did not match requested ${language.bcp47}.`);
+            }
+        }
+        await closeSettingsIfOpen(page);
+        const picker = await captureIntelligencePicker(page, options);
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            status: "ok",
+            capturedAt: new Date().toISOString(),
+            requestedLocale: language.bcp47,
+            requestedNativeName: language.nativeName,
+            htmlLang: picker.htmlLang,
+            url: normalizeChatGPTUrl(picker.url),
+            menuHeading: picker.menuHeading,
+            intelligenceLabels: picker.intelligenceLabels,
+            selectedIntelligenceLabel: picker.selectedIntelligenceLabel,
+            versionFamilyLabels: picker.versionFamilyLabels,
+            modelVersionLabels: picker.modelVersionLabels,
+            warnings
+        };
+    }
+    catch (error) {
+        const proof = await renderedProof(page).catch(() => ({}));
+        return blockedRecord(language, proof, warnings, "capture_failed", error instanceof Error ? error.message : String(error));
+    }
+}
+async function switchLanguage(page, language, options) {
+    await openSettings(page, options);
+    await openLanguageCombobox(page);
+    await clickOptionExact(page, language.nativeName);
+    await waitForRenderedLanguage(page, language.bcp47, options.switchTimeoutMs).catch(async () => {
+        await wait(options.settleMs);
+    });
+}
+async function restoreLanguage(page, selectedLanguageText, options) {
+    await openSettings(page, options);
+    await openLanguageCombobox(page);
+    await clickOptionExact(page, selectedLanguageText);
+    await wait(options.settleMs);
+    await closeSettingsIfOpen(page);
+}
+async function openSettings(page, options) {
+    if (await isSettingsOpen(page))
+        return;
+    await closeFloatingMenus(page);
+    const profile = page.locator?.("[data-testid=\"accounts-profile-button\"]")?.last?.();
+    if (profile?.click === undefined) {
+        throw new Error("Profile menu button was not available.");
+    }
+    await profile.click();
+    await wait(options.settleMs);
+    const settings = page.locator?.("[data-testid=\"settings-menu-item\"]")?.last?.();
+    if (settings?.click === undefined) {
+        throw new Error("Settings menu item was not available.");
+    }
+    await settings.click();
+    await wait(options.settleMs);
+    if (!await isSettingsOpen(page)) {
+        throw new Error("Settings modal did not open.");
+    }
+}
+async function isSettingsOpen(page) {
+    return page.evaluate?.(() => document.querySelector("[role='dialog']") !== null
+        && (location.hash === "#settings"
+            || document.querySelector("[data-testid='close-button']") !== null
+            || document.querySelectorAll("button[role='combobox']").length >= 3)) ?? false;
+}
+async function openLanguageCombobox(page) {
+    const combo = page.locator?.("button[role=\"combobox\"]")?.nth?.(3);
+    if (combo?.click === undefined) {
+        throw new Error("Language combobox was not available.");
+    }
+    await combo.click();
+    await wait(500);
+}
+async function clickOptionExact(page, label) {
+    const option = page.getByRole?.("option", { name: label, exact: true });
+    if (option?.click === undefined) {
+        throw new Error(`Language option ${label} was not available.`);
+    }
+    await option.click();
+}
+async function readSelectedLanguage(page) {
+    await openSettings(page, { settleMs: DEFAULT_SETTLE_MS });
+    const labels = await page.evaluate?.(() => Array.from(document.querySelectorAll("button[role='combobox']")).map(button => (button.textContent ?? "").replace(/\s+/g, " ").trim()));
+    return labels?.[3];
+}
+async function closeSettingsIfOpen(page) {
+    if (!await isSettingsOpen(page))
+        return;
+    const closePoints = await page.evaluate?.(() => Array.from(document.querySelectorAll("[data-testid='close-button']"))
+        .map(element => {
+        const rect = element.getBoundingClientRect();
+        return {
+            x: rect.left + rect.width / 2,
+            y: rect.top + rect.height / 2,
+            width: rect.width,
+            height: rect.height,
+        };
+    })
+        .filter(point => point.width > 0 && point.height > 0)
+        .sort((left, right) => right.x - left.x)) ?? [];
+    for (const point of closePoints) {
+        await clickPagePoint(page, point).catch(() => undefined);
+        await wait(500);
+        if (!await isSettingsOpen(page))
+            return;
+    }
+    const buttons = page.locator?.("[data-testid=\"close-button\"]");
+    const count = await buttons?.count?.().catch(() => 0) ?? 0;
+    for (let index = count - 1; index >= 0; index -= 1) {
+        await buttons?.nth?.(index)?.click?.().catch(() => undefined);
+        await wait(500);
+        if (!await isSettingsOpen(page))
+            return;
+    }
+    await page.keyboard?.press?.("Escape").catch(() => undefined);
+    await wait(500);
+    if (await isSettingsOpen(page)) {
+        throw new Error("Settings modal did not close.");
+    }
+}
+async function closeFloatingMenus(page) {
+    await page.locator?.("body")?.click?.({ position: { x: 12, y: 12 } }).catch(() => undefined);
+    await wait(250);
+}
+async function captureIntelligencePicker(page, options) {
+    await closeFloatingMenus(page);
+    await openPicker(page);
+    await wait(options.settleMs);
+    const first = await readPickerState(page);
+    let modelVersionLabels = [];
+    if (options.openVersionSubmenu && first.versionFamilyLabels.length > 0) {
+        await openVersionSubmenu(page);
+        await wait(options.settleMs);
+        modelVersionLabels = (await readPickerState(page)).modelVersionLabels;
+    }
+    return { ...first, modelVersionLabels };
+}
+async function openPicker(page) {
+    const proCandidates = [
+        page.locator?.("form button.__composer-pill")?.last?.(),
+        page.locator?.("button.__composer-pill")?.last?.(),
+        page.getByRole?.("button", { name: /^Pro$/ })?.last?.(),
+        page.locator?.("button")?.filter?.({ hasText: /^Pro$/ })?.last?.(),
+        page.locator?.("button")?.filter?.({ hasText: /^\s*Pro\s*$/ })?.last?.(),
+    ];
+    for (const proButton of proCandidates) {
+        if (proButton?.click === undefined)
+            continue;
+        await proButton.click().catch(() => undefined);
+        if (await pickerIsOpen(page))
+            return;
+    }
+    await clickStructuralPickerCandidate(page).catch(() => undefined);
+    if (await pickerIsOpen(page))
+        return;
+    for (const label of localeLabels.modeLabels) {
+        const button = page.getByRole?.("button", { name: new RegExp(`^${escapeRegExp(label)}$`, "i") })?.last?.();
+        if (button?.click === undefined)
+            continue;
+        await button.click().catch(() => undefined);
+        if (await pickerIsOpen(page))
+            return;
+    }
+    throw new Error("Unable to open Intelligence picker.");
+}
+async function clickStructuralPickerCandidate(page) {
+    const point = await page.evaluate?.(() => {
+        let targetPoint;
+        let bestScore = Number.NEGATIVE_INFINITY;
+        const considerButton = (button, formScoped) => {
+            const rect = button.getBoundingClientRect();
+            const text = (button.textContent ?? "").replace(/\s+/g, " ").trim();
+            if (text.length === 0 || text.length > 32)
+                return;
+            if (rect.width < 24 || rect.height < 24 || rect.width > 220 || rect.height > 64)
+                return;
+            if (rect.bottom < window.innerHeight * 0.45)
+                return;
+            const aria = button.getAttribute("aria-label") ?? "";
+            const testId = button.getAttribute("data-testid") ?? "";
+            if (/composer-plus|send|microphone|dictat|voice|audio/i.test(`${aria} ${testId}`))
+                return;
+            const score = (formScoped ? 1000 : 0) + rect.bottom + rect.right / 10;
+            if (score > bestScore) {
+                bestScore = score;
+                targetPoint = {
+                    x: rect.left + rect.width / 2,
+                    y: rect.top + rect.height / 2,
+                };
+            }
+        };
+        document.querySelectorAll("form button").forEach(button => considerButton(button, true));
+        if (targetPoint === undefined) {
+            document.querySelectorAll("button").forEach(button => considerButton(button, false));
+        }
+        return targetPoint;
+    });
+    if (point === undefined)
+        return false;
+    await clickPagePoint(page, point);
+    return true;
+}
+async function clickPagePoint(page, point) {
+    const pageWithMouse = page;
+    if (pageWithMouse.mouse?.click !== undefined) {
+        await pageWithMouse.mouse.click(point.x, point.y);
+        return;
+    }
+    const body = page.locator?.("body");
+    if (body?.click === undefined) {
+        throw new Error("Page does not expose pointer click support.");
+    }
+    await body.click({ position: { x: point.x, y: point.y } });
+}
+async function pickerIsOpen(page) {
+    await wait(300);
+    return page.evaluate?.(() => document.querySelector("[data-testid='composer-intelligence-picker-content']") !== null
+        || document.querySelector("[role='menuitemradio']") !== null) ?? false;
+}
+async function readPickerState(page) {
+    return await page.evaluate?.(() => {
+        const menu = document.querySelector("[data-testid='composer-intelligence-picker-content']")
+            ?? Array.from(document.querySelectorAll("[role='menu']")).find(candidate => candidate.querySelector("[role='menuitemradio']"))
+            ?? document;
+        const menuTextLines = (menu.textContent ?? "").split(/\n/).map(line => line.trim()).filter(Boolean);
+        const items = Array.from(document.querySelectorAll("[role='menuitemradio'], [role='menuitem']")).map((element) => {
+            const label = (element.textContent ?? "").replace(/\s+/g, " ").trim();
+            const role = element.getAttribute("role") ?? undefined;
+            return {
+                label,
+                role,
+                checked: element.getAttribute("aria-checked") === "true",
+                expanded: element.getAttribute("aria-expanded") === "true",
+                hasPopup: element.getAttribute("aria-haspopup") ?? undefined,
+                testId: element.getAttribute("data-testid") ?? undefined,
+                ariaLabel: element.getAttribute("aria-label") ?? undefined,
+            };
+        }).filter(item => item.label.length > 0 || item.ariaLabel !== undefined || item.testId !== undefined);
+        const radioLabels = items
+            .filter(item => item.role === "menuitemradio" && item.label.length > 0)
+            .map(item => item.label);
+        const versionLabelPattern = /^(?:o\d+|\d+(?:\.\d+)?)$/i;
+        const modelVersionLabels = radioLabels.filter(label => versionLabelPattern.test(label));
+        const intelligenceLabels = radioLabels.filter(label => !versionLabelPattern.test(label));
+        const selectedIntelligenceLabel = items.find(item => item.role === "menuitemradio"
+            && item.checked
+            && item.label.length > 0
+            && !versionLabelPattern.test(item.label))?.label;
+        const versionFamilyLabels = items
+            .filter(item => item.role === "menuitem" && /^GPT[\s-]/i.test(item.label))
+            .map(item => item.label);
+        const result = {
+            htmlLang: document.documentElement.lang,
+            url: location.href,
+            intelligenceLabels,
+            versionFamilyLabels,
+            modelVersionLabels,
+            items,
+        };
+        const heading = menuTextLines.find(line => !radioLabels.includes(line) && !/^GPT[\s-]/i.test(line));
+        if (heading !== undefined)
+            result.menuHeading = heading;
+        if (selectedIntelligenceLabel !== undefined)
+            result.selectedIntelligenceLabel = selectedIntelligenceLabel;
+        return result;
+    }) ?? {
+        htmlLang: "",
+        url: "",
+        intelligenceLabels: [],
+        versionFamilyLabels: [],
+        modelVersionLabels: []
+    };
+}
+async function openVersionSubmenu(page) {
+    const gptCandidates = [
+        page.getByRole?.("menuitem", { name: /^GPT[\s-]/i })?.last?.(),
+        page.locator?.("[role='menuitem']")?.filter?.({ hasText: /^GPT[\s-]/i })?.last?.(),
+    ];
+    for (const gptMenu of gptCandidates) {
+        if (gptMenu?.click === undefined)
+            continue;
+        await gptMenu.click().catch(() => undefined);
+        if ((await readPickerState(page)).modelVersionLabels.length > 0)
+            return;
+    }
+}
+async function renderedProof(page) {
+    return page.evaluate?.(() => ({
+        htmlLang: document.documentElement.lang,
+        url: location.href
+    })) ?? {};
+}
+async function waitForRenderedLanguage(page, bcp47, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const proof = await renderedProof(page);
+        if (htmlLangMatches(proof.htmlLang, bcp47))
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for rendered language ${bcp47}; html lang is ${proof.htmlLang ?? "unknown"}.`);
+        }
+        await wait(500);
+    }
+}
+function blockedRecord(language, proof, warnings, code, message) {
+    const record = {
+        schemaVersion: SCHEMA_VERSION,
+        status: "blocked",
+        capturedAt: new Date().toISOString(),
+        requestedLocale: language.bcp47,
+        requestedNativeName: language.nativeName,
+        warnings,
+        blocker: {
+            kind: "selector_drift",
+            code,
+            message
+        }
+    };
+    if (proof.htmlLang !== undefined)
+        record.htmlLang = proof.htmlLang;
+    if (proof.url !== undefined)
+        record.url = normalizeChatGPTUrl(proof.url);
+    return record;
+}
+async function appendRecord(path, record) {
+    await mkdir(dirname(path), { recursive: true });
+    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+function printCaptureRecord(record, out) {
+    if (record.status === "ok") {
+        console.log(`captured ${record.requestedLocale} htmlLang=${record.htmlLang ?? "unknown"} intelligence=${record.intelligenceLabels?.length ?? 0} versions=${record.modelVersionLabels?.length ?? 0} out=${out}`);
+    }
+    else {
+        console.log(`blocked ${record.requestedLocale} htmlLang=${record.htmlLang ?? "unknown"} code=${record.blocker?.code ?? "unknown"} out=${out}`);
+    }
+}
+function printQueue(languages) {
+    for (const language of languages) {
+        console.log(`${language.bcp47.padEnd(8)} ${language.nativeName}`);
+    }
+}
+function htmlLangMatches(htmlLang, bcp47) {
+    if (htmlLang === undefined || htmlLang.length === 0)
+        return false;
+    const actual = htmlLang.toLowerCase();
+    const expected = bcp47.toLowerCase();
+    if (actual === expected)
+        return true;
+    if (expected === "zh-hans")
+        return actual === "zh-cn" || actual.includes("hans");
+    if (expected === "zh-hk")
+        return actual.includes("hk");
+    if (expected === "zh-tw")
+        return actual.includes("tw");
+    const [base] = expected.split("-");
+    return base !== undefined && actual === base || (base !== undefined && actual.startsWith(`${base}-`));
+}
+function normalizeChatGPTUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!/chatgpt\.com$/.test(parsed.hostname))
+            return parsed.origin;
+        return `${parsed.origin}${parsed.pathname}${parsed.hash === "#settings" ? "#settings" : ""}`;
+    }
+    catch {
+        return url.slice(0, 120);
+    }
+}
+function requiredValue(argv, index, flag) {
+    const value = argv[index];
+    if (value === undefined || value.startsWith("--")) {
+        throw new CaptureUsageError(`${flag} requires a value.\n\n${USAGE}`);
+    }
+    return value;
+}
+function parsePositiveInteger(value, flag) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new CaptureUsageError(`${flag} must be a positive integer.`);
+    }
+    return parsed;
+}
+function parseIfMissing(value) {
+    if (value === "block" || value === "open" || value === "create")
+        return value;
+    throw new CaptureUsageError("--if-missing must be one of: block, open, create.");
+}
+function defaultOutputPath() {
+    const date = new Date().toISOString().slice(0, 10);
+    return `../../outputs/intelligence-locale-captures/${date}-intelligence-picker.jsonl`;
+}
+function packageRoot() {
+    const scriptDir = dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [resolve(scriptDir, "../.."), resolve(scriptDir, "../../..")]) {
+        if (existsSync(resolve(candidate, "package.json")))
+            return candidate;
+    }
+    return resolve(scriptDir, "../..");
+}
+function wait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const exitCode = await main();
+    process.exitCode = exitCode;
+}

package/dist/src/scripts/check-surface-drift.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/scripts/check-surface-drift.js

@@ -0,0 +1,11 @@
+import { validateSurfaceDrift } from "../testing/surface-drift.js";
+const report = validateSurfaceDrift();
+console.log([
+    "Validated docs/surface drift gate:",
+    `- ${report.commandCount} backend commands`,
+    `- ${report.descriptorCount} command descriptors`,
+    `- ${report.blockerKindCount} blocker kinds`,
+    `- ${report.pythonCommandCount} Python-covered commands`,
+    `- ${report.generatedDocsChecked} generated blocker doc sections`,
+    `- ${report.docAnchorsChecked} doc anchors`
+].join("\n"));