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

package/dist/src/types.d.ts

@@ -1,5 +1,5 @@
 export type CommandStatus = "ok" | "partial" | "timeout" | "blocked" | "needs_confirmation" | "not_found" | "unsupported" | "error";
-export type BlockerKind = "browser_bridge_unavailable" | "login_required" | "captcha" | "rate_limit" | "modal" | "permission" | "confirmation" | "selector_drift" | "download_unavailable" | "upload_failed" | "not_found" | "unknown";
+export type BlockerKind = "browser_bridge_unavailable" | "login_required" | "captcha" | "rate_limit" | "modal" | "permission" | "confirmation" | "selector_drift" | "artifact_unavailable" | "artifact_selector_drift" | "artifact_download_unavailable" | "download_unavailable" | "upload_failed" | "not_found" | "unknown";
 export type CommandContext = {
     url?: string;
     conversationId?: string;
@@ -10,6 +10,32 @@ export type CommandContext = {
     tabId?: string;
     timestamp: string;
 };
+export type ExistingTabMismatchReason = "no_candidate" | "multiple_candidates" | "non_chatgpt_tab" | "conversation_id_mismatch" | "url_mismatch" | "title_mismatch" | "selected_tab_unavailable" | "explicit_tab_id_not_open" | "user_open_tabs_unavailable";
+export type ExistingTabDiagnosticTarget = {
+    type: string;
+    host?: string;
+    tabId?: string;
+    conversationId?: string;
+    url?: string;
+    title?: string;
+    exact?: boolean;
+};
+export type ExistingTabDiagnosticCandidate = {
+    id: string;
+    url?: string;
+    title?: string;
+    conversationId?: string;
+    lastOpened?: string;
+    tabGroup?: string;
+};
+export type ExistingTabDiagnostics = {
+    requestedTarget: ExistingTabDiagnosticTarget;
+    userOpenTabsAvailable: boolean;
+    chatgptTabCount: number;
+    mismatchReason: ExistingTabMismatchReason;
+    candidateTabs: ExistingTabDiagnosticCandidate[];
+    omittedCandidateCount?: number;
+};
 export type CommandResult<T = unknown> = {
     ok: boolean;
     status: CommandStatus;
@@ -37,6 +63,9 @@ export type CommandResult<T = unknown> = {
             label: string;
             role?: string;
         }>;
+        diagnostics?: {
+            existingTab?: ExistingTabDiagnostics;
+        };
         resumable?: boolean;
     };
     context: CommandContext;
@@ -154,10 +183,14 @@ export type WaitArgs = {
     stableMs?: number;
     pollMs?: number;
     mode?: "normal" | "deep_research";
+    responseContent?: "include" | "metadata";
 };
 export type WaitData = {
     complete: boolean;
     responseText?: string;
+    responseChars?: number;
+    responseSha256?: string;
+    responseContent?: "include" | "metadata";
     assistantTurnCount: number;
     elapsedMs: number;
 };
@@ -176,6 +209,11 @@ export type ResponseTable = {
 };
 export type ResponseCaptureSource = "semantic_dom" | "clipboard";
 export type ResponseCaptureFidelity = "clipboard_markdown" | "semantic_markdown" | "visible_text" | "normalized_text" | "html" | "blocks" | "all";
+export type ResponseCaptureLimit = {
+    maxChars: number;
+    originalChars: number;
+    clipped: boolean;
+};
 export type ResponseBranchState = {
     current?: number;
     total?: number;
@@ -225,6 +263,7 @@ export type ReadLatestData = {
     format: Exclude<ResponseFormat, "text">;
     source?: ResponseCaptureSource;
     fidelity?: ResponseCaptureFidelity;
+    captureLimit?: ResponseCaptureLimit;
     warnings?: string[];
     markdown?: string;
     visibleText?: string;
@@ -256,14 +295,101 @@ export type AskReadData = {
 export type AttachFilesArgs = {
     paths: string[];
     timeoutMs?: number;
+    includeDiagnostics?: boolean;
+    includeHashes?: boolean;
 };
 export type AttachedFile = {
     path: string;
     name: string;
     bytes: number;
 };
+export type FileCategory = "text" | "document" | "spreadsheet" | "data" | "image" | "audio" | "video" | "archive" | "unknown";
+export type FilePreflightArgs = {
+    paths: string[];
+    maxBytesPerFile?: number;
+    maxTotalBytes?: number;
+    includeHashes?: boolean;
+};
+export type FilePreflightFile = AttachedFile & {
+    extension: string;
+    mimeType: string;
+    category: FileCategory;
+    sha256?: string;
+};
+export type FilePreflightData = {
+    files: FilePreflightFile[];
+    totalBytes: number;
+};
 export type AttachFilesData = {
     files: AttachedFile[];
+    diagnostics?: FileUploadDiagnostics;
+};
+export type BrowserInputFileDiagnostic = {
+    name: string;
+    size: number;
+    type?: string;
+    lastModified?: number;
+};
+export type BrowserInputDiagnostic = {
+    files: BrowserInputFileDiagnostic[];
+};
+export type FileUploadDiagnostics = {
+    preflight: FilePreflightData;
+    browserInput?: BrowserInputDiagnostic;
+};
+export type ProjectSourceStatus = "ready" | "processing" | "failed" | "unknown";
+export type ProjectSource = {
+    name: string;
+    status: ProjectSourceStatus;
+};
+export type ProjectSourcesUrl = {
+    projectId: string;
+    projectSlug?: string;
+    url: string;
+};
+export type ProjectSourcesListArgs = {
+    projectUrl: string;
+    existingTab?: boolean | ExistingTabPolicy;
+    preferExistingTab?: boolean;
+    timeoutMs?: number;
+};
+export type ProjectSourcesListData = ProjectSourcesUrl & {
+    sources: ProjectSource[];
+};
+export type ProjectSourcePlanFile = FilePreflightFile & {
+    displayPath: string;
+};
+export type ProjectSourceUploadBatch = {
+    index: number;
+    files: ProjectSourcePlanFile[];
+    totalBytes: number;
+};
+export type ProjectSourcesPlanAddArgs = {
+    projectUrl: string;
+    files: string[];
+    batchSize?: number;
+    maxBytesPerFile?: number;
+    maxTotalBytes?: number;
+};
+export type ProjectSourcesAddPlanData = ProjectSourcesUrl & {
+    projectUrl: string;
+    operation: "append_add";
+    dryRun: true;
+    files: ProjectSourcePlanFile[];
+    batches: ProjectSourceUploadBatch[];
+    totalBytes: number;
+};
+export type ProjectSourcesAddArgs = ProjectSourcesPlanAddArgs & {
+    confirmMutation?: boolean;
+    existingTab?: boolean | ExistingTabPolicy;
+    preferExistingTab?: boolean;
+    timeoutMs?: number;
+};
+export type ProjectSourcesAddData = Omit<ProjectSourcesAddPlanData, "dryRun"> & {
+    dryRun: false;
+    before: ProjectSource[];
+    after: ProjectSource[];
+    added: ProjectSource[];
 };
 export type DownloadLatestArgs = {
     destDir: string;
@@ -278,6 +404,47 @@ export type DownloadedFile = {
     suggestedFilename?: string;
     bytes: number;
 };
+export type ArtifactKind = "image";
+export type GeneratedArtifact = {
+    kind: ArtifactKind;
+    index: number;
+    visible: boolean;
+    width?: number;
+    height?: number;
+    alt?: string;
+    ariaLabel?: string;
+    src?: string;
+    turnId?: string;
+    downloadAvailable: boolean;
+    selectorProvenance: string;
+};
+export type ListArtifactsArgs = {
+    kind?: ArtifactKind;
+    max?: number;
+    timeoutMs?: number;
+};
+export type ArtifactListData = {
+    count: number;
+    artifacts: GeneratedArtifact[];
+    latest?: GeneratedArtifact;
+};
+export type ArtifactWaitArgs = ListArtifactsArgs & {
+    afterArtifactCount?: number;
+    requireDownload?: boolean;
+    timeoutMs?: number;
+    stableMs?: number;
+    pollMs?: number;
+};
+export type ArtifactWaitData = {
+    complete: boolean;
+    count: number;
+    latest?: GeneratedArtifact;
+    elapsedMs: number;
+};
+export type ArtifactDownloadArgs = DownloadLatestArgs & {
+    kind?: ArtifactKind;
+    prefer?: "download_control" | "visible_image_source";
+};
 export type CopyResponseArgs = {
     which?: "latest" | {
         assistantIndex: number;
@@ -291,6 +458,7 @@ export type CopiedResponse = {
     source: "clipboard" | "dom";
     format: Exclude<ResponseFormat, "text">;
     fidelity?: ResponseCaptureFidelity;
+    captureLimit?: ResponseCaptureLimit;
     warnings?: string[];
     markdown?: string;
     visibleText?: string;
@@ -309,8 +477,17 @@ export type CopiedResponse = {
 export type SetModeArgs = {
     model?: string;
     effort?: string;
+    intelligence?: string;
+    modelVersion?: string;
+    version?: string;
+    timeoutMs?: number;
+};
+export type GetModeArgs = {
     timeoutMs?: number;
 };
+export type GetModeData = {
+    modes: string[];
+};
 export type SelectToolArgs = {
     tool: "web_search" | "deep_research" | "create_image" | string;
     timeoutMs?: number;
@@ -355,6 +532,18 @@ export type SequenceStep = {
     id: string;
     command: "messages.waitAndRead";
     args: WaitAndReadArgs;
+} | {
+    id: string;
+    command: "artifacts.listLatest";
+    args?: ListArtifactsArgs;
+} | {
+    id: string;
+    command: "artifacts.wait";
+    args?: ArtifactWaitArgs;
+} | {
+    id: string;
+    command: "artifacts.downloadLatest";
+    args: ArtifactDownloadArgs;
 } | {
     id: string;
     command: "files.attach";
@@ -363,6 +552,18 @@ export type SequenceStep = {
     id: string;
     command: "files.downloadLatest";
     args: DownloadLatestArgs;
+} | {
+    id: string;
+    command: "projects.sources.list";
+    args: ProjectSourcesListArgs;
+} | {
+    id: string;
+    command: "projects.sources.planAdd";
+    args: ProjectSourcesPlanAddArgs;
+} | {
+    id: string;
+    command: "projects.sources.add";
+    args: ProjectSourcesAddArgs;
 } | {
     id: string;
     command: "response.copy";
@@ -411,10 +612,13 @@ export type BrowserLike = {
     };
     tabs?: {
         create?: (url: string) => Promise<PageLike> | PageLike;
-        new?: (url: string) => Promise<PageLike> | PageLike;
+        new?: (url?: string) => Promise<PageLike> | PageLike;
         selected?: () => Promise<PageLike | undefined> | PageLike | undefined;
         list?: () => Promise<PageLike[]> | PageLike[];
         get?: (id: string) => Promise<PageLike> | PageLike;
+        finalize?: (options: {
+            keep?: unknown[];
+        }) => Promise<void>;
     };
     newPage?: () => Promise<PageLike> | PageLike;
 };
@@ -462,10 +666,33 @@ export type PageLike = {
     keyboard?: {
         press?: (key: string) => Promise<void>;
     };
+    mouse?: {
+        move?: (x: number, y: number) => Promise<void> | void;
+        click?: (x: number, y: number) => Promise<void> | void;
+    };
+    cua?: {
+        move?: (options: {
+            x: number;
+            y: number;
+        }) => Promise<void> | void;
+        click?: (options: {
+            x: number;
+            y: number;
+            button?: number;
+        }) => Promise<void> | void;
+    };
     waitForTimeout?: (ms: number) => Promise<void>;
     waitForEvent?: (event: string, optionsOrCallback?: WaitForEventOptions | unknown) => Promise<unknown>;
     evaluate?: <T, A = unknown>(fn: (arg: A) => T | Promise<T>, arg?: A) => Promise<T>;
     content?: () => Promise<string>;
+    close?: () => Promise<void>;
+    capabilities?: {
+        get?: (id: string) => Promise<unknown> | unknown;
+    };
+    playwright?: {
+        waitForTimeout?: (ms: number) => Promise<void>;
+        [key: string]: unknown;
+    };
 };
 export type AskHelperArgs = AskArgs & {
     thread?: ThreadTarget;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-chatgpt-control",
-  "version": "0.1.0-alpha.1",
+  "version": "0.3.0-alpha.1",
   "description": "Unofficial SDK for Codex agents controlling visible ChatGPT web sessions.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "bundle:backend": "esbuild src/scripts/backend-server.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-backend.mjs",
     "bundle:live-smoke": "esbuild src/scripts/live-smoke-module.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-live-smoke.bundle.mjs",
     "contract:validate": "node scripts/validate-contract.mjs",
+    "docs:drift": "tsx src/scripts/check-surface-drift.ts",
     "parity:fixtures": "node scripts/check-parity-fixtures.mjs",
     "parity:suite": "tsx src/scripts/check-parity-suite.ts",
     "test:backend-conformance": "vitest run tests/unit/backend-conformance.test.ts",
@@ -73,7 +74,7 @@
   "devDependencies": {
     "@types/node": "^24.13.1",
     "ajv": "^8.17.1",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "tsx": "^4.20.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.8"

package/references/backend-protocol.md

@@ -67,6 +67,8 @@ Current protocol error codes are:
 
 Browser-control blockers are not protocol errors. They are normal command or runner results with `status: "blocked"`, `status: "partial"`, or `status: "needs_confirmation"` plus blocker/interruption details.
 
+`status: "partial"` is the required result for incomplete response capture. A partial result may still include `output_text` and `data.responseText`, but consumers must treat that text as incomplete until a later wait confirms completion. Common causes are wait timeout after partial assistant text, active generation controls such as `Stop answering`, stopped-generation markers such as `Stopped thinking`, or a read fallback after the wait step could not confirm completion. For status-only polling, `messages.wait` accepts `responseContent: "metadata"`; partial and completed wait results then omit assistant text and instead return compact metadata such as `data.responseChars` and `data.responseSha256`. Intentional capture clipping uses `data.captureLimit` plus warnings; it is separate from ChatGPT generation length.
+
 ## Streaming
 
 Streaming commands emit backend event lines until `completed` or `error`.
@@ -107,9 +109,56 @@ The backend must support:
 - runner: `runner.run`, `runner.plan`, `runner.stream`
 - Responses adapter: `responses.create`
 - workflows: `ask`, `askInThread`, `askWithFiles`, `askAndDownload`, `runMessages`, `openThread`, `runPlan`
+- diagnostics: `doctor`
 - reports: `createReport`, `reports.create`, `reports.redact`, `reports.summarize`
 - command discovery: `commands`, `describe`, `help`
-- primitives: `session.bootstrap`, `threads.*`, `messages.*`, `files.*`, `modes.set`, `tools.select`, `response.copy`
+- primitives: `session.bootstrap`, `threads.*`, `messages.*`, `artifacts.*`, `files.preflight`, `files.attach`, `files.downloadLatest`, `projects.sources.list`, `projects.sources.planAdd`, `projects.sources.add`, `modes.set`, `modes.get`, `tools.select`, `response.copy`
+
+`doctor` returns a normal `CommandResult` whose `data.checks` map is extensible. Scenario checks such as `existing_tab`, `artifacts`, `file_preflight`, `localization`, and `reports` may add optional `code`, `blockerKind`, `nextCommand`, and JSON `details` fields to individual check entries while preserving the existing `status`, `message`, and `remediation` fields.
+
+## Host-Local Attachment Paths
+
+Attachment paths are interpreted on the machine running the Node backend. Use an absolute path in that host operating system's native form. On macOS/Linux/WSL, use paths such as `/example/user/file.pdf`, `/home/you/file.pdf`, or `/mnt/c/example/user/file.pdf`. On Windows backend hosts, use fully qualified paths such as `C:\Users\you\file.pdf` or UNC paths such as `\\server\share\file.pdf`. Drive-relative paths like `C:Users\you\file.pdf`, root-relative paths like `\tmp\file.pdf`, and Windows-looking paths sent to a POSIX backend are rejected before filesystem access.
+
+Use `files.preflight` for non-mutating local validation before browser upload workflows. It validates absolute paths, existence, readability, file-vs-directory status, configurable per-file and total byte limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses. Zero-byte files are blocked before browser interaction because ChatGPT rejects empty attachments. By default the command does not open ChatGPT, perform a live upload, read file contents for MIME detection, or return file-content fingerprints. Callers may pass `includeHashes: true` to include SHA-256 metadata for local diagnostics; file contents are never returned. `askWithFiles` and `files.attach` run the same preflight before upload attempts so obvious local file failures stop before browser interaction.
+
+`files.attach` accepts `includeDiagnostics: true` to return metadata-only upload diagnostics in `data.diagnostics`: the preflight result plus the browser input's selected file names and sizes when the DOM exposes them. Pair `includeDiagnostics: true` with `includeHashes: true` when diagnosing whether a non-empty local file became an empty browser-side `File`; do not persist these diagnostics in public reports unless the user has approved content fingerprint metadata.
+
+## Project Sources
+
+Project Sources V1 is a narrow visible-UI surface for ChatGPT Project URLs such as `https://chatgpt.com/g/g-p-.../project`.
+
+- `projects.sources.list` opens or claims the Project Sources UI and returns source names plus coarse statuses only.
+- `projects.sources.planAdd` validates explicit local file paths with the same metadata-only preflight used by `files.preflight`, batches the upload plan, and does not open ChatGPT.
+- `projects.sources.add` is append-only and requires `confirmMutation: true`; without it, the command returns a `needs_confirmation` blocker with the dry-run plan.
+
+The implementation normalizes nested project chat URLs back to the project page before operating. It does not delete, replace, sync repository trees, read cookies/storage/auth headers, call private ChatGPT endpoints, or read source file contents while planning. Confirmed upload uses visible browser file chooser primitives and diffs before/after source names to report added sources.
+
+## Generated Artifacts
+
+Generated images are represented as visible artifacts, not assistant text. A
+ChatGPT image-only result can be complete even when `messages.readLatest` returns
+`not_found` and `assistantTurnCount` is `0`.
+
+Use the artifact primitives for this surface:
+
+- `artifacts.listLatest` detects visible generated artifacts.
+- `artifacts.wait` waits for a generated artifact to appear and stabilize.
+- `artifacts.downloadLatest` downloads via a visible artifact affordance, or
+  saves a visible image source when no browser download event fires.
+
+When a claimed user-open ChatGPT tab stalls bridge page inspection, artifact
+commands may recover by opening the same saved `https://chatgpt.com/c/...`
+conversation in a temporary bridge-owned tab and using the bridge `pageAssets`
+capability to inventory and bundle the latest non-SVG image asset. This is an
+implementation detail of the TypeScript runtime; the wire command and result
+shape are unchanged.
+
+`files.downloadLatest` preserves the existing file-link behavior and falls back
+to generated-artifact download only when no conventional ChatGPT file affordance
+is visible. Artifact failures are reported as structured blockers such as
+`artifact_unavailable`, `artifact_selector_drift`, or
+`artifact_download_unavailable`, not protocol errors.
 
 `session.bootstrap` accepts `existingTab` for explicit reuse of a user-open Chrome tab before any read or prompt step. The wire shape is shared by TypeScript and Python:
 
@@ -166,7 +215,7 @@ Important: in Codex, `globalThis.agent` is not present until the Chrome plugin r
 The live Chrome bootstrap is:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```
@@ -219,6 +268,49 @@ Python SDK -> stdio relay -> bridge-hosted Node backend -> Codex Chrome bridge -
 
 The smoke covers `runner.run`, `runner.run_streamed`, `responses.create`, named `run_plan`, and redacted `reports.create`. It writes redacted JSON summaries and does not persist raw prompt/response content by default.
 
+## Untrusted Output And Integrity
+
+Assistant output captured from ChatGPT is untrusted third-party content. Runner results with non-empty `output_text` expose `data.untrustedOutput`; Responses-shaped results expose the same object at `browser_control.untrustedOutput`.
+
+The envelope schema is:
+
+```json
+{
+  "schemaVersion": "chatgpt.browser_control.untrusted_output_return.v1",
+  "trusted": false,
+  "source": "chatgpt",
+  "capturedAt": "2026-06-06T00:00:00.000Z",
+  "contentSha256": "8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4",
+  "contentBytes": 2,
+  "inline": true,
+  "maxInlineBytes": 12000,
+  "rendered": "UNTRUSTED OUTPUT RETURN ENVELOPE\n..."
+}
+```
+
+Use `rendered` when handing the captured answer to another agent, tool, or prompt. It places routing and hash metadata before the body, tells the consumer not to execute embedded instructions, and uses a markdown fence longer than any backtick run inside the content. Outputs larger than the inline byte guard are not inlined; the envelope points at the persisted output path when one is available.
+
+Run report creation writes a sibling `*.meta.json` sidecar by default:
+
+```json
+{
+  "schemaVersion": "chatgpt.browser_control.integrity.v1",
+  "target": {
+    "path": "reports/runs/run.json",
+    "bytes": 123,
+    "sha256": "..."
+  },
+  "output": {
+    "untrusted": true,
+    "bytes": 2,
+    "sha256": "..."
+  },
+  "inputs": []
+}
+```
+
+The sidecar hashes the report file, normalized prompt text when available, untrusted output text when available, and configured input file paths. Consumers that cross a process or trust boundary should rehash the sidecar targets before acting on the report. Report writes are atomic and refuse to overwrite an existing target path.
+
 ## Contract Fixtures
 
 Shared fixtures live under:
@@ -231,7 +323,9 @@ Required gates:
 
 ```bash
 npm run contract:validate
+npm run docs:drift
 npm run parity:fixtures
+npm run parity:suite
 npm run test:backend-conformance
 ```
 

package/references/language-coverage.md

@@ -0,0 +1,142 @@
+# Language Coverage & Capture Tracker
+
+The full set of languages ChatGPT exposes in **Settings → General → Language** (captured
+2026-06-09), with a rough total-speaker estimate and capture status. Use this to track the
+localization rollout described in [`localization.md`](./localization.md). Strings are
+stored per-locale under `src/dom/locale/<bcp47>.ts`.
+
+- Speaker counts are **crude guesstimates** (native + second-language, rounded), not
+  researched figures. They exist only to prioritize the rollout.
+- `bcp47` is the suggested per-locale file name. Regional variants ChatGPT lists separately
+  (Spanish, French, Portuguese, Chinese) are separate registry entries — capture the
+  larger-reach variant first; the others can be filled later or alias the base.
+- Status: ✅ done · 🟡 in progress · ⬜ pending.
+
+## Capture queue — top 15 by crude speaker count
+
+English is the canonical baseline (already in the registry), so the queue below is the top
+15 **non-English** languages by rough world speaker count. Order is a best-effort
+guesstimate; the tail (≈#11–15) is close and easily reordered.
+
+| # | Language | Native | bcp47 | ~Speakers | Status |
+|---|---|---|---|---|---|
+| — | English (US) | English (US) | `en-US` | ~1.5B | ✅ baseline |
+| 1 | Chinese (Simplified) | 简体中文 | `zh-Hans` | ~1.1B | ✅ |
+| 2 | Hindi | हिन्दी | `hi` | ~600M | ✅ |
+| 3 | Spanish (Latin America) | español (Latinoamérica) | `es-419` | ~450M | ✅ |
+| 4 | Arabic | العربية | `ar` | ~400M | ✅ |
+| 5 | French (France) | français (France) | `fr-FR` | ~300M | ✅ |
+| 6 | Bengali | বাংলা | `bn` | ~270M | ✅ |
+| 7 | Portuguese (Brazil) | português (Brasil) | `pt-BR` | ~260M | ✅ |
+| 8 | Russian | русский | `ru` | ~255M | ✅ |
+| 9 | Urdu | اردو | `ur` | ~230M | ✅ |
+| 10 | Indonesian | Indonesia | `id` | ~200M | ✅ |
+| 11 | German | Deutsch | `de` | ~135M | ✅ |
+| 12 | Punjabi | ਪੰਜਾਬੀ | `pa` | ~130M | ✅ |
+| 13 | Japanese | 日本語 | `ja` | ~125M | ✅ |
+| 14 | Marathi | मराठी | `mr` | ~95M | ✅ |
+| 15 | Turkish | Türkçe | `tr` | ~85M | ✅ |
+
+> Note: this ranks by **raw speaker count** as requested. If you'd rather weight by likely
+> ChatGPT user base, the order would tilt toward European/East-Asian locales (Japanese,
+> German, French, Spanish, Portuguese, Korean, Italian) and away from Punjabi/Marathi/Bengali.
+
+## Full language list
+
+| Language | Native | bcp47 | ~Speakers | Status |
+|---|---|---|---|---|
+| English (US) | English (US) | `en-US` | ~1.5B | ✅ |
+| Amharic | አማርኛ | `am` | ~60M | ✅ |
+| Arabic | العربية | `ar` | ~400M | ✅ |
+| Bulgarian | български | `bg` | ~8M | ✅ |
+| Bengali | বাংলা | `bn` | ~270M | ✅ |
+| Bosnian | bosanski | `bs` | ~3M | ✅ |
+| Catalan | català | `ca` | ~10M | ✅ |
+| Czech | čeština | `cs` | ~11M | ✅ |
+| Danish | dansk | `da` | ~6M | ✅ |
+| German | Deutsch | `de` | ~135M | ✅ |
+| Greek | Ελληνικά | `el` | ~13M | ✅ |
+| Spanish (Latin America) | español (Latinoamérica) | `es-419` | ~450M | ✅ |
+| Spanish (Spain) | español (España) | `es-ES` | ~47M | ✅ |
+| Estonian | eesti | `et` | ~1M | ✅ |
+| Persian | فارسی | `fa` | ~80M | ✅ |
+| Finnish | suomi | `fi` | ~5.5M | ✅ |
+| French (Canada) | français (Canada) | `fr-CA` | ~10M | ✅ |
+| French (France) | français (France) | `fr-FR` | ~300M | ✅ |
+| Gujarati | ગુજરાતી | `gu` | ~60M | ✅ |
+| Hindi | हिन्दी | `hi` | ~600M | ✅ |
+| Croatian | hrvatski | `hr` | ~5M | ✅ |
+| Hungarian | magyar | `hu` | ~13M | ✅ |
+| Armenian | հայերեն | `hy` | ~7M | ✅ |
+| Indonesian | Indonesia | `id` | ~200M | ✅ |
+| Icelandic | íslenska | `is` | ~0.4M | ✅ |
+| Italian | italiano | `it` | ~65M | ✅ |
+| Japanese | 日本語 | `ja` | ~125M | ✅ |
+| Georgian | ქართული | `ka` | ~4M | ✅ |
+| Kazakh | қазақ тілі | `kk` | ~13M | ✅ |
+| Kannada | ಕನ್ನಡ | `kn` | ~60M | ✅ |
+| Korean | 한국어 | `ko` | ~80M | ✅ |
+| Lithuanian | lietuvių | `lt` | ~3M | ✅ |
+| Latvian | latviešu | `lv` | ~2M | ✅ |
+| Macedonian | македонски | `mk` | ~2M | ✅ |
+| Malayalam | മലയാളം | `ml` | ~38M | ✅ |
+| Mongolian | монгол | `mn` | ~5M | ✅ |
+| Marathi | मराठी | `mr` | ~95M | ✅ |
+| Malay | Bahasa Melayu | `ms` | ~80M | ✅ |
+| Burmese | မြန်မာ | `my` | ~43M | ✅ |
+| Norwegian Bokmål | norsk bokmål | `nb` | ~5M | ✅ |
+| Dutch | Nederlands | `nl` | ~25M | ✅ |
+| Punjabi | ਪੰਜਾਬੀ | `pa` | ~130M | ✅ |
+| Polish | polski | `pl` | ~45M | ✅ |
+| Portuguese (Brazil) | português (Brasil) | `pt-BR` | ~210M | ✅ |
+| Portuguese (Portugal) | português (Portugal) | `pt-PT` | ~10M | ✅ |
+| Romanian | română | `ro` | ~24M | ✅ |
+| Russian | русский | `ru` | ~255M | ✅ |
+| Slovak | slovenčina | `sk` | ~5M | ✅ |
+| Slovenian | slovenščina | `sl` | ~2.5M | ✅ |
+| Somali | Soomaali | `so` | ~22M | ✅ |
+| Albanian | shqip | `sq` | ~7.5M | ✅ |
+| Serbian | српски | `sr` | ~9M | ✅ |
+| Swedish | svenska | `sv` | ~10M | ✅ |
+| Swahili | Kiswahili | `sw` | ~120M | ✅ |
+| Tamil | தமிழ் | `ta` | ~85M | ✅ |
+| Telugu | తెలుగు | `te` | ~95M | ✅ |
+| Thai | ไทย | `th` | ~60M | ✅ |
+| Tagalog (Filipino) | Tagalog | `tl` | ~70M | ✅ |
+| Turkish | Türkçe | `tr` | ~85M | ✅ |
+| Ukrainian | українська | `uk` | ~40M | ✅ |
+| Urdu | اردو | `ur` | ~230M | ✅ |
+| Vietnamese | Tiếng Việt | `vi` | ~85M | ✅ |
+| Chinese (Simplified) | 简体中文 | `zh-Hans` | ~1.1B | ✅ |
+| Chinese (Traditional, Hong Kong) | 繁體中文（香港） | `zh-HK` | ~85M | ✅ |
+| Chinese (Traditional, Taiwan) | 繁體中文（台灣） | `zh-TW` | ~23M | ✅ |
+
+## Automated capture
+
+Use the repository capture script to drive the visible ChatGPT UI through Settings → General
+→ Language, then open the composer Intelligence picker and record the localized labels:
+
+```bash
+npm run capture:intelligence-locales -- --auto-switch --all --if-missing open
+```
+
+The script uses the native language names from this tracker, verifies the rendered
+`document.documentElement.lang`, writes JSONL evidence under
+`outputs/intelligence-locale-captures/`, and restores the initially selected language by
+default. It does not write cookies, storage, or private browser state directly; if ChatGPT
+changes the settings or picker DOM, the run should emit a blocker record instead of guessing.
+
+## Capture procedure (per language)
+
+1. Switch ChatGPT **Settings → General → Language** to the target, reload, and confirm via
+   `document.documentElement.lang` + visible text.
+2. Read static controls (composer, add-files, new chat, current model label) via JS.
+3. Open the model switcher and the `+` menu with **real** clicks (Radix menus ignore
+   synthetic `.click()`) and read the menu items → mode + tool labels.
+4. Open search → placeholder; observe a conversation → copy-response + response-actions.
+   `stopControl` is only present mid-generation; login/captcha/rate-limit copy needs a
+   logged-out/limited state — these may lag and rely on the English fallback + the
+   `selector_drift` safety net until captured.
+5. Write the verified strings to `src/dom/locale/<bcp47>.ts` and register it in
+   `src/dom/locale/index.ts`. Build + test + bundle + sync.
+6. Restore the account language to English (US) when the run is complete.