efficient-shell 5.6.0 → 6.4.0

package/dist/markup/index.d.ts

@@ -1,31 +1,46 @@
+/**
+ * MOVED HERE FROM efficient-easel (`src/markup/index.ts` at
+ * 6d31d5df9646afd0d826394292a84b9c002f7355) — Lewis, 2026-10-12, decision D1:
+ * this grammar is THE one grammar, and it lives in efficient-shell as
+ * `efficient-shell/markup`. It replaces the shell's older, smaller grammar
+ * (the 405-line `src/markup/index.ts` of efficient-shell 5.0.0). The file below
+ * is easel's byte for byte, header included, so its history reads as written
+ * (the "WHO OWNS IT" paragraph is easel's own history, now closed: the shell
+ * owns the rule again, and easel, the admin portal and the web builder import
+ * it from here).
+ *
+ * ONE logic change from easel's copy: the read-only `++phrase++` Strong rule
+ * opens only at a WORD START — not right after a letter or a digit — so
+ * `A++ rated tyres, A++ service` stays plain text, while `++20%++` is still
+ * Strong (Lewis, 2026-10-12). See {@link InlineRule.wordStart}.
+ *
+ * Still FRAMEWORK-FREE: no React, no DOM, no imports at all. `efficient-shell/markup`
+ * is its own tsup entry, and the one subpath whose `exports` entry carries a
+ * `default` condition beside `import`, because build scripts reach it through
+ * Node's CJS loader (`tsx`) as well as through bundlers.
+ */
 /**
  * The editorial markup rule — ONE grammar, shared by every product that lets a
  * human type formatted copy into a plain text box.
  *
- * Why this lives in efficient-shell, and why behind its own subpath:
- * the rule is consumed by the admin portal (agent messages + the campaign
- * designer) AND by the public storefront, which has ten dependencies in total
- * and cannot afford the shell's peer graph (a 3D viewer, a PDF renderer, a DXF
- * viewer, an xlsx parser, a Word converter). So this module is deliberately
- * FRAMEWORK-FREE: no React, no JSX, no DOM, no imports at all. `efficient-shell/markup`
- * therefore adds a few hundred bytes of first-party code to a bundle and nothing
- * else — see the subpath's own tsup entry.
- *
- * It is also the ONE subpath whose `exports` entry carries a `default`
- * condition alongside `import`, and that is deliberate rather than untidy. The
- * root and `./apps` are React component entries; a bundler resolves them and
- * nothing else has any business to. This module is consumed by build scripts
- * too — the storefront's media-manifest generator reaches it through its Puck
- * config — and those run under `tsx`, which resolves through Node's CJS
- * loader. With only `types` and `import` declared, that resolution fails with
- * ERR_PACKAGE_PATH_NOT_EXPORTED, which reads like a missing file rather than a
- * missing condition. A module this portable should answer to any resolver.
- *
- * WHAT IS SHARED IS THE RULE, NOT THE RENDERING. Each product renders the token
- * list its own way, because it must: the web uses CSS classes bound to theme
- * tokens, email must inline every style (mail clients drop classes). Two
- * renderers, one grammar, one writer ({@link applyMark}) — so a toolbar button
- * and a parser can never disagree about what a delimiter means.
+ * WHO OWNS IT. This package does (efficient-easel; `efficient-editor` until 0.95.0, `editor-shell` until 0.66.0), since 2026-09-28. Until then the rule lived in
+ * `efficient-shell/markup`, a package Victor owns, and this package only imported
+ * it. Lewis decided to keep our own copy rather than wait on upstream for the
+ * rich text box: "Two copies is fine. We use our own independent one." This
+ * file started from efficient-shell 4.121.0 (the same file as the 4.101.0 and
+ * 4.120.0 the apps pin, bar one spelling) and grows here from now on. The two
+ * copies are expected to drift; nothing in either product reads both.
+ *
+ * FRAMEWORK-FREE, behind its own subpath (`efficient-easel/markup`): no React, no
+ * JSX, no DOM, no imports at all. The public storefront reads it, and the
+ * backend's banner renderer may one day port it, so it must stay a few hundred
+ * bytes of plain code that any bundler or resolver can load.
+ *
+ * WHAT IS SHARED IS THE RULE, NOT THE RENDERING. Each product renders the tree
+ * its own way, because it must: the web uses CSS classes bound to theme tokens,
+ * email must inline every style (mail clients drop classes). Two renderers, one
+ * grammar, one writer ({@link applyMark}) — so a toolbar button and a parser
+ * can never disagree about what a delimiter means.
  *
  * ## The delimiters
  *
@@ -35,6 +50,55 @@
  *   _phrase_     italic
  *   ~~phrase~~   strikethrough
  *   ==phrase==   highlight — the brand accent colour, applied to a selection
+ *   ^^phrase^^   quiet — smaller and softer
+ *
+ * THE THREE NAMES a merchant sees ({@link MARK_NAMES}, owner-approved
+ * 2026-09-28) sit on these marks: Strong is `**`, Emphasis is `==`, Quiet is
+ * `^^`. The storefront once had separate word-style marks for Emphasis and
+ * Strong, `@@phrase@@` and `++phrase++`. Production holds none of them, and no
+ * button writes them any more, but they are still READ — as Emphasis and Strong
+ * — so a string somebody pasted never prints its delimiters.
+ *
+ * And, read by {@link parseMarkup} (the tree a rich text box and a renderer
+ * use), in every product:
+ *
+ *   [words](href)  a link — safe addresses only ({@link isSafeLinkHref})
+ *   - words        a bullet line, one level
+ *   1. words       a numbered line, one level: 1-3 digits, ". ", words
+ *   **a _b_ a**    one run inside another, up to four levels
+ *
+ *   [words]{underline}    underline
+ *   [words]{sup}          superscript
+ *   [words]{sub}          subscript
+ *   [words]{color=name}   a theme colour, by NAME ({@link isColorName})
+ *   [words]{color=#rrggbb}  any colour, six hex digits ({@link isColorValue})
+ *
+ * THE SPANS AND THE NUMBERED LINE (plan step E1, approved by GG 2026-10-06)
+ * are the final text box's marks. One shape for all four, so one reading rule:
+ * `[`, words, `]`, then EXACTLY one of those blocks. Anything else after the
+ * `]` — `{foo}`, `{color=#f00}`, a merge tag's `{{` — is not a span, and the
+ * whole thing stays as typed. Two marks on the same words nest
+ * (`[[x]{sup}]{color=accent}`); one block never holds two.
+ *
+ * Why these cannot clash with an old mark: no old rule closes on `]{` (a link
+ * needs `](`), and the campaign's legacy `[phrase]` italic steps back from a
+ * span block, the way it steps back from a link (`notBeforeBlock`). No inline
+ * rule opens on a digit. Production held neither shape when they were chosen:
+ * 0 of 24,233 text values contained `]{`, and none had a line starting with a
+ * number and `.` or `)`.
+ *
+ * Not chosen: `^x^` / `~x~` (one character from Quiet `^^` and strike `~~`,
+ * and `~20 min` is ordinary copy), `__x__` (pinned as italic below, and
+ * CommonMark's bold) and `++x++` (the old Strong).
+ *
+ * Only the tree ({@link parseMarkup}) reads them. The flat
+ * {@link tokenizeInline} — the old renderers' reading — keeps them as text, as
+ * it keeps links: an email or a page drawn before its renderer learns them
+ * prints the delimiters. No toolbar button writes them yet.
+ *
+ * EVERY READING IS LINE BY LINE: a run never crosses a line break. The email
+ * always read this way; the editor's painter and the storefront used to read
+ * the whole string, so the same saved text drew differently in each.
  *
  * Plus a per-product LEGACY set ({@link STOREFRONT_MARKUP} /
  * {@link CAMPAIGN_MARKUP}) that keeps already-published copy rendering exactly
@@ -72,15 +136,44 @@
  * and the form to reach for. Pinned by a test, so it stays a decision rather
  * than becoming a discovery.
  */
-/** A style a toolbar button can apply. The first five are inline marks; the
- *  last four are the composer-only affordances (a link and the three line
- *  prefixes), which only a renderer that draws block content can honour. */
-type MarkStyle = 'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'link' | 'bullet' | 'number' | 'quote';
+/** A style a toolbar button can apply. The first six are inline marks; then
+ *  the composer-only affordances (a link and the three line prefixes), which
+ *  only a renderer that draws block content can honour; `clear`, which
+ *  writes no mark at all — it takes them off ({@link clearMarks}); and the
+ *  three spans of the final text box (E1), which no button in
+ *  {@link MARKUP_TOOLS} offers yet. A colour carries a name, so it is written
+ *  by {@link applyColor}, not here. */
+type MarkStyle = 'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'quiet' | 'link' | 'bullet' | 'number' | 'quote' | 'clear' | 'underline' | 'sup' | 'sub';
+/** What a span means: `[words]{underline}`, `{sup}`, `{sub}` or
+ *  `{color=name}`. Only the tree reads these; {@link InlineKind} is the flat
+ *  reading's, which never makes one. */
+type SpanKind = 'underline' | 'sup' | 'sub' | 'color';
 /** What a parsed run MEANS. `accent` is the storefront/campaign brand colour —
  *  the legacy `*phrase*` — and `highlight` is its standard-markdown successor;
  *  both resolve to the same paint, which is what makes converting stored copy
  *  from one to the other invisible. */
-type InlineKind = 'text' | 'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'accent';
+type InlineKind = 'text' | 'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'accent' | 'quiet';
+/** A theme colour's name as a span saves it: lowercase letters, digits and
+ *  `-`, starting with a letter (`accent`, `brand-2`). A name is the theme's,
+ *  so changing the theme recolours the words. Never a hex — that is the other
+ *  kind of colour value ({@link isColorValue}). */
+declare function isColorName(name: string): boolean;
+/** A colour a span may carry: a theme NAME ({@link isColorName}), or "any
+ *  colour" as EXACTLY six hex digits after a `#` (`#0b5cff`). Either case
+ *  reads; the writers save lowercase ({@link colorValue}). Nothing else —
+ *  `#f00`, `rgb()`, a typo — is a colour, so it stays plain text.
+ *
+ *  WIDENS E1 (GG 2026-10-06): the final design draws "Any color", and a
+ *  feature is never cut to fit. A hex does not follow the theme; a name does. */
+declare function isColorValue(value: string): boolean;
+/**
+ * The words a press WRITES when nothing is selected — `**bold text**`, left
+ * selected so the next keystroke replaces it. English unless the caller of
+ * {@link applyMark} hands in its own (0.95.0: a host in another language).
+ * They are words put in the box, not rules: nothing here changes what parses.
+ */
+type MarkPlaceholders = Record<'bold' | 'italic' | 'strike' | 'code' | 'highlight' | 'quiet' | 'link', string> & Partial<Record<'underline' | 'sup' | 'sub' | 'color', string>>;
+declare const MARK_PLACEHOLDERS: MarkPlaceholders;
 interface WrapResult {
     text: string;
     /** Where the caret should land — inside the new marks, or after them. */
@@ -96,18 +189,93 @@ interface WrapResult {
  * also unwrapped `*phrase*` would silently strip an accent run in the storefront
  * and the campaign designer, where the asterisk means colour, not slant.
  */
-declare function applyMark(text: string, start: number, end: number, style: MarkStyle): WrapResult;
-/** One toolbar button. `label` is a text glyph for hosts that draw type
- *  (the message composer); hosts with an icon set map `style` to their own.
- *  `shortcut` is the bare key the host combines with its platform modifier. */
+declare function applyMark(text: string, start: number, end: number, style: MarkStyle, rules?: readonly InlineRule[], placeholders?: MarkPlaceholders): WrapResult;
+/**
+ * Colour `text[start:end]` with `name` — a theme colour name or a 6-digit hex
+ * ({@link isColorValue}; a hex is saved lowercase) — writing
+ * `[words]{color=name}` and leaving the words selected. On words that are
+ * already exactly one colour span it changes the colour; `null` takes it
+ * off. A value {@link isColorValue} refuses changes nothing — `#f00` or a typo
+ * is never saved as a block the reader would print as text.
+ *
+ * Separate from {@link applyMark} because a colour carries a value, as a link
+ * does ({@link writeLink}).
+ */
+declare function applyColor(text: string, start: number, end: number, name: string | null, placeholders?: MarkPlaceholders): WrapResult;
+/**
+ * True when `text[start:end]` is ALREADY wrapped in `style`'s own fence — the
+ * very test {@link applyMark} uses to decide that a press unwraps. So a button
+ * drawn as pressed is exactly a button whose press takes the mark off; the two
+ * cannot disagree. False for a style with no fence (a link, a line prefix).
+ */
+declare function markedAt(text: string, start: number, end: number, style: MarkStyle): boolean;
+/** A link as it sits in authored text: where it starts and ends, its words and
+ *  its address. */
+interface LinkSpan {
+    start: number;
+    end: number;
+    label: string;
+    href: string;
+}
+/**
+ * The link the caret or selection sits in — `[words](href)` covering all of
+ * `start..end` — or null. What the link button opens on: inside a link it edits
+ * that link, anywhere else it makes a new one.
+ *
+ * Read with the parser's own rule ({@link linkAt}), so a span this returns is
+ * exactly one the renderers draw as a link — an unsafe address is not a link
+ * and is not offered for editing as one.
+ */
+declare function findLink(text: string, start: number, end: number): LinkSpan | null;
+/**
+ * Make `text[start:end]` a link to `href`, or re-point the link it sits in.
+ * The caret lands after the link, selecting nothing: the link is finished.
+ *
+ * The words are the selection, or — with nothing selected — the address
+ * itself, so a merchant who pastes an address and presses Apply gets a link
+ * that reads as that address rather than a placeholder to type over.
+ *
+ * ⚠️ The address is the CALLER'S to check ({@link isSafeLinkHref}): one that
+ * fails would be written as plain text the renderers never draw as a link.
+ */
+declare function writeLink(text: string, start: number, end: number, href: string): WrapResult;
+/** Take a link off, keeping its words — selected, so a second press of the
+ *  link button puts it straight back. */
+declare function removeLink(text: string, link: LinkSpan): WrapResult;
+/**
+ * One toolbar button.
+ *
+ * - `label` is a text glyph, never a word, for a host that draws type (the
+ *   message composer). The copy box draws the icon set's glyph instead.
+ * - `name` is what the button is CALLED: its accessible name, and the first
+ *   word of its tooltip. Approved 2026-10-02: no word is drawn ON a button,
+ *   so a name lives here and in `title` and nowhere a merchant reads it as
+ *   part of the bar.
+ * - `title` is the tooltip: the name, what the mark writes, and the shortcut.
+ * - `shortcut` is the key the host combines with its platform modifier: a bare
+ *   letter (`'b'`), or `'shift+'` and a letter.
+ */
 interface MarkupTool {
     style: MarkStyle;
     label: string;
     title: string;
+    name?: string;
     shortcut?: string;
 }
-/** Every button, in the order a writer reaches for them. */
+/** Every button, in the order a writer reaches for them. Clear is last: it
+ *  acts on every mark before it. */
 declare const MARKUP_TOOLS: readonly MarkupTool[];
+/**
+ * The names a merchant sees for the three styles that carry one, in both
+ * editors (owner-approved 2026-09-28). One word per idea: Strong IS bold
+ * (`**`, ⌘B) and Emphasis IS the highlight (`==`), so a toolbar that shows the
+ * names shows no separate B or ◆ beside them.
+ */
+declare const MARK_NAMES: {
+    readonly bold: "Strong";
+    readonly highlight: "Emphasis";
+    readonly quiet: "Quiet";
+};
 /** The tools a host shows, resolved to descriptors in {@link MARKUP_TOOLS}
  *  order. Keeps a host from hand-rebuilding a descriptor (and drifting on a
  *  tooltip) just to pick a subset. */
@@ -141,6 +309,23 @@ interface InlineRule {
      * more rule field and no new branch in {@link tokenizeInline}.
      */
     readonly notBefore?: string;
+    /**
+     * True when the run may not close right before a span block (`{sup}`,
+     * `{color=accent}`, …). The campaign's legacy `[phrase]` needs it for the
+     * reason it needs `notBefore: '('`: without it `[x]{sup}` would read as an
+     * italic `x` followed by a printed `{sup}`. Only the four exact blocks count,
+     * so `[x]{{first_name}}` and `[x]{foo}` read as they always did.
+     */
+    readonly notBeforeBlock?: boolean;
+    /**
+     * True when the run may only OPEN at a word start: the open may not follow a
+     * letter or a digit (any script). The read-only `++` Strong needs it, because
+     * `++` is ordinary copy after a word — "A++ rated tyres, A++ service" would
+     * otherwise read as one Strong run from the first `A++` to the second. Only
+     * the open is checked, so "Save ++20%++ today" is still Strong. Lewis,
+     * 2026-10-12 (D1).
+     */
+    readonly wordStart?: boolean;
 }
 /**
  * The standard-markdown marks, shared by every product.
@@ -154,6 +339,14 @@ interface InlineRule {
  * what actually does the work.
  */
 declare const STANDARD_MARKUP: readonly InlineRule[];
+/**
+ * Marks the copy box no longer OFFERS (E5a, 2026-10-06: Lewis dropped
+ * Emphasis `==` and Quiet `^^` from the final design). They are still read,
+ * drawn and written back byte for byte — saved copy wears them — but no bar
+ * button writes them, and `CopyBox` draws none for them even when a host asks.
+ * Declared before {@link COPY_FIELD_TOOLS} reads it at module load.
+ */
+declare const RETIRED_MARKS: readonly MarkStyle[];
 /**
  * The buttons a COPY FIELD offers — a storefront section's copy box and a
  * campaign block's copy box show exactly these, so a merchant meets one toolbar
@@ -167,7 +360,7 @@ declare const STANDARD_MARKUP: readonly InlineRule[];
  * parser read as something else. Now a style with no rule cannot appear here,
  * whatever anyone types into the array.
  *
- * It resolves to bold, italic, strike and highlight. `code` is the one that
+ * It resolves to bold, italic, strike, highlight and quiet. `code` is the one that
  * surprises: it is an inline mark and it has a fence, but no rule reads a
  * backtick, so a copy field would print `` `word` `` verbatim — and a button
  * whose output the renderer draws as literal text is worse than no button.
@@ -231,5 +424,236 @@ declare function tokenizeInline(value: string, rules: readonly InlineRule[]): In
  * visitor actually sees.
  */
 declare function stripInline(value: string, rules: readonly InlineRule[]): string;
+/** Plain words. */
+interface MarkupText {
+    kind: 'text';
+    text: string;
+}
+/** A delimited run. `open` and `close` are the delimiters that were actually
+ *  saved — `#` for a legacy campaign bold, `**` for the standard one, `[` and
+ *  `]{sup}` for a span — so the tree writes back the same bytes it was read
+ *  from. `color` is the theme colour's name, on a `color` span only. */
+interface MarkupRun {
+    kind: InlineRule['kind'] | SpanKind;
+    open: string;
+    close: string;
+    color?: string;
+    children: MarkupNode[];
+}
+/** `[words](href)`. Only made when {@link isSafeLinkHref} passes. */
+interface MarkupLink {
+    kind: 'link';
+    href: string;
+    children: MarkupNode[];
+}
+type MarkupNode = MarkupText | MarkupRun | MarkupLink;
+/** One line of the saved string. `bullet` means it was saved as `- words`;
+ *  `number` holds the digits of a line saved as `12. words`, as typed (`01`
+ *  stays `01`), and is null on every other line. `children` hold what follows
+ *  the prefix. A line built by hand may leave `number` out: it means null. */
+interface MarkupLine {
+    bullet: boolean;
+    number?: string | null;
+    children: MarkupNode[];
+}
+/**
+ * True for an address a link may carry: `http`, `https`, `mailto` or `tel`, or
+ * one with no scheme at all (`/tyres`, `#top`, `terms.html`, `//cdn…`).
+ * Anything else — `javascript:`, `data:`, `file:` — is refused, and so is an
+ * address with any space or control character in it, because browsers drop
+ * those before they read the scheme (`java\tscript:` runs as `javascript:`).
+ *
+ * Renderers call this too, before they write an `href`, so the rule has one
+ * home.
+ */
+declare function isSafeLinkHref(href: string): boolean;
+/**
+ * Read authored text into lines of nodes — the whole grammar, for a rich text
+ * box and for the renderers that draw links and bullets.
+ *
+ * - A run never crosses a line break.
+ * - A line that starts with `- ` and has words after it is a bullet. One level
+ *   only: an indented `  - ` is plain text.
+ * - A line that starts with 1-3 digits, `. ` and words is numbered, the digits
+ *   kept as typed. One level only, as bullets.
+ * - `[words](href)` is a link when {@link isSafeLinkHref} passes; otherwise the
+ *   whole thing stays plain text.
+ * - `[words]{underline}`, `{sup}`, `{sub}` and `{color=name}` are spans; any
+ *   other block stays plain text.
+ * - A run's words are read again, so `**bold _with italic_**` is italic inside
+ *   bold. Four levels: a fifth stays as typed.
+ *
+ * Nothing is lost: {@link serializeMarkup} writes back the exact bytes.
+ */
+declare function parseMarkup(value: string, rules: readonly InlineRule[]): MarkupLine[];
+/** Write lines back to authored text: the inverse of {@link parseMarkup}. */
+declare function serializeMarkup(lines: readonly MarkupLine[]): string;
+/**
+ * One run a character sits in. `id` says WHICH run: two characters with the
+ * same id are in one run, so `**a****b**` (two bold runs, back to back) is told
+ * apart from `**ab**` (one) and is written back as it was saved.
+ *
+ * `open` and `close` are the delimiters that were saved (`#` for a legacy
+ * campaign bold), or, for a run made in the editor, the toolbar's own fence.
+ * A link's `close` is `](href)`, a span's `]{sup}` or `]{color=name}`.
+ */
+interface MarkSpan {
+    id: number;
+    kind: InlineRule['kind'] | SpanKind | 'link';
+    open: string;
+    close: string;
+    href?: string;
+    color?: string;
+}
+/**
+ * A NEW run, as the toolbar writes it: `**` for bold, `_` for italic, and so on
+ * ({@link applyMark}'s own fences), a link to `value`, or a colour span of
+ * `value` — a theme name or a 6-digit hex, saved lowercase ({@link isColorValue}). Null for a style that writes no run (a line
+ * prefix, clear) and for a link or colour with no usable value. A paste filter
+ * or an editor making a run asks here, so no delimiter is spelled outside this
+ * module (E8).
+ */
+declare function spanFor(id: number, style: MarkStyle | 'color', value?: string): MarkSpan | null;
+/** One character of the words — never a delimiter — with the runs it sits in,
+ *  outside first, and its offset in the saved string. */
+interface MarkedChar {
+    ch: string;
+    marks: readonly MarkSpan[];
+    at: number;
+}
+/** One line: its bullet flag or its number (the `- ` and the `12. ` are not
+ *  characters) and its words. `number` left out means null, as on
+ *  {@link MarkupLine}. */
+interface MarkedLine {
+    bullet: boolean;
+    number?: string | null;
+    chars: MarkedChar[];
+}
+/**
+ * Read authored text as characters, each carrying its runs — what an editor
+ * that hides the delimiters edits, and what {@link clearMarks} splits runs on.
+ *
+ * Built on {@link parseMarkup}, so it is the same reading, character by
+ * character. A character is a code point (an emoji is one, two UTF-16 units
+ * long); `at` counts UTF-16 units, as a text box's selection does.
+ *
+ * {@link writeMarkedLines} writes it back byte for byte.
+ */
+declare function markedLines(value: string, rules: readonly InlineRule[]): MarkedLine[];
+/**
+ * Write characters back to authored text: the inverse of {@link markedLines}.
+ * Returns where each character landed (`at[line][char]`), so a selection can be
+ * carried across the write.
+ *
+ * Runs are opened and closed as the characters ask: a character outside a run
+ * that its neighbours are in closes it, and the run's next character opens it
+ * again. That is how a run is SPLIT — clear the middle of `**abcd**` and it is
+ * written `**a**bc**d**`. Whether the result reads back as written is the
+ * caller's to check ({@link sameMarks}): `_` cannot close against a letter.
+ */
+declare function writeMarkedLines(lines: readonly MarkedLine[]): {
+    text: string;
+    at: number[][];
+};
+/** True when two readings hold the same words wearing the same marks — the
+ *  kinds, addresses, colours and list numbers, not which run or which
+ *  delimiter. */
+declare function sameMarks(a: readonly MarkedLine[], b: readonly MarkedLine[]): boolean;
+/**
+ * Take every mark off `text[start:end]`, keeping the words and any link (a
+ * link has its own Remove). A run the selection only partly covers is split,
+ * so the rest of it keeps its mark. Bullets and numbers stay: they are lines,
+ * not marks.
+ *
+ * With nothing selected, the runs the caret touches — the characters either
+ * side of it — come off whole.
+ *
+ * A split the grammar cannot hold comes off whole instead: the middle of
+ * `_word_` would leave an underscore against a letter, which reads as a
+ * literal underscore. And if even that would not read back, nothing changes.
+ */
+declare function clearMarks(text: string, start: number, end: number, rules?: readonly InlineRule[]): WrapResult;
+/**
+ * The final toolbar's Clear style (owner ruling, 2026-10-07): take EVERY mark
+ * off the WORDS in `text[start:end]` but a link, keeping the words selected —
+ * the bar's (bold, italic, underline, strikethrough, colour, superscript,
+ * subscript) and the retired ones it no longer offers (Emphasis, Quiet, the
+ * legacy accent), so the words come back plain (GG, 2026-10-07). A link is
+ * content, not style; a line's bullet or number is a line, not a mark.
+ *
+ * A run the selection only partly covers is split, so the rest of it keeps
+ * its mark; a split the grammar cannot hold (the middle of `_word_`) takes the
+ * run off whole; and if even that would not read back, nothing changes.
+ *
+ * With nothing selected nothing changes: the button is disabled then, so a
+ * press can never wipe a whole paragraph. Unlike {@link clearMarks} (the 0.94
+ * bar's Clear marks), which with a caret takes off the runs it touches.
+ */
+declare function clearStyle(text: string, start: number, end: number, rules?: readonly InlineRule[]): WrapResult;
+/**
+ * Press `style` on the WORDS in `text[start:end]`, whichever runs they sit in —
+ * what a view that hides the delimiters needs, where `applyMark` (which wraps
+ * exactly the characters selected) would cross or strand a delimiter.
+ *
+ * - Every selected word already wears the mark: it comes off them. Part of a
+ *   run is split off; the rest keeps the mark.
+ * - Otherwise the mark goes on, as ONE run over the words and any run of the
+ *   same mark they touch (`**half** off` → `**half off**`).
+ * - Nothing is written that would not read back: a third level of nesting,
+ *   or `_` inside a word, leaves the text as it was.
+ * - With nothing selected it is {@link applyMark}: a selected placeholder.
+ *
+ * Offsets are the saved string's, before and after.
+ */
+declare function toggleMark(text: string, start: number, end: number, style: MarkStyle, rules?: readonly InlineRule[]): WrapResult;
+/**
+ * The marks every word in `text[start:end]` wears — `bold`, `link`, a legacy
+ * `accent` … — or, with nothing selected, the marks of the word just before the
+ * caret on its line: what typing there would continue. What a toolbar draws
+ * as pressed in a view without delimiters.
+ */
+declare function marksIn(text: string, start: number, end: number, rules?: readonly InlineRule[]): Set<string>;
+/**
+ * Link the WORDS in `text[start:end]` to `href`, nesting with any run they
+ * sit in rather than crossing it: words inside a bold run become a link inside
+ * it (`**Book [a fitting](/book)**`), a whole bold run goes inside the link.
+ *
+ * With nothing selected, inside a link it re-points that link; anywhere else
+ * it writes the address as its own words ({@link writeLink}). The caret lands
+ * after the link. ⚠️ The address is the caller's to check ({@link isSafeLinkHref}).
+ */
+declare function linkOver(text: string, start: number, end: number, href: string, rules?: readonly InlineRule[]): WrapResult;
+/** Take off the link the caret or selection touches, keeping its words —
+ *  selected, so a second press of the link button puts it straight back. */
+declare function unlinkAt(text: string, start: number, end: number, rules?: readonly InlineRule[]): WrapResult;
+/**
+ * Colour the WORDS in `text[start:end]` with `name` — a theme colour name or
+ * a 6-digit hex, saved lowercase (`[words]{color=name}`), nesting with any run they sit in rather than
+ * crossing it — the colour window's write, as {@link linkOver} is the link
+ * window's. A colour the words already wear is replaced; `null` takes the
+ * colour off them, splitting a run that only partly covers them.
+ *
+ * A value {@link isColorValue} refuses (`#f00`, a word with a space) changes
+ * nothing: a block the reader would print as text is never written. With
+ * nothing selected nothing changes either — the box keeps a pending colour
+ * for the words typed next instead.
+ */
+declare function colorOver(text: string, start: number, end: number, name: string | null, rules?: readonly InlineRule[]): WrapResult;
+/** The ONE colour every word in `text[start:end]` wears — or, with nothing
+ *  selected, the word before the caret on its line — or null. What the colour
+ *  window draws as chosen, and the colour under the A. */
+declare function colorIn(text: string, start: number, end: number, rules?: readonly InlineRule[]): string | null;
+/**
+ * Make every line `text[start:end]` touches (the caret's line, with nothing
+ * selected) a bulleted list, a numbered list, or — `null` — no list. The
+ * words and their marks keep their bytes; only the line prefixes change. A
+ * numbered list counts on from a numbered line just above it, else from 1.
+ * An empty line becomes an empty list line (`- `), which the rich view draws
+ * as a bullet with nothing after it yet. The selection keeps its words.
+ */
+declare function setList(text: string, start: number, end: number, kind: 'bullet' | 'number' | null, rules?: readonly InlineRule[]): WrapResult;
+/** `bullet` or `number` when every line `text[start:end]` touches is that
+ *  kind of list line, else null — what the list buttons draw as pressed. */
+declare function listIn(text: string, start: number, end: number, rules?: readonly InlineRule[]): 'bullet' | 'number' | null;
 
-export { CAMPAIGN_MARKUP, COPY_FIELD_TOOLS, type InlineKind, type InlineRule, type InlineToken, MARKUP_TOOLS, type MarkStyle, type MarkupTool, STANDARD_MARKUP, STOREFRONT_MARKUP, type WrapResult, applyMark, markupTools, stripInline, tokenizeInline };
+export { CAMPAIGN_MARKUP, COPY_FIELD_TOOLS, type InlineKind, type InlineRule, type InlineToken, type LinkSpan, MARKUP_TOOLS, MARK_NAMES, MARK_PLACEHOLDERS, type MarkPlaceholders, type MarkSpan, type MarkStyle, type MarkedChar, type MarkedLine, type MarkupLine, type MarkupLink, type MarkupNode, type MarkupRun, type MarkupText, type MarkupTool, RETIRED_MARKS, STANDARD_MARKUP, STOREFRONT_MARKUP, type SpanKind, type WrapResult, applyColor, applyMark, clearMarks, clearStyle, colorIn, colorOver, findLink, isColorName, isColorValue, isSafeLinkHref, linkOver, listIn, markedAt, markedLines, marksIn, markupTools, parseMarkup, removeLink, sameMarks, serializeMarkup, setList, spanFor, stripInline, toggleMark, tokenizeInline, unlinkAt, writeLink, writeMarkedLines };

package/dist/markup/index.js

@@ -1 +1 @@
-var e={bold:{fence:"**",placeholder:"bold text"},italic:{fence:"_",placeholder:"italic text"},strike:{fence:"~~",placeholder:"struck out"},code:{fence:"`",placeholder:"code"},highlight:{fence:"==",placeholder:"highlighted text"}},t={bullet:()=>"- ",number:e=>`${e+1}. `,quote:()=>"> "};function l(l,n,i,o){const c=l.slice(n,i);if("link"===o){const e=c||"link text",t=`[${e}](https://)`;return{text:l.slice(0,n)+t+l.slice(i),selectionStart:n+e.length+3,selectionEnd:n+t.length-1}}const s=t[o];if(s){const e=l.lastIndexOf("\n",Math.max(n-1,0))+1,t=l.indexOf("\n",i),o=-1===t?l.length:t,c=l.slice(e,o).split("\n"),r=c.every((e,t)=>e.startsWith(s(t))),d=c.map((e,t)=>r?e.slice(s(t).length):s(t)+e).join("\n");return{text:l.slice(0,e)+d+l.slice(o),selectionStart:e,selectionEnd:e+d.length}}const{fence:r,placeholder:d}=e[o],h=l.slice(Math.max(0,n-r.length),n),u=l.slice(i,i+r.length);if(h===r&&u===r)return{text:l.slice(0,n-r.length)+c+l.slice(i+r.length),selectionStart:n-r.length,selectionEnd:n-r.length+c.length};const a=c||d;return{text:l.slice(0,n)+r+a+r+l.slice(i),selectionStart:n+r.length,selectionEnd:n+r.length+a.length}}var n=[{style:"bold",label:"B",title:"Bold (⌘B)",shortcut:"b"},{style:"italic",label:"I",title:"Italic (⌘I)",shortcut:"i"},{style:"strike",label:"S",title:"Strikethrough"},{style:"highlight",label:"◆",title:"Highlight in the brand color"},{style:"code",label:"‹›",title:"Code"},{style:"link",label:"🔗",title:"Link (⌘K)",shortcut:"k"},{style:"bullet",label:"•",title:"Bulleted list"},{style:"number",label:"1.",title:"Numbered list"},{style:"quote",label:"❝",title:"Quote"}];function i(e){return n.filter(t=>e.includes(t.style))}var o=[{open:"**",close:"**",kind:"bold"},{open:"==",close:"==",kind:"highlight"},{open:"~~",close:"~~",kind:"strike"},{open:"_",close:"_",kind:"italic",wordBoundary:!0}],c=n.map(e=>e.style).filter(e=>o.some(t=>t.kind===e)),s=[...o,{open:"*",close:"*",kind:"accent"}],r=[...o,{open:"*",close:"*",kind:"accent"},{open:"#",close:"#",kind:"bold",notBefore:"0123456789"},{open:"[",close:"]",kind:"italic",notBefore:"("}];function d(e){return!/\s/.test(e)&&!/[!-\/:-@[-`{-~]/.test(e)}function h(e,t){const l=[];let n="",i=0;for(;i<e.length;){const o=u(e,i,t);o?(l.push({kind:"text",text:n}),n="",l.push({kind:o.rule.kind,text:o.inner}),i=o.end):(n+=e[i],i+=1)}return l.push({kind:"text",text:n}),l}function u(e,t,l){for(const n of l){if(!e.startsWith(n.open,t))continue;if(n.wordBoundary&&t>0&&d(e[t-1]))continue;const l=t+n.open.length,i=e.indexOf(n.close,l);if(i<l+1)continue;const o=e.slice(l,i);if(o.includes(n.close[0]))continue;const c=i+n.close.length,s=e[c];if((!n.notBefore||void 0===s||!n.notBefore.includes(s))&&(!n.wordBoundary||void 0===s||!d(s)))return{rule:n,inner:o,end:c}}return null}function a(e,t){return h(e,t).map(e=>e.text).join("")}export{r as CAMPAIGN_MARKUP,c as COPY_FIELD_TOOLS,n as MARKUP_TOOLS,o as STANDARD_MARKUP,s as STOREFRONT_MARKUP,l as applyMark,i as markupTools,a as stripInline,h as tokenizeInline};
+export{CAMPAIGN_MARKUP,COPY_FIELD_TOOLS,MARKUP_TOOLS,MARK_NAMES,MARK_PLACEHOLDERS,RETIRED_MARKS,STANDARD_MARKUP,STOREFRONT_MARKUP,applyColor,applyMark,clearMarks,clearStyle,colorIn,colorOver,findLink,isColorName,isColorValue,isSafeLinkHref,linkOver,listIn,markedAt,markedLines,marksIn,markupTools,parseMarkup,removeLink,sameMarks,serializeMarkup,setList,spanFor,stripInline,toggleMark,tokenizeInline,unlinkAt,writeLink,writeMarkedLines}from"../chunk-PJPK2ADX.js";