proofreader-api — Claude Code skill for the browser Proofreader API

---
name: proofreader-api
description: Implements and debugs browser Proofreader API integrations in JavaScript or TypeScript web apps. Use when adding Proofreader availability checks, monitored model downloads, proofread flows, correction metadata handling, or permissions-policy checks for built-in proofreading. Don't use for generic prompt engineering, server-side LLM SDKs, or cloud AI services.
license: MIT
metadata:
  author: webmaxru
  version: "1.4"
---

# Proofreader API

## Procedures

**Step 1: Identify the browser integration surface**
1. Inspect the workspace for browser entry points, editor or form UI handlers, and any existing built-in AI abstraction layer.
2. Execute `node scripts/find-proofreader-targets.mjs .` to inventory likely frontend files and existing Proofreader API markers when a Node runtime is available.
3. If a Node runtime is unavailable, inspect the nearest `package.json`, HTML entry point, and framework bootstrap files manually to identify the browser app boundary.
4. If the workspace contains multiple frontend apps, prefer the app that contains the active text-entry route, editor component, or user-requested proofreading surface.
5. If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the Proofreader API integration.
6. If the project is not a browser web app, stop and explain that this skill does not apply.

**Step 2: Confirm API viability and option shape**
1. Read `references/proofreader-reference.md` before writing code.
2. Read `references/examples.md` when the feature needs session creation, download monitoring, result rendering, or quota-aware preflight.
3. Read `references/compatibility.md` when preview flags, browser channels, hardware requirements, iframe constraints, or browser-specific option gaps matter.
4. Read `references/troubleshooting.md` when feature detection, availability, creation, or proofreading fails.
5. Verify that the feature runs in a secure `Window` context and that the current frame is allowed to use the `proofreader` permissions-policy feature.
6. Match `availability()` and `create()` option shapes exactly, especially for `expectedInputLanguages`, `includeCorrectionTypes`, `includeCorrectionExplanations`, and `correctionExplanationLanguage` when the target browser supports them.
7. If the feature must run in a worker, on the server, or through a generic text-generation interface, stop and explain the platform mismatch.
8. If the project uses TypeScript, add or preserve typings that cover only the Proofreader API surface actually used by the feature.

**Step 3: Implement a guarded proofreader wrapper**
1. Read `assets/proofreader-session.template.ts` and adapt it to the framework, state model, and file layout in the workspace.
2. Gate session creation behind `Proofreader.availability()` using the same non-transient create options that the runtime session will use.
3. Treat `availability()` as a capability check, not a guarantee that creation will succeed without user activation, download time, or policy approval.
4. Create sessions only after user activation when the target browser may need to start a model download.
5. Use the `monitor` option during `create()` when the UI needs download progress.
6. Use `AbortController` for cancelable create or proofread calls, and call `destroy()` when the proofreading UI no longer needs the session.
7. Recreate the session instead of mutating option-dependent behavior after creation; session options are fixed per instance.
8. If the task requires correction labels or explanations, keep browser-specific fallbacks explicit instead of assuming every preview implements the full specification option set.

**Step 4: Wire UX and result handling**
1. Surface distinct states for missing APIs, unavailable devices, downloadable or downloading models, ready sessions, in-flight proofreading, canceled work, and hard failures.
2. Keep a non-AI fallback for unsupported browsers, blocked frames, or devices that do not meet the current preview requirements.
3. Render both `correctedInput` and the structured `corrections` array when the product needs visible diffs or selective acceptance.
4. Use `measureInputUsage()` before expensive proofreading only when the feature needs quota-aware behavior or large-input preflight.
5. Keep expected input languages explicit when the feature depends on supported language routing.
6. Do not use Proofreader as a general chat, summarization, or rewriting surface; switch to the correct built-in API when the task is not proofreading.

**Step 5: Validate behavior**
1. Execute `node scripts/find-proofreader-targets.mjs .` to confirm that the intended app boundary and Proofreader markers still resolve to the edited integration surface.
2. Verify feature detection, secure-context checks, permissions-policy access, and `availability()` behavior before debugging deeper runtime failures.
3. Test session creation with the exact options used in production, including download progress handling when the environment needs an initial model download.
4. Confirm that `proofread()` returns the expected `correctedInput` and correction ranges for representative user text.
5. If the integration uses `measureInputUsage()`, confirm that large inputs are rejected or trimmed before the browser throws quota-related failures.
6. Confirm that cancellation stops work cleanly and that destroyed sessions are not reused.
7. If the target environment depends on preview flags, origin trials, or channel-specific behavior, confirm the required browser state from `references/compatibility.md` before treating failures as application bugs.
8. Run the workspace build, typecheck, or tests after editing.

## Error Handling
* If `Proofreader` is missing, keep a non-AI fallback and confirm that the environment satisfies the secure-context, browser, and preview requirements before changing product logic.
* If `availability()` returns `downloadable` or `downloading`, require user-driven session creation before promising that proofreading is ready.
* If `create()` or `proofread()` throws `NotAllowedError`, check permissions-policy constraints, missing user activation for downloads, browser policy restrictions, or user rejection.
* If `create()` or `proofread()` throws `NotSupportedError`, align the requested languages and option set with the browser's supported combinations and remove unsupported preview-only assumptions.
* If creation fails with `OperationError`, `UnknownError`, or another runtime exception, retry once only after confirming that device eligibility, storage, and browser flags still match `references/compatibility.md`.
* If the feature must run in a worker or server context, stop and explain that the Proofreader API is a window-only browser API.