edytor

Every name edytor exports, with its declaration and documentation (generated from the published types).

Every name edytor exports, generated from the package’s published type declarations, with the documentation its JSDoc carries. The guides explain how the pieces fit; this page is the exhaustive list. 381 names.

ActorId

The durable per-block attribution record a replica sees.

export type ActorId = string;

ActorProfile

Replicated actor profile record payload (u/ values).

export type ActorProfile = {
    name?: string;
    color?: string;
};

AfterOperationPayload

What onAfterOperation receives: a ChangePayload without prevent (the operation already ran). The Omit distributes over the union, so operation still narrows payload (and text).

export type AfterOperationPayload = ChangePayload extends infer C ? C extends unknown ? Omit<C, 'prevent'> : never : never;

AnchorAffinity

Selection-endpoint affinity — which side of a position the anchor binds to (see T.atomAnchorAt):

• 'left' — bound to the atom BEFORE the position; resolves right after it, so a concurrent insert exactly at the position lands to the anchor’s right. Used for carets and range ENDS.
• 'right' — bound to the atom AT the position; resolves right before it, so a concurrent insert lands to the anchor’s left — outside a range starting here. Used for range STARTS.

export type AnchorAffinity = 'left' | 'right';

Announcer

export declare class Announcer {
    #private;
    private edytor;
    message: string;
    serial: number;
    constructor(edytor: Edytor);
    say: (message: string) => void;
    what: (blocks: readonly Block[]) => string;
    moved: (request: BlockMoveRequest, moved: readonly Block[]) => void;
    deleted: (what: string) => void;
}

• message: The last announcement.
• serial: Bumped by each announcement: the live region renders it as a new node.
• say: Announce message (politely: after what the screen reader is saying).
• what: blocks (one or several) as words: a kind’s label for one, a count for several.
• moved: request’s blocks moved (moveBlocks answered them).
• deleted: Blocks were deleted: what names them, read before they went.

attachDocument

See DocumentBinding.attachDocument.

declare const attachDocument: (doc: YDoc, options?: DocumentOptions) => EdytorDocument;

AttributionActor

The stable application-level author identity (mirrors DocumentActor).

export type AttributionActor = {
    id: string;
    name?: string;
    color?: string;
};

Awareness

Simple shared state protocol for non-persistent data (cursor, username, status…). Semantics are verbatim upstream: clock-ordered LWW per client, remote null states mark peers offline, local state is re-published when outdated, and remote states expire after outdatedTimeout.

export declare class Awareness extends IsolatedObservable<AwarenessEvents> {
    #private;
    doc: AwarenessDoc;
    clientID: number;
    states: AwarenessStates;
    meta: Map<number, MetaClientState>;
    private _destroyed;
    constructor(doc: AwarenessDoc);
    destroy(): void;
    getLocalState(): Record<string, unknown> | null;
    setLocalState(state: Record<string, unknown> | null): void;
    setLocalStateField(field: string, value: unknown): void;
    getStates(): AwarenessStates;
}

• states: Maps from client id to client state

AwarenessLike

Structural awareness surface used by publishPresence — the real Awareness satisfies it; tests may substitute stubs.

export type AwarenessLike = {
    getLocalState: () => Record<string, unknown> | null;
    setLocalState: (state: Record<string, unknown> | null) => void;
};

AwarenessStates

export type AwarenessStates = Map<number, Record<string, unknown>>;

AwarenessUpdate

export type AwarenessUpdate = {
    added: number[];
    updated: number[];
    removed: number[];
};

Block

An id-only, read-only block handle: every getter reads the document index (transaction-aware). Writes are the view’s operations, with the block’s id (edytor.splitBlock(block.id, …)). The view keeps one handle per id (edytor.idToBlock); node is the element the core renders for it.

A reactive reader (a template, a $derived, an $effect) of a getter depends on the cells the answer comes from (this block’s, its parent’s, the root’s list), so it re-runs when a commit changes them, as data does; a read anywhere else is a plain read of the document.

export declare class Block {
    #private;
    readonly: boolean;
    readonly edytor: Edytor;
    readonly id: string;
    node?: HTMLElement;
    constructor(edytor: Edytor, id: string);
    get isRoot(): boolean;
    get parent(): Block | undefined;
    get children(): Block[];
    get content(): (Text | InlineBlock)[];
    get type(): string;
    get data(): Readonly<Record<string, any>>;
    get definition(): BlockDefinition;
    get selected(): boolean;
    get focused(): boolean;
    get movable(): boolean;
    get convertible(): boolean;
    get index(): number;
    get depth(): number;
    get path(): number[];
    get isInTree(): boolean;
    get nextBlock(): Block | null;
    get previousBlock(): Block | null;
    get closestPreviousBlock(): Block | null;
    get closestNextBlock(): Block | null;
    get hasChildren(): boolean;
    get hasContent(): boolean;
    get isEmpty(): boolean;
    get isNested(): boolean;
    get value(): JSONBlock;
    isChildOf(block: Block): boolean;
    get rendersContent(): boolean;
    get isContainer(): boolean;
    get isListItem(): boolean;
    get list(): Block | undefined;
    get firstText(): Text | undefined;
    get lastText(): Text | undefined;
    void: (node: HTMLElement) => void;
    textAtOffset: (offset: number) => {
        text: Text;
        offset: number;
    } | null;
}

• parent: The display parent (the root for a top-level block); none for the root or a dead block.
• content: Text segments and inline atoms, alternating, starting and ending with a text.
• data: The block’s data, read-your-writes; a reactive reader depends on the block’s cell.
• movable: May this block move at all: canPlace without a destination (drag handles).
• convertible: May text-level structural commands (convert, markdown shortcut, slash menu) apply: the block is movable — or the virtual paragraph of an emptied document, which a conversion creates with its kind — has no role of its own and renders its own content — a container (a list) is never converted, its items are.
• isInTree: The block is visible in the document (a dead handle answers false).
• hasContent: It shows content: text or an inline atom (a block holding only a mention is not empty).
• isEmpty: It holds nothing: no content and no children (the emptiness Turn into reads, holdsNothing).
• value: This block’s JSON — the document’s one serializer (facade.blockJSON).
• rendersContent: Whether this kind renders its own content slot — the adopted capability.
• isContainer: A container: it shows only its children (a list), neither void nor an island — the document’s container rule.
• isListItem: An item of a list: its parent is a container whose items are a kind of their own (a list-item in an unordered-list), not the document’s default — a column of paragraphs is no list.
• list: The list this block shows in: its container when it is an item (isListItem), or — an item outdented out of a nested list into the item holding it — the list of the items of its kind it sits under.
• firstText: The first text of this block’s own content — none for a kind that does not render its content (a list container, a divider): its slot is never displayed, so no caret or endpoint may land there.
• lastText: The last text of this block’s own content (see firstText).
• void: Mark an element inside the block’s markup as non-editable chrome (a header, a caption bar).
• textAtOffset: The text segment that displays block offset offset, and the offset in it — the one offset → segment mapper over the committed parts (a boundary before an atom reads the text before it; past the end, the last text’s end).

BLOCK_ACTIVATE_EVENT

The DOM event a grip click dispatches on the editor (the one way to answer it: the block menu’s, or your own). A menu that takes the keyboard answers it with preventDefault() (the block menu does); unanswered, the editor takes the focus, so the keys act on the selected block (Backspace deletes it, Shift+arrows extend it).

declare const BLOCK_ACTIVATE_EVENT = "edytor-block-activate";

BLOCK_ADD_EVENT

The DOM event the + dispatches on the editor. A menu answers it with preventDefault() (the slash menu does), adds nothing until a row is picked, then calls insert(then); unanswered, the + inserts at once.

declare const BLOCK_ADD_EVENT = "edytor-block-add";

BLOCK_COLORS

Notion’s palette: the colour names a block may hold, in menu order (“Default” is none).

declare const BLOCK_COLORS: readonly [
    "gray",
    "brown",
    "orange",
    "yellow",
    "green",
    "blue",
    "purple",
    "pink",
    "red"
];

BlockActivation

export type BlockActivation = {
    block: Block;
    anchor: HTMLElement;
};

BlockAddition

export type BlockAddition = {
    block: Block;
    anchor: HTMLElement | null;
    insert: (then?: () => unknown) => unknown;
};

• anchor: The + clicked, else the block’s element.
• insert: Add an empty block of the parent’s default kind below block (above with Alt; an empty block of that kind is reused), put the caret in it and run then, as one undo step.

BlockAttribution

export type BlockAttribution = {
    createdBy?: ActorId;
    contributors: ReadonlySet<ActorId>;
    lastChangedBy?: ActorId;
};

• createdBy: The actor that created the block — assigned at creation, never rewritten.
• contributors: Union set of actors that committed an edit addressing this block id, plus the pre-split snapshot a split/merge copies to siblings — block-identity LINEAGE, add-only.
• lastChangedBy: The actor whose state change currently wins the LWW resolution.

BlockColorField

A block’s colour fields: its text colour and its background.

export type BlockColorField = 'color' | 'background';

BlockDefinition

Defines the structure and behavior of a block type.

export type BlockDefinition = {
    snippet?: Snippet<[
        BlockSnippetPayload<any>
    ]>;
    element?: BlockElement | ((data: Record<string, any>, id?: string) => BlockElement);
    contentElement?: BlockElement | ((data: Record<string, any>, id?: string) => BlockElement);
    viewState?: string[];
    void?: boolean;
    island?: boolean;
    lines?: boolean;
    layout?: boolean;
    table?: boolean;
    menu?: (block: Block) => KindMenuAction[];
    atomic?: readonly (string | readonly string[])[];
    rendersContent?: boolean;
    upload?: KindUpload;
    continues?: boolean;
    container?: boolean;
    body?: boolean;
    defaultChild?: string;
    itemKind?: string;
    presets?: KindPreset[];
    empty?: Pick<JSONBlock, 'content' | 'children'>;
    html?: string | ((block: JSONBlock, content: string, children: string) => string);
    plain?: (block: JSONBlock, content: string, children: string) => string;
    parse?: (element: HTMLElement) => Record<string, SerializableContent> | undefined;
    transformText?: TextTransform;
    onFocus?: (payload: {
        block: Block;
    }) => void;
    onBlur?: (payload: {
        block: Block;
    }) => void;
    onSelect?: (payload: {
        block: Block;
    }) => void;
    onDeselect?: (payload: {
        block: Block;
    }) => void;
    normalizeContent?: (payload: {
        block: Block;
    }) => (() => void) | void;
    normalizeChildren?: (payload: {
        block: Block;
    }) => (() => void) | void;
};

• snippet: The markup inside the block element; a kind whose element takes no content (hr) has none.
• element: The element the core renders for the block: a tag, or tag and attributes, possibly from the block’s data and id (the second argument: view state the kind keeps per block, such as a column’s width while a resize drags; reactive state it reads re-renders the element; absent when HTML import reads a kind’s tag for data alone).
• contentElement: The element the core wraps around the block’s own text (content()), possibly from the block’s data and id: a heading’s h1–h3, a quote’s blockquote.
• viewState: Attributes of the block element the browser or the user own (open on a details): declared view state, never inverted.
• void: A void kind (an image, a divider): one unit the editor never edits as text and never merges.
• island: An island kind (a code block, a table): editable inside, structurally sealed.
• lines: An island of lines (the code block): each direct child shows as this kind’s defaultChild and holds no children, even when an undo or a peer’s edit puts another kind or a nested block there.
• layout: A layout (the columns plugin’s columns): its defaultChild is its item kind (a column, a container that holds any block), shown side by side.
• table: A table (the table plugin’s table): its defaultChild is its row kind, a container whose own defaultChild is the cell kind (a text island).
• menu: Rows the block menu adds for a block of this kind, when it is opened on that block alone (a table’s Header row switch), after Turn into and Color.
• atomic: Data paths written as one value (data.atomic): a top-level key, or an array of keys for a nested one.
• rendersContent: Whether the snippet renders the block’s own content (content()).
• upload: The files the kind takes (the image’s image/*, the file block’s any): with the uploads plugin listed, an empty block’s Upload sends one and a pasted or dropped file becomes a block of this kind (media.files).
• continues: A list-like kind (Notion’s bullets, numbers, to-dos, toggles): Enter at the start or end of a non-empty block opens another block of this kind (with its first preset’s data), and Enter in an empty one ends the run — it outdents under a parent of a continuing kind, else turns into the parent’s default child in place (at the top level, in a callout).
• container: A container kind (Notion’s toggles, callouts, quotes): its content is a header over its children.
• body: A container whose children are a body that shows even while it is empty (Notion’s callout: a title over its content): Enter at the end of its header opens its first child, as an open toggle’s does, and a paste there leads that body.
• defaultChild: The type a new child of this block takes by default (Enter inside a child, a split, an island merged out into it).
• itemKind: A list container’s flat counterpart (numbered-list-item for an ordered-list): its items show as this kind, so the menus name them by it and turning one into it keeps it in the list.
• presets: Catalogue rows: one per way to create this kind — the slash menu, markdown shortcuts and block menus are generated from them (edytor.kinds).
• empty: The content and children a conversion into this kind creates (a void has none; an island starts with a first child).
• html: Clipboard HTML form: a tag wrapping content then children, or a function of the block and its serialized content and children.
• plain: Clipboard plain-text form; default content then children, one per line.
• parse: HTML import: the block’s data when element is this kind, else undefined.
• transformText: Transform text content within the block
• onFocus: Called when the block receives focus
• onBlur: Called when the block loses focus
• onSelect: Called when the block is selected
• onDeselect: Called when the block is deselected
• normalizeContent: Normalize block content Called at the end of the transaction of each operation that wrote the block’s content: the block is an id-only handle whose reads show the operation’s writes.
• normalizeChildren: Normalize block children Called at the end of the transaction of each operation that changed the block’s children: the block is an id-only handle whose reads show the operation’s writes.

BlockElement

The block element a kind declares: a tag, or a tag and attributes.

export type BlockElement = string | {
    tag: string;
    attributes?: Record<string, string | undefined>;
};

BlockHandleController

export declare class BlockHandleController {
    #private;
    private edytor;
    private options;
    private readonly owner;
    private readonly targets;
    private readonly registered;
    dragging: string | null;
    private scrolling;
    private group;
    private readonly indicator;
    private held;
    private handle;
    private gripped;
    constructor(edytor: Edytor, options?: BlockHandleControllerOptions);
    get readonly(): boolean;
    get draggable(): boolean;
    labelOf: (block: Block) => string;
    opened: (block: Block, control: PopupOpener["control"]) => Popup | undefined;
    grip: (block: Block) => Attachment<HTMLElement>;
    plus: (block: Block) => Attachment<HTMLElement>;
    addsColumn(block: Block): boolean;
    addBlock(block: Block, alt?: boolean, anchor?: HTMLElement | null): void;
    registerHandle(element: HTMLElement, block: Block): () => void;
    addDropTarget(node: HTMLElement, target: Block): () => void;
    private gutter;
    private margin;
    private halves;
    private pick;
    private reorder;
    private moving;
    private covered;
    dragBlocks(source: Block): Block[];
    private select;
    private fits;
    private rowAt;
    private get layouts();
    private besideOf;
    private layoutOf;
    private beside;
    private inside;
    private shown;
    private emptied;
    private zones;
    private placement;
    private carrier;
}

• dragging: The block whose handle is the source of the drag in progress (its handle stays mounted).
• labelOf: The block’s kind as people read it (kindLabel: “Heading 1”), its handle’s name; reactive through the block’s cell (a Turn into renames it).
• opened: The popup the + or the grip of block opened, while it is open (edytor.popups).
• grip: The block’s grip ({@attach handle.grip}): dragging (when draggable), a click that selects the block and opens its menu, the Alt+arrow moves (aria-keyshortcuts), and the ARIA of the menu it opened.
• plus: The block’s + ({@attach handle.plus}): a click offers what to add below (Alt+click above, or a column beside: addBlock) under it; a press keeps the editor’s focus; the ARIA of the menu it opened.
• addsColumn: Whether the +’s Alt+click on block adds a column right of its column (a block directly in a layout’s column, as Notion) rather than a block above it.
• addBlock: The +: offers the new block to a menu (BLOCK_ADD_EVENT), which adds it once the user picks what to insert; with none answering, adds it now (BlockAddition.insert).
• addDropTarget: A candidate drop target; registered at once when our drag is in progress.
• dragBlocks: The blocks a drag (or an Alt+arrow) from source’s handle moves (Notion): the outermost of those the selection covers (covered), in document order — a block’s children and a closed toggle’s hidden body travel with it; else source alone.

BlockHandleSnippetPayload

What a handle snippet receives.

export type BlockHandleSnippetPayload = {
    block: Block;
    label: string;
    grip: Attachment<HTMLElement>;
    plus: Attachment<HTMLElement>;
    add: (alt?: boolean, anchor?: HTMLElement | null) => void;
    beside: boolean;
    readonly: boolean;
    draggable: boolean;
};

• label: The block’s kind as people read it (“Heading 1”, its preset’s label): name your controls with it.
• grip: The grip’s attachment ({@attach handle.grip}): the drag source, a click that opens the block’s menu, the Alt+arrow moves (aria-keyshortcuts), and the ARIA of the menu it opened (aria-expanded, aria-controls, aria-haspopup).
• plus: The +’s attachment ({@attach handle.plus}): a click calls add (Alt+click with true) with the + as the anchor, a press keeps the editor’s focus, and the ARIA of the menu it opened.
• add: The +: the slash menu offers what to add below; with true (Alt+click) above, or, for a block directly in a layout’s column, in a new column right of its column.
• beside: Alt+click on the + adds a column right of the block’s (a block directly in a layout’s column): name your + with it.

BlockHandlesOptions

export type BlockHandlesOptions = {
    draggable?: boolean;
    handle?: Snippet<[
        BlockHandleSnippetPayload
    ]>;
};

• draggable: Keep the handle and its keyboard actions, but omit pointer dragging and drop targets.
• handle: The + and ⋮⋮ beside each block, and their words (without it, no handle shows and no block drags); placement and hover are the plugin’s.

BlockId

Logical block identifier — caller-assigned, immutable per block.

export type BlockId = string;

BlockMenuAction

export type BlockMenuAction = {
    id: string;
    label: string;
    icon: string;
    hint?: string;
    danger?: boolean;
    checked?: boolean;
    submenu?: 'turn' | 'color';
    isEnabled?: () => boolean;
    run?: () => unknown;
};

• checked: A switch’s state (a kind’s row, BlockDefinition.menu): the row is a menuitemcheckbox.
• submenu: Opens a flyout instead of running: the kinds (turn) or the colours (color).

BlockMenuColor

A row of the Color flyout: a text colour or a background, value null for the default.

export type BlockMenuColor = {
    id: string;
    label: string;
    field: BlockColorField;
    value: (typeof BLOCK_COLORS)[number] | null;
};

• id: color.<name> or background.<name> (color.default, background.default).
• label: Its words in the view’s labels (colorText, colorBackground): “Red text”, “Red background”, “Default text”.

BlockMenuController

export declare class BlockMenuController {
    #private;
    private edytor;
    private options;
    block: Block | null;
    blocks: Block[];
    anchor: HTMLElement | null;
    query: string;
    index: number;
    flyout: false | "color" | "turn";
    flyoutIndex: number;
    constructor(edytor: Edytor, options?: BlockMenuOptions);
    get isOpen(): boolean;
    get readonly(): boolean;
    get menuId(): string;
    get flyoutId(): string;
    rowId: (row: BlockMenuAction | KindRow | BlockMenuColor, flyout?: boolean) => string;
    popup: Attachment<HTMLElement>;
    flyoutMenu: Attachment<HTMLElement>;
    keys: Attachment<HTMLElement>;
    option: (index: number, flyout?: boolean) => Attachment<HTMLElement>;
    search(query: string): void;
    get members(): Block[];
    get kinds(): KindRow[];
    get colorable(): Block[];
    get colors(): BlockMenuColor[];
    isCurrentColor: (row: BlockMenuColor) => boolean;
    get flyoutRows(): Array<KindRow | BlockMenuColor>;
    get currentKind(): KindRow | undefined;
    get actions(): BlockMenuAction[];
    get matchingColors(): BlockMenuColor[];
    get rows(): Array<BlockMenuAction | KindRow | BlockMenuColor>;
    open(block: Block, anchor: HTMLElement): void;
    close(restoreCaret?: boolean): void;
    move(direction: 'up' | 'down'): void;
    turnInto(kind: KindRow): void;
    paint(row: BlockMenuColor): void;
    duplicate(blocks: Block[], select: boolean): void;
    remove(): void;
    get linked(): Block | undefined;
    copyLink(): Promise<void>;
    run(row: BlockMenuAction | KindRow | BlockMenuColor | undefined): void;
    openFlyout(which?: 'turn' | 'color'): void;
    private restore;
    private caret;
    private focus;
}

• block: The block whose grip opened the menu.
• blocks: The blocks the actions apply to, in document order: the block selection when it holds block (Notion), else block alone — as clicked, so a grip-selected list is one block (Move, Duplicate, Copy link, the caret after).
• index: The keyboard’s row.
• flyout: The open flyout: the kinds (turn), the colours (color), or none.
• flyoutIndex: The keyboard’s row in the open flyout.
• readonly: The editor is readonly: the menu closes.
• menuId: The menu’s and the Turn into flyout’s element ids (page-unique), for aria-controls.
• rowId: A row’s element id (page-unique; a flyout’s with flyout), for aria-activedescendant.
• popup: The menu element ({@attach controller.popup}, the one with the rows): it takes the menu’s id, its menu role and name unless it has its own, keeps the focus where it is on a press (a field takes its own), and is published to the view’s root (edytor.popups) while it is in the page, the grip that opened it told so.
• flyoutMenu: An open flyout ({@attach controller.flyoutMenu}, named by your markup): its id, menu role, the overlay’s placement beside the menu, and presses that keep the focus.
• keys: The element that holds the keyboard ({@attach controller.keys}: the search field): focused when it mounts, it takes every key of the menu (the arrows, Home and End walk the rows, → opens a row’s flyout and ← closes it, Enter runs the row, Delete removes the blocks while the query is empty, Escape closes the flyout, then the menu), and names the open menu and its highlighted row (aria-controls, aria-activedescendant, once that row is in the page).
• option: The attachment of the row at index (of the open flyout’s rows with flyout): {@attach controller.option(index)} on its element.
• search: The search field typed in: the rows match query, the first one highlighted, no flyout open.
• members: What Delete and Turn into act on: blocks, a list or a code block with its subtree (selectedMembers).
• kinds: The Turn into rows: the kinds, then the commands that turn blocks into something (turnCommands).
• colorable: The blocks the Color flyout paints: the members that take a colour (colorable).
• colors: The Color flyout’s rows: Notion’s text colours, then its backgrounds.
• isCurrentColor: Whether every block the flyout paints holds row’s colour (its ✓).
• flyoutRows: The rows of the open flyout.
• currentKind: The row naming the open block.
• matchingColors: With a query, the colours it names join the list after the kinds (Notion’s “Color” results: red lists “Red text” and “Red background”), when the blocks take one (colorable).
• rows: Every keyboard row: actions, then the matching kinds, then the matching colours.
• turnInto: Convert the open block, or every member (a list’s items) as one undo step (they stay selected); one block’s conversion places the caret (refused: the caret returns).
• paint: Paint the open blocks (colorable, a list’s items too) with row’s colour or background as one undo step (setBlockColor); the menu closes and the blocks stay selected, as in Notion.
• duplicate: Duplicate blocks as one undo step, each copy after its block (a block inside another of them is copied with it; a vetoed one is skipped, dispatcher.each); the copies are selected (select), else the first copy takes the caret (refused: its block keeps it).
• remove: Delete the open blocks’ members (a list with its items) as the keyboard’s block delete does (deleteSelectedBlocks): onDeleteSelectedBlocks may keep them, then one command (deleteBlocks, one plan, so a veto keeps them all), unselected children taking their parent’s place, the caret where that delete puts it (kept or refused: the caret or the selection returns).
• linked: The one block “Copy link” names: the open block, or the layout its block selection covers whole (liftLayouts); none for several.
• run: Run a row of the menu or of its open flyout (a click; Enter runs the keyboard’s): paint a colour, convert to a kind, open an action’s flyout or run it.
• openFlyout: Open a flyout on its first row (keyboard or mouse): the “Turn into” kinds (default) or the colours; that flyout already open stays as it is.

BlockMenuLabels

The block menu’s actions (its search matches them) and the block colours’ commands.

export type BlockMenuLabels = {
    turnInto: string;
    color: string;
    colors: Record<string, string>;
    colorText: (color: string) => string;
    colorBackground: (color: string) => string;
    copyLink: string;
    duplicate: string;
    moveUp: string;
    moveDown: string;
    delete: string;
    ctrl: string;
    shift: string;
    deleteKey: string;
};

• color: The Color row.
• colors: A color’s name, by its BLOCK_COLORS name (red), default for none.
• colorText: A text color row and command, from the color’s name (“Red text”).
• colorBackground: A background row and command, from the color’s name (“Red background”).
• ctrl: Key names in the shortcuts shown off a Mac.

BlockMenuOptions

export type BlockMenuOptions = {
    linkTo?: (block: Block) => string;
    menu?: Snippet<[
        BlockMenuController
    ]>;
};

• linkTo: A link to the block, for “Copy link to block” (the row is hidden without it).
• menu: The menu’s markup and its words; it renders while controller.isOpen, placed beside the handle (mark your panel data-edytor-block-menu for placement; without it, nothing shows).

BlockMoveDirection

One relative step: up/down pass the previous/next sibling, never entering its children, and past the first/last sibling leave the parent (before/after it; a layout’s column: the layout, layout.fits); in = last child of the previous sibling; out = after the parent, the siblings after the last moved block becoming its children (the document’s outdent, unNestBlocks).

export type BlockMoveDirection = 'up' | 'down' | 'in' | 'out';

BlockMovePosition

Where a move places the blocks relative to its target: before, after, inside (its last child), or left/right of it, side by side (prepare.placeBeside, layout.place-beside: a new column of the layout the target is in, else a new layout wrapping the target).

export type BlockMovePosition = 'before' | 'after' | 'inside' | 'left' | 'right';

BlockMoveRequest

export type BlockMoveRequest = {
    blocks: Block[];
} & ({
    target: Block;
    position: BlockMovePosition;
} | {
    direction: BlockMoveDirection;
});

BlockRole

Structural role of a block type (plugin-side policy, resolved per op).

export type BlockRole = {
    void?: boolean;
    island?: boolean;
    lines?: boolean;
    layout?: boolean;
    table?: boolean;
    atomic?: readonly (string | readonly string[])[];
};

• void: Not editable through normal structural flow; no children, no merges.
• island: Editable, but its subtree is structurally sealed from outside blocks.
• lines: An island of lines (code): each direct child displays as its defaultChild kind and holds no children.
• layout: A layout (columns): it displays only its items — its defaultChild kind, a container that renders no content — side by side, and only while it shows two or more (layout.* in the delete contract).
• table: A table: it displays only its rows — its defaultChild kind, a container whose own defaultChild is the cell kind (a text island) — and each row only its cells, in the order of the table’s data.columns (table.* in the delete contract).
• atomic: Data paths written as one leaf (data.atomic): a top-level key, or an array of keys for a nested one (['link', ['media', 'source']]).

BlockSnippetPayload

Represents the payload for block snippets.

export type BlockSnippetPayload<D = Record<string, any>> = {
    block: BlockView<D>;
    content: Snippet;
    children: Snippet | null;
};

BlockSpec

Declarative block description used for inserts (and by seeders).

export type BlockSpec = {
    id: BlockId;
    type: string;
    data?: Record<string, unknown>;
    content?: ContentItem[];
    children?: BlockSpec[];
};

BlockView

What a block snippet receives: declared values read from the block’s cell and the selection — reactive, never the block’s handle itself — plus the handle for document reads and commands.

export type BlockView<D = Record<string, any>> = {
    readonly id: string;
    readonly type: string;
    readonly data: Readonly<D>;
    readonly selected: boolean;
    readonly focused: boolean;
    readonly handle: Block | undefined;
    void: Block['void'];
};

• handle: The block’s id-only, read-only handle (its getters, reactive in a template); undefined in a suggestion’s preview, which is no block of the document.
• void: Marks inner chrome (a header, a toolbar) non-editable; the block element is the core’s.

BookmarkCardPayload

What a bookmark’s card snippet receives: the page it links to, as unfurl described it.

export type BookmarkCardPayload = {
    block: Block | undefined;
    url: string;
    title: string | undefined;
    description: string | undefined;
    image: string | undefined;
    icon: string | undefined;
    link: Attachment<HTMLElement>;
};

• block: The bookmark; undefined in a suggestion’s preview.
• url: The page’s URL (http(s)).
• title: Its title, description, cover image and icon, when unfurl answered them.
• link: The card’s link (<a href={card.url} {@attach card.link}>): a new tab without the opener, never dragged out of the editor.

BookmarkPluginOptions

export type BookmarkPluginOptions = {
    unfurl?: (url: string) => Promise<BookmarkPreview | null | undefined>;
    menu?: Snippet<[
        UrlPasteController
    ]>;
    card?: Snippet<[
        BookmarkCardPayload
    ]>;
};

• unfurl: Read a page’s title, description and images, usually through your server (a browser cannot fetch most pages).
• menu: The menu a URL pasted on an empty line opens (Link, Embed, Bookmark); it renders while controller.open, under the line (without it, the link is kept and nothing shows).
• card: The card of a bookmark with a link (default: Notion’s, the title, description and URL beside the cover): <a href={card.url} {@attach card.link}>.

BookmarkPreview

What an unfurl answers about a page; every field optional.

export type BookmarkPreview = {
    title?: string;
    description?: string;
    image?: string;
    icon?: string;
};

• image: The page’s cover image (og:image): an http(s) URL.
• icon: The page’s icon: an http(s) URL.

CALLOUT_ICONS

The picker’s choices unless createCalloutIconsPlugin({ icons }) names others.

declare const CALLOUT_ICONS: readonly string[];

CalloutIconPayload

What a callout’s calloutIcon snippet receives.

export type CalloutIconPayload = {
    readonly block: Block | undefined;
    readonly icon: string;
    readonly editable: boolean;
    readonly expanded: boolean;
    readonly label: string;
    toggle: () => void;
    readonly control: Attachment<HTMLElement>;
};

• block: The callout; undefined in a suggestion’s preview.
• icon: Its icon: its data.icon, the view’s default without one, '' for none (reactive).
• editable: The icon opens the view’s picker: an editable view listing a picker, not a suggestion’s preview.
• expanded: The picker is open on this callout (reactive).
• label: The button’s accessible name: Change icon, or Add icon over an empty slot.
• toggle: Open the view’s picker on this callout, or close it.
• control: The icon’s attachment ({@attach icon.control}): its marker (data-edytor-callout-icon, which the picker opens under), data-empty without an icon, contenteditable="false"; editable, its aria-label, aria-haspopup, aria-expanded, aria-controls, a press that keeps the editor’s selection and a click that toggles the picker; else aria-hidden.

CalloutIconPicker

A view’s callout icon picker: what a callout.picker snippet receives. The callout it is open on (block), the choices (icons) and the icon that callout shows (current); set(icon) and remove() write it and close, close() closes with nothing written. Put {@attach picker.keys} and {@attach picker.popup} on the picker’s element (it takes the focus and the keys, names the keyboard’s row and is published to the view’s root), attach picker.option(i) to each row (i in icons, icons.length for Remove icon) and run picker.pick(i) on its click.

export declare class CalloutIconPicker extends ChromeList {
    #private;
    readonly icons: readonly string[];
    target: string | null;
    readonly columns = 8;
    constructor(edytor: Edytor, icons?: readonly string[]);
    get isOpen(): boolean;
    get block(): Block | undefined;
    get current(): string | undefined;
    protected get count(): number;
    get readonly(): boolean;
    toggle: (block: Block) => void;
    open: (block: Block) => void;
    close: (keys?: boolean) => void;
    set: (icon: string) => void;
    remove: () => void;
    pick: (index: number) => void;
    option(index: number): Attachment<HTMLElement>;
    keys: Attachment<HTMLElement>;
}

• icons: The picker’s choices.
• target: The callout the picker is open on (its id), null when closed.
• columns: The choices on a row: ArrowUp and ArrowDown move by a row, so lay the icons out in as many columns.
• isOpen: Whether the picker is open (reactive).
• block: The callout it is open on (reactive).
• current: The icon that callout shows ('': none; reactive).
• count: The keyboard’s rows: the icons, then Remove icon.
• readonly: The view is readonly (reactive): the picker closes.
• toggle: Open the picker on block, or close it when it is open there.
• open: Open the picker on the callout block, its icon the keyboard’s row (refused in a view that may not write).
• close: Close the picker; with keys (by default), the editor takes the keys back, with its selection.
• set: Write icon on the callout (one undo step), then close.
• remove: Leave the callout without an icon (data.icon is ''), then close.
• pick: Pick row index: its icon, or Remove icon (icons.length).
• option: Row index’s attachment (icons.length: Remove icon), as every menu’s rows: its id, menuitemradio role and aria-checked (menuitem for Remove icon); its highlight is the markup’s (index).
• keys: The picker’s element ({@attach picker.keys}): it takes the focus as it opens and names the keyboard’s row (aria-activedescendant).

CalloutIconsOptions

export type CalloutIconsOptions = {
    picker?: Snippet<[
        CalloutIconPicker
    ]>;
    icons?: readonly string[];
};

• picker: The icon picker’s markup and its words: it renders while the picker is open, placed under the icon (without it, the icon opens nothing).
• icons: The picker’s choices (CALLOUT_ICONS by default).

Caret

A caret in block offsets: the block and the offset in its content, the offsets edytor.document.facade takes (an inline atom counts 1). The public form of a collapsed text selection (selection.caret), and what selection.setCaret and dispatcher.caret take.

export type Caret = {
    block: Block;
    offset: number;
};

Cell

export type Cell = {
    readonly id: BlockId;
    readonly type: string;
    readonly data: Data;
    readonly childIds: readonly BlockId[];
    readonly runs: readonly ContentRun[];
};

Cells

export type Cells = {
    readonly rootIds: readonly BlockId[];
    readonly size: number;
    get: (id: BlockId) => Cell | undefined;
    apply: (report: CellReport) => Patched;
    remount: (id: BlockId) => void;
    epoch: (id: BlockId) => number;
    dispose: () => void;
};

• rootIds: The root’s visible child ids.
• apply: Patch from one change report.
• remount: Re-create a block’s text elements from its cell (the observer’s repair of foreign damage).
• epoch: Bumped by remount: part of the block’s text element keys.

ChangePayload

What onBeforeOperation receives: a document write under its name with its arguments (payload: Parameters<DocumentWrites[K]>), or a view command with its payload (Commands); operation narrows payload.

export type ChangePayload = {
    [K in keyof DocumentWrites]: Change<K, Parameters<DocumentWrites[K]>>;
}[keyof DocumentWrites] | {
    [K in keyof Commands]: Change<K, Commands[K]>;
}[keyof Commands];

clearDocument

declare const clearDocument: ProviderStack['clearDocument'];

CODE_LANGUAGES

The default languages, after Notion’s list, sorted by label (Plain text first).

declare const CODE_LANGUAGES: readonly CodeLanguage[];

CodeHeader

What a code plugin’s header snippet receives: the code block’s language (language, its id; label, as shown), whether the language may be changed here (editable: an editable view, not a suggestion’s preview), the list’s state (expanded), the actions (toggle, the list’s own pick, copy, and copied for a moment after a copy) and the plugin’s labels. Put {@attach header.button} on the element that opens the language list: it opens it on a click, ArrowDown or ArrowUp, Escape gives the keys back to the editor, the toolbar’s shortcut at a caret in the block reaches it, and it carries the ARIA (aria-haspopup, aria-expanded, aria-controls, its name).

export declare class CodeHeader {
    #private;
    copied: boolean;
    get block(): Block | undefined;
    get language(): string;
    get label(): string;
    get readonly(): boolean;
    get editable(): boolean;
    get expanded(): boolean;
    toggle: (keys?: boolean) => void;
    copy: () => Promise<void>;
    button: Attachment<HTMLElement>;
}

• copied: Copy just copied: the button may read Copied (reactive, for a moment).
• block: The code block; undefined in a suggestion’s preview.
• language: The block’s language id: its data.language, else the plugin’s default (reactive).
• label: The language’s label; a language the plugin does not list shows its id (reactive).
• readonly: The view is readonly (reactive).
• editable: The language may be changed here: an editable view, not a suggestion’s preview (reactive).
• expanded: The language list is open on this block (reactive).
• toggle: Open the language list under the header’s button, or close it (keys: the keyboard opened it, so the keys go back to the button after).
• copy: Copy the block’s code to the clipboard; copied reads true for a moment.
• button: The element that opens the language list ({@attach header.button}, a button): a click opens or closes it (from Enter or Space, the keys opened it and get it back), ArrowDown or ArrowUp opens it, Escape gives the keys back to the editor; a press keeps the editor’s selection.

CodeLabels

export type CodeLabels = {
    code: string;
};

• code: The preset (a language’s name is its CodePluginOptions.languages row’s).

CodeLanguage

A language a code block may be in.

export type CodeLanguage = {
    id: string;
    label: string;
    grammar?: string;
    load?: () => Promise<readonly LanguageDefinition[]>;
};

• id: Stored in the code block’s data.language.
• label: Shown in the header and its picker.
• grammar: The name of the grammar its lines are tokenized with; absent, its lines are plain text (no tokens).
• load: Loads the grammar, then the grammars it embeds (HTML’s styles and scripts).

CodePluginOptions

export type CodePluginOptions = {
    languages?: readonly CodeLanguage[];
    defaultLanguage?: string;
    header?: Snippet<[
        CodeHeader
    ]>;
    menu?: Snippet<[
        LanguageMenu
    ]>;
};

• languages: The languages a code block may be in, in the header’s order, with their names.
• defaultLanguage: The language of a code block whose data.language is unset.
• header: A code block’s header (the language’s button and Copy) and its words: it renders above the code, in the block’s non-editable part (without it, no header).
• menu: The language list: it renders under the header’s button while menu.open is set (without it, nothing shows).

ColumnsLabels

export type ColumnsLabels = {
    columns: (count: number) => string;
    resize: string;
};

• columns: The columns.<n> command.
• resize: A resize band’s accessible name.

ColumnsPluginOptions

export type ColumnsPluginOptions = {
    minWidth?: number;
};

• minWidth: The narrowest a column may be resized to, as a fraction of its layout’s width (default 0.1).

CommandResult

The result of the last command a view ran (edytor.dispatcher.last): its operation and its status.

export type CommandResult = {
    operation: string;
    status: 'refused' | 'noop' | 'applied' | 'failed';
    error?: unknown;
    selection?: SelectionValue;
};

• selection: The result selection the command authored, selected once.

Commands

The view’s commands that are no single document write, each one prepared plan of them, with their payloads: a hook sees each by its name, then its planned steps as the writes they perform.

export interface Commands {
    acceptSuggestion: {
        suggestion: {
            id: string;
            at: ResolvedAt;
            content: readonly JSONBlock[];
        };
    };
    replaceMatches: {
        matches: {
            block: string;
            offset: number;
            length: number;
        }[];
        replacement: string;
    };
    addComment: {
        thread: string;
        runs: {
            block: string;
            offset: number;
            length: number;
        }[];
    };
    moveText: {
        from: {
            start: {
                block: string;
                offset: number;
            };
            end: {
                block: string;
                offset: number;
            };
        };
        to: {
            block: string;
            offset: number;
        };
        copy: boolean;
    };
    inlineMarkdown: {
        value: string;
        start: number;
        end: number;
    };
    insertDivider: Record<string, never>;
    insertTableRow: {
        index: number;
    };
    deleteTableRows: {
        rows: Block[];
    };
    insertTableColumn: {
        index: number;
        width?: number;
    };
    deleteTableColumn: {
        column: string | number;
    };
    moveTableColumn: {
        column: string | number;
        to: number;
    };
    moveTableRows: {
        rows: Block[];
        to: number;
    };
    fillTableCell: {
        row: string;
        column: string | number;
    };
}

• acceptSuggestion: A suggestion placed in the document (edytor.suggestions, suggestion.accept()).
• replaceMatches: Find and replace (plugins/find): each match’s text replaced by replacement, one plan, one undo step.
• addComment: A comment thread’s anchor (plugins/comments): its comment:<thread> mark over each run of the text it was made on, one plan, one undo step.
• moveText: A text range dragged inside the editor and dropped at to (block offsets): its content placed at to, then the range deleted — or, with copy (Alt), only placed.
• inlineMarkdown: A closing marker typed after marked-up text (**bold**): the mark set, the markers removed; value typed at start of the text.
• insertDivider: A divider at the caret: its steps are the conversion, insertion or split it plans.
• insertTableRow: A table’s row at index, one empty cell per column (table.insert-row).
• deleteTableRows: A table’s rows, with their cells (table.delete-row).
• insertTableColumn: A table’s column at index, an empty cell in every row (table.insert-column).
• deleteTableColumn: A table’s column, by id or position, with its cells (table.delete-column).
• moveTableColumn: A table’s column moved to position to (table.move-column).
• moveTableRows: A table’s rows moved to position to among its rows (table.move-row).
• fillTableCell: The cell a row shows none of in column, created (table.pad).

commentAnchors

Every thread’s anchor in doc: the runs of text its comment:<id> mark covers, in document order (adjacent runs of one block joined). A split or a merge moves the marked text, never copies it, so a thread keeps its runs through both; a thread whose marked text was deleted has none.

declare const commentAnchors: (doc: CommentAnchorSource) => Map<string, CommentRun[]>;

CommentCardPayload

What a card snippet receives: one thread (null: the comment being written, comments.draft), the view’s comments controller, and whether it is the active one.

export type CommentCardPayload = {
    thread: PlacedThread | null;
    comments: CommentsController;
    active: boolean;
};

• thread: The thread, placed beside its text (its comments, its anchor’s text, resolved); null for the comment being written (its text comments.draft.quote: post it with comments.submit(body), give it up with comments.cancel()).
• comments: The view’s comments: the actions (reply, resolve, delete, activate), the user.
• active: It is the active thread (its text is selected, or its card was pressed).

CommentChange

What one request changed (the room broadcasts it, onComment receives it).

export type CommentChange = {
    type: 'added' | 'replied' | 'resolved' | 'reopened' | 'deleted' | 'removed';
    thread: CommentThread;
    comment: ThreadComment | null;
    user: string;
    at: number;
    seq: number;
};

• type: added a thread, replied to one, resolved or reopened one, deleted a reply, or removed a whole thread (its anchor marks go with it).
• thread: The thread after the change; for removed, as it was.
• comment: The comment added (added, replied) or deleted (deleted), else null.
• user: Who made the change.
• seq: The change’s sequence number in its document (the thread’s new rev).

CommentDocument

What a client reads and writes of a document: its blocks’ content, and its marks (a removal).

export type CommentDocument = CommentAnchorSource & {
    formatRange(block: string, offset: number, length: number, marks: Record<string, unknown>): unknown;
    transact<T>(fn: () => T): T;
};

CommentDraft

The thread being written: the text it will anchor, held by anchors so edits move it.

export type CommentDraft = {
    id: string;
    quote: string;
    block: string;
    spans: {
        start: DocAnchor;
        end: DocAnchor;
    }[];
};

• id: The new thread’s id (its anchor will be comment:<id>).
• quote: The text it was started on (a preview: the server keeps it as the thread’s quote).
• block: The block it starts in.
• spans: Each run of selected text, by anchors.

CommentFeed

What a client’s subscribe delivers: every thread (at a (re)connect), or one change.

export type CommentFeed = Exclude<CommentMessage, {
    type: 'subscribe';
}>;

CommentMessage

A comment message, decoded.

export type CommentMessage = {
    type: 'subscribe';
    on: boolean;
} | ({
    type: 'snapshot';
} & CommentSnapshot) | {
    type: 'change';
    change: CommentChange;
};

CommentNotice

What onComment receives with each change: whether the current user made it (here or elsewhere).

export type CommentNotice = {
    own: boolean;
};

CommentRequest

A request to a document’s comments, by the user a store verified.

export type CommentRequest = {
    op: 'add';
    thread: string;
    body: string;
    quote?: string;
    block?: string | null;
    comment?: string;
} | {
    op: 'reply';
    thread: string;
    body: string;
    comment?: string;
} | {
    op: 'resolve';
    thread: string;
} | {
    op: 'reopen';
    thread: string;
} | {
    op: 'delete';
    thread: string;
    comment?: string;
};

CommentRequestError

A comments request the server refused: status is its HTTP status (400, 403, 404, 409…).

export declare class CommentRequestError extends Error {
    readonly status: number;
    constructor(status: number, message: string);
}

CommentResult

What a request did: applied (the change) or noop (the thread, unchanged).

export type CommentResult = {
    status: 'applied';
    change: CommentChange;
} | {
    status: 'noop';
    thread: CommentThread;
};

CommentRun

One run of text a thread’s anchor mark covers: length units from offset of block.

export type CommentRun = {
    block: string;
    offset: number;
    length: number;
};

CommentsClient

A document’s comment threads, as the comments plugin reads and writes them.

export type CommentsClient = {
    list(): Promise<CommentSnapshot>;
    send(request: CommentRequest): Promise<CommentResult>;
    subscribe?(listener: (message: CommentFeed) => void): () => void;
    attach?(document: CommentDocument): (() => void) | void;
};

• list: Every thread, with the document’s last sequence number.
• send: One request (add, reply, resolve, reopen, delete) as the client’s user.
• subscribe: Hear the changes anyone makes (and every thread again after a reconnect).
• attach: The document a view shows, given by the comments plugin when it mounts: a client whose store has no document of its own (the memory client) removes a removed thread’s anchor marks from it.

CommentsClientOptions

Options of createCommentsClient.

export type CommentsClientOptions = {
    server: string;
    room: string;
    socket?: string;
    params?: Record<string, string> | (() => Record<string, string>);
    fetch?: typeof fetch;
};

• server: The base URL of the comments route: requests go to <server>/<room>, the room percent-encoded as one path segment (ws:/wss: read as http:/https:).
• room: The document’s id.
• socket: The websocket sync’s server URL (the server of <Edytor> or createWebsocketSync), whose socket hears the room’s changes.
• params: Query parameters sent with each request (a token): an object, or a function read at every request.
• fetch: The fetch to use (default the global one).

commentsController

The comments plugin’s controller of edytor; undefined when the plugin is not listed.

declare const commentsController: (edytor: Edytor) => CommentsController | undefined;

CommentsController

The comments plugin’s state and actions (plugins/comments): the threads the client hears (merged by their newest change), each thread’s anchor read from the document (its comment:<id> mark), the thread being written, the active one (the caret’s, or the one clicked), and the requests. The anchor mark is written by one dispatcher command (addComment) once the server accepted the thread; a removed thread’s marks are its store’s to remove (the room, or the memory client).

export declare class CommentsController {
    #private;
    private edytor;
    private options;
    active: string | null;
    draft: CommentDraft | null;
    showResolved: boolean;
    error: string | null;
    readonly client: CommentsClient;
    readonly user: CommentUser;
    constructor(edytor: Edytor, options: CommentsControllerOptions);
    readonly anchors: Map<string, CommentRun[]>;
    readonly threads: PlacedThread[];
    readonly open: PlacedThread[];
    readonly resolved: PlacedThread[];
    readonly shown: PlacedThread[];
    get canComment(): boolean;
    thread(id: string): PlacedThread | undefined;
    userOf: (id: string) => CommentUser;
    mayDelete: (thread: CommentThread, comment: {
        author: string;
    }) => boolean;
    connect: () => void;
    destroy: () => void;
    start: () => boolean;
    cancel: () => void;
    draftRuns: (draft?: CommentDraft | null) => CommentRun[];
    submit: (body: string) => Promise<boolean>;
    reply: (thread: string, body: string) => Promise<boolean>;
    resolve: (thread: string) => Promise<boolean>;
    reopen: (thread: string) => Promise<boolean>;
    remove: (thread: string, comment?: string) => Promise<boolean>;
    focus: (thread: string | null) => void;
    follow: () => void;
    readonly css: string;
}

• active: The thread the caret is in, or the one picked in the sidebar.
• draft: The thread being written, before it is posted.
• showResolved: The sidebar also shows the resolved threads.
• error: The last request that failed (its message), until the next one succeeds.
• anchors: Every thread’s anchor runs, in document order (maintained per commit).
• threads: Every thread, in the order of its anchor in the document (threads with none last).
• open: The open threads whose text shows (what the sidebar places by default).
• resolved: The resolved threads.
• shown: The threads the sidebar shows: the open ones, the resolved ones on demand, the active one.
• canComment: The view may write: it may start, answer, resolve and delete comments.
• thread: One thread, by id.
• userOf: A user as the sidebar shows them: their name (else their id), avatar and color.
• mayDelete: Whether the current user may delete comment of thread (its author).
• connect: Start hearing the threads: the client’s list, its changes, the document’s commits.
• destroy: Stop hearing them (the editor is going away).
• start: Start a thread on the selected text (the toolbar’s Comment button, Mod+Shift+M): each selected run, held by anchors while it is written; at a caret, its block’s whole text.
• cancel: Drop the thread being written; the editor takes the focus back.
• draftRuns: The runs the draft’s anchors cover now.
• submit: Post the thread being written: the server keeps it, then its anchor mark is written over the draft’s text (one addComment command, one undo step).
• remove: Delete one comment; without comment (or its first), the whole thread.
• focus: Make thread the active one (a click on its card); its text scrolls into view.
• follow: The caret moved (onSelectionChange): the thread whose text holds it becomes the active one (an open one first), or none.
• css: The highlight of the threads’ text: open threads, the active one stronger.

CommentsLabels

The comments plugin (createCommentsPlugin): its toolbar button and its sidebar.

export type CommentsLabels = {
    comment: string;
    sidebar: string;
};

• comment: The toolbar button, and a thread’s card’s accessible name.
• sidebar: The sidebar’s accessible name.

CommentSnapshot

The document’s threads at sequence number seq.

export type CommentSnapshot = {
    seq: number;
    threads: CommentThread[];
};

CommentsPluginOptions

export type CommentsPluginOptions = {
    client: CommentsClient;
    user: string | CommentUser;
    users?: (id: string) => Omit<CommentUser, 'id'> | undefined;
    onComment?: (change: CommentChange, notice: CommentNotice) => void;
    card?: Snippet<[
        CommentCardPayload
    ]>;
    header?: Snippet<[
        CommentsController
    ]>;
};

• client: Where the threads live: createCommentsClient({ server, room }) for the room’s (routeDocumentComments), createMemoryCommentsClient for threads in memory, or any object with list and send.
• user: The current user: their id (the identity your server verifies; it decides who may delete a comment) or { id, name, avatar, color }.
• users: How another user shows: their name, avatar and color, by id (default: the id).
• onComment: Notifications: each change this view hears (a thread added, a reply, a resolve or reopen, a delete), once; own when the current user made it (in this view or another).
• card: A card’s markup: a thread’s (its comments, a reply field, Resolve) or the comment being written (thread: null).
• header: The top of the sidebar’s margin (Notion’s “Show resolved”): the cards stack under it.

CommentThread

A comment thread: its first comment starts it, the others reply.

export type CommentThread = {
    id: string;
    block: string | null;
    quote: string;
    createdBy: string;
    createdAt: number;
    resolved: {
        by: string;
        at: number;
    } | null;
    comments: ThreadComment[];
    rev: number;
};

• id: The thread’s id, which its anchor mark names (comment:<id>).
• block: The block it was started in (null: unknown).
• quote: The text it was started on, as it read then (at most MAX_QUOTE_LENGTH).
• resolved: Who resolved it and when; null while it is open.
• comments: Oldest first; never empty.
• rev: The sequence number of the last change to it (a later change has a greater one).

CommentUser

Who a comment’s author is, as the sidebar shows them.

export type CommentUser = {
    id: string;
    name?: string;
    avatar?: string;
    color?: string;
};

• name: Shown in place of the id.
• avatar: An avatar image URL; without one, the name’s initial on color.

ContentItem

One inline content element in a block spec / projection.

export type ContentItem = {
    kind: 'text';
    text: string;
    marks?: Record<string, unknown>;
} | {
    kind: 'inline';
    id: string;
    type: string;
    data?: Record<string, unknown>;
};

ContentRun

One visible run of a block — the maintained form of ContentItem. marks/data are interned: equal payloads share one frozen instance, so === compares formatting without deep walks. A run carries no authorship: runs never split at author boundaries, and durable attribution is the compact per-block record (blockattr).

export type ContentRun = {
    kind: 'text';
    text: string;
    marks?: Record<string, unknown>;
} | {
    kind: 'inline';
    id: string;
    type: string;
    data?: Record<string, unknown>;
};

convertToKind

Convert block to a row’s kind as one command. With caret (by default when the conversion replaces the content) the caret lands at the start of the converted block, or of its first child when the conversion creates one. A replacing kind (a divider, a code block) converts in place only a block that holds nothing (holdsNothing); after text, atoms or children it is inserted after the block instead, which stays intact. The kind lands where it fits (placing): a list’s item turned into another kind leaves the list — out of every list it sits in directly (a list nested right in a list) — where Shift+Tab lifts it, as a bullet turned into a heading stops being a bullet in Notion; a block’s own kind (only its data changes) never moves it. Each is one plan: one refusal or veto keeps everything, one undo step. Answers whether it applied.

declare const convertToKind: (edytor: Edytor, block: Block | null | undefined, row: Pick<KindRow, "value" | "replaces">, caret?: boolean) => boolean;

createArrowMovePlugin

Block moves from the keyboard (Mod+Up/Down, Mod+Shift+Up/Down): a default plugin.

declare const createArrowMovePlugin: () => Plugin;

createAudioPlugin

Notion’s audio block: an audio file (an http(s) link, or an upload through upload) in the browser’s player, with an editable caption. Void: its only text is the caption.

declare const createAudioPlugin: () => Plugin;

createBlockHandlesPlugin

Block handles in the overlay, created lazily: a handle mounts for a block near the viewport (the overlay’s near top-level blocks and the blocks inside them, not hidden; every block without layout), under the pointer, selected, focused or dragged; drop targets exist only during our own drag. Hover is one delegated listener on the editor and one on the overlay (a block’s handle keeps it hovered).

declare const createBlockHandlesPlugin: (options?: BlockHandlesOptions) => Plugin;

createBlockMenuPlugin

Notion’s block menu: a handle click opens it beside the handle — search, Turn into, Color, Duplicate, Move, Delete, and Copy link when linkTo is given. Also binds Mod+D (duplicate the selected blocks, or the caret’s block), and adds the colours to the slash menu by name (/red: “Red text”, “Red background”).

declare const createBlockMenuPlugin: (options?: BlockMenuOptions) => Plugin;

createBookmarkPlugin

Notion’s web bookmark: a card linking to a page, with its title, description and images when your unfurl answers them, and an editable caption. Void: its only text is the caption. Pasting an http(s) link on an empty line offers “Bookmark”.

declare const createBookmarkPlugin: (options?: BookmarkPluginOptions) => Plugin;

createCalloutIconsPlugin

Callout icons (Notion’s): a callout’s icon opens the view’s picker, and its block menu has a Change icon row (rich text’s, while a picker is listed), the keyboard’s way to it. The first plugin listed claims the view’s picker.

declare const createCalloutIconsPlugin: ({ picker: menu, icons }?: CalloutIconsOptions) => Plugin;

createCodePlugin

Code blocks, in the languages options lists (code.language): the header names the block’s language and picks another; each line is highlighted with its block’s language, its grammar loaded the first time a line of it renders.

declare const createCodePlugin: (options?: CodePluginOptions) => Plugin;

createColumnsPlugin

Notion’s columns (docs/columns-plan.md): a columns layout shows its columns side by side, each holding any blocks; a column grows by its weight (data.width). The roles are the document’s (layoutKinds, layout.* in the delete contract): a layout showing one column shows as its blocks, an empty column does not show. columns.css lays them out and stacks them below a 480px wide layout.

declare const createColumnsPlugin: (options?: ColumnsPluginOptions) => Plugin;

createCommentsClient

The default CommentsClient: the requests routeDocumentComments answers (GET <url> lists, POST <url> sends a request as JSON), and the room’s changes heard on the socket of the document’s websocket sync (subscribe: while a listener is subscribed, that socket asks the room for them). Throws a TypeError at once for a room id no request can carry.

declare const createCommentsClient: (options: CommentsClientOptions) => CommentsClient;

createCommentsPlugin

Comments (Notion’s): select text and press Comment in the toolbar (or Mod+Shift+M) to start a thread on it. The thread’s text carries its anchor, a comment:<id> mark the document keeps through splits and merges and that copy and cut leave behind; its comments live in the client’s store (the room’s threads and comments tables). Open threads are highlighted, and a sidebar beside the text (under it, on a narrow screen) places a card for each one.

declare const createCommentsPlugin: (options: CommentsPluginOptions) => Plugin;

createDocument

See DocumentBinding.createDocument.

declare const createDocument: (options?: CreateDocumentOptions) => EdytorDocument;

CreateDocumentOptions

export type CreateDocumentOptions = DocumentOptions & {
    value?: JSONDoc;
};

createEmbedPlugin

Notion’s embed block: an “Embed a link” panel until it has a link, then the provider’s player in a sandboxed frame, with an editable caption. Only an allowlisted provider (providers) plays: the frame’s src is the player URL the provider derives from the stored link, never the stored value, and it has a sandbox and no srcdoc. Void: its only text is the caption. Pasting a link a provider plays on an empty line offers “Embed”.

declare const createEmbedPlugin: (options?: EmbedPluginOptions) => Plugin;

createEquationPlugin

Equations (Notion’s): a block equation (equation, void, its TeX in data.expression) and an inline equation atom (inlineEquation), both drawn by KaTeX, loaded the first time an equation shows in a browser: from jsDelivr by default, or as katex says (a URL, your loader). A click on one, or Enter on a selected one, opens its TeX source in an editor under it; the equation is the live preview. “Block equation” and “Inline equation” are slash commands, $$…$$ typed in text is an inline equation, and Mod+Shift+E turns the selected text into one. Copied, an equation is MathML carrying its TeX; pasted HTML with KaTeX or MathML math becomes equations again.

declare const createEquationPlugin: (options?: EquationPluginOptions) => Plugin;

createFilePlugin

Notion’s file block: an attachment, uploaded through upload (or linked), shown as its name and size, linking to the file, with an editable caption. Void: its only text is the caption.

declare const createFilePlugin: (options?: FilePluginOptions) => Plugin;

createFindPlugin

Find and replace (Notion’s find in page), opt-in: Mod+F opens a bar over the editor’s top right. It searches the document’s text in reading order, a closed toggle’s body included (the toggle opens when a match there becomes the current one), highlights the matches in the overlay, and replaces one or all as one command (replaceMatches) and one undo step.

declare const createFindPlugin: (options?: FindPluginOptions) => Plugin;

createHistoryClient

The default HistoryClient: the requests routeDocumentHistory answers. GET <url> lists, GET <url>?key= reads (404: null), POST <url>?restore= restores (404: refused), POST <url>?undo undoes; any other refusal throws a HistoryRequestError. Throws a TypeError at once for a room id no request can carry.

declare const createHistoryClient: (options: HistoryClientOptions) => HistoryClient;

createImagePlugin

Notion’s image block: an “Add an image” panel until it has a source (a pasted link, or an upload when upload is given), then the image with an editable caption, its alt text, width and alignment set from the chrome the plugin shows over it. Void: its only text is the caption.

declare const createImagePlugin: () => Plugin;

createImageToolbarPlugin

The image toolbar: your toolbar over the image the chrome is on. The first listed claims the view.

declare const createImageToolbarPlugin: ({ toolbar }: ImageToolbarOptions) => Plugin;

createIndexeddbSync

declare const createIndexeddbSync: (name: string) => EdytorSync;

createMarkdownShortcutsPlugin

Markdown prefixes come from the kind catalogue: a row whose shortcut the typed character completes.

declare const createMarkdownShortcutsPlugin: () => Plugin;

createMarqueePlugin

Block selection with a rectangle (Notion’s rubber band), opt-in: a press in the editor’s empty area — the margins beside the blocks (the handle gutter, not a handle), the space below the last block, an optional container around the editor — then a drag draws a rectangle and selects, live, the blocks it meets. Shift or Mod adds to the selection there was; Escape gives it back. On release the block selection stays and the editor has the keys. A click without a drag keeps what a press there did (below the last block, the trailing paragraph).

declare const createMarqueePlugin: (options?: MarqueePluginOptions) => Plugin;

createMediaEmptyPlugin

The empty image and media blocks’ chrome: your empty snippet for each of them (without the plugin, an empty block shows nothing). The first listed claims the view.

declare const createMediaEmptyPlugin: ({ empty }: MediaEmptyOptions) => Plugin;

createMemoryCommentsClient

Comment threads kept in memory, under the rules the room applies (decideComment): for tests, demos and a document without a room. Its siblings (as(user)) share the threads; each change reaches every subscriber, asynchronously as over a network. A removed thread’s anchor marks leave the last document a plugin attached.

declare const createMemoryCommentsClient: (options: MemoryCommentsClientOptions) => MemoryCommentsClient;

createMentionPlugin

People mentions, as in Notion: @ opens a menu of the people your app’s items(query) answers; picking one replaces @query with a mention atom ({ id, label }) and puts the caret after it, in one undo step.

declare const createMentionPlugin: (options: MentionPluginOptions) => Plugin;

createPageLinkPlugin

Links to your app’s pages, as Notion’s [[: it opens a menu of the pages your app’s search(query) answers; picking one replaces [[query with a pageLink atom ({ id, title, href, icon }), an <a> to the page, and puts the caret after it, in one undo step.

declare const createPageLinkPlugin: (options: PageLinkPluginOptions) => Plugin;

createPagePlugin

Notion’s subpage block: a page block links to another document by id (data.pageId), and shows its title (data.title, the cache your title lookup refreshes). Each page is a document of its own (a room per page): moving a subpage is moving this block, and the page itself, its content and history, never moves. A click opens it (open), and so does Enter over it selected alone; a modified or middle click opens it in a new tab ({ newTab: true }, the browser’s own on an href). With create, the “Page” command (slash menu, +) creates a page, inserts a block linking to it where the caret is (an empty line becomes it) and opens it.

createPagePlugin({
  open: (pageId) => goto(`/p/$\{pageId\}`),
  href: (pageId) => `/p/$\{pageId\}`,
  title: (pageId) => pages.get(pageId)?.title,
  create: () => crypto.randomUUID()
});

declare const createPagePlugin: (options?: PagePluginOptions) => Plugin;

createRichTextPlugin

The rich text kinds and marks, their words and slash keywords the view’s (labels, English by default).

declare const createRichTextPlugin: (options?: RichTextPluginOptions) => Plugin;

createSlashMenuPlugin

The slash menu, drawn by your menu snippet.

declare const createSlashMenuPlugin: (options?: SlashMenuOptions) => Plugin;

createSuggestionBarPlugin

The suggestion bar (Notion AI’s): your bar under each block suggestion (Accept, Discard, and Try again when the app passed onRetry); its keys are the suggestions plugin’s.

declare const createSuggestionBarPlugin: ({ bar }: SuggestionBarOptions) => Plugin;

createSuggestionsPlugin

The keys of edytor.suggestions (Notion AI’s), a default plugin: for the latest one, Mod+Enter accepts and Escape discards; Tab accepts an end suggestion at the caret. Its bar is createSuggestionBarPlugin’s.

declare const createSuggestionsPlugin: () => Plugin;

createTablePlugin

Notion’s simple table (table.* in the delete contract): a table of tableRows of tableCells, each cell a text island whose lines are line breaks (Enter is a line break in a cell). The columns are the table’s data.columns (ids and widths), each cell names its column, and the header flags are data.headerRow and data.headerColumn. The table is a CSS grid (table.css): a row shows its cells in its table’s column order, a padded cell (a peer’s row inserted while a column was) as an empty placeholder whose first press creates it. Tab and Shift+Tab walk the cells (Tab in the last one adds a row), ArrowUp and ArrowDown go to the cell above and below. On hover, a + under and beside the table adds a row or a column, the grips of a row and a column open their menus (insert, move, delete), and a band on each column’s edge resizes it. The block menu of a table has its Header row and Header column switches. Not a default plugin; its roles are in defaultSemantics.

declare const createTablePlugin: (options?: TablePluginOptions) => Plugin;

createTocPlugin

Notion’s table of contents: a toc block lists the document’s headings, live, indented by level; a click scrolls to one (opening the closed toggles it sits in). Void: it holds no text, and its list is never stored, only drawn. Its preset in the slash menu turns an empty line into one, or inserts it after the line; its words are the view’s toc labels (English by default).

declare const createTocPlugin: (options?: TocPluginOptions) => Plugin;

createToolbarPlugin

The selection toolbar, drawn by your toolbar snippet, and the link card by your card.

declare const createToolbarPlugin: (options?: ToolbarOptions) => Plugin;

createUploadsPlugin

File uploads (Notion’s): the view’s one uploader, for every kind whose record takes files (upload: the image, file, video and audio kinds). Without it, only links are embedded. The first listed claims the view.

declare const createUploadsPlugin: ({ upload }: UploadsOptions) => Plugin;

createVideoPlugin

Notion’s video block: a video file (an http(s) link, or an upload through upload) in the browser’s player, with an editable caption. A YouTube or Vimeo link is an embed (createEmbedPlugin()). Void: its only text is the caption.

declare const createVideoPlugin: () => Plugin;

createWebsocketSync

declare const createWebsocketSync: (options: WebsocketSyncOptions) => WebsocketSync;

DataPatch

One data edit at path (object keys and array indexes from the data’s root): splice takes Array.prototype.splice’s arguments and order the array’s current indexes in their new order; else it sets value, or deletes the key or removes the item when there is none.

export type DataPatch = {
    readonly path: readonly string[];
    readonly value?: unknown;
    readonly splice?: readonly [
        start: number,
        deleteCount?: number,
        ...items: unknown[]
    ];
    readonly order?: readonly number[];
};

DataTarget

What a data patch edits: a block, one of its inline atoms, or the document (null).

export type DataTarget = BlockId | null | {
    block: BlockId;
    atom: string;
};

DEFAULT_PRESENCE_THROTTLE

The least ms between two presence writes of a view by default: a caret held down or a drag publishes about 20 writes a second instead of one per selection change, which every peer and the room relay.

declare const DEFAULT_PRESENCE_THROTTLE = 50;

defaultSemantics

The rich-text, code, image, media, columns, page, table of contents, table and equation plugins’ block roles together (and the rich-text and comment mark edges) — what the room and a headless createDocument/loadDocument adopt by default (semantics: {} checks none). The media, columns, page, table of contents, table and equation plugins are not default plugins of <Edytor>, but their roles are here so their blocks read the same on every replica.

declare const defaultSemantics: {
    roles: Record<string, BlockRole>;
    rendersContent: Record<string, boolean>;
    defaultChild: Record<string, string>;
} & {
    marks: Record<string, {
        edge: MarkEdge;
    }>;
};

deleteTableColumn

Delete a column (table.delete-column, by id or position among the grid’s): it leaves data.columns (every entry naming it) and every shown cell of it is deleted, in one plan; a table left with no column goes with it. A column the table shows but no longer lists (table.cell) loses its cells. ids: the table.

declare const deleteTableColumn: (doc: Omit<DocumentOperations, "transact">, table: BlockId, column: string | number) => Prepared;

deleteTableRows

Delete rows with their cells (table.delete-row): one plan; a table left with no row goes with them. ids: the rows.

declare const deleteTableRows: (doc: Omit<DocumentOperations, "transact">, rows: readonly BlockId[]) => Prepared;

Destination

Where a block goes: parent = logical block id or null for root.

export type Destination = {
    parent: BlockId | null;
    index: number;
};

Dispatcher

export declare class Dispatcher {
    #private;
    private edytor;
    get last(): CommandResult | null;
    private active;
    private running;
    private kind;
    private applied;
    private depth;
    private replacing;
    private queue;
    private current;
    private leading;
    private patched;
    private untracked;
    outside: <T>(body: () => T) => T;
    permits: () => boolean;
    run: <T>(kind: string, body: () => T) => T | undefined;
    each: <T, R>(kind: string, parts: readonly T[], part: (item: T) => R) => (R | undefined)[];
    dispatch: <P, R>(operation: string, payload: P, context: {
        block: unknown;
        text?: Text;
    }, body: (payload: P, plan?: Prepared) => R, prepare?: (payload: P) => Prepared) => R | undefined;
    plan: <P>(operation: string, payload: P, prepare: (payload: P) => Prepared, block?: Block, text?: Text) => OpResult;
    lead: <T>(lead: Prepared, body: () => T) => {
        out: T | undefined;
        taken: boolean;
    };
    caret: {
        (text: Text | null | undefined, offset: number, ops?: () => OpResult): OpResult | undefined;
        (caret: Caret | DocPosition | null | undefined, ops?: () => OpResult): OpResult | undefined;
    };
    private policy;
    private decide;
    private settle;
    private replace;
    private steps;
}