@vectojs/markdown 0.13.0 → 0.15.0

package/README.md

@@ -4,12 +4,11 @@ Canvas-native Markdown (with TeX math) rendering for [VectoJS](https://github.co
 
 `Markdown` is a high-level entity that parses Markdown with
 [`marked`](https://marked.js.org/), renders TeX math to SVG with
-[MathJax](https://www.mathjax.org/), and lays the result out using
-`@vectojs/ui` components (`RichText`, `Stack`, `Table`, `Text`, `Image`). It also
-exports `CodeBlock`.
+`@vectojs/tex`, and lays the result out using `@vectojs/ui` components
+(`RichText`, `Stack`, `Table`, `Text`, `Image`). It also exports `CodeBlock`.
 
 This package was split out of `@vectojs/ui` so that the heavy `marked` +
-`mathjax-full` dependencies are only pulled in by apps that actually render
+`@vectojs/tex` dependencies are only pulled in by apps that actually render
 Markdown. Because it depends on `@vectojs/ui` components, it sits **above** `ui`
 in the dependency graph — install it alongside `@vectojs/ui` and `@vectojs/core`.
 
@@ -135,26 +134,32 @@ converted once no matter how many documents or instances render it.
 Inline `$...$` math is a separate path: it is currently shown as styled source
 text, not typeset.
 
-#### MathJax is loaded on demand
+#### The math engine is loaded on demand
 
-MathJax is imported dynamically, the first time a document actually has a formula
-to typeset. It is by far the heaviest thing this package can pull in — measured
-against a browser bundle of a consumer that renders only prose:
+TeX math is typeset by `@vectojs/tex`, which is imported dynamically the first
+time a document actually has a formula. It is by far the heaviest thing this
+package can pull in — measured against a browser bundle of a consumer that renders
+only prose, built with code splitting and minification:
 
-| prose-only consumer       |       raw |    gzip |
-| ------------------------- | --------: | ------: |
-| eagerly imported (before) | 2,157,295 | 725,012 |
-| lazily imported (now)     |   339,767 | 106,095 |
+| prose-only consumer    |       raw |    gzip | chunks |
+| ---------------------- | --------: | ------: | -----: |
+| `mathjax-full`         | 2,199,869 | 748,713 |     19 |
+| `@vectojs/tex` (now)   |   758,249 | 273,754 |      3 |
+| no math at all (floor) |   379,224 | 118,670 |      3 |
 
-That is 85% of the bundle a document with no formulas used to carry, plus roughly
-150 ms of module evaluation at startup. Your bundler needs code splitting enabled
-to see this; without it the bytes are still in the output, just not evaluated
-until first use.
+Against that floor the math path itself is 630,043 gzip under `mathjax-full` and
+155,033 under `@vectojs/tex` — **4.06x smaller**. The eagerly-downloaded entry
+chunk a prose-only consumer actually pays for is 117,889 gzip, within 1 KB of the
+no-math floor.
+
+Your bundler needs code splitting enabled to see this; without it the bytes are
+still in the output, just not evaluated until first use.
 
 The tradeoff is that **the first formula on a page cannot be typeset
 synchronously.** It renders as a code block of TeX source — the same state an
 unclosed fence already shows — and is replaced once the module resolves. Every
-formula after that is synchronous again.
+formula after that is synchronous again. (The engine itself is synchronous; the
+lazy import is what defers it, and it is kept for the bundle size above.)
 
 While streaming this is invisible: the load starts as soon as an _opening_ math
 fence appears, several chunks before the closing one, so the formula is typeset on
@@ -176,6 +181,63 @@ from several places starts one load. `isMathJaxReady()` reports whether formulas
 currently typeset without waiting. If the load fails, formulas keep rendering as
 TeX source rather than throwing.
 
+Both names are historical: they date from when `mathjax-full` was the engine and
+mean "the math engine", whichever one that is. They keep those names because they
+are public API and a rename would break every consumer for cosmetics.
+
+A formula containing a symbol outside the engine's shipped glyph corpus also
+renders as TeX source rather than being drawn with that symbol missing.
+
+## Images
+
+An image renders in one of two ways, decided by where it is written.
+
+**On its own, or in a paragraph, blockquote or list item**, the paragraph splits
+into blocks and the image becomes an `Image` entity at its natural size, capped
+to the available width. This is the ordinary `![alt](url)` case.
+
+**On a line it shares with text** — in a heading, or in a table cell — it renders
+as an inline box in the text run, so the prose flows around it and selection and
+the accessible name still work. Its height is a multiple of the run's font size
+(`theme.inlineImageScale`, default `1.15`) and its width follows the image's
+natural aspect ratio, so a badge stays wide and a square icon stays square:
+
+```ts
+const md = new Markdown("# Build ![passing](https://img.example/badge.svg)");
+```
+
+This is a deliberate departure from HTML, which would render an inline image at
+its intrinsic size. A 512px logo written into an `h1` would otherwise tower over
+its own heading, and an inline box has to be sized before the image has decoded.
+The height is fixed up front for the same reason: the line box never moves, and
+only the width settles once the aspect ratio is known.
+
+The `alt` text is the accessible name and the copied text — never painted as
+visible prose. If the image fails to load, the box is replaced by the alt text
+rather than left as an invisible gap.
+
+## Syntax coverage
+
+Everything in [CommonMark](https://spec.commonmark.org/) plus the
+[GFM](https://github.github.com/gfm/) extensions this renderer draws: tables,
+strikethrough, task lists, autolinks, plus `$…$` / `$$…$$` TeX math and
+` ```math ` fences.
+
+Two constructs are deliberately **not** supported, and both are pinned by tests
+so the behaviour cannot drift silently:
+
+- **Definition lists.** `Term` then `: definition` renders as the two literal
+  lines the source contains, colon included.
+- **Raw HTML blocks.** `<details>`, `<div>`, `<iframe>` and HTML comments render
+  nothing at all.
+
+Definition lists are neither CommonMark nor GFM; when they arrive it will be
+through the same syntax-extension mechanism footnotes need. Raw HTML blocks
+cannot work in a zero-DOM renderer — there is no DOM to hand markup to. `<svg>`
+is the one exception, because a self-contained SVG document can be rasterized.
+
+Footnotes (`[^1]`) are **not yet parsed** and currently render as literal source.
+
 > Migrating from `@vectojs/ui` ≤ 1.x? `Markdown` and `CodeBlock` used to be
 > exported from `@vectojs/ui`. As of `@vectojs/ui@2.0.0` they live here — change
 > `import { Markdown } from '@vectojs/ui'` to `from '@vectojs/markdown'`.

package/dist/Markdown.d.ts

@@ -1,167 +1,47 @@
-import { type ContentProjectionHint, Entity, type DevtoolsDescriptor, GlyphRasterAtlas, type GlyphRasterAtlasStats, IRenderer, type ContentProjection } from '@vectojs/core';
+import { Entity, type DevtoolsDescriptor, IRenderer } from '@vectojs/core';
 import { type Token } from 'marked';
 import { type StreamController, type StreamControllerOptions } from './StreamController';
+export { isMathJaxReady, MathBlock, preloadMathJax } from './markdown-math';
+export { CodeBlock, codeAtlas, codeAtlasStats } from './markdown-code';
+import { type MarkdownTheme } from './theme';
+export type { MarkdownTheme } from './theme';
 import { Stack, UIComponent } from '@vectojs/ui';
-export declare function preloadMathJax(): Promise<void>;
-/** Whether formulas can be typeset without waiting. Exposed for tests. */
-export declare function isMathJaxReady(): boolean;
-/** Color and typography theme for Markdown rendering. */
-export interface MarkdownTheme {
-    /** Body text color. */
-    textColor?: string;
-    /** Heading text color. */
-    headingColor?: string;
-    /** Code text color (inline + block). */
-    codeColor?: string;
-    /** Code block background color. */
-    codeBgColor?: string;
-    /** Blockquote border/accent color. */
-    quoteBorderColor?: string;
-    /** Blockquote text color. */
-    quoteTextColor?: string;
-    /** Horizontal-rule color. */
-    hrColor?: string;
-    /** Table background color. */
-    tableBgColor?: string;
-    /** Table header background color. */
-    tableHeaderBgColor?: string;
-    /** Body font. */
-    bodyFont?: string;
-    /** Monospace font for code. */
-    codeFont?: string;
-    /** Base font size in px. */
-    fontSize?: number;
-}
-/** A simple concrete container entity for nested layouts. */
-declare class MarkdownContainer extends Entity {
-    isPointInside(_globalX: number, _globalY: number): boolean;
-    render(_r: any): void;
-}
-/**
- * One display formula: a `$$..$$` block or a closed ```` ```math ```` fence.
- *
- * A named class rather than a bare {@link MarkdownContainer} because the formula
- * needs a stable handle, and after the switch to an inline object it has none:
- * the typeset raster lives in a `paint` closure captured by the span, so removing
- * the `Image` entity left nothing exposing either the source or the SVG bytes.
- * Devtools, tests, and anything auditing what a formula actually rendered all
- * want that. `markstream-vue` reaches the same conclusion from the DOM side and
- * publishes `data-markstream-mode` on its math node for the same reason.
- *
- * Deliberately carries no typeset-vs-source flag. A formula MathJax has not
- * converted yet renders as a bare {@link CodeBlock} of its TeX, which this class
- * does not wrap — wrapping it would put a container between `content` and a
- * `CodeBlock` that the streamed `setCode` path locates by type. So a flag would
- * have exactly one reachable value, which is the dead-API trap that cost CTX-0208
- * a debugging pass. Add it together with wrapping the fallback, or not at all.
- */
-export declare class MathBlock extends MarkdownContainer {
+export interface MarkdownOptions {
+    maxWidth?: number;
+    theme?: MarkdownTheme;
+    onLinkClick?: (url: string) => void;
+    /** Allow browser-native drag selection and copy for rendered text. Default `true`. */
+    selectable?: boolean;
+    /** Emit a `vecto:markdown:parse` User Timing measure. Default `false`. */
+    userTiming?: boolean;
     /**
-     * The TeX source, exactly as written between the delimiters.
+     * Draw copy / download controls in the top-right corner of code blocks and
+     * tables. Default `false`.
      *
-     * Also the projected text and the accessible name, so this is the one string a
-     * reader can find, select, and copy.
+     * Opt-in rather than on by default because it adds two focusable stops per such
+     * block to the tab order, which a document with many code fences would make
+     * tedious to navigate past, and because a reader who cannot act on a control
+     * (no clipboard permission, no filesystem) is better served by not being
+     * offered one.
      */
-    readonly formula: string;
-    /** The `data:image/svg+xml` URI of the typeset glyphs. */
-    readonly svgUri: string;
-    constructor(formula: string, svgUri: string);
-    getDevtoolsDescriptor(): DevtoolsDescriptor;
-}
-/**
- * A single self-rendering entity for fenced code blocks.
- *
- * Replaces the old N×M child-entity explosion (Container → Stack → Text per
- * segment per line) with a flat leaf that draws its own background + text.
- */
-export declare class CodeBlock extends UIComponent {
-    private lines;
-    private grid;
-    /** Raw (unhighlighted) lines of the last build, for prefix reuse in buildLines. */
-    private rawLines;
-    private cellWidth;
-    private source;
-    /** Bumped by {@link buildLines} and {@link setSelectable}; read by `Scene`. */
-    private contentEpoch;
-    private lang;
-    private theme;
-    private lineH;
-    private pad;
-    private codeFont;
-    selectable: boolean;
-    constructor(code: string, lang: string, maxWidth: number, theme: Required<MarkdownTheme>, selectable?: boolean);
-    /** Re-parse code content (e.g. for live editing). */
-    setCode(code: string, lang?: string): this;
-    /** Enable or disable browser-native selection for this code block. */
-    setSelectable(selectable: boolean): this;
-    getContentEpoch(): number;
+    blockAffordances?: boolean;
     /**
-     * Change the block's box width.
+     * Writes text to the clipboard for the copy controls.
      *
-     * Deliberately does **not** rebuild the grid or the highlight, because code does
-     * not reflow: lines are placed on a fixed monospace grid at `col × cellWidth` and
-     * a long line overflows rather than wrapping, so `height` is a function of line
-     * *count* alone. The width only sizes the rounded background. Anything that would
-     * change the glyph geometry — the source, the language, the font — goes through
-     * {@link setCode} and invalidates the grid there.
-     *
-     * @returns `this` for chaining.
+     * Injectable because the real path (`navigator.clipboard.writeText`) is absent
+     * in jsdom and, in a browser, rejects a write that did not originate in a user
+     * gesture — so a test can only assert the payload, never the platform call.
+     * Defaults to `navigator.clipboard.writeText` when available.
      */
-    setWidth(width: number): this;
-    getContentProjection(hint?: ContentProjectionHint): ContentProjection | null;
+    writeClipboard?: (text: string) => void;
     /**
-     * Re-highlight the code, reusing the highlight of any unchanged line prefix.
+     * Saves a generated file for the download controls.
      *
-     * Streaming appends to the END of a block, so all but the last line or two are
-     * byte-identical to the previous call — yet this used to re-highlight every
-     * line on every chunk, making a streamed block O(N) per append and O(N^2)
-     * overall. Reusing the stable prefix makes an append proportional to what
-     * actually changed.
-     *
-     * The last previously-seen line is deliberately NOT reused: a chunk usually
-     * lands mid-line, so that line's text (and therefore its tokenization) changes.
+     * Defaults to an anchor-click download that revokes its object URL. Injectable
+     * for the same reason as {@link MarkdownOptions.writeClipboard}: jsdom has no
+     * download behaviour to observe.
      */
-    private buildLines;
-    private ensureGrid;
-    /** Code blocks are decorative — not interactive. */
-    isPointInside(): boolean;
-    render(r: IRenderer): void;
-}
-/**
- * Instrumentation for the code-block glyph atlas in use, or `null` before first
- * use.
- *
- * Exposed so an app or benchmark can confirm the atlas is actually active and
- * reusing slots. Watch `resets`: a steadily climbing count means the glyph set is
- * unbounded for the atlas size, so every reset re-rasterizes everything and the
- * atlas is doing net harm rather than saving work.
- *
- * Reports the *most recently used* atlas, which after a zoom is the one now being
- * blitted — see {@link codeAtlas}.
- */
-export declare function codeAtlasStats(): GlyphRasterAtlasStats | null;
-/**
- * The code-block atlas most recently blitted from, or `null` before first use.
- *
- * For instrumentation that must map a traced `drawImage` back to the glyph it
- * painted — a blit carries only a source rect, so `slotAt()` is the only way to
- * recover the cluster and its metrics. Used by `e2e/text-projection.e2e.ts` to
- * keep the code-grid positioning assertions working on the blit path.
- *
- * "Most recently used" rather than "the one" because atlases are pooled per DPR:
- * a caller resolving a traced blit wants the atlas that produced it, which is the
- * one the last render selected. Compare its {@link GlyphRasterAtlas.pixelRatio}
- * against {@link IRenderer.pixelRatio} to assert the blit is 1:1.
- */
-export declare function codeAtlas(): GlyphRasterAtlas | null;
-export interface MarkdownOptions {
-    maxWidth?: number;
-    theme?: MarkdownTheme;
-    onLinkClick?: (url: string) => void;
-    /** Allow browser-native drag selection and copy for rendered text. Default `true`. */
-    selectable?: boolean;
-    /** Emit a `vecto:markdown:parse` User Timing measure. Default `false`. */
-    userTiming?: boolean;
+    saveFile?: (filename: string, content: string, mimeType: string) => void;
 }
 /**
  * Renders Markdown content into a VectoJS entity tree using {@link marked}.
@@ -185,6 +65,18 @@ export declare class Markdown extends UIComponent {
     theme: Required<MarkdownTheme>;
     onLinkClick?: (url: string) => void;
     selectable: boolean;
+    /**
+     * Whether code blocks and tables carry copy / download controls.
+     *
+     * Read when a block entity is built, so it affects blocks rendered from here on
+     * rather than retroactively; a document does not rebuild to gain or lose an
+     * affordance.
+     */
+    blockAffordances: boolean;
+    /** Clipboard writer used by the copy controls. */
+    writeClipboard: (text: string) => void;
+    /** File saver used by the download controls. */
+    saveFile: (filename: string, content: string, mimeType: string) => void;
     private activeBlockMetrics;
     /**
      * Called after a streamed append has re-laid-out the document.
@@ -260,6 +152,20 @@ export declare class Markdown extends UIComponent {
      * field only so {@link destroy} can remove the exact closure it added.
      */
     private inlineMathRepaint?;
+    /**
+     * This instance's entry in the inline-image decode waiters, or `undefined` if it
+     * has never rendered an image. Held as a field only so {@link destroy} can remove
+     * the exact closure it added.
+     */
+    private inlineImageRemeasure?;
+    /**
+     * URLs whose decoded aspect ratio this document has already reserved a box for.
+     *
+     * The guard that makes the re-measure fire once per image rather than once per
+     * decode-notification-per-image: the waiter set is module-level, so a page of
+     * many documents tells all of them about all decodes.
+     */
+    private readonly inlineImagesMeasured;
     /**
      * True while this document is waiting on the lazy MathJax load.
      *
@@ -447,6 +353,45 @@ export declare class Markdown extends UIComponent {
      * one closure per instance.
      */
     private subscribeInlineMathRepaint;
+    /**
+     * Re-measure this document when an inline image's raster finishes decoding.
+     *
+     * Inline images differ from inline formulas in one way that matters: a formula's
+     * box is known synchronously the moment it typesets, while an image's aspect
+     * ratio arrives only with the decode. The span reserved a square until then, so a
+     * decode that reports anything else has invalidated a WIDTH, and a repaint into
+     * the old box would letterbox or stretch the picture.
+     *
+     * So this rebuilds through {@link retypesetFromTokens} — the same late-arrival
+     * path MathJax uses — but only when a reserved width actually changed. Every live
+     * document is notified for every decode, including images it does not contain, so
+     * an unconditional rebuild here would be O(documents x images) full re-renders
+     * for a page of many blocks.
+     *
+     * Subscribed lazily and held as a field for the same two reasons as its math
+     * counterpart: a document with no images costs nothing, and `destroy` must remove
+     * the exact closure it added.
+     */
+    private subscribeInlineImageRemeasure;
+    /**
+     * Whether any inline image in this document has just learned it is not square.
+     *
+     * An inline image's span reserves a square box before its raster decodes, because
+     * that is the only shape available without a natural size. The decode supplies the
+     * real aspect ratio, so a non-square image needs one rebuild to reserve the right
+     * width — and exactly one. Every live document is notified of every decode on the
+     * page, including images it does not contain, so this has to answer "did MY
+     * geometry just change" and not merely "did something decode".
+     *
+     * Walks the tokens rather than the entity tree: the reserved box is a function of
+     * the raster's aspect ratio, which is available here, and a token walk cannot be
+     * confused by an entity a previous rebuild already corrected.
+     *
+     * Only headings and table cells are inspected. Every other context splits an image
+     * into its own block whose `Image` entity resizes itself in `onLoad`, so a rebuild
+     * for one of those would be pure cost.
+     */
+    private inlineImageBoxesStale;
     destroy(): void;
     /**
      * Streaming and parse state — the markdown streaming inspector.
@@ -578,6 +523,28 @@ export declare class Markdown extends UIComponent {
      * policy for a zero-dimension source is a separate decision from notifying
      * the scene, which is the actual defect here.
      */
+    /**
+     * Wraps a block in its copy / download controls, or returns it untouched.
+     *
+     * The controls are built lazily through `make` so a document with
+     * `blockAffordances` off pays nothing — not the closures, not the measurement
+     * `BlockAffordanceButton` does in its constructor.
+     */
+    private withBlockAffordances;
+    /** Copy and download controls for one fenced code block. */
+    private codeBlockAffordances;
+    /** Copy (as Markdown) and download (as CSV) controls for one table. */
+    private tableAffordances;
+    /**
+     * Button styling for the affordances, derived from the document theme.
+     *
+     * Themed rather than hardcoded so a light-theme document does not get the dark
+     * default palette. `focusColor` is set explicitly from the theme's accent
+     * because `Button`'s default cyan is tuned for the dark palette and reads as
+     * off-brand elsewhere — while a focus ring is the one affordance a keyboard
+     * user cannot do without.
+     */
+    private affordanceButtonOptions;
     private paragraphImage;
     /** One table cell entity, shared by the render arm and the streamed-table path. */
     private tableCellRichText;
@@ -887,4 +854,3 @@ export declare class Markdown extends UIComponent {
     /** Structural — children draw themselves. */
     render(_r: IRenderer): void;
 }
-export {};

package/dist/blockAffordances.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Take-away affordances for block content: copy to the clipboard, download as a
+ * file.
+ *
+ * Split out of `Markdown.ts` rather than added to it because none of this is
+ * parsing or rendering — it is serialization plus two platform primitives — and
+ * that file is already 4.8k lines.
+ *
+ * The reference implementation is `streamdown` (clone `e5deed3`,
+ * `packages/streamdown/lib/`), read and recorded in
+ * `vectojs-docs/forge/findings/upstream/README.md`. Two details of its `save()`
+ * (`lib/utils.ts:35`) are borrowed deliberately: revoking the object URL, and the
+ * UTF-8 BOM for CSV. Both are commonly omitted and each is a real defect when
+ * missing — the first leaks a blob for the document's lifetime, the second makes
+ * Excel on Windows read the file in the system ANSI codepage and corrupt every
+ * non-ASCII cell.
+ */
+import type { A11yAttributes, Entity, LayoutControlledProperty } from '@vectojs/core';
+import { Button, type ButtonOptions, UIComponent } from '@vectojs/ui';
+/** Extension for a fence info string, without the dot. `txt` when unrecognised. */
+export declare function extensionForLanguage(lang: string): string;
+/** MIME type for a downloaded code block. */
+export declare function mimeForLanguage(lang: string): string;
+/**
+ * Escapes one CSV field per RFC 4180.
+ *
+ * A field containing a comma, a quote or a newline is wrapped in quotes, and an
+ * internal quote is doubled. Anything else is returned unchanged, so the common
+ * case allocates nothing.
+ */
+export declare function escapeCsvField(value: string): string;
+/**
+ * Escapes one Markdown table cell.
+ *
+ * Backslash first, then pipe: doing it the other way escapes the backslash that
+ * the pipe escape just introduced, which is why `streamdown` documents the order
+ * at `lib/table/utils.ts:137`.
+ */
+export declare function escapeMarkdownTableCell(cell: string): string;
+/** Column alignment as `marked` reports it on a table token. */
+export type TableAlign = 'left' | 'center' | 'right' | null;
+/** Plain-text table content, extracted from the token before entities are built. */
+export interface TableContent {
+    headers: string[];
+    rows: string[][];
+    align: readonly TableAlign[];
+}
+/**
+ * Serializes a table as CSV, prefixed with a UTF-8 BOM.
+ *
+ * Rows are `\r\n`-separated per RFC 4180.
+ *
+ * The BOM lives here rather than in {@link defaultSaveFile} — where `streamdown`
+ * puts it — so that the guarantee survives a caller supplying its own
+ * `saveFile`. Excel on Windows reads a BOM-less file in the system ANSI codepage
+ * and corrupts every non-ASCII cell, and that would be a silent,
+ * locale-dependent defect for anyone who replaced only the platform primitive.
+ * A property of the CSV belongs to the CSV.
+ */
+export declare function tableToCsv(table: TableContent): string;
+/**
+ * Serializes a table back to GitHub-flavoured Markdown.
+ *
+ * The alignment row is reproduced from the token's own `align`, so a copied table
+ * re-lexes to the same alignment rather than silently becoming left-aligned.
+ */
+export declare function tableToMarkdown(table: TableContent): string;
+/** Writes text to the clipboard, where the platform offers one. */
+export declare function defaultWriteClipboard(text: string): void;
+/**
+ * Downloads generated content as a file.
+ *
+ * Mirrors `streamdown`'s `save()` in revoking the object URL once the click has
+ * been dispatched. The other borrowed detail, the UTF-8 BOM for CSV, lives in
+ * {@link tableToCsv} instead — see there for why.
+ */
+export declare function defaultSaveFile(filename: string, content: string, mimeType: string): void;
+/**
+ * A copy or download control drawn in a block's top-right corner.
+ *
+ * Extends `@vectojs/ui`'s `Button` rather than hand-rolling an a11y hotspot: that
+ * class already projects `tag: 'button'` with a label, drives its focus ring from
+ * real DOM focus/blur, and handles hover and the disabled state. The repo rule
+ * against reimplementing what a `@vectojs/*` package provides applies to
+ * affordances too, and a bespoke hotspot would have to re-earn focus-ring
+ * behaviour `Button` already has.
+ *
+ * What this adds is transient success feedback. The label changes to a
+ * confirmation for `FEEDBACK_MS` and then reverts, which is the only signal a copy
+ * gives — nothing else about the document changes, so without it a reader cannot
+ * tell a working control from a broken one.
+ */
+export declare class BlockAffordanceButton extends Button {
+    private readonly act;
+    /** How long the confirmation label stays up, in ms. */
+    static readonly FEEDBACK_MS = 1600;
+    private readonly restingLabel;
+    private readonly successLabel;
+    private feedbackTimer;
+    constructor(label: string, successLabel: string, act: () => void, opts?: ButtonOptions);
+    /**
+     * Runs the action, then shows the confirmation.
+     *
+     * The action runs first and a throw propagates: a clipboard write the browser
+     * rejected must not be reported as a success.
+     */
+    private run;
+    private setTransientLabel;
+    /**
+     * The label a reader hears is the one they see, transient confirmation
+     * included, so an AT user gets the same feedback a sighted user does.
+     */
+    getA11yAttributes(): A11yAttributes;
+    /** Clears the pending revert so a destroyed block leaves no timer behind. */
+    destroy(): void;
+}
+/**
+ * Wraps one block and positions its affordances in the top-right corner.
+ *
+ * A wrapper is necessary rather than adding the buttons to the block directly,
+ * because both candidate parents already own their children's geometry: `Stack`
+ * positions each child in flow, and `Table` recomputes `x`/`y`/`width`/`height`
+ * for every child from its column widths (`Table.ts:66`). A button added to
+ * either would be moved on the next layout. This owns only its own children's
+ * placement and delegates its size to the block, so the surrounding document
+ * lays out exactly as it did before.
+ */
+export declare class BlockWithAffordances extends UIComponent {
+    readonly block: Entity;
+    private readonly controls;
+    /** Gap between the block's edges and the controls, in px. */
+    private static readonly INSET;
+    /** Gap between adjacent controls, in px. */
+    private static readonly GAP;
+    constructor(block: Entity, controls: readonly BlockAffordanceButton[]);
+    /**
+     * Places the controls right-aligned along the block's top edge.
+     *
+     * Laid out right-to-left from the block's right edge so the first control in
+     * the list ends up leftmost, which keeps DOM order (and therefore tab order and
+     * the a11y reading order) matching the visual order.
+     */
+    private layoutAffordances;
+    /**
+     * Re-places the controls after the block's own box changed.
+     *
+     * Called by the owner when a block is resized or its content grew; the controls
+     * are anchored to the right edge, so a width change moves them.
+     */
+    refreshAffordances(): void;
+    /** The wrapper is a pass-through: its size is the block's size. */
+    getLayoutControlledProperties(): ReadonlyArray<LayoutControlledProperty>;
+    /**
+     * Projected as a group so assistive technology reports one labelled region
+     * containing the block and its controls, rather than two unrelated siblings.
+     */
+    getA11yAttributes(): A11yAttributes;
+    render(): void;
+}
+/**
+ * Extracts plain-text table content from a `marked` table token.
+ *
+ * Reads the token rather than the built `Table` entity because the entity holds
+ * `RichText` children, not strings — reconstructing cell text from spans would
+ * have to reverse the inline formatting, and the token still has the source.
+ *
+ * `cell.text` is the cell's raw inline Markdown, which is what a copy should
+ * preserve: `**bold**` copied out of a table and pasted into another Markdown
+ * document should still be bold.
+ */
+export declare function tableContentOf(token: {
+    header: ReadonlyArray<{
+        text: string;
+    }>;
+    rows: ReadonlyArray<ReadonlyArray<{
+        text: string;
+    }>>;
+    align: readonly TableAlign[];
+}): TableContent;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './Markdown';
+export { BlockAffordanceButton, BlockWithAffordances, escapeCsvField, escapeMarkdownTableCell, extensionForLanguage, mimeForLanguage, tableContentOf, tableToCsv, tableToMarkdown, } from './blockAffordances';
+export type { TableAlign, TableContent } from './blockAffordances';
 export { parseFrontMatterFields, scanFrontMatter } from './frontMatter';
 export type { FrontMatterScan } from './frontMatter';
 export type { IncompleteMarkdownMode, StreamController, StreamControllerOptions, StreamControllerState, StreamPacingOptions, } from './StreamController';