Skip to content

Contenteditable Web Contract

Jump to bottom
유용태 edited this page Jun 24, 2026 · 3 revisions

Contenteditable Web Contract

This repo follows the naming and package shape used by json-document/packages/contenteditable-web.

Scope

packages/contenteditable-web is the thin browser bridge between @interactive-os/json-document and a browser contenteditable text surface. It is not a product editor, document schema, toolbar system, markdown layer, or React rendering framework.

The /codex route is only a smoke demo for the package contract.

Stable Responsibilities

  • Map DOM Selection to json-document SelectionSnap.
  • Keep native text input and IME composition inside a leased text surface.
  • Flush browser-owned text back to json-document through JSON Patch commits.
  • Preserve selectionAfter for undo/redo and toolbar commands.
  • Copy, cut, and paste plain text plus structured JSON fragments.
  • Treat atoms as one model character using \uFFFC.
  • Rebase range metadata for marks and other inline annotations.
  • Route undo/redo through json-document history.

Non-Goals

  • No legacy src/editor product surface.
  • No block editor command suite.
  • No overlay/caret geometry engine.
  • No markdown import/export policy.
  • No app-owned toolbar or design system.
  • No long audit/history documents in this repo.

Browser Boundary

The browser is allowed to own only the active text surface during native input or IME composition. The canonical document remains json-document.

Normal flow:

json-document transaction
  -> host render
  -> DOM selection restore

Native input flow:

contenteditable mutation
  -> read leased text surface
  -> json-document patch commit
  -> host render

IME flow:

compositionstart
  -> lease active text surface
  -> let browser own composition DOM
compositionend/input
  -> flush leased text
  -> release lease

Naming

Use contenteditable-web for the package because contenteditable is the standard browser concept and web names the DOM adapter layer.

Avoid tool-specific names such as codex/core for source modules or public contracts. The word codex may remain only as the demo route path when that URL is intentionally preserved.

Verification Contract

  • pnpm run test:core checks jsdom package contracts.
  • pnpm run verify:browser checks the /codex browser smoke route.
  • pnpm run verify:internal checks TypeScript, Vitest, Biome, and production build.

Clone this wiki locally