@danxbot/ui 1.0.0

package/dist/types/lib/dnd/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The drag-and-drop contract. One session shape, produced by every input
+ * source, read by everything downstream.
+ *
+ * WHY NOT HTML5 DRAG-AND-DROP. The obvious design — and the one the danxbot
+ * dashboard's Kanban board uses today — is `draggable="true"` plus
+ * `dragstart`/`dragover`/`drop`. It cannot do three of the four things this
+ * component exists to deliver:
+ *
+ *   1. TOUCH. Mobile browsers do not fire drag events for touch input at all.
+ *      Not throttled, not partial — absent. A board built on that API is inert
+ *      on every phone, and nothing inside the API can fix it.
+ *   2. KEYBOARD. There is no keyboard path into a drag session; the events only
+ *      exist as a consequence of a pointer gesture.
+ *   3. EDGE AUTO-SCROLL. `dragover` is throttled and the browser owns the
+ *      gesture, so a scroll ramp driven from it stutters.
+ *
+ * Pointer Events give one code path for mouse, touch and pen, and leave the
+ * gesture under our control — so keyboard becomes a second SENSOR feeding the
+ * same session rather than a parallel implementation that has to be kept in
+ * agreement with the first one.
+ *
+ * The invariant that removes the entire off-by-one bug class, asserted by the
+ * geometry tests: `DropTarget.index` is the insertion index in the container's
+ * item list WITH THE DRAGGED ITEM ALREADY REMOVED. Same-container and
+ * cross-container drops are then arithmetically identical, and a consumer never
+ * has to ask "does this index account for the hole the item left behind".
+ */
+/** Client-space point. Always viewport coordinates, never page. */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A draggable item's identity. Stable across renders — never an array index. */
+export type DragId = string;
+/** A container that holds draggable items: a column, a list, a board lane. */
+export type ContainerId = string;
+/**
+ * The reorder axis of a container. `"y"` is a vertical list, `"x"` a row of
+ * columns. The axis decides which coordinate the midpoint rule reads and which
+ * arrow keys move within the container rather than between containers.
+ */
+export type DragAxis = "x" | "y";
+/**
+ * Where the dragged item lands if released now.
+ *
+ * `index` counts the container's items WITHOUT the dragged item — see the file
+ * header. `0` is before every remaining item, `length` is after all of them.
+ */
+export interface DropTarget {
+    container: ContainerId;
+    index: number;
+}
+/**
+ * Which sensor started the session. Downstream behaviour genuinely differs:
+ * the floating clone follows a pointer but snaps to the target in keyboard
+ * mode, and announcements are only worth emitting for a session a screen-reader
+ * user could be driving.
+ */
+export type DragMode = "pointer" | "keyboard";
+/**
+ * `pending` is a pointer that is down on a handle but has not yet passed its
+ * activation constraint. It exists so a tap stays a tap and a swipe stays a
+ * scroll — the single most common way a drag list becomes unusable on a phone
+ * is starting the drag on `pointerdown`.
+ */
+export type DragPhase = "idle" | "pending" | "dragging";
+export interface DragState {
+    phase: DragPhase;
+    /** The item being carried. Non-null in `pending` and `dragging`. */
+    id: DragId | null;
+    /** Where it came from, captured at pickup so cancel can restore it. */
+    from: DropTarget | null;
+    /** Where it would land now. Never null while `dragging`. */
+    over: DropTarget | null;
+    mode: DragMode | null;
+    /** Live pointer position. Null in keyboard mode — there is no pointer. */
+    point: Point | null;
+    /**
+     * The cursor's offset inside the item at pickup, so the floating clone tracks
+     * the exact point that was grabbed rather than snapping a corner to the
+     * cursor. Null in keyboard mode.
+     */
+    grab: Point | null;
+}
+/** A registered draggable item. Registration is what makes it measurable. */
+export interface ItemRegistration {
+    id: DragId;
+    container: ContainerId;
+    /** Position within its container, as the consumer's data currently orders it. */
+    index: number;
+    element: HTMLElement;
+}
+export interface ContainerRegistration {
+    id: ContainerId;
+    element: HTMLElement;
+    axis: DragAxis;
+}
+/** One item's measured box, taken at snapshot time. */
+export interface ItemRect {
+    id: DragId;
+    container: ContainerId;
+    index: number;
+    rect: DOMRect;
+}
+export interface ContainerRect {
+    id: ContainerId;
+    axis: DragAxis;
+    rect: DOMRect;
+}
+/**
+ * Every box measured once, at pickup.
+ *
+ * WHY A SNAPSHOT. `getBoundingClientRect` forces layout, and a drag reads every
+ * candidate box on every move. Measuring per `pointermove` costs a forced
+ * reflow per frame of the one gesture that must never drop a frame — and it
+ * measures boxes that are MID-ANIMATION, so the midpoint rule reads a moving
+ * target and the insertion point oscillates. The snapshot is invalidated by
+ * scroll and resize, which are the only two things that move a box the drag
+ * itself did not.
+ */
+export interface LayoutSnapshot {
+    items: ItemRect[];
+    containers: ContainerRect[];
+}
+/** Emitted once per completed drag. `from` and `to` may be equal — see `moved`. */
+export interface DragEndEvent {
+    id: DragId;
+    from: DropTarget;
+    to: DropTarget;
+    mode: DragMode;
+    /**
+     * `false` when the release lands the item exactly where it started. Consumers
+     * MUST skip their write in that case: the dashboard's implementation churned
+     * its ordering field on every no-op release, and a write that changes nothing
+     * still costs a request, a re-render and an audit-log row.
+     */
+    moved: boolean;
+}
+/** Emitted at pickup, before any movement. */
+export interface DragStartEvent {
+    id: DragId;
+    from: DropTarget;
+    mode: DragMode;
+}
+/** Emitted when a session ends without committing — Esc, or a cancelled pointer. */
+export interface DragCancelEvent {
+    id: DragId;
+    from: DropTarget;
+    mode: DragMode;
+}
+export interface DragSessionCallbacks {
+    onDragStart?: (e: DragStartEvent) => void;
+    /** Fires on every change of `over`, never on mere pointer movement. */
+    onDragOver?: (e: {
+        id: DragId;
+        from: DropTarget;
+        over: DropTarget;
+    }) => void;
+    onDragEnd?: (e: DragEndEvent) => void;
+    onDragCancel?: (e: DragCancelEvent) => void;
+}

package/dist/types/lib/dnd/use-drag.d.ts

@@ -0,0 +1,56 @@
+import { DragSession } from "./session";
+import type { PointerActivation } from "./sensors/pointer";
+import type { ContainerId, DragAxis, DragId, DragSessionCallbacks, DragState } from "./types";
+export declare const DragSessionProvider: import("react").Provider<DragSession | null>;
+export declare function useDragSession(component: string): DragSession;
+/**
+ * Create the session a `<DragDrop>` owns.
+ *
+ * Built ONCE, with its callbacks swapped on every render. Rebuilding it when a
+ * consumer's `onDragEnd` identity changes — which it does on every render
+ * unless they memoize, and they will not — would destroy the machine mid-gesture
+ * and drop the drag.
+ */
+export declare function useCreateDragSession(callbacks: DragSessionCallbacks): DragSession;
+/** Subscribe to the session. */
+export declare function useDragState(session: DragSession): DragState;
+export interface UseDraggableOptions {
+    id: DragId;
+    container: ContainerId;
+    /** Position in the consumer's data. Re-registers when it changes. */
+    index: number;
+    /**
+     * The reorder axis of this item's container. Decides which arrow pair steps
+     * within the container and which moves between containers.
+     *
+     * @default "y"
+     */
+    axis?: DragAxis;
+    disabled?: boolean;
+    activation?: PointerActivation;
+}
+export interface UseDraggableResult {
+    /** The item's own element — this is what gets measured. */
+    setItemRef: (el: HTMLElement | null) => void;
+    /**
+     * The drag handle. Pass the same element as `setItemRef` to make the whole
+     * item draggable, or a grip inside it to make only the grip draggable. They
+     * are deliberately separate: a card full of buttons must not start a drag
+     * from every one of them.
+     */
+    setHandleRef: (el: HTMLElement | null) => void;
+    isDragging: boolean;
+}
+export declare function useDraggable(session: DragSession, options: UseDraggableOptions): UseDraggableResult;
+export interface UseDropContainerOptions {
+    id: ContainerId;
+    axis?: DragAxis;
+}
+export interface UseDropContainerResult {
+    setContainerRef: (el: HTMLElement | null) => void;
+    /** True while the carried item would land in this container. */
+    isOver: boolean;
+    /** Insertion index within this container, or null when it is not the target. */
+    overIndex: number | null;
+}
+export declare function useDropContainer(session: DragSession, options: UseDropContainerOptions): UseDropContainerResult;

package/dist/types/lib/icons.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Icon registry.
+ *
+ * Icons are DATA here, not components. A `[tag, attrs]` tuple list is ~100
+ * bytes, carries no React overhead, and can be registered at runtime — which
+ * is what makes the icon set swappable rather than baked in.
+ *
+ * WHY A REGISTRY AT ALL, rather than importing icon components directly:
+ *
+ *   1. Components reference icons BY NAME (`<Icon name="check" />`), so a
+ *      consumer can re-point `check` at their own drawing and every checkbox,
+ *      menu tick and status chip in the system follows. Direct imports would
+ *      hard-wire our drawing into their app.
+ *   2. It keeps any icon library an OPTIONAL dependency. The core set below is
+ *      shipped as data with no package behind it; anything further is
+ *      registered by the consumer from whatever set they already use.
+ *   3. Names resolve at render, so an icon can be swapped per theme or per
+ *      brand without re-rendering the tree that uses it.
+ *
+ * The core set's geometry is Lucide's (ISC licensed — see src/icons/data.ts),
+ * extracted to data at build time so nothing ships at runtime.
+ */
+/** A single SVG child: an element name and its attributes. */
+export type IconNodeChild = readonly [tag: string, attrs: Record<string, string | number>];
+/** An icon's full geometry — the children of a 24x24 `<svg>`. */
+export type IconNode = readonly IconNodeChild[];
+/**
+ * Register (or replace) one icon. Replacement is deliberate and unguarded:
+ * overriding a core name with a brand's own drawing is the primary reason this
+ * registry exists, so it must not require a different call than adding one.
+ */
+export declare function registerIcon(name: string, node: IconNode): void;
+/** Register many at once — the shape a generated icon module exports. */
+export declare function registerIcons(icons: Record<string, IconNode>): void;
+/** Look up an icon, or `undefined` when the name was never registered. */
+export declare function getIcon(name: string): IconNode | undefined;
+/** Every registered name, sorted — powers icon galleries and docs pages. */
+export declare function iconNames(): string[];
+/** True when `name` resolves — for a consumer validating config-driven icons. */
+export declare function hasIcon(name: string): boolean;

package/dist/types/lib/markdown/caret-map.d.ts

@@ -0,0 +1,48 @@
+import type { Projection } from "./project";
+/** A half-open source range. */
+export interface Span {
+    start: number;
+    end: number;
+}
+export interface CaretMap {
+    source: string;
+    /** Every offset the caret may occupy, ascending and unique. */
+    stops: readonly number[];
+    /** The source range of every VISIBLE grapheme, in document order. */
+    graphemes: readonly Span[];
+    /**
+     * The stop that stands for each source offset, indexed by offset.
+     *
+     * NEEDED BECAUSE "NEAREST" IS THE WRONG QUESTION. Deleting the "d" from
+     * `**bold**` leaves the caret at offset 5, which is the same PLACE as offset
+     * 7 but two characters closer to 4 — so a nearest-by-distance snap puts the
+     * caret before the "l" instead of after the construct, and the next keystroke
+     * lands in the wrong word. An offset belongs to the coincident group it falls
+     * in, and only this table knows which that is.
+     */
+    representative: readonly number[];
+}
+/**
+ * Builds the map for a projection.
+ *
+ * Pure, and rebuilt with every projection rather than maintained across edits —
+ * the same reasoning the projection itself gives. Nothing is kept in step, so
+ * nothing can drift.
+ */
+export declare function caretMap(projection: Projection): CaretMap;
+/**
+ * The legal offset standing for `offset` — the caret's real place.
+ *
+ * Not "the closest number in `stops`": see `representative`. Out-of-range
+ * offsets clamp, because a caret that cannot be placed is worse than one placed
+ * at the edge.
+ */
+export declare function nearestStop(map: CaretMap, offset: number): number;
+/** The next legal offset in `direction`, or the same one at a document edge. */
+export declare function stepStop(map: CaretMap, offset: number, direction: 1 | -1): number;
+/** The visible grapheme immediately before `offset`, if there is one. */
+export declare function graphemeBefore(map: CaretMap, offset: number): Span | null;
+/** The visible grapheme immediately after `offset`, if there is one. */
+export declare function graphemeAfter(map: CaretMap, offset: number): Span | null;
+/** The first legal offset on the line holding `offset` — where Home goes. */
+export declare function lineStartStop(map: CaretMap, offset: number): number;

package/dist/types/lib/markdown/caret.d.ts

@@ -0,0 +1,6 @@
+export declare function stepOffset(source: string, offset: number, direction: 1 | -1): number;
+/** The source range of the line containing `offset`, terminator excluded. */
+export declare function lineAt(source: string, offset: number): {
+    start: number;
+    end: number;
+};

package/dist/types/lib/markdown/commands.d.ts

@@ -0,0 +1,170 @@
+import type { SourceSelection } from "./position";
+import type { Splice } from "./surface";
+export interface Edit {
+    splice: Splice;
+    select: SourceSelection;
+}
+/** A command returns null when it does not apply, so the key falls through. */
+export type Command = (source: string, selection: SourceSelection) => Edit | null;
+interface LineSpan {
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Toggles a symmetric inline marker around the selection.
+ *
+ * WRAPPING AND UNWRAPPING ARE THE SAME COMMAND, and which one happens is
+ * decided by looking at the source on both sides — not by asking the rendered
+ * tree whether the selection "is bold". The tree answer is ambiguous the moment
+ * a selection spans a boundary; the source answer never is.
+ */
+export declare function toggleInline(marker: string): Command;
+export declare const toggleBold: Command;
+export declare const toggleItalic: Command;
+export declare const toggleCode: Command;
+export declare const toggleStrike: Command;
+/** The heading level of a line, 0 for a paragraph. */
+export declare function headingLevel(text: string): number;
+/**
+ * Sets a line's heading level. Level 0 removes the heading.
+ *
+ * Applied to the FIRST line of the selection only. A multi-line selection means
+ * "make this a heading", and a heading is one line — turning six selected lines
+ * into six headings is a destructive reading of an ambiguous gesture.
+ */
+export declare function setHeading(level: number): Command;
+export declare function adjustHeading(delta: number): Command;
+/**
+ * Toggles a list over every line the selection touches.
+ *
+ * Removes only when EVERY line already has that kind of marker — the same
+ * convention every editor uses, and the one that makes a mixed selection do
+ * something predictable rather than alternating line by line.
+ */
+export declare function toggleList(asOrdered: boolean): Command;
+export declare const indentLines: Command;
+export declare const outdentLines: Command;
+/** Toggles a task checkbox, adding one if the item has none. */
+export declare const toggleTask: Command;
+export declare const toggleQuote: Command;
+/**
+ * Wraps the selected lines in a fence, or unwraps the fence they are inside.
+ *
+ * The fence is built from the lines OUTSIDE the selection when unwrapping, so
+ * putting the caret anywhere in a code block and pressing the key removes the
+ * block — rather than requiring the user to select the fence lines they cannot
+ * see.
+ */
+export declare function toggleCodeBlock(language?: string): Command;
+/** The fenced block containing `offset`, if any. */
+export declare function fenceAround(source: string, offset: number): {
+    start: number;
+    end: number;
+    bodyStart: number;
+    bodyEnd: number;
+} | null;
+export declare const insertRule: Command;
+/**
+ * Wraps the selection as a link, leaving the caret in the destination.
+ *
+ * With no href the destination is empty and the caret sits inside the
+ * parentheses, which is where a popover would put it too — the command is the
+ * same whether a popover drove it or a hotkey did.
+ */
+export declare function insertLink(href?: string, title?: string): Command;
+/**
+ * Inserts an image, using the selection as its alt text.
+ *
+ * ALT TEXT IS NOT OPTIONAL AND NOT AN AFTERTHOUGHT, which is why the selection
+ * becomes it rather than the source: an image whose alt is the filename is
+ * exactly as useless to a screen reader as one with none, and the person
+ * inserting it is the only one who knows what it shows. With nothing selected
+ * the caret lands between the brackets, on the alt, before the URL.
+ */
+export declare function insertImage(src?: string, alt?: string): Command;
+export interface TableSpan {
+    start: number;
+    end: number;
+    /** Whole lines: header, delimiter, then body rows. */
+    rows: LineSpan[];
+}
+/** The GFM table containing `offset`, if any. */
+export declare function tableAround(source: string, offset: number): TableSpan | null;
+/** A row's cells, by their text, with the outer pipes removed. */
+export declare function cellsOf(text: string): string[];
+/** Which row and column an offset falls in, within a table. */
+export declare function cellAt(source: string, table: TableSpan, offset: number): {
+    row: number;
+    column: number;
+} | null;
+export declare function insertTable(columns?: number, bodyRows?: number): Command;
+export declare function insertRow(below: boolean): Command;
+export declare function insertColumn(after: boolean): Command;
+export declare const deleteRow: Command;
+export declare const deleteColumn: Command;
+export declare const deleteTable: Command;
+export declare function alignColumn(align: "left" | "center" | "right"): Command;
+/**
+ * Moves the caret to the next or previous CELL of the table it is in.
+ *
+ * Tab between cells is the one table affordance people notice the absence of
+ * immediately, because every spreadsheet and every other table editor has it.
+ * It is a MOVEMENT, not an edit, so it returns a zero-width splice — the same
+ * shape every other command uses, which keeps one code path in the caller.
+ *
+ * Wraps to the next ROW at the end of one, and stops at the table's ends rather
+ * than escaping into the document: a Tab that leaves the table by surprise is
+ * how a user loses their place in it.
+ */
+export declare function tableTab(forward: boolean): Command;
+/**
+ * Enter, with the block structure carried onto the next line.
+ *
+ * The one place a command looks at what the line IS rather than what the user
+ * selected — because pressing Enter in a list and getting a bare line is the
+ * single most-noticed omission in a markdown editor.
+ *
+ * An EMPTY list item exits the list instead of making another one, which is
+ * what every editor does and what stops a stray marker being left behind.
+ */
+/**
+ * Backspace at the start of a block's own text, which removes that block's
+ * markup instead of the character before it.
+ *
+ * THIS IS THE ONLY WAY TO REMOVE MARKUP YOU CANNOT SEE. Under the old contract
+ * the marker was reachable text, so deleting a list item's dash was just
+ * backspacing over a dash. Now the caret cannot enter a marker at all, and the
+ * character before an item's first letter is the newline that ends the line
+ * above — so a plain backspace would MERGE THE ITEM INTO THE PREVIOUS LINE and
+ * leave `previous- item` behind, printing a marker as prose. Every rich editor
+ * uses this rule for the same reason; here it is load-bearing rather than
+ * conventional.
+ *
+ * It is a LADDER, one rung per press, so holding backspace unwinds a nested
+ * item cleanly instead of jumping to plain text: checkbox, then one indent
+ * level per press, then the marker itself.
+ *
+ * Returns null unless the caret is collapsed AT OR BEFORE the block's content
+ * start — anywhere past it, backspace means what it always meant.
+ *
+ * AT OR BEFORE, not exactly at, because with the markup collapsed every offset
+ * from the line's start to its content start is the SAME PLACE on screen, and
+ * which of them the caret map picks depends on what else is on the line. An
+ * empty task item holding a table turned out to put it at offset 0 rather than
+ * at 6, and an exact test then declined — leaving a document that rendered as a
+ * checkbox and an empty table with no key that could remove either.
+ */
+export declare const backspaceBlockPrefix: Command;
+export declare const smartEnter: Command;
+/**
+ * Tab: indent inside a list, otherwise decline so focus can leave.
+ *
+ * WCAG 2.1.2 permits an editor to own Tab, but the advisement clause is
+ * normative — an undocumented escape is a failure even when the escape exists.
+ * Declining outside a list means Tab does the ordinary thing almost everywhere,
+ * which is the cheapest possible way to satisfy it.
+ */
+export declare const smartTab: Command;
+export declare const smartShiftTab: Command;
+export {};

package/dist/types/lib/markdown/convert.d.ts

@@ -0,0 +1,82 @@
+import { type Command, type Edit } from "./commands";
+import type { Projection } from "./project";
+/** The block kinds a line-type control can offer. */
+export type BlockKind = "paragraph" | "heading" | "quote" | "code" | "bullet" | "ordered" | "task" | "table" | "rule";
+export interface BlockInfo {
+    kind: BlockKind;
+    /** 1–6 for a heading, otherwise undefined. */
+    level?: number;
+    /** The info string of a fence, "" when it has none. */
+    language?: string;
+    /** Whether a task item is ticked. */
+    checked?: boolean;
+    /** The source span this control operates on. */
+    start: number;
+    end: number;
+}
+/**
+ * What the block at `offset` is, and the span a conversion would replace.
+ *
+ * The span is the whole construct for a fence or a table and the caret's own
+ * line otherwise — see the header. A caller with a real selection widens it
+ * itself; this answers for a point.
+ */
+export declare function blockAt(source: string, offset: number): BlockInfo;
+export interface ConvertOptions {
+    /** 1–6, for `heading`. Ignored otherwise. */
+    level?: number;
+    /** Info string, for `code`. Ignored otherwise. */
+    language?: string;
+}
+/**
+ * Converts the block at the selection to `kind`, whatever it is now.
+ *
+ * SET, NOT TOGGLE: converting a quote to a quote is a no-op rather than an
+ * un-quote, because a menu item that undoes itself when the current type is
+ * picked is a menu item that punishes confirming what you already have.
+ */
+export declare function convertBlock(kind: BlockKind, options?: ConvertOptions): Command;
+/**
+ * Rewrites a fenced block's info string.
+ *
+ * Its own command rather than `convertBlock("code", {language})`, because that
+ * would rebuild the whole block to change one word — losing nothing, but
+ * replacing every line and therefore every DOM node the reconciler had kept.
+ */
+export declare function setFenceLanguage(language: string): Command;
+export interface ConstructInfo {
+    kind: "link" | "image";
+    /** Destination — `href` for a link, `src` for an image. */
+    target: string;
+    /** Label for a link, alt text for an image. */
+    label: string;
+    title?: string;
+    start: number;
+    end: number;
+}
+/**
+ * The innermost link or image containing `offset`.
+ *
+ * Read from the PROJECTION rather than by matching brackets, for the reason
+ * every other reader in this codebase gives: the parser has already decided
+ * what is a link, including the cases a regex gets wrong — a bracket inside a
+ * code span, an unbalanced one, a reference definition elsewhere in the file.
+ */
+export declare function constructAt(projection: Projection, offset: number): ConstructInfo | null;
+export interface ConstructPatch {
+    target?: string;
+    label?: string;
+    title?: string;
+    /** Rewrites a link as an image or the other way round. */
+    kind?: "link" | "image";
+}
+/** Rewrites the link or image at `offset` from its parts. */
+export declare function editConstruct(projection: Projection, offset: number, patch: ConstructPatch): Edit | null;
+/**
+ * Replaces a link or image with its own text.
+ *
+ * The one conversion that removes a construct rather than changing it, and the
+ * only way to get rid of a link now that its brackets are markup the caret
+ * cannot reach.
+ */
+export declare function unwrapConstruct(projection: Projection, offset: number): Edit | null;

package/dist/types/lib/markdown/dom.d.ts

@@ -0,0 +1,67 @@
+import type { Frame } from "../syntax/markdown/frames";
+/** Marks the wrapper around a run of markup, for the collapse rule. */
+export declare const SYNTAX_ATTR = "data-md-syntax";
+/** Names the frame an element came from, for styling and for the reconciler. */
+export declare const FRAME_ATTR = "data-md";
+export interface TagSpec {
+    tag: string;
+    /** Attributes the element carries, beyond `data-md`. */
+    attrs?: Record<string, string>;
+    /**
+     * A rendered decoration appended after the frame's own characters.
+     *
+     * THE ONLY WAY TO SHOW A PICTURE WITHOUT LYING ABOUT THE TEXT. An image's
+     * source is `![alt](src)` and every one of those characters must stay in the
+     * DOM and stay reachable — so the picture cannot replace them. It is an extra
+     * node that holds NO TEXT, which is exactly why it is invisible to the
+     * projection invariant and to position mapping: both walk text nodes only.
+     *
+     * Marked with its own attribute so the reconciler can lift it out before
+     * diffing children and put it back after, the same way the trailing-line
+     * filler is handled. Without that it would occupy a child index and shift
+     * every sibling the positional diff is counting.
+     */
+    decoration?: {
+        tag: string;
+        attrs: Record<string, string>;
+    };
+}
+/** Marks a rendered decoration, which carries no text and no source range. */
+export declare const DECORATION_ATTR = "data-md-decoration";
+/**
+ * What an image's `src` may be — a DIFFERENT policy from a link's `href`, and
+ * deliberately so.
+ *
+ * `sanitizeHref` allows only `http(s)`, `mailto`, `tel` and `ftp`, because a
+ * link is something a person clicks and `data:text/html` is a working attack.
+ * That rule is right for links and it is NOT loosened here.
+ *
+ * An image is not clicked, and `data:image/*` is how an inline avatar, an icon
+ * or a pasted screenshot is written — refusing it would make the editor unable
+ * to show a very ordinary document. The narrow addition is safe for one
+ * specific reason worth stating: an SVG loaded through `<img>` has scripting
+ * DISABLED by specification, which is not true of the same SVG in an `<object>`
+ * or an `<iframe>`. So `data:image/*` is allowed only because the decoration is
+ * an `<img>` and nothing else.
+ */
+export declare function sanitizeImageSrc(src: string): string | null;
+/**
+ * The element a frame becomes.
+ *
+ * `a` deliberately renders as a `<span>`, NOT an anchor. An anchor inside a
+ * contenteditable is a trap: the browser gives it its own selection behaviour,
+ * some engines make it draggable, and a click navigates away from the document
+ * being edited. The link's appearance is a class; its behaviour belongs to the
+ * editor, which knows whether a modifier key was held.
+ */
+export declare function tagFor(frame: Frame): TagSpec;
+/**
+ * Whether two frames describe the same element, for reuse during a patch.
+ *
+ * Compared by TAG and by the attributes that would have to change, not by deep
+ * equality of the frame: a heading whose text changed is the same `<h2>` and
+ * must keep its identity, while a heading that became an `<h3>` is a different
+ * element. Getting this wrong in the permissive direction replaces nodes the
+ * caret is inside; getting it wrong in the strict direction is merely slower.
+ */
+export declare function sameElement(a: Frame, b: Frame): boolean;

package/dist/types/lib/markdown/edit.d.ts

@@ -0,0 +1,16 @@
+import type { CaretMap } from "./caret-map";
+import type { Edit } from "./commands";
+import type { Projection } from "./project";
+export type { Edit } from "./commands";
+/**
+ * Removes every visible character in `[from, to)`, and any inline construct
+ * that is left with nothing inside it.
+ *
+ * Returns null when the range holds no visible characters at all, so a caller
+ * can tell "nothing to delete" from "deleted nothing".
+ */
+export declare function deleteVisible(projection: Projection, from: number, to: number): Edit | null;
+/** Backspace: removes the visible character before `offset`, or an atomic construct. */
+export declare function deleteVisibleBefore(projection: Projection, map: CaretMap, offset: number): Edit | null;
+/** Forward delete: removes the visible character after `offset`, or an atomic construct. */
+export declare function deleteVisibleAfter(projection: Projection, map: CaretMap, offset: number): Edit | null;