diff --git a/.changeset/markdown-callout-variant-fix.md b/.changeset/markdown-callout-variant-fix.md new file mode 100644 index 0000000000..faf49e95c4 --- /dev/null +++ b/.changeset/markdown-callout-variant-fix.md @@ -0,0 +1,5 @@ +--- +"@platejs/markdown": patch +--- + +Fix `` deserializing into `variant` without clobbering the callout node type diff --git a/.changeset/streaming-mdx-multiline-tail.md b/.changeset/streaming-mdx-multiline-tail.md new file mode 100644 index 0000000000..ba74cdf69f --- /dev/null +++ b/.changeset/streaming-mdx-multiline-tail.md @@ -0,0 +1,5 @@ +--- +"@platejs/markdown": patch +--- + +Keep multiline incomplete MDX tails visible while preserving a complete parsed prefix during streaming fallback diff --git a/.changeset/streaming-mdx-replay-prefix.md b/.changeset/streaming-mdx-replay-prefix.md new file mode 100644 index 0000000000..bba0b23ee6 --- /dev/null +++ b/.changeset/streaming-mdx-replay-prefix.md @@ -0,0 +1,5 @@ +--- +"@platejs/ai": patch +--- + +Fix insert streaming preserving completed markdown and MDX blocks before an incomplete MDX tail diff --git a/.claude/docs/analysis/compound-engineering-tree.md b/.claude/docs/analysis/compound-engineering-tree.md new file mode 100644 index 0000000000..2b0ed18bab --- /dev/null +++ b/.claude/docs/analysis/compound-engineering-tree.md @@ -0,0 +1,260 @@ +# Plate Compound Engineering Tree + +This is the Plate-specific reduction of the Compound Engineering agent tree. + +It is grounded in: + +- `skiller-lock.json` for what Plate actually installed from `EveryInc/compound-engineering-plugin` +- `.agents/rules/task.mdc` for the default task lane +- `.agents/rules/major-task.mdc` for the heavyweight architecture/comparison lane +- `.agents/rules/agent-browser-issue.mdc` for the browser parity escalation +- `.agents/AGENTS.md` for explicit exclusions + +This is not the whole plugin zoo. It is the slice Plate actually keeps, where it is wired, and why the rest stays dead. + +## Actual Plate Tree + +```text +Plate CE set +├── task lane +│ ├── ce:brainstorm +│ ├── learnings-researcher +│ ├── framework-docs-researcher (conditional, second-pass only) +│ ├── risky-change review lane +│ │ ├── ce-review +│ │ ├── correctness-reviewer +│ │ ├── maintainability-reviewer +│ │ ├── project-standards-reviewer +│ │ └── code-simplicity-reviewer +│ └── agent-native parity lane +│ └── agent-native-reviewer +├── major-task lane +│ ├── ce:plan +│ ├── learnings-researcher +│ ├── repo-research-analyst +│ ├── architecture-strategist +│ ├── pattern-recognition-specialist +│ ├── framework-docs-researcher (conditional, after local clone/source pass) +│ ├── best-practices-researcher (conditional) +│ ├── performance-oracle +│ ├── spec-flow-analyzer +│ └── issue-intelligence-analyst / git-history-analyzer (conditional) +└── major-task conditional document-review pass + ├── coherence-reviewer + ├── feasibility-reviewer + ├── scope-guardian-reviewer + ├── product-lens-reviewer + └── adversarial-document-reviewer +``` + +## Installed CE Agents + +### Research + +- `best-practices-researcher` +- `framework-docs-researcher` +- `git-history-analyzer` +- `issue-intelligence-analyst` +- `learnings-researcher` +- `repo-research-analyst` + +### Review + +- `agent-native-reviewer` +- `architecture-strategist` +- `code-simplicity-reviewer` +- `correctness-reviewer` +- `maintainability-reviewer` +- `pattern-recognition-specialist` +- `performance-oracle` +- `project-standards-reviewer` + +### Workflow + +- `spec-flow-analyzer` + +### Document Review + +- `adversarial-document-reviewer` +- `coherence-reviewer` +- `feasibility-reviewer` +- `product-lens-reviewer` +- `scope-guardian-reviewer` + +## Where Plate Uses Them + +## `task.mdc` + +Direct CE references in `.agents/rules/task.mdc`: + +- `ce:brainstorm` + Use when the task is still mushy after reading the source of truth and nearby code. +- `learnings-researcher` + Default early pass for repeated domains, prior solutions, and non-trivial work. +- `framework-docs-researcher` + Conditional only. Use after the AGENTS-required local clone/source/docs pass when third-party behavior is still unclear, unfamiliar, or version-sensitive. +- `ce-review` +- `correctness-reviewer` +- `maintainability-reviewer` +- `project-standards-reviewer` +- `code-simplicity-reviewer` + This is the risky-change review lane. It is not default. It is reserved for risky, large, user-facing, or architecture-sensitive work. +- `agent-native-reviewer` + Separate conditional lane. Use only for `.agents/**`, `.claude/**`, AI/tooling surfaces, commands, or user-action parity work. + +Companion rule outside the CE tree: + +- `.agents/rules/agent-browser-issue.mdc` + If browser/tool automation exposes a reusable action-parity gap, it tells the task flow to load `agent-native-reviewer` and capture that gap as a real follow-up instead of shrugging. + +What `task` does not do: + +- It does not default to the full CE review zoo. +- It does not default to document-review personas. +- It does not default to architecture research unless intake escalates to `major-task`. + +## `major-task.mdc` + +Direct CE references in `.agents/rules/major-task.mdc`: + +- `ce:plan` + Main planning spine for heavyweight work. +- `learnings-researcher` + Early repo-memory pass when prior decisions matter. +- `repo-research-analyst` + Default repo-grounding helper for major work. +- `architecture-strategist` + Public API, layering, ownership, abstraction cleanup, and cross-package refactor work. +- `pattern-recognition-specialist` + Repo-wide pattern extraction, repeated smell detection, and consistency analysis across packages. +- `framework-docs-researcher` + Conditional second pass only. Local clone and source reading come first per AGENTS. This comes in when official docs are needed to settle third-party behavior or compare competing frameworks honestly. +- `best-practices-researcher` + Only when official docs still leave gaps or the task genuinely needs wider field patterns. +- `performance-oracle` + Explicit performance and optimization lane. Used for benchmark design, scalability analysis, hot-path tradeoffs, and editor/runtime comparison strategy. +- `spec-flow-analyzer` + RFC, proposal, acceptance-criteria, rollout, and completeness pressure-testing. +- `issue-intelligence-analyst` or `git-history-analyzer` + Conditional only when issue churn, historical regressions, or design history matter. + +`major-task` also points editor-framework analysis at: + +- `docs/analysis/editor-architecture-candidates.md` + +That keeps comparison work bounded instead of widening into random framework tourism. + +### `major-task` document-review pass + +These are no longer manual-only. They are conditionally wired into `major-task`: + +- `coherence-reviewer` +- `feasibility-reviewer` + Default pair for explicit plan, RFC, proposal, or spec review. +- `scope-guardian-reviewer` + Add when abstraction count, rollout shape, or scope drift smells inflated. +- `product-lens-reviewer` + Add when the document makes product framing, value, roadmap, or "are we solving the right problem?" claims. +- `adversarial-document-reviewer` + Add when the doc is large, assumption-heavy, architecture-heavy, or high-stakes enough to deserve premise stress-testing. + +The rule is selective. `major-task` does not load every reviewer just because a doc exists. + +### `major-task` performance and comparison lane + +This is the sharpest major-task branch for Plate-specific framework work: + +- define the workload first +- separate measured evidence from hypothesis +- compare equivalent workloads, not vibes +- start from repo constraints before internet takes +- for editor-framework performance questions: + - prefer `Plate vs Slate` first for direct inheritance pressure + - use `ProseMirror` and `Lexical` for deeper runtime or architecture direction + - use `Tiptap` more for product-layer or packaging cost than raw engine performance + - use `Pretext` and `Premirror` for pagination, composition, and layout-aware editing questions + +## Rejected Or Deferred + +### Wrong repo shape + +- `data-integrity-guardian` +- `data-migration-expert` +- `data-migrations-reviewer` +- `schema-drift-detector` +- `deployment-verification-agent` +- `api-contract-reviewer` + +Reason: + +- Plate is a framework/editor monorepo, not a migration-heavy or deploy-heavy product app. +- These agents bias toward data-plane or operational concerns that are not central here. + +### Wrong stack + +- `dhh-rails-reviewer` +- `kieran-rails-reviewer` +- `kieran-python-reviewer` + +Reason: + +- Wrong language family. +- Installing them would just add noise and fake sophistication. + +### Workflow noise + +- `previous-comments-reviewer` +- `pr-comment-resolver` +- `figma-design-sync` +- `bug-reproduction-validator` + +Reason: + +- PR-thread replay, Figma sync, and extra browser-validator choreography are not part of Plate's default execution model. +- Plate already has its own task, review, and browser flows. + +### Overkill for default Plate use + +- `security-lens-reviewer` +- `design-lens-reviewer` +- `security-reviewer` +- `security-sentinel` +- `reliability-reviewer` +- `performance-reviewer` +- `adversarial-reviewer` +- `julik-frontend-races-reviewer` +- `kieran-typescript-reviewer` + +Reason: + +- Some are legit, but not legit enough to justify default install. +- Plate wanted a lean set that earns its keep. +- Add one later on proof, not because the catalog exists. + +### Orphan / not first-class yet + +- `design-implementation-reviewer` +- `ankane-readme-writer` +- `cli-agent-readiness-reviewer` + +Reason: + +- No strong first-class parent skill in the current CE tree. +- Not worth pulling into Plate just because they are lying around. + +## Why This Shape + +Plate wanted two modes: + +1. `task` stays lean for normal issue execution. +2. `major-task` handles architecture, comparison, benchmark, and proposal work without turning every task into a research circus. + +That means: + +- keep a small serious research spine +- keep a small serious risky-change review spine +- wire document-review agents conditionally behind `major-task` +- keep performance/comparison work explicit and evidence-first +- reject data/deploy/Rails/Figma/PR-thread sludge + +That is the current best-fit CE slice for Plate. diff --git a/.claude/docs/analysis/editor-architecture-candidates.md b/.claude/docs/analysis/editor-architecture-candidates.md new file mode 100644 index 0000000000..71aae41fd9 --- /dev/null +++ b/.claude/docs/analysis/editor-architecture-candidates.md @@ -0,0 +1,341 @@ +# Editor Architecture Candidates for Plate + +This is the opinionated shortlist. Not a market map. Not a graveyard of every editor repo on GitHub. Just the candidates and inspirations actually worth keeping in Plate's future architectural comparison set. + +It is intentionally not a prescription for exact features Plate should copy. The current analysis is strong enough to rank and frame the field, not to lock Plate into a shopping list. + +## Repos + +- [ProseMirror](https://github.com/ProseMirror/prosemirror) +- [Lexical](https://github.com/facebook/lexical) +- [Tiptap](https://github.com/ueberdosis/tiptap) +- [Pretext](https://github.com/chenglou/pretext) +- [Premirror](https://github.com/samwillis/premirror) +- [Slate](https://github.com/ianstormtaylor/slate) +- [edix](https://github.com/inokawa/edix) +- [use-editable](https://github.com/FormidableLabs/use-editable) +- [rich-textarea](https://github.com/inokawa/rich-textarea) +- [@react-libraries/markdown-editor](https://github.com/ReactLibraries/markdown-editor) +- [urql](https://github.com/urql-graphql/urql) +- [TanStack DB](https://github.com/TanStack/db) +- [VS Code](https://github.com/microsoft/vscode) +- [Language Server Protocol](https://github.com/microsoft/language-server-protocol) +- [EditContext API docs](https://developer.mozilla.org/en-US/docs/Web/API/EditContext_API) +- [Open UI Richer Text Fields](https://open-ui.org/components/richer-text-fields.explainer/) + +## Clone Or Update + +Run this from `/Users/zbeyens/git/plate` if you want the comparison repos checked out in `..`: + +```bash +for repo in \ + ProseMirror/prosemirror \ + facebook/lexical \ + ueberdosis/tiptap \ + chenglou/pretext \ + samwillis/premirror \ + ianstormtaylor/slate \ + inokawa/edix \ + FormidableLabs/use-editable \ + inokawa/rich-textarea \ + ReactLibraries/markdown-editor \ + urql-graphql/urql \ + TanStack/db \ + microsoft/vscode \ + microsoft/language-server-protocol +do + name="${repo##*/}" + if [ -d "../$name/.git" ]; then + git -C "../$name" pull --ff-only + else + git clone "https://github.com/$repo.git" "../$name" + fi +done +``` + +## Ranking + +1. ProseMirror +2. Lexical +3. Tiptap +4. Pretext + Premirror +5. Slate +6. edix +7. use-editable +8. rich-textarea +9. @react-libraries/markdown-editor +10. urql +11. TanStack DB +12. VS Code + Language Server Protocol +13. EditContext API +14. Open UI Richer Text Fields + +## Tier 1: Direct Comparison Targets + +### ProseMirror + +Still the center of gravity. + +Why it matters: + +- Best substrate for schema, transforms, plugins, and serious document structure. +- Still the cleanest answer to "what does a disciplined rich-text engine look like?" +- If Plate wants to absorb the best ideas in the space instead of inventing weird local alternatives, this is still the first stop. + +Take: + +If Plate ever compares itself against one core editor architecture, this is the one. Everything else is either reacting to it, productizing it, or trying to escape its complexity. + +### Lexical + +The strongest non-ProseMirror engine to study hard. + +Why it matters: + +- Strong modern runtime posture: immutable editor state, command system, own reconciliation strategy. +- Serious performance intent instead of accidental performance. +- Backed by Meta, which matters when evaluating whether ideas survived real product abuse. + +Take: + +If Plate ever questions its underlying runtime model, Lexical is the real challenger, not a side-show wrapper. + +### Tiptap + +Not the engine winner. The productization winner. + +Why it matters: + +- Massive extension surface and polished packaging around ProseMirror. +- Strong docs, onboarding, examples, and "this actually ships in products" energy. +- Useful benchmark for DX, extension ergonomics, collaboration packaging, and ecosystem capture. + +Take: + +Do not compare Plate to Tiptap as a better engine. Compare Plate to Tiptap as a better developer product. + +### Pretext + Premirror + +This is the most important future-facing lane. + +Why Pretext matters: + +- It tackles multiline text measurement and layout without relying on DOM reflow. +- That is a huge missing primitive in web editors, especially for pagination, composition, and layout-aware editing. + +Why Premirror matters: + +- It treats ProseMirror as document truth and `@chenglou/pretext` as the measurement/layout primitive. +- The local `../premirror` direction is exactly the kind of synthesis worth watching: document engine plus deterministic page composition instead of pretending pagination is a CSS afterthought. + +Take: + +This is not "another editor." It is the strongest path toward solving the unsolved page-layout problem on the web. + +## Tier 2: Important, But Not the Main Bet + +### Slate + +Important because Plate comes from this world. + +Why it matters: + +- It shaped a lot of Plate's current mental model and ergonomics. +- It stays attractive because it is flexible and React-friendly. + +Why it is not the north star: + +- Even its own repo still describes it as beta. +- Historically great for flexibility, less convincing as the long-term answer for strict structure, heavy composition, and platform-grade editor architecture. + +Take: + +Study Slate to understand your inheritance and its limits, not because it is the future benchmark. + +### edix + +Very good inspiration repo. Not a core replacement candidate. + +Why it matters: + +- It is explicitly an experimental, framework-agnostic, small `contenteditable` state manager. +- Its motivation is sharp: full editor frameworks are too much for small editing surfaces, but raw `contenteditable` is a mess. + +Take: + +`edix` is a scalpel, not the next spine. Worth studying for lightweight surfaces, not for replacing Plate's serious document architecture. + +### use-editable + +Still one of the cleanest small-surface inspirations. + +Why it matters: + +- It is a tiny React hook for turning elements into editable, fully renderable content surfaces. +- Great example of "I want a custom editable surface without dragging in a cathedral." + +Take: + +This is not a full editor framework. It is a strong reminder that not every editable surface deserves the full Plate stack. + +### rich-textarea + +A very relevant companion to the `edix` line of thinking. + +Why it matters: + +- It aims to keep native textarea behavior while adding highlighting, decoration, autocomplete, and caret-aware interactions. +- Strong example of going "smaller than a full editor" without falling back to dumb plain text. + +Take: + +Good inspiration for lightweight, high-polish text surfaces. Not a contender for Plate's core document model. + +### @react-libraries/markdown-editor + +Narrower, but still useful. + +Why it matters: + +- Markdown-first editing surface with SSR support and externally controllable editing events. +- Useful example of a focused editing package that is trying to stay controllable instead of becoming an everything-framework. + +Take: + +Relevant as a markdown-surface inspiration, not as a major architecture benchmark. + +## Tier 3: Cross-Domain Architecture Inspirations + +### urql + +Not an editor. Still extremely relevant. + +Why it matters: + +- Highly customizable pipeline architecture through exchanges. +- Clear stance on normalized caching and composable behavior layers. + +Take: + +This is useful when thinking about editor infrastructure, not text rendering. + +### TanStack DB + +One of the best non-editor inspirations on the list. + +Why it matters: + +- Normalized collections. +- Sub-millisecond live queries. +- Instant optimistic writes. + +Take: + +If Plate wants better projections, indexes, or derived editor state, TanStack DB is a smarter inspiration than another random editor repo. + +### VS Code + Language Server Protocol + +This is the service architecture model worth studying closely. + +Why it matters: + +- Stable core editor plus protocolized external intelligence. +- Analyzers, completions, diagnostics, and actions can live outside the core UI process. + +Take: + +If Plate ever grows semantic services, AI analyzers, structural linting, or document reasoning, this is the right mental model. + +### EditContext API + +Important future platform primitive. + +Why it matters: + +- The web platform is finally acknowledging that serious custom text editing needs more direct control than classic `contenteditable`. +- This is the kind of primitive that could eventually let editors escape a lot of legacy DOM pain. + +Take: + +Do not bet Plate on it yet. Track it aggressively. + +### Open UI Richer Text Fields + +More important than it looks. + +Why it matters: + +- It is standards work aimed at text controls that need more than plain `` and `