@aihu/editor

function activeState(core: EditorCore, sel: SelectionState | null): ActiveState

Toolbar-facing state (spec §9.2).

function applyStep(doc: DocNode, step: Step): string | null

function blockElOf(root: Element, node: Node): Element | null

Nearest ancestor (or self) carrying data-block-id, bounded by root.

function canExecute( core: EditorCore, sel: SelectionState | null, cmd: Command, features?: FeaturesConfig, ): boolean

function containerLength(node: InlineContainer): number

UTF-16 code-unit length of a container's flattened text (A3).

function containerText(node: InlineContainer): string

function diffToSteps(doc: DocNode, blockId: string, domText: string): Step[]

Flat single-container char diff (common prefix/suffix) → minimal steps.

function docEqualsIgnoringIds(a: DocNode, b: DocNode): boolean

Structural doc equality modulo ids (round-trip acceptance A4).

function emptyDoc(): DocNode

function executeCommand( core: EditorCore, sel: SelectionState | null, cmd: Command, features?: FeaturesConfig, origin: Origin = 'user.command', ): boolean

Execute a command against the resolved selection.

function findContainer(doc: DocNode, id: string): Located | null

Find any node (block, listItem) by id.

function freshId(): string

function fromMarkdown(src: string): DocNode

Markdown → DocNode.

function inlineContainers(doc: DocNode): InlineContainer[]

Document-ordered list of inline containers (listItems expanded in place).

function invertStep(step: Step, docBefore: DocNode): Step

function mapPoint(step: Step, p: Point): Point

function markAt(node: InlineContainer, offset: number): Mark | null

Mark of the code unit left of `offset` — what typed text inherits.

function matchInputRules( doc: DocNode, blockId: string, caretOffset: number, trigger: string, features: FeaturesConfig, extraRules: InputRule[] = [], ): { rule: InputRule; steps: Step[]; caretAfter: Point } | null

Find the first matching rule for the text before the caret.

function migrate(doc: unknown): DocNode

Versioned loader (I7): v1 loaders reject unknown major versions, forward-migrate known ones.

function normalizeRuns(runs: TextNode[]): TextNode[]

Normalize runs (I3): merge adjacent equal-mark runs, drop empty runs.

function parseInlineToRuns(src: string): TextNode[]

function plainTextToBlocks(text: string): BlockNode[]

Plain-text paste: blank lines split paragraphs; single newlines too (no hard breaks).

function readDomSelection(root: Element): SelectionState | null

function reconcileSteps(doc: DocNode, blockId: string, containerEl: Element): Step[]

Structure-aware reconciliation step for one container: null when the DOM already equals the model.

function resolveFeatures(f?: FeaturesConfig | null): FeaturesConfig

function runsFromDom(containerEl: Element): TextNode[]

Container element → normalized runs (structure-aware read, A2).

function safeHref(href: string): string | null

safeHref — the one link-safety contract (spec §6.1 step 4, threat T2).

function sanitizeHtmlToBlocks(html: string, features?: FeaturesConfig): BlockNode[]

HTML string → BlockNode[] via the inert-DOMParser allowlist walk.

function toDom(root: Element, point: Point): { node: Node; offset: number } | null

Model Point → DOM (node, offset).

function toJSON(doc: DocNode): DocNode

Canonical JSON (spec §8.1): the DocNode itself with stable key order and no undefineds — what persistence and agents see.

function toMarkdown(doc: DocNode): string

function toModel(root: Element, node: Node, offset: number): Point | null

DOM (node, offset) → model Point.

function validateDoc(doc: DocNode): string | null

Invariant check (spec §1.3) — run after every transaction; violation rejects the whole transaction.

function writeDomSelection(root: Element, state: SelectionState): boolean

const builtinRules: InputRule[]

const defaultFeatures: Required< Pick<FeaturesConfig, 'headings' | 'lists' | 'blockquote' | 'link'> > & FeaturesConfig

class AgentGateway

class EditorCore

class EditorView

interface ActiveState {
  marks: Set<'strong' | 'em' | 'code' | 'link'>
  blockType: 'paragraph' | 'heading' | 'blockquote' | 'listItem' | null
  headingLevel: 1 | 2 | 3 | null
  listOrdered: boolean | null
  canUndo: boolean
  canRedo: boolean
}

interface AgentCallResult {
  ok: boolean
  code?: string
  /** For suggest mode: the staged proposal id. */
  proposalId?: string
  result?: unknown
}

interface AgentProposal {
  id: string
  action: string
  origin: `agent:${string}`
  steps: Step[]
  createdAt: number
}

interface DocNode {
  schema: 'aihu-editor/doc'
  version: 1
  children: BlockNode[]
}

interface DocOutlineEntry {
  id: string
  type: BlockNode['type']
  level?: number
  text: string
}

interface EditorViewOptions {
  features?: FeaturesConfig
  readonly?: boolean
  inputRules?: InputRule[]
}

interface FeaturesConfig {
  headings?: boolean
  lists?: boolean
  blockquote?: boolean
  codeBlock?: boolean
  table?: boolean
  link?: boolean
  inputRules?: boolean | { disable?: string[] }
}

FeaturesConfig (spec §9.1): off ⇒ commands rejected, paste content degrades to text, input rules pruned.

interface HeadingAttrs {
  level: 1 | 2 | 3
}

interface InputRule {
  id: string
  scope: 'blockStart' | 'inline'
  /** Char whose insertion arms the check ('\n' = Enter, checked pre-split). */
  trigger: string
  /** Applied to block text [0, caret); must end at the caret. */
  match: RegExp
  apply(m: RegExpExecArray, ctx: InputRuleContext): Step[]
}

interface InputRuleContext {
  blockId: string
  caret: Point
  doc: DocNode
}

interface ListAttrs {
  ordered: boolean
}

interface ListItemNode {
  id: string
  type: 'listItem'
  content: TextNode[]
}

interface Point {
  block: string
  offset: number
}

A position: (inline-container id, UTF-16 code-unit offset into the flattened inline text — mark-transparent).

interface SelectionContext {
  selection: SelectionState | null
  /** Up to 80 code units either side of the caret/range, for grounding "insert here". */
  textAround: { before: string; after: string } | null
}

interface TextNode {
  text: string
  mark: Mark | null
}

A flat run of text carrying at most ONE mark (invariant I4 — dialect guard).

interface Transaction {
  id: string
  time: number
  origin: Origin
  steps: Step[]
  selectionAfter?: SelectionState
}

type AgentAccess = 'none' | 'read' | 'suggest' | 'write'

type ApplyResult = { ok: true; tr: Transaction } | { ok: false; code: string; step?: Step }

type BlockNode =
  | { id: string; type: 'paragraph'; content: TextNode[] }
  | { id: string; type: 'heading'; attrs: { level: 1 | 2 | 3 }; content: TextNode[] }
  | { id: string; type: 'list'; attrs: { ordered: boolean }; children: ListItemNode[] }
  | { id: string; type: 'blockquote'; content: TextNode[] }
  | { id: string; type: 'hr' }

type Command =
  | { type: 'toggleMark'; mark: 'strong' | 'em' | 'code' }
  | { type: 'setLink'; href: string | null }
  | { type: 'setBlockType'; block: 'paragraph' | 'blockquote' }
  | { type: 'setBlockType'; block: 'heading'; level: 1 | 2 | 3 }
  | { type: 'toggleList'; ordered: boolean }
  | { type: 'insertHr' }
  | { type: 'undo' }
  | { type: 'redo' }

type Dispose = () => void

type InlineContainer = Extract<BlockNode | ListItemNode, { content: TextNode[] }>

Any node that carries inline content and can be addressed by a Point.

type Mark =
  | { type: 'strong' }
  | { type: 'em' }
  | { type: 'code' }
  | { type: 'link'; attrs: { href: string } }

type Origin =
  | 'user.typing'
  | 'user.command'
  | 'user.paste'
  | 'inputrule'
  | 'history'
  | 'dom.readback'
  | 'load'
  | `agent:${string}`

Transaction origins (spec §2, amended per Phase-0: `dom.readback` is the MutationObserver recovery path's distinct origin — G3 attribution).

type SelectionState =
  | { type: 'caret'; at: Point }
  | { type: 'range'; anchor: Point; head: Point } // anchor = where drag started
  | { type: 'node'; block: string }

type Step =
  | { t: 'insertText'; at: Point; text: string; mark: Mark | null }
  | { t: 'insertRuns'; at: Point; runs: TextNode[] }
  | { t: 'deleteRange'; from: Point; to: Point } // same container
  | { t: 'setMark'; from: Point; to: Point; mark: Mark | null }
  | { t: 'setRuns'; id: string; runs: TextNode[] } // whole-container run replace (inverse carrier)
  | {
      t: 'splitBlock'
      at: Point
      newId: string
      /** Tail container kind. Default: same type for paragraph/listItem; paragraph for heading/blockquote. */
      tail?: { type: 'paragraph' | 'heading' | 'blockquote' | 'listItem'; attrs?: HeadingAttrs }
    }
  | { t: 'mergeBlock'; first: string; second: string }
  | {
      t: 'insertBlock'
      after: string | null // null = start (of doc, or of `in` list)
      node: BlockNode | ListItemNode
      /** Parent list id when inserting a listItem at list start (`after: null`). */
      in?: string
    }
  | { t: 'removeBlock'; id: string }
  | {
      t: 'setBlockType'
      id: string
      type: 'paragraph' | 'heading' | 'blockquote' | 'list'
      attrs?: HeadingAttrs | ListAttrs
      /** New wrapper-list id for the `→ list` conversion (the container keeps its id as the listItem). */
      newId?: string
    }
  | { t: 'setAttrs'; id: string; attrs: HeadingAttrs | ListAttrs }

Steps — the serializable, invertible mutation primitives (spec §2).