writing-assistance-apis

Writing Assistance APIs

Procedures

Step 1: Identify the browser integration surface

1. Inspect the workspace for browser entry points, UI handlers, and any existing AI abstraction layer.
2. Execute node scripts/find-writing-assistance-targets.mjs . to inventory likely frontend files and existing Summarizer, Writer, or Rewriter usage 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 route, component, or user-requested feature surface.
5. If the inventory still leaves multiple plausible frontend targets, stop and ask which app should receive the Writing Assistance 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 choose the right surface

1. Read references/writing-assistance-reference.md before writing code.
2. Read references/examples.md when the feature needs a session shape for monitoring downloads, batch output, streaming output, or cancellation.
3. Read references/compatibility.md when preview flags, browser channels, hardware requirements, or iframe constraints matter.
4. Read references/troubleshooting.md when availability checks, creation, streaming, or session cleanup fail.
5. Verify that the feature runs in a secure Window context and that the relevant permissions-policy feature allows access from the current frame.
6. Choose the narrowest surface that matches the task:
   • Summarizer for article, document, or conversation summaries.
   • Writer for generating new text from a short prompt or writing task.
   • Rewriter for transforming existing text while preserving its intent.
7. If the feature must run in a worker, on the server, or against a remote model provider, stop and explain the platform mismatch.
8. If the project uses TypeScript, add or preserve typings that cover the specific browser APIs used by the feature.

Step 3: Implement a guarded session wrapper

1. Read assets/writing-assistance-session.template.ts and adapt it to the framework, state model, and file layout in the workspace.
2. Gate session creation behind the API's availability() method using the same create options that will be used at runtime.
3. Treat availability() as a capability check, not a guarantee that creation will succeed without user interaction or download time.
4. Create sessions only after user activation when creation may initiate a download.
5. Use the monitor option during create() when the UI needs download progress.
6. Use AbortController for cancelable create and run calls, and call destroy() when the session is no longer needed.
7. Recreate the session instead of mutating options after creation; session options are fixed per instance.
8. If the feature lives in a cross-origin iframe, require explicit delegation for each API that the frame needs.

Step 4: Wire UX and fallback behavior

1. Surface distinct states for missing APIs, unavailable devices, downloadable or downloading models, ready sessions, in-flight generation, and aborted work.
2. Keep a non-AI fallback for unsupported browsers, blocked frames, or devices that do not meet the current preview requirements.
3. Strip or normalize HTML before summarization or rewriting when the source text comes from rendered page content.
4. Use the batch methods when the feature needs the full result before continuing, and use the streaming methods when the UI should reveal output incrementally.
5. Pass sharedContext only for persistent session-wide guidance, and pass per-call context only for request-specific background detail.
6. Keep language options explicit when the feature depends on supported input, context, or output languages.
7. Do not route generic chatbot, tool-calling, or open-ended assistant tasks through these APIs; switch to the Prompt API or another approved capability when the task is not summarization, writing, or rewriting.

Step 5: Validate behavior

1. Execute node scripts/find-writing-assistance-targets.mjs . to confirm that the intended app boundary and API markers still resolve to the edited integration surface.
2. Verify feature detection, secure-context checks, and availability() behavior before debugging deeper runtime failures.
3. Test at least one batch call and one streaming call when the feature exposes both modes.
4. Confirm that cancellation stops generation cleanly and that destroyed sessions are not reused.
5. If the target environment depends on preview browser flags or channel-specific behavior, confirm the required browser state from references/compatibility.md before treating failures as application bugs.
6. Run the workspace build, typecheck, or tests after editing.

Error Handling

• If Summarizer, Writer, or Rewriter is missing, keep a non-AI fallback and confirm that the environment satisfies the browser and preview requirements before changing product logic.
• If availability() returns downloadable or downloading, require user-driven session creation before promising that generation is ready.
• If create() throws NotAllowedError, check permissions-policy constraints, missing user activation for downloads, browser policy restrictions, or user rejection.
• If create() or a run call throws NotSupportedError, align the requested languages, output format, summary type, tone, or length with the browser's supported combinations.
• If a call throws QuotaExceededError, shrink sharedContext, per-call context, or the user input before retrying.
• If the feature must run in a worker or server context, stop and explain that the Writing Assistance APIs are window-only browser APIs.