@50arms/ui 0.0.0-stage → 35.1.0

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;

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

@@ -0,0 +1,59 @@
+import type { SourceSelection } from "./position";
+export interface HistoryEntry {
+    source: string;
+    selection: SourceSelection | null;
+}
+/** What produced an edit, for deciding whether two of them belong together. */
+export type EditKind = "type" | "delete" | "compose" | "other";
+export interface HistoryOptions {
+    /** Quiet time after which the next edit starts a new group. */
+    groupMs?: number;
+    /** Entries kept. Beyond this the oldest are dropped. */
+    limit?: number;
+    /** Injected so tests are deterministic; never read a clock directly. */
+    now?: () => number;
+}
+export declare class History {
+    private readonly entries;
+    private index;
+    private readonly groupMs;
+    private readonly limit;
+    private readonly now;
+    /** State of the group currently open for merging. */
+    private lastAt;
+    private lastKind;
+    private lastEnd;
+    constructor(initial: HistoryEntry, options?: HistoryOptions);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** Entry count, for tests that assert coalescing rather than behaviour. */
+    get size(): number;
+    /**
+     * Records a state.
+     *
+     * `at` is where the edit happened; adjacency to the previous edit is what
+     * separates "still typing" from "went somewhere else and typed". Passing the
+     * position rather than deriving it from the diff is deliberate — a diff of
+     * two strings finds the shortest edit, which is not always the edit that
+     * happened, and coalescing decisions made from the wrong position are worse
+     * than none.
+     */
+    record(entry: HistoryEntry, kind: EditKind, at: number): void;
+    private shouldMerge;
+    /** Forces the next edit to open a new group — a selection change, a blur. */
+    break(): void;
+    /**
+     * Replaces every occurrence of `from` with `to` in EVERY entry, carrying
+     * each entry's selection through the change.
+     *
+     * The upload swap (DX-3134, see `MarkdownSurface.substitute`): a stored
+     * image's object URL must not survive anywhere Ctrl+Z or Ctrl+Y could reach.
+     * The entries are rewritten in place rather than a new one recorded, so the
+     * swap is not itself an undo step and the undo depth is unchanged.
+     */
+    substitute(from: string, to: string): void;
+    /** Whether any entry, reachable by undo or redo, still holds `text`. */
+    includes(text: string): boolean;
+    undo(): HistoryEntry | null;
+    redo(): HistoryEntry | null;
+}

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

@@ -0,0 +1,63 @@
+import { type Command } from "./commands";
+export type HotkeyGroup = "formatting" | "headings" | "lists" | "blocks" | "tables";
+/**
+ * What a row does, in the words of no language: the help surface looks the row's
+ * description up under this id in the active `UiLocaleProvider`'s strings
+ * (`markdownEditor.hotkeys`), so the table holds chords and commands only.
+ */
+export type HotkeyId = "bold" | "italic" | "inlineCode" | "strikethrough" | "link" | "attachFile" | "paragraph" | "heading1" | "heading2" | "heading3" | "heading4" | "heading5" | "heading6" | "decreaseHeading" | "increaseHeading" | "bulletList" | "numberedList" | "taskCheckbox" | "indent" | "outdent" | "codeBlock" | "blockquote" | "horizontalRule" | "table" | "rowAbove" | "rowBelow" | "columnLeft" | "columnRight" | "deleteRow" | "deleteColumn" | "deleteTable" | "alignLeft" | "alignCenter" | "alignRight";
+/**
+ * Something only the editor itself can do, because it is not a function of the
+ * source (DX-3134).
+ *
+ * Attaching a file means choosing it first, which needs a file picker —
+ * a browser dialog, not a splice. The row that used to insert an empty `![]()`
+ * (a construct with nothing to show, which rendered as nothing) now asks the
+ * editor for the picker instead, and the chosen files go through the same
+ * pipeline as a paste or a drop.
+ */
+export type EditorRequest = "pickFiles" | "insertTable" | "insertColumnLeft" | "insertColumnRight";
+interface HotkeyBase {
+    id: HotkeyId;
+    /**
+     * The chord this matches: lower-case, modifiers first, in the order ctrl,
+     * alt, shift.
+     *
+     * PUNCTUATION IS SPELLED BY PHYSICAL KEY (`bracketleft`, `comma`), not by the
+     * character it produces. The browser probe found why: with Shift held, the
+     * `[` key reports `event.key === "{"`, so a table keyed on `[` never matched
+     * and Ctrl+Shift+[ was silently inert. `event.code` is the same regardless of
+     * which character the modifier produced.
+     */
+    key: string;
+    group: HotkeyGroup;
+}
+/** A chord, and EITHER the pure edit it makes OR the editor request it raises. */
+type HotkeyAction = {
+    command: Command;
+    request?: never;
+} | {
+    request: EditorRequest;
+    command?: never;
+};
+export type Hotkey = HotkeyBase & HotkeyAction;
+export declare const HOTKEYS: readonly Hotkey[];
+/**
+ * The chords a key event could be, most specific first.
+ *
+ * TWO SPELLINGS, because neither alone is enough. The CHARACTER spelling is
+ * what a letter or digit chord needs — Ctrl+B is the letter B whatever key
+ * produced it. The PHYSICAL spelling is what punctuation needs: with Shift
+ * held, the `[` key reports `event.key === "{"`, so a table keyed on the
+ * character never matches and the chord is silently inert. The browser probe
+ * found exactly that: Ctrl+Shift+[ did nothing at all, and nothing in the unit
+ * suite could have seen it, because the commands themselves were correct.
+ *
+ * Modifiers in a FIXED order, because `ctrl+shift+s` and `shift+ctrl+s` are the
+ * same chord and a table keyed on free-form strings silently misses one of
+ * them. `metaKey` folds into `ctrl` so one table serves macOS, where the
+ * platform convention is Command for every one of these.
+ */
+export declare function chordsOf(event: KeyboardEvent): string[];
+export declare function hotkeyFor(event: KeyboardEvent): Hotkey | null;
+export {};

package/dist/types/lib/markdown/image-pipeline.d.ts

@@ -0,0 +1,173 @@
+import type { SourceSelection } from "./position";
+import type { MarkdownSurface } from "./surface";
+/**
+ * Stores one file and says where it now lives. The same contract serves a picture (`uploadImage`) and any
+ * other file (`uploadFile`).
+ *
+ * `signal` aborts when the editor unmounts; an uploader that ignores it still
+ * works, its result is simply discarded. The returned `url` must be one an
+ * `<img>` may load (`http(s)`, a relative URL, or `data:image/*` -
+ * `sanitizeImageSrc`) and never another `blob:`; anything else is reported
+ * as a failed upload rather than written into the document.
+ */
+export type ImageUploader = (file: File, options: {
+    signal: AbortSignal;
+}) => Promise<{
+    url: string;
+}>;
+/**
+ * What the consumer needs to decide whether it may save (PLN-10 R-1).
+ *
+ * Counts REFERENCES IN THE CURRENT DOCUMENT to a file not stored yet, one per construct - the same unit
+ * `findUnstoredImages` returns, so `unstored === findUnstoredImages(value).length`
+ * always. `uploading` are being stored, `failed` cannot be stored without the
+ * author acting (a rejected upload, or a `blob:` this editor did not mint), and
+ * `unstored` is every file not stored yet - `uploading + failed` plus those
+ * with no storage configured. `unstored > 0` means the value must not be saved.
+ */
+export interface ImageUploadState {
+    uploading: number;
+    failed: number;
+    unstored: number;
+}
+/** The editor's own view: the public counts, plus what its chrome needs. */
+export interface ImagePipelineSnapshot extends ImageUploadState {
+    /** Files that cannot be stored because there is no uploader. */
+    local: number;
+    /** Bumps whenever a file's state moves, so a tile redraws even when the counts above do not change. */
+    revision: number;
+}
+/** What the pipeline knows about one object URL it minted: the strip's source for a tile's picture and state. */
+export interface LocalFileInfo {
+    file: File;
+    state: "uploading" | "failed" | "local";
+    /** The rejection's own text, present only when `state === "failed"` and the uploader threw an `Error`. */
+    message?: string;
+}
+/**
+ * The browser facilities the pipeline touches, injectable so a test never
+ * needs a real object URL or a real network.
+ */
+export interface ImagePipelineEnvironment {
+    createObjectURL: (file: File) => string;
+    revokeObjectURL: (url: string) => void;
+    /**
+     * Settles once `url` has loaded or failed to. The swap waits for it so the
+     * stored picture is already in the cache when it replaces the local one -
+     * otherwise the tile blinks empty for as long as the download takes.
+     */
+    preload: (url: string) => Promise<unknown>;
+    /**
+     * The longest the swap waits for `preload`. A stored URL whose download
+     * stalls would otherwise hold a file that IS stored in "uploading" for
+     * ever - save disabled, page-leave guarded - for want of a cache warm-up.
+     */
+    preloadTimeoutMs: number;
+}
+export interface ImagePipelineOptions {
+    /** The picture uploader in force right now, or null when there is no storage for pictures. */
+    uploadImage: () => ImageUploader | null;
+    /** The uploader for any other file, or null: then a file that is not a picture is ignored. */
+    uploadFile: () => ImageUploader | null;
+    /** The picture types `uploadImage` stores, or undefined for every `image/*`. A picture outside them goes to `uploadFile` as a link. */
+    imageTypes: () => readonly string[] | undefined;
+    /** Whether a link's destination is a file the app stores or a file this editor minted; numbering counts only those. */
+    isFileUrl: () => (url: string) => boolean;
+    /** The word a file's reference name starts with ("Image", "PDF"), from the library's strings. */
+    kindWord: (file: File) => string;
+    /** Called whenever the snapshot changes, and once when attached. */
+    onChange: (snapshot: ImagePipelineSnapshot) => void;
+    environment?: Partial<ImagePipelineEnvironment>;
+}
+export declare class ImagePipeline {
+    private readonly options;
+    private surface;
+    private readonly entries;
+    /** Where each stored URL came from: the object URL that held its place in the document until its upload finished. */
+    private readonly origins;
+    private readonly env;
+    private last;
+    private revision;
+    private disposed;
+    constructor(options: ImagePipelineOptions);
+    /**
+     * What the strip knows about an object URL this editor minted, or null for
+     * anything else. An arrow property so it can be handed around before the
+     * surface exists.
+     */
+    readonly resolve: (src: string) => LocalFileInfo | null;
+    /**
+     * A name for a file that does not change when its upload finishes: the object URL it was first written under,
+     * or the URL itself for a file that was never swapped. A tile keyed or opened on it survives the swap.
+     */
+    readonly identity: (src: string) => string;
+    /** Whether a file of this MIME type is a picture `uploadImage` stores. */
+    private isPicture;
+    /**
+     * Whether the editor takes a file of this MIME type: a picture it stores, or any file once `uploadFile` is set.
+     * Read by paste, drop and the picker, so all three agree.
+     */
+    readonly accepts: (mimeType: string) => boolean;
+    /** Connects the surface this pipeline edits, and reports the first snapshot. */
+    attach(surface: MarkdownSurface): void;
+    /**
+     * THE pipeline: every file that enters the editor comes through here -
+     * paste, drop and the file picker alike.
+     *
+     * `at` is where the references go: the caret for a paste or a pick, the drop
+     * point for a drop. With none (an editor that was never focused), they go at
+     * the end of the document - never at offset 0 in front of whatever the
+     * author wrote first. A file the editor does not take (`accepts`) is ignored;
+     * the picker's `accept` is a hint the user can override, not a guarantee.
+     *
+     * Returns the object URLs it inserted, in order.
+     */
+    insert(files: readonly File[], at: SourceSelection | null): string[];
+    /**
+     * Uploads a failed file again, with the SAME File it was inserted with.
+     *
+     * With no uploader configured any more, the file becomes local-only rather
+     * than staying "failed" - the honest state for something nothing can store.
+     */
+    retry(src: string): void;
+    /**
+     * Starts uploading every local-only file once an uploader exists.
+     *
+     * The component calls this when an uploader changes: a file pasted before an
+     * app's storage provider mounted should not stay unsaveable when the storage
+     * it needed arrives a moment later.
+     */
+    uploaderChanged(): void;
+    /**
+     * Recomputes the snapshot from the CURRENT document, and releases object
+     * URLs nothing can reach any more. Called after every change to the source.
+     *
+     * THE COUNTS COME FROM `findUnstoredImages`, the same exported function a
+     * consumer's save path calls - one detection source, never a second opinion
+     * the two could disagree on (DX-3134).
+     *
+     * AN OBJECT URL IS RELEASED WHEN ITS FILE IS GONE AND SETTLED: not in the
+     * document, not in any undo or redo entry (Ctrl+Z could bring it back), and
+     * not mid-upload (the upload will swap it wherever it still is). Revoking one
+     * any earlier turns an undo into a broken file; never revoking leaks the
+     * file's bytes for the life of the page.
+     */
+    sync(): void;
+    /**
+     * Stops everything: aborts every upload in flight and releases every object
+     * URL. The editor is going away, so nothing it minted can be drawn anywhere
+     * again - no other editor will render another's `blob:`.
+     */
+    dispose(): void;
+    private uploaderFor;
+    private upload;
+    /**
+     * Resolves when `work` settles, `preloadTimeoutMs` passes, or `signal`
+     * aborts - never rejects. Every timer and listener is cleaned up.
+     */
+    private settled;
+    private release;
+    /** A file's state moved: re-report, so its tile redraws. */
+    private changed;
+    private requireSurface;
+}

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

@@ -0,0 +1,138 @@
+import { type Projection } from "./project";
+/**
+ * A reference to a file that exists only in this page's memory: an image `![name](blob:...)` or a link
+ * `[name](blob:...)` (DXUI-74 - a file the editor stores is a named reference, whatever its kind).
+ */
+export interface UnstoredImage {
+    /** The `blob:` URL exactly as the source spells it. */
+    src: string;
+    /** The reference name: the bracket text. */
+    alt: string;
+    /** The whole `![name](src)` or `[name](src)` construct, as source offsets. */
+    start: number;
+    end: number;
+}
+/** Whether an image src names a picture that has not been stored anywhere. */
+export declare function isUnstoredImageSrc(src: string): boolean;
+/**
+ * Every image and link in `markdown` whose destination is a `blob:` URL, in source order.
+ *
+ * THE SINGLE DETECTION SOURCE. The editor's own warning strip, its
+ * `onImageUploadStateChange` counts and its `beforeunload` guard all read this
+ * function, and it is exported so a consumer's save path can re-check the
+ * exact value it is about to persist with the same answer (DX-3134, PLN-10
+ * "Pending-state event").
+ *
+ * Read from the PARSER, not with a regex, for the reason `constructAt` gives:
+ * the parser has already decided what is an image, including the cases a
+ * pattern gets wrong — a `![x](blob:…)` inside a code span is prose, not a
+ * picture, and saving it loses nothing.
+ */
+export declare function findUnstoredImages(markdown: string): UnstoredImage[];
+/**
+ * The bracket text of a link or image as the person reads it: the source slice with markdown backslash escapes
+ * undone (`Bob \[final\]\!` reads `Bob [final]!`). It is the inverse of `escapeReferenceName`, so a rename that
+ * is read back and saved again never grows backslashes.
+ */
+export declare function referenceLabel(source: string, content: readonly {
+    start: number;
+    end: number;
+}[]): string;
+/**
+ * What a stored file's URL may be, and what a tile's `<img>` may load.
+ *
+ * `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 not loosened: this only narrows it to
+ * `http(s)` and relative URLs, since the other three name nothing to load, and adds `data:image/*`, how an
+ * inline avatar, an icon or a pasted screenshot is written. That narrow addition is safe because an SVG
+ * loaded through `<img>` has scripting disabled by specification. `blob:` is refused here and stays
+ * refused: an object URL is only rendered when the editor that minted it vouches for it.
+ */
+export declare function sanitizeImageSrc(src: string): string | null;
+/**
+ * A URL written so the destination parses as exactly that URL.
+ *
+ * Whitespace ends a destination, an unbalanced parenthesis ends the construct,
+ * and a backslash before punctuation is an escape markdown would consume — so
+ * all of them are percent-encoded, which is the same URL to every server and
+ * the only spelling that survives being written into markdown.
+ */
+export declare function markdownDestination(url: string): string;
+/** `name` written so it reads back as exactly that bracket text. */
+export declare function escapeReferenceName(name: string): string;
+/** `![name](src)` for a picture, `[name](src)` for any other file, with both halves escaped so they read back as themselves. */
+export declare function referenceMarkdown(kind: "image" | "link", src: string, name: string): string;
+/** The result of replacing every occurrence of one string with another. */
+export interface Substitution {
+    source: string;
+    /** Carries an offset in the old source to the same place in the new one. */
+    map: (offset: number) => number;
+}
+/**
+ * Replaces EVERY occurrence of `from` in `source` with `to`, or returns null
+ * when there is none.
+ *
+ * A PLAIN TEXT REPLACEMENT, deliberately, and only safe because of what `from`
+ * is: an object URL this editor minted, which embeds a random UUID and was
+ * never typed by anyone. Every occurrence of it is that image, whatever
+ * construct holds it now — including one the author has since turned into a
+ * link, which a parser-driven swap would leave pointing at a dead handle in
+ * the saved value (DX-3134).
+ *
+ * `map` is what lets the caret survive the swap: offsets before an occurrence
+ * stay, offsets after one shift by the length change, and an offset that was
+ * INSIDE a replaced URL lands at the end of its replacement.
+ */
+export declare function substituteAll(source: string, from: string, to: string): Substitution | null;
+/** The innermost code construct containing an offset — see `enclosingCode`. */
+export interface CodeConstruct {
+    end: number;
+    block: boolean;
+}
+/**
+ * The innermost code construct — fenced block, indented block, or inline span
+ * — containing `offset`, or null when `offset` sits in ordinary prose.
+ *
+ * DX-3140: read from the PROJECTION, the same source `marksAt`/`constructAt`
+ * in `convert.ts` use, rather than re-deriving fence syntax with a second
+ * regex — `blockAt`'s own `fenceAround` regex only ever recognises a FENCED
+ * block, so it would miss an indented one entirely, and every code kind here
+ * (fenced, indented, span) shares exactly one frame shape either way: the
+ * parser has already decided the boundary in every case a hand-rolled pattern
+ * gets wrong. Boundaries are inclusive on both ends, matching `marksAt` — a
+ * caret at either edge still reads as inside. When several code frames
+ * contain `offset` (a nested case the grammar does not produce today), the
+ * outermost one wins, so the image lands past all of them, not between two.
+ *
+ * SHARED, not private to the image pipeline: `insertImage` below is public
+ * API (`src/index.ts`), so a consumer calling it directly with a selection
+ * inside a code construct is exactly as able to write dead `![](…)` text into
+ * code as a paste ever was — the ONE check has to live somewhere both paths
+ * reach, not be re-derived per caller.
+ */
+export declare function enclosingCode(projection: Projection, offset: number): CodeConstruct | null;
+/**
+ * The text to actually write at `at` when it sits at the boundary of a code
+ * BLOCK (fenced or indented) — reshaped so it lands cleanly outside it.
+ *
+ * CALLERS MUST PASS THE SAME `at` THEY ACTUALLY SPLICE AT, and nothing else —
+ * this was a real bug (DX-3140 code review, round 1): reading the boundary
+ * characters from `enclosingCode`'s raw `end` while splicing at a DIFFERENT,
+ * caret-map-snapped offset meant the two could disagree, most detectably when
+ * `nearestStop` ever moved the insertion point off `end`. There being exactly
+ * ONE offset in this function's signature makes that class of drift
+ * impossible to reintroduce by construction, rather than by convention.
+ *
+ * A BLOCK FRAME ALREADY OWNS ITS OWN TRAILING NEWLINE, when one exists (`at`
+ * sits at the START of the next line, not at the fence's last backtick) — so
+ * blindly prefixing "\n\n" would stack a THIRD newline on top of the one
+ * already there, splitting the image from the code by a full extra blank
+ * line no author asked for. Reading what is already on each side of `at` and
+ * adding only what is missing keeps it to exactly one blank line before the
+ * image, and puts it on its own line after, whatever originally followed the
+ * block (nothing, a line right away, or an existing blank line of its own).
+ *
+ * A SPAN NEEDS NO RESHAPING — it just continues the line it was on — so this
+ * is only ever called for `enclosingCode(...).block === true`.
+ */
+export declare function reshapeForCodeBoundary(source: string, at: number, text: string): string;

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

@@ -0,0 +1,38 @@
+import { type SourceSelection } from "./position";
+import { type EditorRequest } from "./hotkeys";
+import type { MarkdownSurface } from "./surface";
+export interface InputOptions {
+    /**
+     * Called for an intent this layer cancelled but did not act on.
+     *
+     * Not a warning to be silenced — it is the list of what phase 4 owes. An
+     * editor that quietly ignores `formatBold` looks like one where Ctrl+B is
+     * broken, and this is how that gets noticed before a user reports it.
+     */
+    onUnhandled?: (inputType: string) => void;
+    /**
+     * Receives the files of a paste or a drop, and where they go (DX-3134, DXUI-74).
+     *
+     * `accepts` says from a MIME type alone whether the editor takes that file (a drag only exposes the type, never
+     * the file, until it is dropped). `receive` gets the accepted files and `at`: the caret for a paste and the drop
+     * point for a drop, already on a caret stop. Without this option files are not handled here at all, and a paste
+     * or drop behaves exactly as it always did.
+     */
+    files?: {
+        accepts: (mimeType: string) => boolean;
+        receive: (files: File[], at: SourceSelection | null) => void;
+    };
+    /**
+     * Receives a hotkey that asks the EDITOR to do something rather than making
+     * an edit — the Attach-file chord opening a file picker (DX-3134). A
+     * request with no receiver lets the key fall through, like a command that
+     * declined.
+     */
+    onRequest?: (request: EditorRequest) => void;
+}
+/**
+ * Binds the input layer to a surface. Returns the unbind function.
+ */
+export declare function attachInput(surface: MarkdownSurface, options?: InputOptions): () => void;
+/** Marks the surface while files it takes are dragged over it, for the affordance. */
+export declare const DROP_TARGET_ATTR = "data-md-drop-target";

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

@@ -0,0 +1,34 @@
+import type { CaretMap } from "./caret-map";
+import { type Edit } from "./edit";
+import type { SourceSelection } from "./position";
+import type { Projection } from "./project";
+export type KeyIntent = {
+    kind: "insert";
+    text: string;
+} | {
+    kind: "backspace";
+} | {
+    kind: "delete";
+} | {
+    kind: "enter";
+} | {
+    kind: "lineBreak";
+} | {
+    kind: "tab";
+} | {
+    kind: "shiftTab";
+};
+/** Everything a decision needs, and nothing it does not. */
+export interface KeyContext {
+    source: string;
+    projection: Projection;
+    map: CaretMap;
+}
+/**
+ * The edit a keystroke produces, or null to let the caller decline the key.
+ *
+ * Null is a real answer and not a failure: Tab outside a list declines so focus
+ * can leave the editor, which is what makes the WCAG 2.1.2 keyboard trap not
+ * happen in the first place.
+ */
+export declare function resolveKey(ctx: KeyContext, selection: SourceSelection, intent: KeyIntent): Edit | null;

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

@@ -0,0 +1,9 @@
+/**
+ * Converts one pasted HTML fragment to markdown.
+ *
+ * `parser` is injected so this stays testable and so it never reaches for a
+ * global — the editor passes its own document, and a test passes whatever it
+ * has. A module that grabs `window` is a module that cannot be tested without
+ * one.
+ */
+export declare function htmlFragmentToMarkdown(html: string, parse: (html: string) => Document): string;

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

@@ -0,0 +1,43 @@
+export interface DomPoint {
+    /**
+     * Usually a text node. It is an ELEMENT when the position has no text of its
+     * own to sit in — beside a picture, say, where every character of the
+     * construct is markup and every markup node is zero-width. An element point
+     * names a place BETWEEN children, which is a position the browser renders a
+     * caret for and `sourceOffsetAt` already knows how to read back.
+     */
+    node: Node;
+    offset: number;
+}
+/** Which side of a boundary an offset belongs to when two runs meet there. */
+export type Association = "before" | "after";
+export declare function domPointAt(root: Node, offset: number, association?: Association): DomPoint | null;
+/**
+ * The source offset for a DOM point.
+ *
+ * Accepts an ELEMENT container as well as a text node, because that is what a
+ * browser hands back: a selection at the start of an empty paragraph, or one
+ * that landed between two children, is reported as `(element, childIndex)`.
+ * Resolving it here rather than at each call site is the difference between one
+ * correct conversion and six approximate ones.
+ *
+ * Returns null for a point in a subtree this module did not build, which is a
+ * REAL event — the browser creates nodes during composition and on paste — and
+ * the caller must handle it as one rather than substitute a plausible number.
+ */
+export declare function sourceOffsetAt(root: Node, node: Node, offset: number): number | null;
+export interface SourceSelection {
+    anchor: number;
+    head: number;
+}
+/** The current selection as source offsets, or null if it is not in `root`. */
+export declare function readSelection(root: HTMLElement): SourceSelection | null;
+/**
+ * Puts the selection at the given source offsets.
+ *
+ * DOES NOTHING IF IT ALREADY MATCHES. That is the first of the three rules both
+ * ProseMirror and CodeMirror carry verbatim: writing a selection that is already
+ * correct is itself a source of caret jumps, because some engines scroll,
+ * collapse or re-anchor on assignment even when nothing moved.
+ */
+export declare function writeSelection(root: HTMLElement, selection: SourceSelection, association?: Association): boolean;

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

@@ -0,0 +1,88 @@
+import type { Frame, FrameRecord } from "../syntax/markdown/frames";
+/**
+ * A run of literal source characters.
+ *
+ * `syntax` is what the view collapses. It is not a rendering hint — it is the
+ * parser's own answer to "did any frame claim this as its text", so a run that
+ * says `syntax: false` is genuinely editable prose and one that says true is
+ * genuinely markup.
+ */
+export interface PText {
+    type: "text";
+    start: number;
+    end: number;
+    text: string;
+    syntax: boolean;
+    /**
+     * The highlight class this run carries, inside a fenced block.
+     *
+     * Only ever set for code, and only when a tokenizer was supplied. Prose stays
+     * untyped so it stays a BARE text node — see ../markdown/dom.ts, constraint 3:
+     * every wrapper around prose is another reason to replace a node, and a
+     * replaced node is a cancelled composition.
+     */
+    token?: string;
+}
+/** How a fenced block's body is highlighted, if the caller wants it. */
+export interface ProjectOptions {
+    /**
+     * Returns tokens with ABSOLUTE offsets into `source`, exactly as
+     * `lib/syntax`'s `tokenize` does.
+     *
+     * Injected rather than imported, and the reason is the same one the module
+     * header gives for not tokenizing at all before: reaching for the grammar
+     * REGISTRY from here would make a pure function's output depend on which
+     * languages happened to be registered when it ran. Passing it in keeps the
+     * projection reproducible and keeps this module's tests grammar-free.
+     */
+    highlight?: (code: string, language: string | null, at: number) => Array<{
+        start: number;
+        end: number;
+        type: string;
+    }>;
+}
+/** A frame with its projected children, in source order. */
+export interface PElement {
+    type: "element";
+    frame: Frame;
+    start: number;
+    end: number;
+    children: PNode[];
+}
+export type PNode = PText | PElement;
+/** The document root. `source` is kept so consumers never re-derive it. */
+export interface Projection {
+    source: string;
+    children: PNode[];
+    /** Every frame, in the order the parser opened them. */
+    frames: readonly FrameRecord[];
+}
+/**
+ * Thrown when the parser's frames do not nest, which would make the projection
+ * ambiguous.
+ *
+ * This is a FAIL-LOUD, not a repair. A projector that silently reordered
+ * overlapping frames would produce a tree that reads correctly and maps the
+ * caret to the wrong character — the exact defect this whole design exists to
+ * make impossible, reintroduced by the code meant to prevent it.
+ */
+export declare class ProjectionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Projects a markdown string.
+ *
+ * The walk is linear over the SOURCE, descending into a frame when it starts
+ * and leaving when it ends. Every character is emitted exactly once, by
+ * exactly one of the two paths — inside a frame or at the document level —
+ * which is the invariant stated as an algorithm rather than as a test.
+ */
+export declare function project(source: string, options?: ProjectOptions): Projection;
+/**
+ * Reads a projection's text back, in document order.
+ *
+ * Deliberately dumb — no knowledge of frames, no special cases. The moment this
+ * function needs to know what a table is, the invariant has stopped being an
+ * invariant.
+ */
+export declare function projectedText(nodes: readonly PNode[]): string;