Slate v2 Android markdown shortcut flush DX ralplan

Status: done Runtime id: 019e38e2-368d-76d0-bccb-a77c561625be Previous runtime id: 019e3627-238b-7993-a8cf-26be45504c47 Current pass: verification-sweep-pass Current pass status: complete Next pass: none

Current verdict

No. scheduleAndroidMarkdownShortcutFlush(editor) is not the absolute-best canonical DX.

It is a valid local workaround for Android's deferred text-diff path, but it is the wrong thing to teach in the first-party markdown example. The example asks app code to:

• subscribe to raw native beforeinput;
• wait for a microtask;
• read Android pending diffs;
• reconstruct would-be model text;
• know that a pending diff ending in a space should force an Android flush;
• call an Android-specific DOM capability.

That is runtime plumbing, not app authoring. Raw Slate users should express the model behavior once through extension.transforms.insertText(...); Slate React should own Android native-input timing.

Accepted final target:

• Keep markdownShortcuts() as a Slate core extension using transform middleware.
• Remove Android-specific scheduling from the public example.
• Do not reintroduce public Editable inputRules, EditableInputRule*, or a raw Slate markdown-shortcut API.
• Add an internal React/DOM runtime bridge so Android pending text diffs use the existing flush path when transform:insertText middleware is registered.
• Do not duplicate markdown shortcut detection in the Android runtime. The runtime should not know about spaces, headings, lists, or block-start rules.
• Keep rich semantic input-rule families in Plate.

Current score: 0.92 as an implemented local-regression slice. Exact #4532 closure still needs raw Android browser/device proof.

Intent boundary

Live source evidence

Before and after target

Current example:

<Editable
  autoFocus
  onDOMBeforeInput={() => scheduleAndroidMarkdownShortcutFlush(editor)}
  placeholder="Write some markdown..."
  renderElement={renderElement}
  spellCheck
/>

Target example:

<Editable
  autoFocus
  placeholder="Write some markdown..."
  renderElement={renderElement}
  spellCheck
/>

The extension stays the visible customization point:

const markdownShortcuts = () =>
  defineEditorExtension<CustomEditor>()({
    name: "markdown-shortcuts",
    transforms: {
      insertText({ editor, next, text }) {
        if (applyMarkdownShortcut(editor, text)) return;

        next();
      },
    },
  });

Internal bridge target:

if (canStoreDiff) {
  storeDiff(start.path, diff);

  if (diff.text && hasTransformMiddleware(editor, "insertText")) {
    scheduleFlush();
  }

  schedulePendingSelectionAction();
  return;
}

The exact helper name is not final. The principle is final: apps should not read Android pending diffs to make model shortcuts work, and the runtime should not grow markdown-specific predicates.

Decision brief

Principles:

• Model behavior belongs in Slate model transforms, not DOM event parsing.
• Slate React owns browser and Android timing.
• Raw Slate stays unopinionated; Plate owns rich input-rule families.
• First-party examples should show the durable public contract, not the mobile workaround.
• Browser/mobile fixes need executable proof before issue closure.

Top drivers:

• The markdown example already has the right public model hook: transforms.insertText.
• Android pending diffs are an implementation detail of the native-input manager.
• Reintroducing public input rules would conflict with the accepted Slate/Plate ownership split.

Options:

Decision hardening pass

Pass result: complete.

The critical question was whether the runtime should flush only for whitespace or markdown-looking pending diffs. It should not. That would move product policy into slate-react and recreate the userland helper in a less visible place.

The better contract is lower-level and cleaner:

• transforms.insertText middleware means the editor has model policy that needs to observe inserted text through the normal transform path.
• Android pending text diffs are a DOM synchronization optimization, not a license to bypass registered model policy until a later native flush.
• Therefore the internal trigger is any non-empty stored Android text diff when transform:insertText middleware exists.
• Editors without insertText middleware keep the existing Android deferred diff behavior.
• No public option is added. If a public option becomes necessary later, that is proof the transform middleware contract is underspecified, not proof that markdown shortcuts deserve an Android API.

Implementation-facing shape:

const shouldFlushStoredTextDiff =
  diff.text.length > 0 && hasTransformMiddleware(editor, "insertText");

storeDiff(start.path, diff);

if (shouldFlushStoredTextDiff) {
  scheduleFlush();
}

The hasTransformMiddleware helper belongs next to transform middleware or the extension registry, not in the example. It can read the registered transform:insertText command handler list once per event without exposing a new public API.

Ecosystem comparison

Ecosystem decision: Slate should steal the ownership split, not the public API shape. ProseMirror proves DOM input timing belongs in the view/runtime. Lexical proves typed behavior should re-enter the model command/update path. Tiptap and Plate prove markdown/input-rule ergonomics are product-extension territory. The result is not another user-facing prop; it is a runtime guarantee that Android text input reaches insertText middleware soon enough.

Issue ledger accounting

No fixed issue claim is accepted by this pass.

Issue sync performed in the related-issue pass:

• docs/slate-issues/gitcrawl-v2-sync-ledger.md: #4532 moved from issue-reviewed to implementation-reviewed with this plan and local proof as proof owners.
• docs/slate-v2/ledgers/issue-coverage-matrix.md: added one Related row for #4532.
• docs/slate-v2/ledgers/fork-issue-dossier.md: added a long-form Android markdown shortcut flush section.
• docs/slate-v2/references/pr-description.md: related matrix count updated and a zero fixed/improved claim bullet added.

Related issue discovery pass

Pass result: complete.

Discovery source: durable ledgers only. No broad live GitHub discovery was needed. The generated live ledger has the current #4532 row; the manual sync ledger had it as issue-reviewed; the issue dossier says the report is strong enough but example-specific; the test-candidate map says the direct current contract is not a good red-test target.

Issue matrix:

Decision:

• #4532 should not stay as generic docs/example noise. The current DX problem is exactly that the example is compensating for runtime timing.
• It still cannot be Fixes or Improves from local proof alone. Improves #4532 becomes valid only after raw Android proof shows markdown shortcuts convert.
• The PR summary should mention zero new exact fixed/improved claims so maintainers do not read this as auto-close bait.

Regression proof target

Implementation cannot be accepted from code review alone.

Required proof candidates:

• .tmp/slate-v2/packages/slate-react/test/android-input-manager-contract.test.ts or equivalent: Android manager schedules the existing flush when an insertText transform middleware is installed and a non-empty Android storable text diff lands.
• .tmp/slate-v2/packages/slate-react/test/android-input-manager-contract.test.ts or equivalent: plain editors without insertText transform middleware keep the existing deferred pending-diff path.
• .tmp/slate-v2/packages/slate-react/test/android-input-manager-contract.test.ts or equivalent: empty delete diffs do not take the text-middleware fast-flush path.
• .tmp/slate-v2/packages/slate-react/test/android-input-manager-contract.test.ts or equivalent: composition/SwiftKey insert-position hint handling still schedules its existing flush and is not replaced by the middleware trigger.
• .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts: the internal middleware-presence helper returns true only for registered transform:insertText handlers and false for unrelated transform middleware.
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx: the markdown example still uses deleteBackward, insertBreak, and insertText transform middleware; it does not use onKeyDown; it also must not use onDOMBeforeInput, androidPendingDiffs, androidScheduleFlush, or scheduleAndroidMarkdownShortcutFlush.
• .tmp/slate-v2/packages/slate-react/test/app-owned-customization.tsx: app-owned markdown shortcuts remain expressible through editor-owned model behavior.
• .tmp/slate-v2/playwright/integration/examples/markdown-shortcuts.test.ts: desktop and mobile projects still create blockquote, unordered list, ordered list, and heading shortcuts from the public example.
• .tmp/slate-v2: raw Android Chrome/device proof before claiming #4532 fixed.

Planning-only verification for this Ralplan:

• plate-2: node tooling/scripts/completion-check.mjs passes after this planning lane is marked done.

Regression-proof review pass

Pass result: complete.

Harsh answer: the plan is regression-conscious, not regression-proof by itself. It becomes regression-safe only if the implementation lands with the targeted tests below. Anything less is a guess dressed up as confidence.

Regression risks to lock:

Minimum implementation gate:

cd .tmp/slate-v2
bun test packages/slate/test/extension-methods-contract.ts \
  packages/slate-react/test/surface-contract.tsx \
  packages/slate-react/test/app-owned-customization.tsx \
  packages/slate-react/test/with-react-contract.tsx
cd packages/slate-react && bun test:vitest -- \
  test/model-input-strategy-contract.test.ts \
  test/android-input-manager-contract.test.ts
cd ../..
playwright test playwright/integration/examples/markdown-shortcuts.test.ts \
  --project=chromium --project=mobile
bun --filter slate-react typecheck
bun typecheck:site

Issue-closure gate:

cd .tmp/slate-v2
SLATE_BROWSER_RAW_MOBILE_REQUIRED=1 bun test:mobile-device-proof:raw

Do not claim Fixes #4532 from the minimum gate. The minimum gate is enough to say the implementation is locally regression-locked. The raw mobile/device gate is what can justify exact Android issue closure.

Ralph execution result

Pass result: complete.

Implementation files:

• .tmp/slate-v2/packages/slate/src/core/transform-middleware.ts
• .tmp/slate-v2/packages/slate/src/internal/index.ts
• .tmp/slate-v2/packages/slate/test/extension-methods-contract.ts
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-before-input-events.ts
• .tmp/slate-v2/packages/slate-react/src/editable/runtime-editor-api.ts
• .tmp/slate-v2/packages/slate-react/src/hooks/android-input-manager/android-input-manager.ts
• .tmp/slate-v2/packages/slate-react/test/android-input-manager-contract.test.ts
• .tmp/slate-v2/packages/slate-react/test/model-input-strategy-contract.test.ts
• .tmp/slate-v2/packages/slate-react/test/surface-contract.tsx
• .tmp/slate-v2/site/examples/ts/markdown-shortcuts.tsx

Behavior landed:

• Core now exposes an internal hasTransformMiddleware(editor, key) helper.
• Slate React can treat registered insertText transform middleware as app input policy, so native chromium text input does not bypass model behavior.
• Android stored text diffs schedule the existing flush path when a non-empty diff lands on an editor with registered insertText transform middleware.
• The markdown-shortcuts example no longer wires onDOMBeforeInput, reads androidPendingDiffs, calls androidScheduleFlush, or defines scheduleAndroidMarkdownShortcutFlush.

Important regression found and fixed:

• First Playwright markdown-shortcuts run failed on chromium after removing the example onDOMBeforeInput helper. Root cause: that helper was accidentally acting as hasAppInputPolicy, which disabled native insertion and kept markdown shortcuts on the model-owned path. The fix is to count registered insertText transform middleware as input policy directly.

Verification:

bun test ./packages/slate/test/extension-methods-contract.ts
bun test ./packages/slate-react/test/surface-contract.tsx ./packages/slate-react/test/app-owned-customization.tsx ./packages/slate-react/test/with-react-contract.tsx ./packages/slate/test/extension-methods-contract.ts
bun test:vitest -- test/model-input-strategy-contract.test.ts test/android-input-manager-contract.test.ts
bun run playwright playwright/integration/examples/markdown-shortcuts.test.ts --project=chromium --project=mobile
bun --filter slate-react typecheck
bun --filter slate typecheck
bun typecheck:site
bun lint

Results:

• Focused Bun tests: passed.
• Focused Vitest tests: passed.
• Playwright markdown-shortcuts chromium/mobile: passed, 14 tests.
• slate-react typecheck: passed.
• slate typecheck: passed.
• site typecheck: passed.
• lint: passed with one existing warning in packages/slate-react/src/components/slate.tsx about reactEditor dependency; no lint errors.
• Raw Android device proof: not run; therefore #4532 remains Related.

Maintainer objection pass

Pass result: complete.

Issue sync accounting pass

Pass result: complete.

• Fixed issue claims: 0.
• Improved issue claims: 0.
• Related issue rows added: 1 for #4532.
• PR reference related count: 192.
• #4532 remains candidate Improves only after raw Android browser/device proof.

Current scorecard

Weighted total: 0.92.

Pass-state ledger

Closed decisions

• No app-side onDOMBeforeInput for markdown shortcuts.
• No public Editable inputRules revival.
• No public raw Slate markdown shortcut API.
• No public Android flush predicate.
• Internal trigger: non-empty stored Android text diff plus registered transform:insertText middleware.
• #4532 remains Related until raw Android browser/device proof exists.