typewright 0.2.1

package/dist/core/index.d.ts

@@ -0,0 +1,410 @@
+import { E as EditorConfig, a as EditorEvents, D as DocChange, b as DocSelection } from '../types-CX1GOx0Y.js';
+export { A as AnticipationOptions, C as CommentReply, c as CommentThread, d as CommentsOptions, e as ComponentMap, f as DocPosition, g as DocRange, h as EditorMode, i as Extensions, F as FoldingOptions, G as GfmFeatures, K as KeymapOptions, M as MathOptions, j as MdxOptions, k as MdxTransform, l as MermaidOptions, P as PresencePeer, S as SandboxOptions, m as SettingsCommand, n as SettingsOptions, o as StreamController, p as StreamOptions, q as SyntaxHighlightOptions, T as ThemeOptions } from '../types-CX1GOx0Y.js';
+import { P as ParseOptions, D as Document, I as Inline, B as Block, a as Pos, T as Table, C as CellAlign } from '../commands-Z3ndUSza.js';
+export { A as AstNode, b as Autolink, c as Blockquote, d as COMMANDS, e as CodeBlock, f as Command, g as CommandResult, h as DefItem, i as DefList, E as Emphasis, F as FootnoteDef, j as FootnoteRef, H as Heading, k as HtmlBlock, l as Image, m as InlineCode, L as LineBreak, n as Link, o as List, p as ListItem, M as Math, q as MathBlock, r as Paragraph, S as Sel, s as Strikethrough, t as Strong, u as TableCell, v as TaskState, w as TextNode, x as ThematicBreak, y as applyCommand, z as childrenOf, G as isInline, J as walk } from '../commands-Z3ndUSza.js';
+
+/**
+ * Document model — an immutable text container with transaction-based edits and
+ * position mapping. The string is the source of truth (SPEC.md §4.1): every edit
+ * is a `{from, to, insert}` change, applying one returns a NEW `TextDoc`, and
+ * offsets can be mapped across a change so decorations / anchors survive edits.
+ */
+interface Change {
+    /** Inclusive start offset of the replaced range. */
+    from: number;
+    /** Exclusive end offset of the replaced range. */
+    to: number;
+    /** Text inserted in place of `[from, to)`. */
+    insert: string;
+}
+interface LineInfo {
+    /** 1-based line number. */
+    number: number;
+    /** Offset of the first character of the line. */
+    from: number;
+    /** Offset just past the last character (before the newline). */
+    to: number;
+    /** The line's text (without the trailing newline). */
+    text: string;
+}
+interface Position {
+    /** 1-based line. */
+    line: number;
+    /** 1-based column (UTF-16 units within the line). */
+    column: number;
+}
+declare class TextDoc {
+    readonly text: string;
+    private _lineStarts;
+    constructor(text?: string);
+    get length(): number;
+    /** Apply one change, returning a new document. */
+    apply(change: Change): TextDoc;
+    /**
+     * Apply several changes, returning a new document. Changes are given in
+     * document coordinates of THIS doc; they are applied right-to-left so earlier
+     * offsets stay valid.
+     */
+    applyAll(changes: Change[]): TextDoc;
+    private lineStarts;
+    /** Total number of lines (a trailing newline yields an extra empty line). */
+    get lines(): number;
+    /** The line (1-based) containing `offset`. */
+    lineAt(offset: number): LineInfo;
+    /** Line/column (both 1-based) for an offset. */
+    positionAt(offset: number): Position;
+    /** Offset for a 1-based line/column. */
+    offsetAt(line: number, column: number): number;
+    /**
+     * Map an offset from this document's coordinates to the coordinates AFTER the
+     * given change(s). `assoc` controls which side of an insertion at the offset
+     * the mapped position sticks to: -1 = before (default), 1 = after.
+     */
+    mapOffset(offset: number, changes: Change | Change[], assoc?: -1 | 1): number;
+    toString(): string;
+}
+
+/**
+ * Typewright block + inline parser — a hand-written, zero-dependency GitHub
+ * Flavored Markdown (+ light MDX-flow) parser that produces the offset-exact
+ * AST in `./ast`. Every node carries `from`/`to` UTF-16 source offsets; markers
+ * (heading `### `, list bullets, emphasis delimiters) are exposed so a consumer
+ * can hide/reveal the raw syntax.
+ *
+ * Design notes:
+ *  - Block parsing works line-by-line. Container blocks (blockquote, list) build
+ *    a fresh line list whose `from` is advanced past the stripped prefix; because
+ *    only `from` moves, `src.slice(from, to)` still equals the line's content, so
+ *    offsets stay exact through arbitrary nesting.
+ *  - Inline parsing stitches a block's content lines into one buffer with a
+ *    per-character source-offset map, so emphasis/code spanning a soft line break
+ *    still reports correct absolute offsets.
+ *  - The parser never throws: unterminated emphasis / code / links / fences all
+ *    degrade to text (or run to end-of-input) rather than failing.
+ */
+
+/**
+ * Parse Markdown/MDX source into an offset-exact {@link Document}.
+ *
+ * `options` gates the opt-in extensions (math, footnotes, definition lists);
+ * every flag defaults to `false`, so `parse(src)` is unchanged from before.
+ */
+declare function parse(src: string, options?: ParseOptions): Document;
+/**
+ * Incrementally reparse `prev` (the parse of `prevSrc`) after a single
+ * {@link Change} produced `nextSrc`. The result is deep-equal to
+ * `parse(nextSrc, options)`; pass the SAME `options` that produced `prev`.
+ */
+declare function parseIncremental(prev: Document, prevSrc: string, change: Change, nextSrc: string, options?: ParseOptions): Document;
+
+/**
+ * AST → sanitized HTML renderer.
+ *
+ * This is the `read`/`preview` output path (SPEC.md §4): it walks the offset-exact
+ * AST produced by the parser and emits HTML that is safe to inject into a host
+ * page. Safety is structural, not incidental:
+ *
+ *  - every text / attribute value is HTML-escaped (`&`, `<`, `>`, `"`);
+ *  - every URL passes {@link safeUrl}, so `javascript:` / `data:` / other active
+ *    schemes collapse to `#`;
+ *  - raw HTML / MDX blocks are emitted ESCAPED inside `<pre>` — this renderer
+ *    never re-emits untrusted markup, so it can be used on model output;
+ *  - footnote / definition ids are slugged to a URL-safe charset *and* escaped
+ *    before they reach an `id`/`href` attribute.
+ *
+ * The renderer never throws: malformed / partial nodes degrade to escaped text.
+ *
+ * {@link RenderOptions} lets a host plug in escaped-HTML producers for the two
+ * constructs the core cannot render on its own — syntax highlighting and a math
+ * engine. Both are trusted to return already-escaped HTML; without them the
+ * renderer falls back to the safe escaped-source form. Passing no options
+ * reproduces the exact default behaviour.
+ */
+
+/**
+ * Optional, host-supplied output producers for constructs the core cannot
+ * render itself. Both hooks MUST return already-escaped, safe HTML — the
+ * renderer trusts their output and does not re-escape it. Omitting a hook (or
+ * the whole object) falls back to the safe escaped-source form.
+ */
+interface RenderOptions {
+    /**
+     * Syntax highlighter for fenced code. Receives the fence info string and the
+     * raw code; returns escaped HTML (e.g. `<span class="tw-tok-…">` runs). The
+     * host is responsible for escaping — see {@link highlightToHtml}.
+     */
+    highlight?: (lang: string, code: string) => string;
+    /**
+     * Math engine. Receives the TeX source and whether it is display math;
+     * returns escaped/safe HTML. Without it, math renders as escaped source.
+     */
+    math?: (src: string, display: boolean) => string;
+}
+/**
+ * Return `url` when it is safe to place in an `href`/`src`, otherwise `'#'`.
+ *
+ * Safe = an http/https/mailto absolute URL, OR anything without an explicit
+ * scheme (relative paths, `?query`, `#anchor`, protocol-relative `//host`).
+ * Any other scheme (`javascript:`, `data:`, `vbscript:`, `file:`, …) is denied.
+ *
+ * Scheme detection is done against a copy with whitespace + control characters
+ * stripped, so obfuscations like `java\tscript:` or a leading newline can't
+ * smuggle an active scheme past the check.
+ */
+declare function safeUrl(url: string): string;
+/** Render a run of inline nodes to sanitized HTML. */
+declare function renderInline(nodes: Inline[], options?: RenderOptions): string;
+/** Render a single block node to sanitized HTML. */
+declare function renderNode(node: Block, options?: RenderOptions): string;
+/** Render a whole document to sanitized HTML. */
+declare function renderToHtml(doc: Document, options?: RenderOptions): string;
+
+/**
+ * Unified (Obsidian-style live-preview) source-revealing logic.
+ *
+ * In `unified` mode the formatting renders inline, but the raw syntax markers
+ * (a heading's `### `, an emphasis `*`, a link's `](url)`, …) are hidden UNLESS
+ * the caret/selection is on top of them — then they reveal so you can edit the
+ * source. This module is pure and offset-exact: it maps the AST to the set of
+ * hideable marker ranges (`collectMarkers`) and decides which stay hidden for a
+ * given selection (`hiddenMarkers`). It never mutates the tree or the string.
+ */
+
+/**
+ * A hideable syntax-marker range: `[from, to)` with a `kind` tag.
+ *
+ * `kind` is an open string (not a closed union) so new marker families can be
+ * added without a breaking type change. The kinds currently emitted are
+ * `heading`, `emphasis`, `strong`, `strike`, `code`, `link`, `image`,
+ * `listMarker`, `math`, `footnoteRef`, `fence` and `blockquote`.
+ */
+interface Marker extends Pos {
+    kind: string;
+}
+/**
+ * Every hideable syntax-marker range in the document, in document order.
+ *
+ * Covers: heading `#… ` prefixes, the two emphasis/strong/strike delimiter runs
+ * on each side, inline-code backtick fences, link `[`/`](`/url/`)` pieces, the
+ * image `!` (plus its bracket/paren pieces), list-item markers, inline-math `$`
+ * (or `$$`) delimiters, and footnote-reference `[^`/`]` brackets.
+ *
+ * When the original `source` string is supplied it additionally emits the
+ * `fence` (opening + closing fenced-code lines) and `blockquote` (the leading
+ * `>` run on each quoted line) markers — these need the raw text to be
+ * offset-exact, so they are omitted when `source` is not passed (keeping the
+ * source-free call identical to before). Always pure; never mutates.
+ */
+declare function collectMarkers(doc: Document, source?: string): Marker[];
+/**
+ * The markers that stay HIDDEN for a given selection: those whose `[from, to)`
+ * does NOT intersect the selection widened by 1 on each side. Markers that DO
+ * intersect are revealed (returned excluded), so the caret can edit the raw
+ * syntax it sits on — the live-preview reveal rule.
+ *
+ * `source` is forwarded to {@link collectMarkers} so the fence/blockquote
+ * markers participate in the reveal too; omit it to keep the source-free set.
+ * The selection filter itself is unchanged.
+ */
+declare function hiddenMarkers(doc: Document, sel: {
+    from: number;
+    to: number;
+}, source?: string): Marker[];
+/**
+ * Index into `doc.children` of the top-level block whose inclusive `[from, to]`
+ * range contains `offset`, or -1 when the offset falls in a gap between blocks.
+ */
+declare function activeBlockIndex(doc: Document, offset: number): number;
+
+/**
+ * Heading-based folding.
+ *
+ * A heading folds away everything from the end of its line down to (but not
+ * including) the next heading of the same or higher level — the standard
+ * "collapse a section" affordance. Pure and offset-exact.
+ */
+
+/** A foldable region owned by a heading. `[from, to)` is the collapsible body. */
+interface FoldRange {
+    /** Offset where the owning heading starts (its `#`). */
+    headingFrom: number;
+    /** The heading's level (1–6). */
+    level: number;
+    /** Start of the collapsible body — the end of the heading line. */
+    from: number;
+    /** End of the collapsible body — the next same-or-higher heading, or doc end. */
+    to: number;
+}
+/**
+ * One `FoldRange` per top-level heading: `from` is the heading node's `to` (end
+ * of the heading line), `to` is the `from` of the next heading whose level is
+ * `<=` this heading's level (or the document's `to` if there is none). Ranges
+ * with an empty body (`to <= from`) are omitted.
+ */
+declare function headingFoldRanges(doc: Document): FoldRange[];
+
+/**
+ * Native, zero-dependency syntax highlighter.
+ *
+ * {@link highlightToHtml} turns a fenced code block's source into an HTML
+ * string with tokens wrapped in `<span class="tw-tok-KIND">…</span>`. The
+ * tokenizers are small, hand-written, single-pass line/char scanners — NOT
+ * full grammars. They recognise the shapes that carry the most colour signal:
+ * keywords, strings (including template literals), line + block comments,
+ * numbers, punctuation, and a light dusting of function / type / property
+ * classification.
+ *
+ * Safety is the load-bearing invariant: **every** character that reaches the
+ * output — token content and the gaps between tokens alike — is HTML-escaped
+ * through the local {@link escapeHtml}. A `<script>` (or `<img onerror=…>`)
+ * embedded in the code therefore always appears inert/escaped, never as live
+ * markup. This mirrors the sanitizing contract of `render.ts` so the
+ * highlighter can be handed straight to the renderer without widening the
+ * attack surface.
+ *
+ * Complexity is O(n) in the source length. There are no unbounded-backtracking
+ * regexes; scanning advances the cursor monotonically, so pathological input
+ * (huge whitespace runs, unterminated strings/comments) is safe.
+ */
+/**
+ * Highlight `code` for the given fence `info` string.
+ *
+ * `info` is the WHOLE fence info (e.g. `"js {1,3}"` or `"ts title=foo"`); the
+ * language is the first whitespace-delimited token, lowercased, run through
+ * {@link ALIASES}. Unknown / empty / unsupported languages return the escaped
+ * source with no spans, so the output is always safe to inject.
+ *
+ * @param lang the fence info string (language + any attributes)
+ * @param code the raw code block source
+ * @returns HTML with `<span class="tw-tok-KIND">` tokens; fully HTML-escaped.
+ */
+declare function highlightToHtml(lang: string, code: string): string;
+
+/**
+ * Comment-anchor maintenance (plan-TW-0002 Phase A2).
+ *
+ * A comment thread is anchored to a text range `{from, to}`. Every time the
+ * document is edited we must move that range so the highlight keeps covering
+ * the same words — or drop the anchor (return `null`) when the words it pointed
+ * at have been deleted. This is the first real consumer of `TextDoc.mapOffset`
+ * (previously dead code) — it is built directly on top of that primitive rather
+ * than re-deriving the position math here.
+ */
+
+/**
+ * Re-anchor a comment range across a single document `change`.
+ *
+ * @returns the mapped `{from, to}` (always `from <= to`), or `null` when the
+ * change deleted the entire anchored range.
+ */
+declare function mapAnchor(anchor: {
+    from: number;
+    to: number;
+}, change: Change): {
+    from: number;
+    to: number;
+} | null;
+
+/**
+ * Pure table-editing helpers (Phase F1 of plan-TW-0002).
+ *
+ * These are the headless layer under the in-place table grid: no DOM, no React,
+ * just string → string transforms over the offset-exact {@link Table} AST that
+ * `./parser` produces. Every mutation keeps the Markdown *canonical* — a GFM
+ * pipe table with a delimiter row — so `parse → mutate → parse` round-trips to
+ * the same structure.
+ *
+ * Two edit shapes, matching the plan:
+ *  - **Single-cell** edits are scoped: {@link cellSourceRange} hands back a
+ *    cell's *exact* source range so the caller can splice only that slice.
+ *  - **Structural** ops (add/remove row/column, set alignment) re-serialize the
+ *    whole table block and return a full-block splice over `[table.from, table.to]`.
+ *
+ * Addressing convention (documented once, used everywhere):
+ *  - Rows use a **grid index**: row `0` is the header, rows `1..N` are body rows
+ *    (this mirrors the rendered grid, where the header is the top row).
+ *  - Columns are 0-based.
+ *
+ * The AST contract these helpers lean on (see `src/core/ast.ts:144-156`):
+ *   - `TableCell extends Pos` — every cell carries exact `{from,to}` UTF-16
+ *     offsets of its *trimmed* content (`splitRow`, `parser.ts:447-459`).
+ *   - `Table { from; to; align: CellAlign[]; header: TableCell[]; rows: TableCell[][] }`.
+ *   The delimiter row has no node of its own, so alignment edits (like every
+ *   structural op) re-serialize the block rather than splicing that row in place.
+ */
+
+/** Result of a structural (whole-block) table edit. */
+interface TableEdit {
+    /** The full new document text after the splice. */
+    text: string;
+    /** A sensible caret offset into {@link text} after the edit. */
+    selection: number;
+}
+/**
+ * Exact source range of a single cell's (trimmed) text, for scoped single-cell
+ * splices. Row `0` is the header; rows `1..N` are body rows. Returns `null` when
+ * the coordinate is out of bounds.
+ */
+declare function cellSourceRange(table: Table, row: number, col: number): Pos | null;
+/**
+ * Insert a new empty body row so it lands at grid position `atRow`
+ * (clamped into the body range). Re-serializes the whole block.
+ */
+declare function addRow(text: string, table: Table, atRow: number): TableEdit;
+/**
+ * Insert a new empty column at index `atCol` (clamped), widening the header,
+ * the alignment row, and every body row. Re-serializes the whole block.
+ */
+declare function addColumn(text: string, table: Table, atCol: number): TableEdit;
+/**
+ * Remove the body row at grid position `atRow` (row `0`, the header, and
+ * out-of-range indices are no-ops). Re-serializes the whole block.
+ */
+declare function removeRow(text: string, table: Table, atRow: number): TableEdit;
+/**
+ * Remove the column at index `atCol` from the header, alignment row, and every
+ * body row. The last remaining column is never removed (a GFM table needs ≥1
+ * column), and out-of-range indices are no-ops. Re-serializes the whole block.
+ */
+declare function removeColumn(text: string, table: Table, atCol: number): TableEdit;
+/**
+ * Set column `col`'s alignment and rewrite the delimiter row (via a canonical
+ * re-serialization of the whole block). Out-of-range `col` is a no-op.
+ */
+declare function setAlignment(text: string, table: Table, col: number, align: CellAlign): TableEdit;
+
+/**
+ * `typewright/core` — the headless, framework-agnostic engine.
+ *
+ * Status: PRE-ALPHA SCAFFOLD. The from-scratch document model, incremental
+ * block-structured parser, and virtualized DOM view described in SPEC.md are
+ * not yet implemented. This module defines the public surface those internals
+ * will fulfil so integrators can build against a stable contract.
+ */
+
+interface EditorViewOptions extends EditorConfig, EditorEvents {
+    /** Element the editor mounts into. */
+    parent: HTMLElement;
+}
+/**
+ * PRE-ALPHA SCAFFOLD — not yet implemented. Constructing an `EditorView`
+ * throws: the stateful mounted engine (document string, incremental parse tree,
+ * decoration set, virtualized viewport) described in SPEC.md is still to come.
+ * This class only reserves the eventual public surface.
+ *
+ * To edit or render Markdown today, use the functional headless API exported
+ * from this module — {@link parse}, {@link parseIncremental}, {@link renderToHtml} —
+ * or the React `TypewrightEditor` component in `typewright`.
+ */
+declare class EditorView {
+    readonly dom: HTMLElement;
+    constructor(options: EditorViewOptions);
+    /** Current document string. */
+    get doc(): string;
+    /** Apply an edit. */
+    dispatch(_change: DocChange): void;
+    setSelection(_selection: DocSelection): void;
+    destroy(): void;
+}
+
+export { Block, CellAlign, type Change, DocChange, DocSelection, Document, EditorConfig, EditorEvents, EditorView, type EditorViewOptions, type FoldRange, Inline, type LineInfo, type Marker, ParseOptions, Pos, type Position, type RenderOptions, Table, type TableEdit, TextDoc, activeBlockIndex, addColumn, addRow, cellSourceRange, collectMarkers, headingFoldRanges, hiddenMarkers, highlightToHtml, mapAnchor, parse, parseIncremental, removeColumn, removeRow, renderInline, renderNode, renderToHtml, safeUrl, setAlignment };

package/dist/core/index.js

@@ -0,0 +1,4 @@
+export { COMMANDS, EditorView, TextDoc, activeBlockIndex, addColumn, addRow, applyCommand, cellSourceRange, collectMarkers, headingFoldRanges, hiddenMarkers, highlightToHtml, mapAnchor, removeColumn, removeRow, setAlignment } from '../chunk-CZQO7TTL.js';
+export { childrenOf, isInline, parse, parseIncremental, renderInline, renderNode, renderToHtml, safeUrl, walk } from '../chunk-M6IVEMXO.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}