feat(rich-text): add AI patch finalization API and harden BlockIdExtension (FCT-50714) by mjh-sakh · Pull Request #3781 · factorialco/f0

mjh-sakh · 2026-03-27T06:44:29Z

Description

The One assistant co-creates page documents with users. This PR adds the editor-layer requirements that make that possible:

NotesTextEditorHandle.applyPageDocumentPatch() — the imperative API the frontend co-creation hook calls to apply a structured patch to the open Tiptap instance. This allows AI to work with blocks as per RFC.
Null block ID population — legacy documents store some block IDs as null; patches look up blocks by ID, so null IDs silently fail without this fix. BLOCK_NODE_TYPES_SET is also exported as ReadonlySet to prevent caller mutation.

⚠️ This will trigger "You have changes pending to be saved" on Policies Pages created before BlockIdExtension.

Double-spinner and flicker fix in F0AiChat — the co-creation confirmation protocol uses followUp: true, which produces a tool-call-only assistant message followed immediately by a new empty message. This caused two concurrent spinners and a flickery thinking indicator. Fixed via a useDebouncedFalseEdge hook that smooths the ~10ms gap between followUp requests, and suppressed the empty placeholder when a turn already has active progress.

Implementation details

fix(rich-text): harden BlockIdExtension — populate null block IDs and export ReadonlySet
Null IDs populated via onCreate round-trip in BlockIdExtension/index.tsx.
BLOCK_NODE_TYPES_SET re-exported as ReadonlySet<string>.

feat(rich-text): add AI patch finalization API to NotesTextEditorHandle
Adds applyPageDocumentPatch(patch: PageDocumentPatch): PageDocumentPatchResult to the handle interface. Applies the patch as a Tiptap transaction. Called by factorial's usePageCoCreation hook after receiving a patch from the agent.
⚠️ The factorial frontend co-creation hook has a hard dependency on this method — the f0 package must be published before the factorial PR merges.

fix(ai-chat): suppress double spinner and followUp flicker via useDebouncedFalseEdge
New useDebouncedFalseEdge hook smooths the isLoading gap between CopilotKit followUp requests. Suppresses the empty follow-up assistant placeholder when a turn already has active progress. Debounce delay reduced from 150ms to 40ms (below the 100ms human perception threshold). Must be published before the factorial-agent PR deploys to avoid the known regression.

📦 Dependencies

Has to be merged before https://github.com/factorialco/factorial/pull/93214.

Note: there is another change that has introduced a need for creditWarning translation to frontend. It fails without it.

🏡 Context

💼 Jira — Related to FCT-50714
Frontend implementation: factorial PR feat(pages): add page document co-creation for onboarding policies

Copilot

Copilot wasn't able to review any files in this pull request.

github-actions · 2026-03-27T13:34:23Z

✅ No New Circular Dependencies

No new circular dependencies detected. Current count: 0

github-actions · 2026-03-27T13:36:17Z

📦 Alpha Package Version Published

Use pnpm i github:factorialco/f0#npm/alpha-pr-3781 to install the package

Use pnpm i github:factorialco/f0#1739cfc5bc6f6fc3dd9eafe211ab0f629c51c8de to install this specific commit

github-actions · 2026-03-27T13:36:36Z

🔍 Visual review for your branch is published 🔍

Here are the links to:

github-actions · 2026-03-27T13:37:56Z

Coverage Report for packages/react

Status	Category	Percentage	Covered / Total
🔵	Lines	46.05%	11193 / 24301
🔵	Statements	45.33%	11538 / 25450
🔵	Functions	38.03%	2534 / 6662
🔵	Branches	37.68%	7302 / 19378

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/react/src/experimental/RichText/CoreEditor/Extensions/BlockIdExtension/index.tsx	74.6%	72.72%	82.35%	75.4%	72, 124-129, 161-171, 175-184
packages/react/src/experimental/RichText/NotesTextEditor/applyPageDocumentPatch.ts	98.75%	80.43%	100%	98.75%	68
packages/react/src/experimental/RichText/NotesTextEditor/index.tsx	56.25%	42.5%	44%	59.15%	104-112, 133, 181-183, 186, 192-224, 229, 237-241, 256, 262-284, 296, 331-360, 423-485
packages/react/src/experimental/RichText/NotesTextEditor/types.tsx	100%	100%	100%	100%
packages/react/src/sds/ai/F0AiChat/components/messages/MessagesContainer.tsx	5.33%	0%	0%	5.79%	54-56, 70-413, 447-466
packages/react/src/sds/ai/F0AiChat/hooks/useDebouncedFalseEdge.ts	87.5%	83.33%	100%	87.5%	21-22
packages/react/src/sds/ai/F0AiChat/utils/turnUtils.ts	98%	88.63%	100%	97.91%	56

Generated in workflow #12479 for commit e13f6fb by the Vitest Coverage Report Action

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

packages/react/src/experimental/RichText/NotesTextEditor/applyPageDocumentPatch.test.ts

packages/react/src/experimental/RichText/NotesTextEditor/applyPageDocumentPatch.ts

packages/react/src/experimental/RichText/NotesTextEditor/index.spec.tsx

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

packages/react/src/experimental/RichText/CoreEditor/Extensions/BlockIdExtension/index.tsx

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

packages/react/src/experimental/RichText/NotesTextEditor/applyPageDocumentPatch.ts

packages/react/src/experimental/RichText/CoreEditor/Extensions/BlockIdExtension/index.tsx

packages/react/src/experimental/RichText/NotesTextEditor/types.tsx

packages/react/src/experimental/RichText/NotesTextEditor/index.test.tsx

mjh-sakh · 2026-03-28T08:01:43Z

build

mjh-sakh · 2026-03-28T08:11:00Z

build

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

mjh-sakh · 2026-03-28T08:50:39Z

build

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

packages/react/src/sds/ai/F0AiChat/utils/turnUtils.ts

packages/react/src/sds/ai/F0AiChat/components/messages/MessagesContainer.tsx

packages/react/src/sds/ai/F0AiChat/hooks/__tests__/useDebouncedFalseEdge.test.ts

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

packages/react/src/sds/ai/F0AiChat/hooks/__tests__/useDebouncedFalseEdge.test.ts

… export ReadonlySet

…ouncedFalseEdge

…es.tsx

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

packages/react/src/sds/ai/F0AiChat/hooks/useDebouncedFalseEdge.ts

mjh-sakh · 2026-03-30T06:06:09Z

Note

Medium Risk
Introduces new mutation paths for the Tiptap document (insert/replace/delete by block id) and adjusts block-id generation logic, which could impact editor state integrity if edge cases are missed. Chat UI changes are low risk but affect loading/turn rendering behavior during followUp flows.

Overview
Enables AI-driven, structured edits to the rich-text editor by adding NotesTextEditorHandle.applyPageDocumentPatch() plus supporting patch types (prepend/append/insert before/after/replace block/replace content/delete) that return a {json, html} snapshot and throw a dedicated NotesTextEditorPatchTargetNotFoundError when target IDs are missing.

Hardens block ID handling: BlockIdExtension now exports BLOCK_NODE_TYPES_SET as a ReadonlySet and fixes range tracking so newly inserted blocks reliably receive fresh IDs; NotesTextEditor also normalizes legacy id: null blocks on mount and only emits onChange when IDs are actually populated.

Improves AI chat follow-up UX by debouncing the false edge of inProgress via new useDebouncedFalseEdge, suppressing redundant empty assistant placeholders, and refining analyzeTurn to avoid double spinners; adds targeted tests and ProseMirror Range rect stubs to stabilize JSDOM runs.

^{Written by Cursor Bugbot for commit b60c97d. This will update automatically on new commits. Configure here.}

…ation

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

packages/react/src/sds/ai/F0AiChat/utils/turnUtils.ts

Copilot · 2026-04-02T09:07:40Z

packages/react/src/experimental/RichText/NotesTextEditor/index.tsx

+    onCreate: ({ editor }) => {
+      // Legacy documents may contain block nodes with `id: null` because the
+      // initial content load is not a `docChanged` transaction, so
+      // BlockIdExtension's appendTransaction never fires for it. Re-setting
+      // the content triggers a real transaction that lets the plugin assign
+      // proper nanoid strings to every block that still has a null id.
+      const initialSnapshot = getNotesTextEditorSnapshot(editor)
+
+      editor.commands.setContent(editor.getJSON())
+
+      const normalizedSnapshot = getNotesTextEditorSnapshot(editor)
+
+      // Only notify the consumer when IDs were actually populated, so pages
+      // with already-valid content don't trigger a spurious onChange/autosave.
+      if (
+        JSON.stringify(initialSnapshot.json) !==
+        JSON.stringify(normalizedSnapshot.json)
+      ) {
+        onChange(normalizedSnapshot)
+      }


onCreate always calls editor.commands.setContent(editor.getJSON()) even when there are no id: null blocks to normalize. This forces an extra ProseMirror transaction on every mount (potentially impacting startup performance/history/plugin state) and then does a full JSON.stringify comparison of the entire document. Consider first scanning the initial document for any block node with attrs.id == null and only then re-set content, so the normalization transaction (and stringify work) only runs for legacy documents that actually need it.

Copilot · 2026-04-02T09:07:40Z

packages/react/src/experimental/RichText/NotesTextEditor/types.tsx

+interface NotesTextEditorHandle {
  clear: () => void
  focus: () => void
  setContent: (content: string) => void
+  applyPageDocumentPatch: (
+    patch: NotesTextEditorPageDocumentPatch
+  ) => NotesTextEditorSnapshot


PR description says NotesTextEditorHandle.applyPageDocumentPatch() returns a PageDocumentPatchResult, but the implementation/types define it as returning a NotesTextEditorSnapshot ({ json, html }). If downstream consumers (e.g. the referenced factorial PR) expect a different shape, this mismatch will be a breaking integration issue. Either update the PR description (and any external contracts) to match the snapshot return type, or adjust the handle method to return the documented result type.

Copilot AI review requested due to automatic review settings March 27, 2026 06:44

Copilot AI reviewed Mar 27, 2026

View reviewed changes

github-actions bot added the feat label Mar 27, 2026

mjh-sakh force-pushed the aoskin/20260325-one-onboarding-policy-co-creation branch 2 times, most recently from 33b0015 to db4a08c Compare March 27, 2026 13:32

Copilot AI review requested due to automatic review settings March 27, 2026 13:32

github-actions bot added the react Changes affect packages/react label Mar 27, 2026

Copilot started reviewing on behalf of mjh-sakh March 27, 2026 13:32 View session

Copilot AI reviewed Mar 27, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 28, 2026 07:35

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 07:36 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

packages/react/src/experimental/RichText/CoreEditor/Extensions/BlockIdExtension/index.tsx Outdated Show resolved Hide resolved

mjh-sakh force-pushed the aoskin/20260325-one-onboarding-policy-co-creation branch from fa547ac to 05a5aa8 Compare March 28, 2026 07:48

Copilot AI review requested due to automatic review settings March 28, 2026 07:48

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 07:49 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 28, 2026 08:17

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 08:18 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings March 28, 2026 10:39

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 10:39 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

packages/react/src/sds/ai/F0AiChat/utils/turnUtils.ts Show resolved Hide resolved

packages/react/src/sds/ai/F0AiChat/components/messages/MessagesContainer.tsx Show resolved Hide resolved

packages/react/src/sds/ai/F0AiChat/hooks/__tests__/useDebouncedFalseEdge.test.ts Show resolved Hide resolved

mjh-sakh changed the title ~~feat(rich-text): expose AI finalization editor API~~ feat(rich-text): add AI patch finalization API and harden BlockIdExtension (FCT-50714) Mar 28, 2026

Copilot AI review requested due to automatic review settings March 28, 2026 13:47

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 13:47 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

packages/react/src/sds/ai/F0AiChat/hooks/__tests__/useDebouncedFalseEdge.test.ts Show resolved Hide resolved

mjh-sakh added 3 commits March 28, 2026 19:56

fix(rich-text): harden BlockIdExtension — populate null block IDs and…

9270acc

… export ReadonlySet

feat(rich-text): add AI patch finalization API to NotesTextEditorHandle

11efe38

fix(ai-chat): suppress double spinner and followUp flicker via useDeb…

50d2c63

…ouncedFalseEdge

mjh-sakh force-pushed the aoskin/20260325-one-onboarding-policy-co-creation branch from 3450f28 to 50d2c63 Compare March 28, 2026 17:01

mjh-sakh added 2 commits March 28, 2026 20:30

fix(rich-text): use import type for JSONContent, Message, User in typ…

a1fbf16

…es.tsx

minor

b60c97d

Copilot AI review requested due to automatic review settings March 28, 2026 19:54

Copilot started reviewing on behalf of mjh-sakh March 28, 2026 19:54 View session

Copilot AI reviewed Mar 28, 2026

View reviewed changes

packages/react/src/sds/ai/F0AiChat/hooks/useDebouncedFalseEdge.ts Show resolved Hide resolved

packages/react/src/sds/ai/F0AiChat/hooks/useDebouncedFalseEdge.ts Show resolved Hide resolved

mjh-sakh marked this pull request as ready for review March 30, 2026 05:46

mjh-sakh requested a review from a team as a code owner March 30, 2026 05:46

luluconcha added 2 commits April 2, 2026 10:49

Merge branch 'main' into aoskin/20260325-one-onboarding-policy-co-cre…

4aa3c96

…ation

Add constant for follow-up loading delay (deleted by error)

13aeadc

Copilot AI review requested due to automatic review settings April 2, 2026 09:00

Copilot started reviewing on behalf of luluconcha April 2, 2026 09:01 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

style(rich-text): fix formatting in MessagesContainer

e13f6fb

Conversation

mjh-sakh commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Implementation details

📦 Dependencies

🏡 Context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ No New Circular Dependencies

Uh oh!

github-actions bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Alpha Package Version Published

Uh oh!

github-actions bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Visual review for your branch is published 🔍

Uh oh!

github-actions bot commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report for packages/react

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mjh-sakh commented Mar 28, 2026

Uh oh!

mjh-sakh commented Mar 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mjh-sakh commented Mar 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

mjh-sakh commented Mar 30, 2026

Uh oh!

mjh-sakh commented Mar 27, 2026 •

edited

Loading

github-actions bot commented Mar 27, 2026 •

edited

Loading

github-actions bot commented Mar 27, 2026 •

edited

Loading

github-actions bot commented Mar 27, 2026 •

edited

Loading

github-actions bot commented Mar 27, 2026 •

edited

Loading