@quillmark/svelte 0.2.0 → 0.3.0

package/README.md

@@ -149,7 +149,7 @@ The package ships English and a seam to replace it. `strings` is keyed and **par
 	{quill}
 	strings={{
 		cardDelete: 'Supprimer la carte',
-		addCardOfKind: (kind) => `Ajouter : ${kind}`
+		addCard: '+ Ajouter une carte'
 	}}
 	formatDiagnostic={(d) =>
 		d.code === 'validation::must_fill' ? `${d.path} est obligatoire` : undefined}
@@ -200,7 +200,7 @@ onPick: (at) => visualEditor.setCaret(at);
 onCaretMove: preview.focusPosition;
 ```
 
-A pick carries a caret where the compile tracks the content under the point, and the field alone where it tracks only the placement — a scalar the plate prints without tracking. `setCaret` takes both: an absent `pos` reveals and focuses the field, which is the whole of what a click on plate-placed ink can mean. The address may name an array ELEMENT (`main.references.0`), which lands on that row.
+A pick carries a caret where the compile tracks the content under the point, and the field alone where it tracks only the placement — a scalar the plate prints without tracking. `setCaret` takes both: an absent `pos` reveals and focuses the field, which is the whole of what a click on plate-placed ink can mean. The address may name an array element (`main.references.0`), which lands on that row.
 
 A consumer holding an `Addr` of its own maps it with `fieldPathForAddr` (from `@quillmark/svelte/core`). The playground app's split-pane route is the full reference shell: one session, both bridge directions, the preview following edits, and diagnostics routed inline.
 

package/THEMING.md

@@ -41,7 +41,9 @@ The whole contract is **ten CSS custom properties**. They are dials, not a palet
 
 ### Two of them are not branding
 
-`--qm-bg` and `--qm-fg` are the two a themed host sets before any brand decision. Their defaults are a self-consistent neutral for a bare mounting site, not a guess at your page: an app that paints its own plate and leaves them mounts one plate inside another. Two tones a few percent apart read as a fault rather than as a layer, so meet your page's tone exactly or stand far enough off it to be a layer.
+`--qm-bg` and `--qm-fg` are the two a themed host sets before any brand decision. Their defaults are a self-consistent neutral for a bare mounting site, not a guess at your page.
+
+`--qm-bg` is the **card**, not the column behind it: the plane a document is written on, which is also the sheet the preview paints. Everything else is a step off it, and the column the cards sit in is a step down, so a mounted editor draws its own ground and the cards read as islands on it. Give it the tone you want a card to be — white, in most light themes — and let the column fall out. If you want the column to meet your page instead, set a `background` of your own on `.qm-editor`; your CSS is unlayered and wins.
 
 The poles take a colour, not `transparent` or `inherit`: the raised surfaces, the borders and the muted inks are each a `color-mix` against `--qm-bg`, so a transparent pole makes every one of them translucent instead of letting your page through. Hand over the value your page is painted with and the derivation steps off it.
 
@@ -49,8 +51,8 @@ The poles take a colour, not `transparent` or `inherit`: the raised surfaces, th
 
 | Token            | Default                                | What it sets                                                                                                                                                   |
 | ---------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--qm-bg`        | `#fff` / `#14171c`                     | Base surface. Cards, fields, the painted page, the popover, and the column behind them step off it.                                                            |
-| `--qm-fg`        | `#1a1a1a` / `#e8eaed`                  | Base ink. Body text, labels, and borders step off it.                                                                                                          |
+| `--qm-bg`        | `#fff` / `#272729`                     | Base surface: a card, and the preview's sheet. Fields, the popover and the column behind the cards each step off it.                                           |
+| `--qm-fg`        | `#1c1c1c` / `#d7dadc`                  | Base ink. Body text, labels, and borders step off it.                                                                                                          |
 | `--qm-accent`    | `#2563eb`                              | Focus rings, active marks, the preview's active field box.                                                                                                     |
 | `--qm-danger`    | `#c5221f`                              | Error diagnostics, the required marker, the delete glyph.                                                                                                      |
 | `--qm-warning`   | `#b25000`                              | Warning diagnostics.                                                                                                                                           |
@@ -76,7 +78,9 @@ Declared before our sheet it fixes the order outright; declared after, `qm` is a
 
 ### The surface follows your colour scheme
 
-Surfaces step `bg → fg` and ink steps `fg → bg`, mixed in **oklab**, so inverting the two poles inverts the whole scale, including borders and the popover's translucent fill.
+Ink steps `fg → bg` and the borders and hover fills step `bg → fg`, mixed in **oklab**, so inverting the two poles inverts all of them together.
+
+**Planes are the exception**, and deliberately: the raised plane is the brighter one in both schemes, which is what makes a card read as a card rather than as a differently-tinted page. So the column under the cards sinks from `--qm-bg` toward shadow and a floating surface rises from it toward light, and neither reads the ink pole. Each direction takes a step sized to the scheme it is in, which is why pinning a dark palette while your `color-scheme` still says light leaves the column barely off its cards — the one case §"Make it yours" tells you to pin the scheme alongside the poles.
 
 Which way the poles default is **your `color-scheme`**, not the operating system's. Declare the scheme your app is in and the surface lands on it, along with native chrome, which reads the same property:
 
@@ -137,7 +141,7 @@ It carries a `--qmh-*` scale for the page, derived from the same ten dials and c
 
 ### The shell, if you are building a tool
 
-An app that mounts an editor beside a preview over one session needs a screen to put them in, and the SHAPE of that screen is the same every time. Five more classes are that shape, so what you write is the wiring rather than the grid:
+An app that mounts an editor beside a preview over one session needs a screen to put them in, and the shape of that screen is the same every time. Five more classes are that shape, so what you write is the wiring rather than the grid:
 
 ```html
 <div class="qm-workspace">
@@ -169,9 +173,9 @@ An app that mounts an editor beside a preview over one session needs a screen to
 | `.qm-switch`    | The band that says which track is showing, and nothing at the widths where both are. Its controls read as even halves and stand at the touch floor (`--qmh-tap`, 44px); depth past that is yours. |
 | `.qm-frame`     | The mounting site: an edge, a corner, and the clip that holds a surface to them. What is inside it is the surface's own.                                                                          |
 
-The narrow shape is one mount at a time, not two of them stacked: half a narrow viewport is under the width either surface reads at. The track you are not showing is `display: none`, so it leaves the tab order, hit-testing and the accessibility tree together: you need no `inert` on it, and no breakpoint in your JS, since the only state you hold is which of the two you last asked for. Keep both MOUNTED: the hidden pane keeps its pixels, its caret and its scroll, and repaints itself when it comes back. A click that lands in the hidden pane is the one thing the shape adds to your wiring, so send the caret and reveal the track together, or the hit goes somewhere the reader cannot see.
+The narrow shape is one mount at a time, not two of them stacked: half a narrow viewport is under the width either surface reads at. The track you are not showing is `display: none`, so it leaves the tab order, hit-testing and the accessibility tree together: you need no `inert` on it, and no breakpoint in your JS, since the only state you hold is which of the two you last asked for. Keep both mounted: the hidden pane keeps its pixels, its caret and its scroll, and repaints itself when it comes back. A click that lands in the hidden pane is the one thing the shape adds to your wiring, so send the caret and reveal the track together, or the hit goes somewhere the reader cannot see.
 
-The shape is shared; the LOOK of a band is not. Your wordmark, your nav and the depth of your head are the most app-specific things on the screen, and a preset that drew them would hand every tool built on this the same face, so they read `--qmh-*` like everything else and you write the rules. `.qm-split`'s gap is a default rather than a fact about splitting: close it to `0` and carry a hairline on one pane if you want the two mounts to meet instead of stand apart.
+The shape is shared; the look of a band is not. Your wordmark, your nav and the depth of your head are the most app-specific things on the screen, and a preset that drew them would hand every tool built on this the same face, so they read `--qmh-*` like everything else and you write the rules. `.qm-split`'s gap is a default rather than a fact about splitting: close it to `0` and carry a hairline on one pane if you want the two mounts to meet instead of stand apart.
 
 It is **unlayered**, so your own rules beat it by ordinary precedence, exactly as they beat the surfaces. It is also opt-in and side-effect free until imported: nothing that styles your document arrives with a component.
 

package/dist/core/address.d.ts

@@ -1,7 +1,7 @@
 import type { Addr, HitGranularity } from '@quillmark/wasm';
 /**
  * A canonical field address: `main.<field>` / `main.body` /
- * `cards.<kind>[<i>].<field>`, cards keyed by ABSOLUTE document index.
+ * `cards.<kind>[<i>].<field>`, cards keyed by absolute document index.
  *
  * The grammar `parseDocPath` / `formatDocPath` speak, and the one
  * `Diagnostic.path`, `ContentHit.field`, `FieldRegion.field` and
@@ -27,7 +27,7 @@ export interface Place {
  * Where a preview click landed. What the preview surfaces and what the editor's
  * `setCaret` takes.
  *
- * **An absent `pos` is the PLACEMENT rung**, not a caret at zero: the click resolved
+ * **An absent `pos` is the placement rung**, not a caret at zero: the click resolved
  * a field the plate places without tracking its content (`fieldAt` answers,
  * `positionAt` does not), so there is no offset and the landing is a focus. A `Place`
  * is a landing carrying its caret, and a `ContentHit` is one too.
@@ -43,7 +43,7 @@ export interface Landing {
 /**
  * A field's canonical `DocPath`, or `undefined` when `addr.card` is outside the live
  * `kinds` array (a stale address: drop it rather than mis-target). A field-less card
- * addresses its BODY, which is the leaf `{card: i}` names.
+ * addresses its body, which is the leaf `{card: i}` names.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
@@ -55,7 +55,7 @@ export interface Landing {
  */
 export declare function fieldPathForAddr(addr: Addr, kinds: readonly string[]): DocPath | undefined;
 /**
- * A CARD's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
+ * A card's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
  * where the change is the card rather than anything inside it. `undefined` for an
  * index outside `kinds`.
  */
@@ -72,7 +72,7 @@ export declare function cardPath(index: number, kinds: readonly string[]): DocPa
  */
 export declare function addrForFieldPath(path: DocPath): Addr | undefined;
 /**
- * An ARRAY ELEMENT's address, split. `main.references.0` and `main.references[0]`
+ * An array element's address, split. `main.references.0` and `main.references[0]`
  * both land here; anything {@link addrForFieldPath} can name, and anything whose
  * trailing segment is not an index, does not.
  *
@@ -80,11 +80,11 @@ export declare function addrForFieldPath(path: DocPath): Addr | undefined;
  * and `positionAt` emit `main.references.0`, which `parseDocPath` reads as a field
  * literally named `"0"`, while `formatDocPath` spells the index segment
  * `main.references[0]`. A trailing all-digits field name is therefore an index that
- * lost its brackets — but only under a field the SCHEMA declares an array, the
+ * lost its brackets — but only under a field the schema declares an array, the
  * caller's guard to apply: this module holds the grammar and no schema.
  */
 export declare function elementAddrForFieldPath(path: DocPath): ElementAddr | undefined;
-/** An array element's address: the ARRAY's `Addr`, and which element of it. */
+/** An array element's address: the array's `Addr`, and which element of it. */
 export interface ElementAddr {
     field: Addr;
     index: number;

package/dist/core/address.js

@@ -8,7 +8,7 @@ import { core } from './lifecycle.js';
 /**
  * A field's canonical `DocPath`, or `undefined` when `addr.card` is outside the live
  * `kinds` array (a stale address: drop it rather than mis-target). A field-less card
- * addresses its BODY, which is the leaf `{card: i}` names.
+ * addresses its body, which is the leaf `{card: i}` names.
  *
  * - `{}` → `"main.body"`
  * - `{field}` → `"main.<field>"`
@@ -26,7 +26,7 @@ export function fieldPathForAddr(addr, kinds) {
     return core().formatDocPath([head, tail]);
 }
 /**
- * A CARD's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
+ * A card's own path (`cards.<kind>[i]`), not a leaf's: what a structure op names,
  * where the change is the card rather than anything inside it. `undefined` for an
  * index outside `kinds`.
  */
@@ -49,7 +49,7 @@ export function addrForFieldPath(path) {
     return segs && addrForSegs(segs);
 }
 /**
- * An ARRAY ELEMENT's address, split. `main.references.0` and `main.references[0]`
+ * An array element's address, split. `main.references.0` and `main.references[0]`
  * both land here; anything {@link addrForFieldPath} can name, and anything whose
  * trailing segment is not an index, does not.
  *
@@ -57,7 +57,7 @@ export function addrForFieldPath(path) {
  * and `positionAt` emit `main.references.0`, which `parseDocPath` reads as a field
  * literally named `"0"`, while `formatDocPath` spells the index segment
  * `main.references[0]`. A trailing all-digits field name is therefore an index that
- * lost its brackets — but only under a field the SCHEMA declares an array, the
+ * lost its brackets — but only under a field the schema declares an array, the
  * caller's guard to apply: this module holds the grammar and no schema.
  */
 export function elementAddrForFieldPath(path) {
@@ -73,11 +73,11 @@ export function elementAddrForFieldPath(path) {
     if (index == null)
         return undefined;
     const field = addrForSegs(segs.slice(0, -1));
-    // A body has no elements: the parent must name a FIELD.
+    // A body has no elements: the parent must name a field.
     return field?.field != null ? { field, index } : undefined;
 }
 /** `parseDocPath`, with a malformed path as `undefined` rather than a throw. The gate
- *  is read OUTSIDE the try: an uninitialized core is not a malformed path, and would
+ *  is read outside the try: an uninitialized core is not a malformed path, and would
  *  otherwise leave here as one. */
 function segsOf(path) {
     const { parseDocPath } = core();

package/dist/core/bloom.d.ts

@@ -9,12 +9,12 @@ export interface BloomTiming {
 /**
  * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
  *
- * ONE property, both motion preferences: `--_qm-bloom-dwell` already shortens under
+ * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
  * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
- * the SHAPE: a hold and a cut carry no ramps, which is a frame list rather than a
+ * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
  * number and the one half CSS cannot hand over.
  *
- * Read ONCE PER BATCH, not per element: `getComputedStyle` forces a style recalc and
+ * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
  * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
  * each). The rungs inherit, so every element in a batch resolves the same numbers.
  */
@@ -27,10 +27,10 @@ export declare function bloomTiming(el: HTMLElement): BloomTiming;
  */
 export declare function bloom(el: HTMLElement, elapsed?: number, timing?: BloomTiming): Animation | undefined;
 /**
- * Bloom over `host`'s CONTENT: an inset child, so the wash neither tints the host's
+ * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
- * ONE wash node per host, reused while it lives: two quick landings on the same leaf
+ * One wash node per host, reused while it lives: two quick landings on the same leaf
  * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
  * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
  */

package/dist/core/bloom.js

@@ -1,12 +1,12 @@
 // The correlation bloom: a soft accent wash that rises over a target and decays to
-// nothing. The editor↔preview address is an EVENT, not a state: the preview claims
+// nothing. The editor↔preview address is an event, not a state: the preview claims
 // to be the rendered output, so it carries no resting ink, and a highlight that
 // outlives the hop that caused it is ink the document did not ask for. Both
 // directions land here: the preview's field boxes bloom themselves (they are already
 // empty rects over the page), an editor leaf blooms a transient child over its
 // surface.
 //
-// OPACITY is the animated property, never the colour. The wash's alpha is a peak
+// Opacity is the animated property, never the colour. The wash's alpha is a peak
 // fixed by `--_qm-accent-wash`, so interpolating 0→1→0 keeps the scale in CSS where
 // `color-mix` resolves, instead of in keyframe values a script would have to
 // pre-resolve and re-resolve on a theme change.
@@ -23,7 +23,7 @@ const WASH = 'var(--_qm-accent-wash)';
  *  absence of the scale, not a copy of it. */
 const FALLBACK_MS = 1100;
 // Rise fast, hold, then leave slowly: a highlighter's decay, not a linear fade. A
-// keyframe's easing governs the segment that STARTS at it. Under reduced motion the
+// keyframe's easing governs the segment that starts at it. Under reduced motion the
 // ramps are dropped entirely: the wash holds at full for a beat and cuts, which
 // still answers "here" with nothing to track.
 const FRAMES = [
@@ -40,12 +40,12 @@ export function primeWash(el) {
 /**
  * Resolve the timing off `el`, so the dwell is single-sourced in CSS.
  *
- * ONE property, both motion preferences: `--_qm-bloom-dwell` already shortens under
+ * One property, both motion preferences: `--_qm-bloom-dwell` already shortens under
  * `prefers-reduced-motion` in the derivation, so what is left to `matchMedia` here is
- * the SHAPE: a hold and a cut carry no ramps, which is a frame list rather than a
+ * the shape: a hold and a cut carry no ramps, which is a frame list rather than a
  * number and the one half CSS cannot hand over.
  *
- * Read ONCE PER BATCH, not per element: `getComputedStyle` forces a style recalc and
+ * Read once per batch, not per element: `getComputedStyle` forces a style recalc and
  * `animate` re-dirties style, so a read inside a loop flushes once per element (~0.15ms
  * each). The rungs inherit, so every element in a batch resolves the same numbers.
  */
@@ -74,10 +74,10 @@ export function bloom(el, elapsed = 0, timing) {
     return anim;
 }
 /**
- * Bloom over `host`'s CONTENT: an inset child, so the wash neither tints the host's
+ * Bloom over `host`'s content: an inset child, so the wash neither tints the host's
  * own background nor fades the text under it. `host` must be positioned.
  *
- * ONE wash node per host, reused while it lives: two quick landings on the same leaf
+ * One wash node per host, reused while it lives: two quick landings on the same leaf
  * must not stack two alphas over it. No `elapsed` seam: the surfaces that use this
  * (editor leaves) are not rebuilt under the animation the way the preview's boxes are.
  */

package/dist/core/codec/anchor.d.ts

@@ -8,7 +8,7 @@ export interface RangeAnchor {
 /**
  * A virtual anchor over one PM range, measured when asked rather than when made.
  *
- * The measure is TOTAL. `coordsAtPos` reads layout, and layout can be gone: a
+ * The measure is total. `coordsAtPos` reads layout, and layout can be gone: a
  * position the document has since invalidated, a leaf inside a collapsed section, a
  * view torn down between a scroll firing and the measure running. `autoUpdate` calls
  * this at moments none of its callers choose, so an unmeasurable anchor returns the

package/dist/core/codec/anchor.js

@@ -1,7 +1,7 @@
 /**
  * A virtual anchor over one PM range, measured when asked rather than when made.
  *
- * The measure is TOTAL. `coordsAtPos` reads layout, and layout can be gone: a
+ * The measure is total. `coordsAtPos` reads layout, and layout can be gone: a
  * position the document has since invalidated, a leaf inside a collapsed section, a
  * view torn down between a scroll firing and the measure running. `autoUpdate` calls
  * this at moments none of its callers choose, so an unmeasurable anchor returns the

package/dist/core/codec/atoms.d.ts

@@ -0,0 +1,10 @@
+import { type Command } from 'prosemirror-state';
+import type { Schema } from 'prosemirror-model';
+/**
+ * The block-atom bindings for a block-schema leaf: `{}` for the inline/plaintext
+ * schemas, which hold no block to be against.
+ *
+ * Both keys are the same command on opposite sides, because what a delete against an
+ * atom means does not depend on which side the caret approached from.
+ */
+export declare function atomKeymap(schema: Schema): Record<string, Command>;

package/dist/core/codec/atoms.js

@@ -0,0 +1,78 @@
+// The block-atom link of the body's Backspace/Delete chains: a delete against an
+// island or a divider selects it, and the press after that deletes it.
+//
+// This is the neighbour half of the rule the leaf already holds for a key typed over a
+// selection (CODEC §"The table island"): a selection is the subject of the next
+// command, never a thing armed for replacement. Without it the base keymap's
+// `joinBackward` / `joinForward` reach their "the neighbour is an atom, delete it" arm
+// and a table goes in one keystroke, from the paragraph a table insert parks the caret
+// in — with nothing drawn first to say what is about to go.
+//
+// It runs last of the links, after the list ones: a Backspace at the start of a list's
+// first item lifts the item, and that stays the item's answer whatever sits above the
+// list.
+import { NodeSelection, TextSelection } from 'prosemirror-state';
+/** The caret, when it sits at a textblock edge with an empty selection: the only place
+ *  a delete is about a neighbour rather than about a character. `null` everywhere else,
+ *  which is where the key keeps its ordinary meaning. */
+function atEdge(state, side) {
+    const { selection } = state;
+    if (!(selection instanceof TextSelection) || !selection.empty)
+        return null;
+    const $head = selection.$head;
+    const at = side < 0 ? 0 : $head.parent.content.size;
+    return $head.parentOffset === at ? $head : null;
+}
+/**
+ * The cut the caret's block sits against on `side`: the shallowest boundary with a
+ * sibling beyond it. `prosemirror-commands` walks the same one to find the node a join
+ * would reach; this reads it to find the node a delete would take.
+ */
+function cutAt($pos, side) {
+    if ($pos.parent.type.spec.isolating)
+        return null;
+    for (let d = $pos.depth - 1; d >= 0; d--) {
+        if (side < 0) {
+            if ($pos.index(d) > 0)
+                return $pos.doc.resolve($pos.before(d + 1));
+        }
+        else if ($pos.index(d) + 1 < $pos.node(d).childCount) {
+            return $pos.doc.resolve($pos.after(d + 1));
+        }
+        if ($pos.node(d).type.spec.isolating)
+            break;
+    }
+    return null;
+}
+/** Select the block atom the caret is against, rather than deleting it. Declines when
+ *  the neighbour is anything a caret can enter, so a paragraph, a heading, a quote and
+ *  a list all keep the join the base keymap gives them. */
+function selectAtom(side) {
+    return (state, dispatch) => {
+        const $head = atEdge(state, side);
+        const $cut = $head && cutAt($head, side);
+        if (!$cut)
+            return false;
+        const node = side < 0 ? $cut.nodeBefore : $cut.nodeAfter;
+        if (!node || !node.isAtom || !node.isBlock || !NodeSelection.isSelectable(node))
+            return false;
+        const at = side < 0 ? $cut.pos - node.nodeSize : $cut.pos;
+        dispatch?.(state.tr.setSelection(NodeSelection.create(state.doc, at)).scrollIntoView());
+        return true;
+    };
+}
+/**
+ * The block-atom bindings for a block-schema leaf: `{}` for the inline/plaintext
+ * schemas, which hold no block to be against.
+ *
+ * Both keys are the same command on opposite sides, because what a delete against an
+ * atom means does not depend on which side the caret approached from.
+ */
+export function atomKeymap(schema) {
+    if (!schema.nodes.island_block)
+        return {};
+    return {
+        Backspace: selectAtom(-1),
+        Delete: selectAtom(1)
+    };
+}

package/dist/core/codec/clipboard.d.ts

@@ -0,0 +1,59 @@
+import { DOMParser as PMDOMParser, Slice } from 'prosemirror-model';
+import type { Node as PMNode, Schema } from 'prosemirror-model';
+import { Plugin } from 'prosemirror-state';
+import type { TableCell, TableProps } from '@quillmark/wasm';
+import { type TableAlign } from './table.js';
+/** What a clipboard event hands over, which is all either arm needs of it: jsdom has no
+ *  `DataTransfer`, and the suite drives these paths with the two methods themselves. */
+interface Clipboard {
+    getData: (type: string) => string;
+    setData: (type: string, data: string) => void;
+}
+/**
+ * A `<table>` element as props. `rowspan` is not carried — a merged cell is not a
+ * rectangle, so a table with one arrives with the rows below it short and
+ * {@link normalizeTable} pads them at the end. `colspan` is, as the empty cells it
+ * covers, so the columns after it keep their index.
+ *
+ * Only the table's own rows: a `<tr>` inside a nested table belongs to a cell this
+ * reader is about to flatten, not to a rank of this one.
+ */
+export declare function tableFromDOM(dom: Element): TableProps;
+/** The table a paste is carrying, or `undefined` for a paste that holds none. The first
+ *  one: a clipboard holding a table among other blocks is a document paste, and only a
+ *  surface that takes nothing but a table (a cell) reads it this way. */
+export declare function tableFromClipboard(data: Clipboard | null | undefined): TableProps | undefined;
+/**
+ * A rectangle as a `<table>`: the wire the HTML arm writes and reads. Its first row is
+ * a `<th>` row whatever row of the source it came from, that being the row index 0 a
+ * paste lands it at.
+ */
+export declare function tableToDOM(block: TableCell[][], aligns: TableAlign[], owner: Document): Element;
+/**
+ * A rectangle as pipe rows, delimiter row included: what a plain-text target reads as a
+ * table and what markdown carries. The delimiter follows the first row for the reason
+ * that row serializes as `<th>` — a pasted rectangle's row 0 is a header.
+ */
+export declare function tableToPipe(block: TableCell[][], aligns: TableAlign[]): string;
+/** Put a rectangle on the clipboard, both arms. The caller is a `copy` / `cut` handler
+ *  over a selection its own surface holds, so the rectangle arrives already cut out and
+ *  claiming the event is the caller's. */
+export declare function writeRectangle(data: Clipboard, block: TableCell[][], aligns: TableAlign[], owner: Document): void;
+/** The clipboard's parser: the schema's own rules with the table rule ahead of them.
+ *  Ahead, because a `<table>` otherwise matches nothing and its cells' text falls
+ *  through to the enclosing block. */
+export declare function tableClipboardParser(schema: Schema): PMDOMParser;
+/** Mint an id for every island a paste is carrying. An id is part of the document's
+ *  canonical bytes and the channel that addresses an island (CODEC §Islands), so a
+ *  pasted island with none reaches the store as an insert nothing can name afterwards.
+ *  One minter for the whole slice, or a paste placing two tables hands them one id. */
+export declare function stampIslandIds(slice: Slice, doc: PMNode): Slice;
+/**
+ * The block leaf's clipboard plugin: the table rule on the way in, and the id mint over
+ * what it produced. A `clipboardParser` rather than the schema's own `parseDOM`,
+ * because what a `<table>` in the DOM means is a question only the clipboard asks — the
+ * schema's parse rules are also what a re-parse of the editor's own DOM runs through,
+ * where an island is already a node and a `<table>` is the chrome drawing one.
+ */
+export declare function tableClipboardPlugin(schema: Schema): Plugin;
+export {};

package/dist/core/codec/clipboard.js

@@ -0,0 +1,202 @@
+// The table island's clipboard door, both directions: what a copy writes, a paste
+// reads. The design and the two wire formats are CODEC §"The table island" and
+// §"Markdown at the edges"; what is here is the grammar.
+//
+// What crosses is A rectangle, never a cell. A `<table>` read in is one; the held cell
+// selection written out is one; a rectangle overlaid onto a table at a cell is one. The
+// wire therefore carries `TableCell[][]` and no coordinates: each end names its own
+// corner.
+//
+// A row 0 is A header, on both sides, which is the model's own rule (`table.ts`
+// §`allRows`): whichever row holds index 0 is the header. So a `<table>` with no `<th>`
+// promotes its first row, and a copied rectangle's first row is the header of what it
+// pastes.
+import { DOMParser as PMDOMParser, DOMSerializer, Fragment, Slice } from 'prosemirror-model';
+import { Plugin } from 'prosemirror-state';
+import { islandMinter } from './islands.js';
+import { inlineSchema } from './schema.js';
+import { ALIGNS, cellContent, cellFromDoc, emptyCell, normalizeTable } from './table.js';
+import { decode } from './decode.js';
+/** The two keys, spelled once: a reader and a writer that disagreed about which holds
+ *  the table would each work alone and never round-trip. */
+const HTML = 'text/html';
+const PLAIN = 'text/plain';
+// ── Reading a table in ──────────────────────────────────────────────────────
+/**
+ * One cell from its `<td>` / `<th>`. The inline schema is the whole normalization: it
+ * declares one paragraph, no containers and no islands, so a cell holding blocks
+ * flattens to its text and an image in one drops out rather than leaving a slot char
+ * behind. Whitespace collapses and the ends trim, which is PM's own parse.
+ */
+function cellFromDOM(dom) {
+    const para = PMDOMParser.fromSchema(inlineSchema).parse(dom, {
+        topNode: inlineSchema.nodes.paragraph.create()
+    });
+    return cellFromDoc(inlineSchema.nodes.doc.create(null, para), emptyCell());
+}
+/** A column's alignment off its header cell, which is where a pipe table's delimiter
+ *  row puts it. Anything else (`start`, `justify`, absent) is `none`. */
+function alignFromDOM(dom) {
+    const raw = (dom.getAttribute('align') ??
+        dom.style?.textAlign ??
+        '').toLowerCase();
+    return ALIGNS.includes(raw) ? raw : 'none';
+}
+/**
+ * A `<table>` element as props. `rowspan` is not carried — a merged cell is not a
+ * rectangle, so a table with one arrives with the rows below it short and
+ * {@link normalizeTable} pads them at the end. `colspan` is, as the empty cells it
+ * covers, so the columns after it keep their index.
+ *
+ * Only the table's own rows: a `<tr>` inside a nested table belongs to a cell this
+ * reader is about to flatten, not to a rank of this one.
+ */
+export function tableFromDOM(dom) {
+    const rows = [];
+    const aligns = [];
+    for (const tr of dom.querySelectorAll('tr')) {
+        if (tr.closest('table') !== dom)
+            continue;
+        const cells = [];
+        for (const box of tr.children) {
+            if (box.tagName !== 'TD' && box.tagName !== 'TH')
+                continue;
+            if (!rows.length)
+                aligns.push(alignFromDOM(box));
+            cells.push(cellFromDOM(box));
+            const span = Number(box.getAttribute('colspan')) || 1;
+            for (let i = 1; i < span; i++) {
+                if (!rows.length)
+                    aligns.push('none');
+                cells.push(emptyCell());
+            }
+        }
+        rows.push(cells);
+    }
+    const [header = [], ...body] = rows;
+    return normalizeTable({ header, rows: body, aligns });
+}
+/** The table a paste is carrying, or `undefined` for a paste that holds none. The first
+ *  one: a clipboard holding a table among other blocks is a document paste, and only a
+ *  surface that takes nothing but a table (a cell) reads it this way. */
+export function tableFromClipboard(data) {
+    const html = data?.getData(HTML);
+    if (!html || !/<table[\s>]/i.test(html))
+        return undefined;
+    const dom = new DOMParser().parseFromString(html, HTML).querySelector('table');
+    return dom ? tableFromDOM(dom) : undefined;
+}
+// ── Writing a rectangle out ─────────────────────────────────────────────────
+/** A cell's inline DOM, serialized by the schema that declares its marks, which is what
+ *  makes {@link cellFromDOM} its exact inverse. */
+function cellToDOM(cell, owner) {
+    const doc = decode(cellContent(cell), inlineSchema);
+    const line = doc.firstChild;
+    return DOMSerializer.fromSchema(inlineSchema).serializeFragment(line ? line.content : Fragment.empty, { document: owner });
+}
+/**
+ * A rectangle as a `<table>`: the wire the HTML arm writes and reads. Its first row is
+ * a `<th>` row whatever row of the source it came from, that being the row index 0 a
+ * paste lands it at.
+ */
+export function tableToDOM(block, aligns, owner) {
+    const table = owner.createElement('table');
+    block.forEach((cells, r) => {
+        const tr = owner.createElement('tr');
+        cells.forEach((cell, c) => {
+            const box = owner.createElement(r === 0 ? 'th' : 'td');
+            const align = aligns[c] ?? 'none';
+            if (align !== 'none')
+                box.style.textAlign = align;
+            box.appendChild(cellToDOM(cell, owner));
+            tr.appendChild(box);
+        });
+        table.appendChild(tr);
+    });
+    return table;
+}
+/** A cell's text as one pipe-table field: the delimiter escaped, since a `|` inside a
+ *  cell would otherwise open a column that is not there. Marks are dropped, markdown
+ *  being the lossy arm. */
+const pipeCell = (cell) => cell.text.replaceAll('|', '\\|');
+/**
+ * A rectangle as pipe rows, delimiter row included: what a plain-text target reads as a
+ * table and what markdown carries. The delimiter follows the first row for the reason
+ * that row serializes as `<th>` — a pasted rectangle's row 0 is a header.
+ */
+export function tableToPipe(block, aligns) {
+    const width = block[0]?.length ?? 0;
+    const rule = Array.from({ length: width }, (_, c) => {
+        const align = aligns[c] ?? 'none';
+        if (align === 'center')
+            return ':---:';
+        return align === 'left' ? ':---' : align === 'right' ? '---:' : '---';
+    });
+    const line = (cells) => `| ${cells.join(' | ')} |`;
+    const [head = [], ...body] = block;
+    return [line(head.map(pipeCell)), line(rule), ...body.map((row) => line(row.map(pipeCell)))].join('\n');
+}
+/** Put a rectangle on the clipboard, both arms. The caller is a `copy` / `cut` handler
+ *  over a selection its own surface holds, so the rectangle arrives already cut out and
+ *  claiming the event is the caller's. */
+export function writeRectangle(data, block, aligns, owner) {
+    data.setData(HTML, tableToDOM(block, aligns, owner).outerHTML);
+    data.setData(PLAIN, tableToPipe(block, aligns));
+}
+// ── The paste door ──────────────────────────────────────────────────────────
+/** The `<table>` rule: a clipboard table becomes the island the model already holds
+ *  rather than the paragraph its text flattens to. `id` is left empty for
+ *  {@link stampIslandIds}, a parse rule having no document to mint against. `loss` is
+ *  authored: what this reader produces is a pipe table, so markdown carries it whole. */
+function tableParseRule() {
+    return {
+        tag: 'table',
+        node: 'island_block',
+        getAttrs: (dom) => ({
+            id: '',
+            islandType: 'table',
+            props: tableFromDOM(dom),
+            loss: 'lossless'
+        })
+    };
+}
+/** The clipboard's parser: the schema's own rules with the table rule ahead of them.
+ *  Ahead, because a `<table>` otherwise matches nothing and its cells' text falls
+ *  through to the enclosing block. */
+export function tableClipboardParser(schema) {
+    return new PMDOMParser(schema, [tableParseRule(), ...PMDOMParser.fromSchema(schema).rules]);
+}
+/** An island node a parse rule produced, which is the only kind carrying no id. */
+const unstamped = (node) => (node.type.name === 'island_block' || node.type.name === 'island_inline') && !node.attrs.id;
+/** Mint an id for every island a paste is carrying. An id is part of the document's
+ *  canonical bytes and the channel that addresses an island (CODEC §Islands), so a
+ *  pasted island with none reaches the store as an insert nothing can name afterwards.
+ *  One minter for the whole slice, or a paste placing two tables hands them one id. */
+export function stampIslandIds(slice, doc) {
+    const mint = islandMinter(doc);
+    const walk = (fragment) => {
+        const out = [];
+        fragment.forEach((node) => {
+            const next = node.content.size ? node.copy(walk(node.content)) : node;
+            out.push(unstamped(next) ? next.type.create({ ...next.attrs, id: mint() }, next.content) : next);
+        });
+        return Fragment.fromArray(out);
+    };
+    return new Slice(walk(slice.content), slice.openStart, slice.openEnd);
+}
+/**
+ * The block leaf's clipboard plugin: the table rule on the way in, and the id mint over
+ * what it produced. A `clipboardParser` rather than the schema's own `parseDOM`,
+ * because what a `<table>` in the DOM means is a question only the clipboard asks — the
+ * schema's parse rules are also what a re-parse of the editor's own DOM runs through,
+ * where an island is already a node and a `<table>` is the chrome drawing one.
+ */
+export function tableClipboardPlugin(schema) {
+    const parser = tableClipboardParser(schema);
+    return new Plugin({
+        props: {
+            clipboardParser: parser,
+            transformPasted: (slice, view) => stampIslandIds(slice, view.state.doc)
+        }
+    });
+}