Skip to content

feat(editor): accept no provider, add WriteGate and the decoration host (P2.2) - #123

Merged
9 commits merged into
mainfrom
claude/feat-p2-2-editor-no-provider-a52225
Nov 17, 2026
Merged

9 commits merged into
mainfrom
claude/feat-p2-2-editor-no-provider-a52225

Conversation

@HMarzban

@HMarzban HMarzban commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Desktop Phase 2, P2.2 (plan v8 §8.4, Appendix A; details spec §1 rules 2, 5 and 6; architecture §4 "Shared editor changes").

What changes

  • No provider. DocumentEditor takes the session's awareness and provider: HocuspocusProvider | null.
    • CollaborationCaret is configured with { awareness, on, off }. Its 3.33 runtime reads only provider.awareness.
    • The extensions memo depends on awareness, never on the provider, so attaching one later never calls setOptions.
    • CollabStatusGroup renders only with a provider, because its useConnectionState creates the shared socket.
    • useYjsDocument gains one line (awareness: provider.awareness), the DocHandle shape from feat(platform): add DocSession and DocStore port types (P2.1a) #119.
  • UniqueID gotcha (caught by the new tests, not in the spec).
    • UniqueID reads the caret's provider option and calls provider.on("synced", …) on create.
    • An awareness-only object would have thrown on the live web editor.
    • So on and off forward through a ref to the provider of the moment. The web waits on the real provider exactly as before. With no provider, nothing is waited for.
  • WriteGate (extensions/write-gate/): filterTransaction: !docChanged || isChangeOrigin || canWrite(), over a ref and never setEditable.
    • It is driven by the new optional readOnly prop, which also feeds setEditable. It covers ProseMirror changes. The schema guard repairs by writing Yjs directly and is not gated yet; whoever first sets readOnly must gate it too, which costs a few bytes this line doesn't have.
    • The web never sets it, so refused web documents behave as today.
    • Desktop and the web library wire readOnlyReason to it later (hand-over note left for P2.1).
  • Decoration host (extensions/decoration-host/), the action-preview stub made general.
    • Each declared layer is one plugin holding a DecorationSet, set by the meta-only setDecorationLayer(name, set).
    • On a document change a layer is cleared, or mapped if it was declared with map: true.
    • It is registered with no layers. Comments (P4.9) and Find (P2.11) declare theirs, and their logic stays in lazy chunks.
    • ActionPreview is deliberately not migrated: its redraw-on-remote rule doesn't fit a plain layer.
  • Appendix A: P2.2 adds no build-target check, so "the target flag is compared as a literal" holds trivially.
  • Fence. EDITOR_CHUNK_BUDGET_BYTES = main growth (15,284 B at 08b7663) + the D23 ledger (1,580 B) = +16,864 B, down from 23.5 KB. The script now prints exact bytes; CI already runs it in the checks job.

Editor chunk (gz, bun scripts/check-editor-chunk-size.ts)

Group bytes Growth over 58a9d22
main (08b7663, after #126) 393,172 +15,284
This branch, merged with it 393,466 +15,578 (+294 B; the ledger line is 300 B)

P2.2 measured the same +294 B on 1ed981e (after #118) and +297 B on f9cfc3a.

Stepwise while building (on f9cfc3a):

  • no provider: +27
  • WriteGate: +109
  • host: +143
  • UniqueID forwarding: +39
  • trims (WriteGate's default option, the host's redundant empty-set branch and addToHistory meta): −21

The fence leaves 1,286 B for the ledger's other lines. #118 and #126 landed first, so the fence is measured on main after both (commit 1c15715). Any later PR that adds to main before the ledger lines land spends ledger bytes, which is the point of D23.

Tests

  • tests/unit/extensions/write-gate.test.ts runs the app's real extension list over Yjs:
    • the opening writes are blocked when read-only (no Yjs update, and UniqueID's sync pass is gated too), with a writable control;
    • local edits are blocked while a collaborator's change still renders;
    • folds still work on a read-only document;
    • with no provider, edits and updateUser go through the Awareness;
    • UniqueID's synced wait is forwarded to the provider.
  • tests/unit/extensions/decoration-host.test.ts: one plugin per layer, show and clear, layers are independent, plain layers clear, map: true layers map.
  • tests/unit/components/document-editor-no-provider.test.tsx renders the real DocumentEditor:
    • with no provider it is editable, has no status chip and makes zero socket requests or WebSockets;
    • attaching a provider with the same Awareness keeps the same editor and makes zero setOptions calls;
    • control: a new Awareness does call setOptions.
  • bun run test on the tree merged with 08b7663: 1,695 pass, 0 fail.
  • Playwright on that merged tree, chromium + perf with --retries=1: 526 passed, 0 failed, 1 flaky.
    • The flaky case is the 50-heading toolbar-on vs toolbar-off p95: 5.5 vs ≤ 5.28 ms on the first try; the retry passed at 5.1 vs 4.9 ms.
    • Both sides of that comparison include this change.
  • Playwright: CI= bun playwright test --project=chromium --project=perf --retries=1 against isolated dev servers (Next on 3310, Hocus on 1534, raised socket limits as in playwright.config.ts).
    • 518 passed, 0 flaky.
    • Three specs failed because I hadn't passed DB_PATH to Playwright: the helpers read ./db.sqlite while my servers used another file. With DB_PATH set, those two files pass 9/9.
    • perf (skipped behind them in the first run) passes 4/4: 50-heading typing p95 median 5.6 ms off and 6.0 ms on; 500-heading arrow p95 25.2 ms.
  • Biome, ESLint and bun run typecheck are clean.

E2E helper fix after #118 (commit abebef8).

  • Cause: test: run 500-heading perf documents at production's 2 MiB cap #116's expectSavedToServer read isSynced off the caret's provider option, which this PR turns into the Awareness holder. So performance-collab timed out in CI, and every perf and soak spec that calls the helper would have done the same.
  • Hidden case: filter.spec's copy of the check saw undefined, which made its wait pass at once without waiting.
  • Fix: the helper gets the real provider from the caret's forwarding on, because HocuspocusProvider.on returns this. filter.spec now uses the same helper, and a unit test pins the contract.
  • Why not an app hook: a dev-only window hook cost 10–12 B of the 6 B left on this line, from identifier reshuffling, so the fix stays in test code. App bytes are unchanged (+294 B).
  • Re-run locally: performance-collab, filter, filter-collab, collaboration and identity-dialog pass 10/10; perf 4/4; quick soak and soak-collab 2/2; all with no retries.

Not in this PR

  • use-yjs-document over DocSession (P2.1).
  • Wiring readOnlyReason to readOnly.
  • The desktop status chip.

WriteGate filters every local transaction that changes the document
while canWrite() is false, appended ones included, so read-only never
makes a Yjs update that would later have to be dropped (details spec §1
rules 1-2). Changes from Yjs and meta-only transactions pass.

The decoration host generalises the action-preview stub (rule 6): each
declared layer is one plugin holding a DecorationSet, set by the
meta-only setDecorationLayer command and mapped or cleared on document
changes, so comments and Find add no eager plugin of their own.
DocumentEditor now takes the session's Awareness and a provider that
may be null (desktop P2.2). The caret is configured with that
Awareness, and the extensions memo depends on it rather than on the
provider, so attaching a provider later never calls setOptions. The
connection chip renders only with a provider: its connection state
creates the shared socket.

UniqueID finds the caret's provider option and waits for its "synced"
event, so on and off forward to the provider of the moment through a
ref; the web behaves as before.

WriteGate and an empty decoration host join the extensions. The new
readOnly prop drives the gate and setEditable; the web never sets it.
The budget was 23.5 KB of growth (contract A12); main is at +15,691 B.
D23 lowers it to main plus the 1,580 B ledger, +17,271 B, so unrelated
work cannot spend the ledger's bytes. The report prints exact bytes.
…or-no-provider-a52225

# Conflicts:
#	CHANGELOG.md
#118 landed first: main is at +15,674 B, so the fence is +17,254 B
(main plus the 1,580 B ledger). P2.2 measures 294 B on the merged tree.
expectSavedToServer (#116) read isSynced from the caret's provider
option, which P2.2 made the editor's Awareness holder, so it never saw
the server ack and the perf and collab runs timed out. filter.spec's
copy saw undefined and stopped waiting at all. The caret option's on
returns the provider's on, which returns the provider, so the helper
asks it; filter.spec now uses the same helper. A unit test pins it.
…or-no-provider-a52225

# Conflicts:
#	CHANGELOG.md
#126 landed first: main is at +15,284 B, so the fence is +16,864 B
(main plus the 1,580 B ledger). P2.2 still measures 294 B on the
merged tree (+15,578 B).
@HMarzban HMarzban closed this pull request by merging all changes into main in 29f6faf Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant