feat(sdk): browser SDK + AI tool quality improvements

[tupizz]

Summary

This PR improves AI tool call quality and efficiency by fixing tool definitions, adding ref handles to API responses, and introducing the browser SDK for in-browser AI agent workflows.

Problem

AI agents (LLMs) using SuperDoc tools were inefficient and error-prone:

• Wrong target format: Models tried {kind:"text"} instead of {kind:"selection"} due to incorrect fallback descriptions
• Partial replacements: Search refs only cover matched text, so "shorten this paragraph" replaced part of the text and left the rest
• Unnecessary steps: Creating content required 3 calls (create → search → format) instead of 1
• Styling mismatch: New headings/paragraphs used template defaults (Aptos Display, blue) instead of the document's actual font (Calibri, black)
• Reverse ordering: Multiple sequential creates at the same anchor appeared in reverse order
• Confusing flat params: blockId, start, end in edit tools confused models into trying flat params instead of refs

Changes

Block refs in blocks.list — Each non-empty block now returns a ref handle covering its full text. Agents can pass this directly to superdoc_edit replace or superdoc_format without searching first. This is the key enabler for efficient "rewrite this paragraph" flows.

Ref from superdoc_create — Create responses include a ref for the new block, enabling immediate formatting without a search step.

Auto-formatting on create — createParagraphWrapper and createHeadingWrapper automatically inherit fontFamily + color (and fontSize for paragraphs) from nearby blocks. New content matches the document's visual style with zero extra LLM calls.

Fixed target descriptions — Corrected the fallback target description from {kind:'text', blockId, range:{start,end}} (wrong) to {kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}} (correct). This was the root cause of models trying wrong target formats.

Tool description improvements —

• superdoc_edit: guides toward ref usage, warns that search refs are partial, block refs are full
• superdoc_create: removed manual format instructions (auto-formatting handles it), added ordering guidance
• superdoc_get_content: mentions that blocks returns ref handles
• superdoc_list: system prompt includes preset: "disc" example to prevent missing-kind errors

Hidden confusing params — blockId, start, end, offset flat params removed from agent tool schemas (kept for CLI). Pushes models toward ref which is simpler and more reliable.

Browser SDK — New @superdoc-dev/sdk-browser package with:

• dispatchSuperDocTool() for in-browser AI agent integration
• Proper envelope param extraction (changeMode, dryRun, force → options, not input)
• Auto-generated intent dispatch and system prompt from codegen
• Tool catalog loaded from bundled JSON

Schema validator fix — Added description, minimum, maximum to supported keywords so contract conformance tests pass with described schema properties.

Mark-copying helpers — findNearbyMarks() shared helper with heading/body preference, parasitic mark filtering, and defensive guard for mock docs.

Efficiency gains

Workflow	Before	After
Create heading	1 call (wrong style)	1 call (correct style)
Create + format paragraph	3 calls (create → search → format)	1 call (auto-formatted)
Create 3 list items	13 calls (with errors)	7 calls
Rewrite/shorten a paragraph	10 calls (wrong targets, retries)	2 calls (blocks → replace with block ref)
Eval pass rate	78% → 96% (before this PR)	99.3%

Files changed

Area	Files	What
Contract	operation-definitions.ts, schemas.ts	Tool descriptions, block ref schema, create output ref
Types	blocks.types.ts, create.types.ts	ref field on BlockListEntry and create results
Codegen	generate-intent-tools.mjs	Fixed target fallback description, ref description
CLI params	operation-params.ts	Hidden flat params from agent tools
Browser SDK	langs/browser/src/*	New package: dispatch, validation, assets
System prompt	system-prompt.md	Workflow guidance, list preset, targeting docs
Editor	insertHeadingAt.js, insertParagraphAt.js	Mark-copying from nearby paragraphs
Helpers	findNearbyMarks.js	Shared mark extraction with style preference
Adapters	blocks-wrappers.ts, create-wrappers.ts	Block refs, auto-formatting on create
Tests	schema-validator.ts	Support description/minimum/maximum keywords

Test plan

• Run pnpm --filter super-editor test — 9527 passed, 0 failed
• Run eval suite — 99.3% pass rate (143/144)
• Manual test: create heading at document start → verify it inherits document font
• Manual test: get blocks → use block ref to replace entire paragraph
• Manual test: create 3 list items → verify correct order and styling

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
SuperDoc	🟢 Ready	View Preview	Mar 21, 2026, 1:24 PM