fix(document-api): improve AI tool definitions, add block refs, and fix formatting extraction#2511
Open
fix(document-api): improve AI tool definitions, add block refs, and fix formatting extraction#2511
Conversation
The create response now includes a ref handle that can be passed directly to superdoc_format or superdoc_edit without a search step. Before: create → search → format (3 calls) After: create → format using ref from response (2 calls) The ref is minted from the created block's nodeId + text range + document revision. It's a V4 block-scoped ref that resolves to the full text range of the created content.
- Removed "optional styleId" reference (styleId was removed) - Changed "search after create" to "use ref from response" - Separated heading vs paragraph formatting rules - Added create ref to targeting section - Removed contradictory "search before editing" for create flow
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
… for insert and replace operations
tupizz
changed the title
…mbering
- Apply fontFamily/fontSize/color/bold from nearby body text blocks via
runProperties + textStyle marks + sdPreserveRunPropertiesKeys meta so the
style engine cascade respects inline overrides on heading-styled paragraphs.
- Set numberingProperties {numId:'0'} on created headings to suppress
outline numbering inherited from template heading styles.
- Update superdoc_create tool description: LLM MUST call superdoc_format
after create with bold:false and body-text formatting values.
- Use editor.dispatch() instead of editor.view?.dispatch() for consistency
with the plan engine executor dispatch path.
…minting Remove findNearbyFormatting, applyFormattingToCreatedBlock, and mark-copying from insertHeadingAt/insertParagraphAt. These added ~200 lines of complexity but didn't work: the style engine cascade overrides inline marks for headings, and the code incorrectly copied bold from title paragraphs. The LLM handles formatting correctly via superdoc_format after create, guided by tool descriptions. Server-side auto-formatting was a wrong turn. Keep: numberingProperties suppression, mintBlockRef, block refs in blocks.list.
- Headings: set fontFamily, fontSize (scaled up from body), color, bold:true - Paragraphs: set fontFamily, fontSize, color, bold:false - Always use color #000000 (never copy from blocks — some have white text) - Call blocks without limit/filters to get full document context - Get fontFamily/fontSize from body text blocks, not info defaults
Restore pre-existing generated files to main versions. New browser SDK files (package.json, dispatch.ts, validate.ts, etc.) moved to local-only for a separate PR.
- Only read fontFamily/fontSize/color from textStyle marks and bold from bold marks. Prevents highlight mark background colors from being reported as text color in blocks.list. - Remove "always use color #000000" restriction from create tool description and system prompt since blocks data now reports correct text colors. - Revert unrelated formatting change in apps/create/src/index.ts. - Revert orphaned findNearbyMarks defensive guard (was added for removed auto-formatting code).
…k-with-improvements
tupizz
changed the title
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 390a130c19
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
packages/super-editor/src/document-api-adapters/plan-engine/blocks-wrappers.ts
Outdated
Show resolved
Hide resolved
packages/super-editor/src/document-api-adapters/__conformance__/schema-validator.ts
Show resolved
Hide resolved
LLMs interpret "do not add limit/filters" as "set them to zero/empty" rather than omitting them. Normalize these values before validation: limit=0 is treated as "all blocks", empty nodeTypes as "no filter". Also simplify system prompt wording to "just pass action, nothing else".
…val tests - Fix list creation prompt: use BlockRange target to create one contiguous list instead of calling superdoc_list per paragraph. - Add set_type guidance for bullet/numbered conversion. - Expand superdoc_list tool description with key actions. - Restore neutral replace operation description for human docs (agent-directive language stays in INTENT_GROUP_META.edit). - Add eval tests for multi-item list creation and list conversion.
…guidance The BlockRange target converts ALL paragraphs between from and to. If the LLM places the first item mid-document and the rest at the end, the entire document gets converted into a numbered list. Updated prompt to explicitly require: create all items at the same location using documentEnd + nodeId chaining, ensure they are consecutive before applying the range.
…g styles - Introduced a new workflow to create an "Exhibit X" page that matches the style of an existing "Exhibit A" page, including formatting and summary. - Enhanced assertions to validate the creation and formatting of the new page, ensuring proper tool usage and style replication.
- Added a new utility function `dispatchWithRetry` to handle automatic reference revision bumps on `REVISION_MISMATCH` errors during SDK tool dispatch. - Updated `convertTool` and `runAgentLoop` functions to utilize `dispatchWithRetry`, enhancing resilience against transient errors. - Modified customer workflow test to simplify task description.
- Introduced `intentGroup` and `intentAction` for the table creation operation in operation definitions. - Updated intent dispatch logic to handle the new `table` action, allowing for seamless execution of table creation commands. - Enhanced system prompt documentation to include guidance on avoiding overlap errors during text mutations.
…ascade extractBlockFormatting now calls resolveRunProperties() from the style engine instead of only reading inline textStyle marks. This resolves the full cascade (doc defaults → Normal style → paragraph style → inline overrides) so blocks.list always reports accurate fontFamily, fontSize, color, bold, and underline values. Previously, documents with style-driven formatting (no inline marks) reported no fontFamily/fontSize for body paragraphs. The LLM then copied the heading's 20pt size for body text, producing wrong results.
…engine cascade" This reverts commit bb074f6.
andrii-harbour
requested changes
Mar 27, 2026
Contributor
andrii-harbour
left a comment
andrii-harbour
left a comment
There was a problem hiding this comment.
Nicely done! Just a few comments and UX suggestions
examples/collaboration/ai-node-sdk/client/src/components/landing/create-room-form.tsx
Show resolved
Hide resolved
examples/collaboration/ai-node-sdk/client/src/components/shared/sidebar-toggle.tsx
Show resolved
Hide resolved
packages/super-editor/src/document-api-adapters/__conformance__/schema-validator.ts
Show resolved
Hide resolved
packages/super-editor/src/document-api-adapters/plan-engine/blocks-wrappers.ts
Outdated
Show resolved
Hide resolved
- Fix ref length: use computeTextContentLength instead of textContent.length to correctly count inline atoms (tabs, images) in block refs. Prevents refs from undercovering blocks with non-text inline nodes. - Remove #000000 color default: let color be absent when no explicit color mark exists. Filter OOXML "auto" sentinel value. Prevents propagating black to documents with themed non-black defaults. - Add unit tests for normalizeBlocksListInput (limit=0, nodeTypes=[]). - Strengthen list conversion eval assertion to verify tool action. - Add source comment for text:v4 ref prefix in eval utils.
Traces: abort previous SSE connection on re-call and on unmount, add event deduplication in state updaters. Prevents React StrictMode double-mount from producing duplicate trace entries. Quick actions: clicking "Use sample document" or "Start blank" now populates the form state instead of immediately creating the room. Users can adjust model, edit mode, and display name before creating. Selected quick action shows visual feedback (highlighted button, status text in drop zone).
…k-with-improvements # Conflicts: # pnpm-lock.yaml
- Introduced new operations for managing permission ranges: create, get, list, remove, and updatePrincipal. - Added protection operations: get, setEditingRestriction, and clearEditingRestriction. - Updated documentation to reflect these changes, including new reference pages and operation details. - Enhanced existing API documentation with new tables for permission ranges and protection operations.
- Enhanced the documentation for creating paragraphs, headings, and tables in the document API. - Clarified the required formatting steps after creation, specifying the need for two format calls: one for character styling and another for paragraph alignment. - Improved examples for body paragraphs and headings to ensure correct usage of inline properties and alignment settings.
- Updated operation definitions to specify that paragraph actions must use a flat block target format and cannot include selection-like structures. - Added documentation in the system prompt to emphasize that format calls must be sequential and that all created items should be formatted, addressing potential issues with parallel calls and partial failures.
…d headings - Updated operation definitions to clarify the formatting requirements for body paragraphs, emphasizing the exclusion of underline styles and the correct inline properties. - Enhanced documentation in the system prompt to specify the necessary attributes for body text and headings, ensuring consistent formatting practices across the API.
…k-with-improvements
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes AI tool call quality by adding ref handles to API responses, fixing formatting extraction bugs, correcting tool descriptions, and rewriting the system prompt.
Problems fixed
{kind:'text', blockId, range:{start,end}}but the correct format is{kind:'selection', start:{kind:'text', blockId, offset}, end:{kind:'text', blockId, offset}}.blockId,start,endin edit tool schemas confused models into building targets manually instead of using refs.extractBlockFormattingreadcolorfrom all marks includinghighlightmarks, reporting#FFFFFFas text color when paragraphs had white highlight backgrounds.superdoc_listonce per item, creating N independent lists instead of one.set_typeaction for converting bullet/numbered wasn't mentioned in prompt or tool description.limit: 0andnodeTypes: []to mean "all."Changes
Block refs in
blocks.list— Each non-empty block now returns arefhandle covering its full text. Agents pass this directly tosuperdoc_editorsuperdoc_formatwithout searching first.Ref from
superdoc_create— Create responses include areffor the new block, enabling immediate formatting without a search step (create > format instead of create > search > format).Fixed
extractBlockFormatting— Only readsfontFamily/fontSize/colorfromtextStylemarks andboldfromboldmarks. No longer picks up highlight background colors.Fixed target descriptions — Corrected the fallback
targetdescription in codegen from wrong{kind:'text'}format to correct{kind:'selection'}format.Tool description improvements:
superdoc_edit: guides towardrefusage, explains that search refs are partial while block refs cover full textsuperdoc_create: documents the ref in the response, required format-after-create workflow with examplessuperdoc_get_content: mentions that blocks returns ref handles and formatting datasuperdoc_list: expanded description with key actions (create, set_type, insert, indent, outdent, detach)List creation fix — Prompt now instructs creating all paragraphs first, then one
superdoc_listcall with aBlockRangetarget to produce a single contiguous list. Addedset_typeguidance for bullet/numbered conversion.Heading numbering fix —
insertHeadingAtsetsnumberingProperties: { numId: '0', ilvl: '0' }to suppress outline numbering from template heading styles.Tolerant input normalization —
blocks.listnow normalizeslimit: 0to "all blocks" andnodeTypes: []to "no filter" before validation.Hidden confusing params —
blockId,start,end,offsetflat params hidden from agent tool schemas (kept for CLI).System prompt rewrite — Blocks-first workflow, concrete formatting examples for paragraphs and headings, correct list creation with
BlockRangetargets, list type conversion, sequential create ordering via nodeId.Schema validator — Added
description,minimum,maximumto supported keywords for contract conformance tests.Files changed
operation-definitions.ts,schemas.tsblocks.types.ts,create.types.tsrefandcolorfieldsgenerate-intent-tools.mjsoperation-params.tsblocks/blocks.tssystem-prompt.mdinsertHeadingAt.jsblocks-wrappers.tscreate-wrappers.tsschema-validator.tsdescription/minimum/maximumexecution.yamlapps/docs/document-api/reference/*Test plan
pnpm --filter super-editor testpasses