@blankdotpage/cake 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# 🍰 Cake
+
+Cake is a small, extension-first, markdown-based editor toolkit. It’s designed
+to give you a reliable plain-text source of truth while still supporting rich
+behaviors (bold, links, lists, images, overlays) through extensions. The project
+includes a core runtime, a DOM/engine layer, and a thin React wrapper.
+
+## What it does
+
+- **Edits plain text with markdown semantics**: the underlying value is always
+  a markdown string, not a proprietary document model.
+- **Runs on a runtime+engine split**: the runtime parses/serializes and applies
+  edit commands; the engine handles DOM rendering, selection, and events.
+- **Extensible by design**: features are extensions (inline, block, overlay)
+  that can add syntax, behavior, and UI without changing the core.
+
+## How it’s different from other editors
+
+- **No hidden document model**: Cake never stores a separate rich‑text AST.
+  The markdown string is the source of truth.
+- **Extension-first architecture**: rich features are optional and removable,
+  rather than baked into a monolith.
+- **Tested at the behavior level**: includes Vitest unit + browser tests to
+  validate parsing, selection, and DOM behavior.
+
+## When to use it
+
+- You want **markdown as the canonical format**.
+- You need **custom editing features** without forking a large editor.
+- You prefer a **small surface area** and predictable behavior.
+
+If you need a full WYSIWYG document editor with complex layout, tables, or
+collaborative editing out of the box, Cake likely isn’t the right fit.
+
+## Development
+
+```bash
+npm install
+npm run test
+npm run build
+```
+
+## Demo
+
+```bash
+npm --workspace demo install
+npm run demo
+```
+
+## Library usage
+
+```tsx
+import { CakeEditor, defaultEditorSettings } from "@blankdotpage/cake";
+```

package/dist/cake/clipboard.d.ts

@@ -0,0 +1 @@
+export declare function htmlToMarkdownForPaste(html: string): string;

package/dist/cake/core/mapping/cursor-source-map.d.ts

@@ -0,0 +1,32 @@
+import type { Affinity } from "../types";
+export type CursorBoundary = {
+    sourceBackward: number;
+    sourceForward: number;
+};
+export type CursorSourceMap = {
+    cursorLength: number;
+    boundaries: CursorBoundary[];
+    cursorToSource(cursorOffset: number, affinity: Affinity): number;
+    sourceToCursor(sourceOffset: number, bias: Affinity): {
+        cursorOffset: number;
+        affinity: Affinity;
+    };
+};
+export declare function createCursorSourceMap(boundaries: CursorBoundary[], cursorLength: number): CursorSourceMap;
+export declare class CursorSourceBuilder {
+    private sourceParts;
+    private boundaries;
+    private cursorLength;
+    private sourceLengthValue;
+    appendSourceOnly(text: string): void;
+    appendText(text: string): void;
+    appendCursorAtom(sourceText: string, cursorUnits?: number): void;
+    appendSerialized(serialized: {
+        source: string;
+        map: CursorSourceMap;
+    }): void;
+    build(): {
+        source: string;
+        map: CursorSourceMap;
+    };
+}

package/dist/cake/core/runtime.d.ts

@@ -0,0 +1,121 @@
+import type { Block, Doc, Inline, Selection } from "./types";
+import type { ReactElement } from "react";
+import { type CursorSourceMap } from "./mapping/cursor-source-map";
+import type { DomRenderContext } from "../dom/types";
+import type { OverlayExtensionContext } from "../extensions/overlay-types";
+type BlockParseResult = {
+    block: Block;
+    nextPos: number;
+};
+type InlineParseResult = {
+    inline: Inline;
+    nextPos: number;
+};
+export type ParseBlockResult = BlockParseResult | null;
+export type ParseInlineResult = InlineParseResult | null;
+export type SerializeBlockResult = {
+    source: string;
+    map: CursorSourceMap;
+};
+export type SerializeInlineResult = {
+    source: string;
+    map: CursorSourceMap;
+};
+export type EditCommand = {
+    type: "insert";
+    text: string;
+} | {
+    type: "insert-line-break";
+} | {
+    type: "delete-backward";
+} | {
+    type: "delete-forward";
+} | {
+    type: "indent";
+} | {
+    type: "outdent";
+} | {
+    type: "toggle-bullet-list";
+} | {
+    type: "toggle-numbered-list";
+} | {
+    type: "toggle-inline";
+    marker: string;
+} | {
+    type: "wrap-link";
+    url?: string;
+    openPopover?: boolean;
+};
+export type EditResult = {
+    source: string;
+    selection: Selection;
+};
+export type KeyBinding = {
+    key: string;
+    meta?: boolean;
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    command: EditCommand | ((state: RuntimeState) => EditCommand | null);
+};
+export type InlineWrapperAffinity = {
+    kind: string;
+    /**
+     * Whether the wrapper should be considered "active" when the caret is at its
+     * end boundary. For v1 parity, links are non-inclusive; emphasis is inclusive.
+     */
+    inclusive: boolean;
+};
+export type ExtensionContext = {
+    parseInline: (source: string, start: number, end: number) => Inline[];
+    serializeInline: (inline: Inline) => SerializeInlineResult;
+    serializeBlock: (block: Block) => SerializeBlockResult;
+};
+export type CakeExtension = {
+    name: string;
+    inlineWrapperAffinity?: InlineWrapperAffinity[];
+    /**
+     * Declares which inline wrapper kind a `toggle-inline` marker corresponds to.
+     * This keeps the core runtime syntax-agnostic while still allowing extension-
+     * specific toggle behavior at wrapper boundaries.
+     */
+    toggleInline?: {
+        kind: string;
+        markers: string[];
+    };
+    parseBlock?: (source: string, start: number, context: ExtensionContext) => ParseBlockResult;
+    parseInline?: (source: string, start: number, end: number, context: ExtensionContext) => ParseInlineResult;
+    serializeBlock?: (block: Block, context: ExtensionContext) => SerializeBlockResult | null;
+    serializeInline?: (inline: Inline, context: ExtensionContext) => SerializeInlineResult | null;
+    normalizeBlock?: (block: Block) => Block | null;
+    normalizeInline?: (inline: Inline) => Inline | null;
+    onEdit?: (command: EditCommand, state: RuntimeState) => EditResult | null;
+    onPasteText?: (text: string, state: RuntimeState) => EditCommand | null;
+    keybindings?: KeyBinding[];
+    renderInline?: (inline: Inline, context: DomRenderContext) => Node | Node[] | null;
+    renderBlock?: (block: Block, context: DomRenderContext) => Node | Node[] | null;
+    renderOverlay?: (context: OverlayExtensionContext) => ReactElement | null;
+};
+export type RuntimeState = {
+    source: string;
+    selection: Selection;
+    map: CursorSourceMap;
+    doc: Doc;
+    runtime: Runtime;
+};
+export type Runtime = {
+    extensions: CakeExtension[];
+    parse(source: string): Doc;
+    serialize(doc: Doc): {
+        source: string;
+        map: CursorSourceMap;
+    };
+    createState(source: string, selection?: Selection): RuntimeState;
+    updateSelection(state: RuntimeState, selection: Selection, options?: {
+        kind?: "dom" | "keyboard" | "programmatic";
+    }): RuntimeState;
+    serializeSelection(state: RuntimeState, selection: Selection): string;
+    applyEdit(command: EditCommand, state: RuntimeState): RuntimeState;
+};
+export declare function createRuntime(extensions: CakeExtension[]): Runtime;
+export {};

package/dist/cake/core/types.d.ts

@@ -0,0 +1,42 @@
+export type Affinity = "backward" | "forward";
+export type Selection = {
+    start: number;
+    end: number;
+    affinity?: Affinity;
+};
+export type Doc = {
+    type: "doc";
+    blocks: Block[];
+};
+export type Block = ParagraphBlock | BlockWrapperBlock | AtomBlock;
+export type ParagraphBlock = {
+    type: "paragraph";
+    content: Inline[];
+};
+export type BlockWrapperBlock = {
+    type: "block-wrapper";
+    kind: string;
+    blocks: Block[];
+    data?: Record<string, unknown>;
+};
+export type AtomBlock = {
+    type: "block-atom";
+    kind: string;
+    data?: Record<string, unknown>;
+};
+export type Inline = TextInline | InlineWrapper | InlineAtom;
+export type TextInline = {
+    type: "text";
+    text: string;
+};
+export type InlineWrapper = {
+    type: "inline-wrapper";
+    kind: string;
+    children: Inline[];
+    data?: Record<string, unknown>;
+};
+export type InlineAtom = {
+    type: "inline-atom";
+    kind: string;
+    data?: Record<string, unknown>;
+};

package/dist/cake/dom/dom-map.d.ts

@@ -0,0 +1,21 @@
+import type { Affinity } from "../core/types";
+export type TextRun = {
+    node: Text;
+    cursorStart: number;
+    cursorEnd: number;
+    boundaryOffsets: number[];
+};
+export type DomPoint = {
+    node: Text;
+    offset: number;
+};
+export type DomMap = {
+    runs: TextRun[];
+    domAtCursor(cursorOffset: number, affinity: Affinity): DomPoint | null;
+    cursorAtDom(node: Text, offset: number): {
+        cursorOffset: number;
+        affinity: Affinity;
+    } | null;
+};
+export declare function createTextRun(node: Text, cursorStart: number): TextRun;
+export declare function createDomMap(runs: TextRun[]): DomMap;

package/dist/cake/dom/dom-selection.d.ts

@@ -0,0 +1,4 @@
+import type { Selection } from "../core/types";
+import type { DomMap } from "./dom-map";
+export declare function applyDomSelection(selection: Selection, map: DomMap): void;
+export declare function readDomSelection(map: DomMap): Selection | null;

package/dist/cake/dom/render.d.ts

@@ -0,0 +1,14 @@
+import type { Doc, Inline } from "../core/types";
+import type { CakeExtension } from "../core/runtime";
+import { createDomMap } from "./dom-map";
+export type RenderResult = {
+    root: HTMLElement;
+    map: ReturnType<typeof createDomMap>;
+};
+export type RenderContentResult = {
+    content: Node[];
+    map: ReturnType<typeof createDomMap>;
+};
+export declare function renderDocContent(doc: Doc, extensions: CakeExtension[], _root?: HTMLElement): RenderContentResult;
+export declare function renderDoc(doc: Doc, extensions: CakeExtension[]): RenderResult;
+export declare function mergeInlineForRender(inlines: Inline[]): Inline[];

package/dist/cake/dom/types.d.ts

@@ -0,0 +1,10 @@
+import type { Block, Inline } from "../core/types";
+import type { TextRun } from "./dom-map";
+export type DomRenderContext = {
+    renderInline: (inline: Inline) => Node[];
+    renderBlock: (block: Block) => Node[];
+    renderBlocks: (blocks: Block[]) => Node[];
+    createTextRun: (node: Text) => TextRun;
+    getLineIndex: () => number;
+    incrementLineIndex: () => void;
+};

package/dist/cake/engine/cake-engine.d.ts

@@ -0,0 +1,208 @@
+import type { Selection } from "../core/types";
+import { type CakeExtension, type EditCommand } from "../core/runtime";
+import type { SelectionRect } from "./selection/selection-geometry";
+type EngineOptions = {
+    container: HTMLElement;
+    value: string;
+    selection?: Selection;
+    extensions?: CakeExtension[];
+    onChange?: (value: string, selection: Selection) => void;
+    onSelectionChange?: (selection: Selection) => void;
+    readOnly?: boolean;
+    spellCheckEnabled?: boolean;
+};
+export declare class CakeEngine {
+    private container;
+    private runtime;
+    private extensions;
+    private _state;
+    private originalCaretRangeFromPoint;
+    private patchedCaretRangeFromPoint;
+    private get state();
+    private set state(value);
+    private contentRoot;
+    private domMap;
+    private isApplyingSelection;
+    private isComposing;
+    private beforeInputHandled;
+    private beforeInputResetId;
+    private keydownHandledBeforeInput;
+    private suppressSelectionChange;
+    private suppressSelectionChangeResetId;
+    private ignoreTouchNativeSelectionUntil;
+    private blockTrustedTextDrag;
+    private selectedAtomicLineIndex;
+    private lastAppliedSelection;
+    private compositionCommit;
+    private compositionCommitTimeoutId;
+    private overlayRoot;
+    private caretElement;
+    private caretBlinkTimeoutId;
+    private overlayUpdateId;
+    private scrollCaretIntoViewId;
+    private onChange?;
+    private onSelectionChange?;
+    private readOnly;
+    private spellCheckEnabled;
+    private extensionsRoot;
+    private placeholderRoot;
+    private lastFocusRect;
+    private verticalNavGoalX;
+    private history;
+    private pendingClickHit;
+    private isEventTargetInContentRoot;
+    private handleBeforeInputBound;
+    private handleInputBound;
+    private handleCompositionStartBound;
+    private handleCompositionEndBound;
+    private handleSelectionChangeBound;
+    private handleScrollBound;
+    private handleResizeBound;
+    private handleClickBound;
+    private handleKeyDownBound;
+    private handlePasteBound;
+    private handleCopyBound;
+    private handleCutBound;
+    private handlePointerDownBound;
+    private handlePointerMoveBound;
+    private handlePointerUpBound;
+    private handleDragStartBound;
+    private handleDragOverBound;
+    private handleDropBound;
+    private handleDragEndBound;
+    private dragState;
+    private dropIndicator;
+    private textDragState;
+    private selectionDragState;
+    private pointerDownPosition;
+    private hasMovedSincePointerDown;
+    constructor(options: EngineOptions);
+    destroy(): void;
+    setReadOnly(readOnly: boolean): void;
+    setSpellCheckEnabled(enabled: boolean): void;
+    getValue(): string;
+    getSelection(): Selection;
+    getFocusRect(): SelectionRect | null;
+    getContainer(): HTMLElement;
+    getContentRoot(): HTMLElement | null;
+    getOverlayRoot(): HTMLDivElement | null;
+    syncPlaceholder(): void;
+    insertText(text: string): void;
+    replaceText(oldText: string, newText: string): void;
+    setSelection(selection: Selection): void;
+    setValue({ value, selection }: {
+        value: string;
+        selection?: Selection;
+    }): void;
+    focus(selection?: Selection): void;
+    blur(): void;
+    hasFocus(): boolean;
+    selectAll(): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    executeCommand(command: EditCommand): boolean;
+    private attachListeners;
+    private attachDragListeners;
+    private detachDragListeners;
+    private detachListeners;
+    private installCaretRangeFromPointShim;
+    private uninstallCaretRangeFromPointShim;
+    private render;
+    private isEmptyParagraphDoc;
+    private updatePlaceholder;
+    private syncPlaceholderPadding;
+    private updateContentRootAttributes;
+    private applySelection;
+    private handleSelectionChange;
+    private syncSelectionFromDom;
+    private adjustSelectionForAtomicBlocks;
+    private getAtomicBlockSelectionFromClick;
+    private handleClick;
+    private handleKeyDown;
+    private resolveExtensionKeybinding;
+    private handleCopy;
+    private handleCut;
+    private handlePaste;
+    private handleBeforeInput;
+    private applyInputIntent;
+    private handleInput;
+    private handleCompositionStart;
+    private handleCompositionEnd;
+    private resolveBeforeInputIntent;
+    private selectionFromTargetRangesWithStatus;
+    private cursorFromDom;
+    private applyEdit;
+    private handleDeleteAtomicBlockSelection;
+    private handleBackspaceAfterAtomicBlock;
+    private recordHistory;
+    private applySelectionUpdate;
+    private getLayoutForNavigation;
+    private moveSelectionByChar;
+    private moveOffsetByChar;
+    private moveSelectionVertically;
+    private moveSelectionToVisualRowStart;
+    private moveSelectionToVisualRowEnd;
+    private extendSelectionToVisualRowStart;
+    private extendSelectionToVisualRowEnd;
+    private extendSelectionToDocumentStart;
+    private extendSelectionToDocumentEnd;
+    private extendFullLineSelectionByLine;
+    private moveSelectionByWord;
+    private extendSelectionByWord;
+    private moveOffsetByWord;
+    private deleteToVisualRowStart;
+    private handleIndent;
+    private handleOutdent;
+    private readDomText;
+    /**
+     * Reconcile DOM text changes with the model while preserving formatting markers.
+     * Used when external agents (IME, Grammarly) modify the DOM directly.
+     *
+     * Strategy:
+     * 1. Get visible text from DOM (what was modified)
+     * 2. Get visible text from model (what we had)
+     * 3. Find the minimal diff (common prefix/suffix)
+     * 4. Map the changed region from cursor space to source space
+     * 5. Replace the corresponding source region, preserving markers
+     */
+    private reconcileDomChanges;
+    private resolveCollapsedReconcileAffinity;
+    private markBeforeInputHandled;
+    private suppressSelectionChangeForTick;
+    private markCompositionCommit;
+    private clearCompositionCommit;
+    private handleScroll;
+    private handleResize;
+    private openLinkPopoverForSelection;
+    private scheduleOverlayUpdate;
+    private flushOverlayUpdate;
+    private ensureOverlayRoot;
+    private ensureExtensionsRoot;
+    private updateExtensionsOverlayPosition;
+    private updateSelectionOverlay;
+    private syncSelectionRects;
+    private updateCaret;
+    private markCaretActive;
+    private stopCaretBlink;
+    private clearCaretBlinkTimer;
+    private scheduleScrollCaretIntoView;
+    private scrollCaretIntoView;
+    private hitTestFromClientPoint;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private showDropIndicator;
+    private hideDropIndicator;
+    private findClosestLineByY;
+    private calculateDropLineIndex;
+    private detectFullLineSelection;
+    private moveLines;
+    private handleDragStart;
+    private handleDragOver;
+    private handleDrop;
+    private handleDragEnd;
+    private dataTransferHasImageFile;
+}
+export {};

package/dist/cake/engine/selection/selection-geometry-dom.d.ts

@@ -0,0 +1,23 @@
+import type { Selection } from "../../core/types";
+import { type LineInfo } from "./selection-layout";
+import { type SelectionRect } from "./selection-geometry";
+export type SelectionGeometry = {
+    selectionRects: SelectionRect[];
+    caretRect: SelectionRect | null;
+    focusRect: SelectionRect | null;
+};
+export declare function getSelectionGeometry(params: {
+    root: HTMLElement;
+    container: HTMLElement;
+    docLines: LineInfo[];
+    selection: Selection;
+}): SelectionGeometry;
+export declare function getCaretRect(params: {
+    lineElement: HTMLElement;
+    lineInfo: LineInfo;
+    offsetInLine: number;
+    affinity?: "forward" | "backward";
+}): {
+    rect: DOMRect;
+    lineRect: DOMRect;
+} | null;

package/dist/cake/engine/selection/selection-geometry.d.ts

@@ -0,0 +1,23 @@
+import type { Selection } from "../../core/types";
+import type { LayoutModel, LayoutRect } from "./selection-layout";
+export type SelectionRect = {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};
+export type SelectionCaretMeasurement = {
+    lineRect: LayoutRect;
+    caretRect: LayoutRect;
+    lineLength: number;
+    lineHeight: number | null;
+    fontSize: number | null;
+    padding: {
+        top: number;
+        bottom: number;
+    };
+    nearestTextCaretHeight: number | null;
+};
+export type OffsetToXMeasurer = (lineIndex: number, offsetInLine: number) => number | null;
+export declare function computeSelectionRects(layout: LayoutModel, selection: Selection, measurer?: OffsetToXMeasurer): SelectionRect[];
+export declare function computeCaretRect(caret: SelectionCaretMeasurement): SelectionRect | null;

package/dist/cake/engine/selection/selection-layout-dom.d.ts

@@ -0,0 +1,30 @@
+import type { LayoutMeasurer, LayoutModel, LayoutRect, LineInfo } from "./selection-layout";
+export declare function toLayoutRect(params: {
+    rect: DOMRect;
+    containerRect: DOMRect;
+    scroll: {
+        top: number;
+        left: number;
+    };
+}): LayoutRect;
+export declare function createDomLayoutMeasurer(params: {
+    root: HTMLElement;
+    container: HTMLElement;
+    lines: LineInfo[];
+}): LayoutMeasurer | null;
+export declare function measureLayoutModelFromDom(params: {
+    lines: LineInfo[];
+    root: HTMLElement;
+    container: HTMLElement;
+}): LayoutModel | null;
+export declare function getLineElement(root: HTMLElement, lineIndex: number): HTMLElement | null;
+export declare function resolveDomPosition(lineElement: HTMLElement, offsetInLine: number): {
+    node: Node;
+    offset: number;
+};
+export declare function createOffsetToXMeasurer(params: {
+    root: HTMLElement;
+    container: HTMLElement;
+    lines: LineInfo[];
+}): (lineIndex: number, offsetInLine: number) => number | null;
+export declare function cursorOffsetToDomOffset(cursorToCodeUnit: number[], offset: number): number;

package/dist/cake/engine/selection/selection-layout.d.ts

@@ -0,0 +1,54 @@
+import type { Doc } from "../../core/types";
+export type LayoutRect = {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+};
+export type LayoutRow = {
+    startOffset: number;
+    endOffset: number;
+    rect: LayoutRect;
+};
+export type LineLayout = {
+    lineIndex: number;
+    lineStartOffset: number;
+    lineLength: number;
+    lineHasNewline: boolean;
+    lineBox: LayoutRect;
+    rows: LayoutRow[];
+};
+export type LayoutModel = {
+    container: LayoutRect;
+    lines: LineLayout[];
+};
+export type LineMeasurementInput = {
+    lineIndex: number;
+    lineText: string;
+    lineLength: number;
+    lineHasNewline: boolean;
+    top: number;
+};
+export type LineMeasurement = {
+    lineBox: LayoutRect;
+    rows: LayoutRow[];
+};
+export type LayoutMeasurer = {
+    container: LayoutRect;
+    measureLine: (input: LineMeasurementInput) => LineMeasurement;
+};
+export type LineInfo = {
+    lineIndex: number;
+    text: string;
+    cursorLength: number;
+    hasNewline: boolean;
+    cursorToCodeUnit: number[];
+    isAtomic: boolean;
+};
+export declare function buildLayoutModel(lines: LineInfo[], measurer: LayoutMeasurer): LayoutModel;
+export declare function getDocLines(doc: Doc): LineInfo[];
+export declare function getLineOffsets(lines: LineInfo[]): number[];
+export declare function resolveOffsetToLine(lines: LineInfo[], offset: number): {
+    lineIndex: number;
+    offsetInLine: number;
+};

package/dist/cake/engine/selection/selection-navigation.d.ts

@@ -0,0 +1,21 @@
+import type { Selection } from "../../core/types";
+import type { LayoutModel, LineInfo } from "./selection-layout";
+type Affinity = "forward" | "backward";
+export type VerticalNavigationResult = {
+    selection: Selection;
+    goalX: number;
+};
+export declare function moveSelectionVertically(params: {
+    lines: LineInfo[];
+    layout: LayoutModel;
+    selection: Selection;
+    direction: "up" | "down";
+    goalX: number | null;
+    focusRowIndex?: number;
+    hitTestCursorAt?: (x: number, y: number) => {
+        cursorOffset: number;
+        affinity: Affinity;
+        caretTop?: number;
+    } | null;
+}): VerticalNavigationResult | null;
+export {};

package/dist/cake/engine/selection/visible-text.d.ts

@@ -0,0 +1,4 @@
+import { type LineInfo } from "./selection-layout";
+export declare function getVisibleText(lines: LineInfo[]): string;
+export declare function visibleOffsetToCursorOffset(lines: LineInfo[], visibleOffset: number): number | null;
+export declare function cursorOffsetToVisibleOffset(lines: LineInfo[], cursorOffset: number): number;

package/dist/cake/extensions/blockquote/blockquote.d.ts

@@ -0,0 +1,2 @@
+import type { CakeExtension } from "../../core/runtime";
+export declare const blockquoteExtension: CakeExtension;

package/dist/cake/extensions/bold/bold.d.ts

@@ -0,0 +1,2 @@
+import type { CakeExtension } from "../../core/runtime";
+export declare const boldExtension: CakeExtension;