@uniweb/press 0.4.15 → 0.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/press",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Press your React components into downloadable files — Word, Excel, PDF. Registration-based pattern with lazy-loaded format adapters.",
   "type": "module",
   "exports": {

package/src/adapters/math-css.js

@@ -1,89 +1,425 @@
 /**
  * @fileoverview The CSS a Temml-produced MathML document needs to lay out.
  *
- * Math arrives as MathML, which browsers render natively — so it is tempting
- * to conclude, as this pipeline's own comments once did, that it carries no
- * CSS dependency at all. It does, for two separate reasons:
+ * Math arrives as MathML, which browsers render natively — so it is tempting to
+ * conclude, as this pipeline's own comments once did, that it carries no CSS
+ * dependency at all. It carries a large one, and `<menclose>` is the proof:
+ * that element is NOT part of MathML-Core, it is Temml's own polyfill, and the
+ * rules that draw `\cancel`, `\overline` and `\sout` over it exist only in
+ * Temml's stylesheet. Without them those constructs render as the bare term — a
+ * formula that means something different from what the author wrote.
  *
- * 1. **Temml emits class hooks and expects a stylesheet to define them.**
- *    `tml-left` / `tml-right` carry the `&` column alignment of an `aligned`
- *    environment, and `tml-jot` carries its extra row spacing. With nothing
- *    defining them, a derivation's `=` signs do not line up and its rows sit
- *    flush against each other. The declarations below are Temml's own, from
- *    `Temml-Local.css`.
+ * ── Why this is a vendored string and not an import ──
  *
- * 2. **`mtd` gets no vertical padding from the browser.** Temml's stylesheet
- *    only *adjusts* row spacing for jot and small, on the stated assumption
- *    that "default mtd top padding is 0.5ex per MathML-Core and user-agent
- *    CSS". Measured in Chrome 2026-07, a pristine `mtd` gets 0px — so a
- *    `pmatrix` or `cases`, which carries no `tml-*` class at all, renders with
- *    its rows touching. Shipping Temml's stylesheet verbatim fixes the
- *    derivation and leaves the matrix broken; the `math mtd` rule below is the
- *    part Temml does not have.
+ * The browser lane (`@uniweb/kit/math-tokens.css`) simply does
+ * `@import "temml/dist/Temml-Local.css"` and lets the bundler resolve it. press
+ * cannot: its adapters EMIT CSS as a string into a document, run in browser
+ * hosts as well as Node ones (see the host-supplied asset loaders in
+ * `assets/fetch.js`), and press has — by constitution — no `@uniweb/*`
+ * dependency at all. So the declarations are genuinely duplicated here.
  *
- * ── Why this is a string and not an imported stylesheet ──
+ * That duplicate is pinned mechanically rather than by comment:
+ * `framework/_contracts/math-css-parity.test.js` recomposes this value from the
+ * real `temml` package plus kit's stylesheet and fails when they disagree.
+ * Regenerate rather than hand-edit `TEMML_BASE`.
  *
- * These adapters run in browser hosts as well as Node ones (see the host-
- * supplied asset loaders in `assets/fetch.js`), so press cannot read a file at
- * runtime, and it does not depend on `@uniweb/kit`. The same declarations
- * therefore live in `kit/src/prose-tokens.css` for the browser lane.
+ * ── The two deliberate departures from Temml's sheet ──
  *
- * That is a duplicate, and duplicates drift — so it is pinned mechanically
- * rather than by comment: `framework/_contracts/math-css-parity.test.js`
- * parses both and fails when they disagree. Change one, change the other, or
- * the contract test names it.
+ * 1. **`@font-face` is stripped.** It points at `Temml.woff2`, which a bundler
+ *    emits as an asset for the browser lane but which press would have to
+ *    package into the EPUB itself. Fixing it is an asset question for the EPUB
+ *    adapter, not a CSS one.
+ *
+ *    Consequence, accepted for now, and it is wider than it first looks: two
+ *    rules want that face — `math .mathscr` and, more commonly, `mo.tml-prime`,
+ *    so every `f'` and `f''` in a compiled document loses its prime alignment
+ *    and falls back to a system glyph. (It is NOT what draws `\mathcal`; that
+ *    is `*.mathcal { font-feature-settings: 'ss01' }` and survives stripping.)
+ *
+ * 2. **`.tml-eqn::before` is rescoped to `.tml-eqn:empty::before`.** Temml
+ *    leaves the tag span empty and asks a CSS counter to draw the number. That
+ *    works in a browser and not in a document: Paged.js rewrites counters for
+ *    its own pagination and strips `counter-increment`, so every equation
+ *    rendered as "(0)" (measured 2026-07-31). `numberEquations` below therefore
+ *    writes the number in as TEXT — and a span carrying a number is no longer
+ *    `:empty`, so the counter rule and the text can never both fire.
+ */
+
+/**
+ * Temml's own stylesheet, vendored. Generated from `temml/dist/Temml-Local.css`
+ * with the two departures described above. Do not hand-edit.
  */
+const TEMML_BASE = `math {
+  font-family: "Cambria Math", 'STIXTwoMath-Regular', 'NotoSansMath-Regular', math;
+  font-style: normal;
+  font-weight: normal;
+  line-height: normal;
+  font-size-adjust: none;
+  text-indent: 0;
+  text-transform: none;
+  letter-spacing: normal;
+  word-wrap: normal;
+  direction: ltr;
+  /* Prevent Firefox from omitting the dot on i or j. */
+  font-feature-settings: "dtls" off;
+}
+
+math * {
+  border-color: currentColor;
+}
+
+/* display: block is necessary in Firefox and Safari.
+ * Not in Chromium, which recognizes display: "block math" written inline. */
+ math.tml-display {
+  display: block;
+  width: 100%;
+}
+
+*.mathcal {
+  /* NotoSans */
+  font-feature-settings: 'ss01';
+}
+
+math .mathscr {
+  font-family: "Temml";
+}
+
+mo.tml-prime {
+  font-family: Temml;
+}
+
+/* Cramped superscripts in WebKit */
+mfrac > :nth-child(2),
+msqrt,
+mover > :first-child {
+  math-shift: compact
+}
+
+.menclose {
+  display: inline-block;
+  position: relative;
+  padding: 0.5ex 0ex;
+}
+.tml-cancelto {
+  display: inline-block;
+  position: absolute;
+  top: 0;
+  left: 0;
+  padding: 0.5ex 0ex;
+  background-color: currentColor;
+  /* Use the SVG as an alpha mask (painted by background-color) */
+  -webkit-mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'><defs><marker id='a' markerHeight='5' markerUnits='strokeWidth' markerWidth='7' orient='auto' refX='7' refY='2.5'><path fill='black' d='m0 0 7 2.5L0 5z'/></marker></defs><line x2='100%25' y1='100%25' stroke='black' stroke-width='.06em' marker-end='url(%23a)' vector-effect='non-scaling-stroke'/></svg>");
+          mask-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'><defs><marker id='a' markerHeight='5' markerUnits='strokeWidth' markerWidth='7' orient='auto' refX='7' refY='2.5'><path fill='black' d='m0 0 7 2.5L0 5z'/></marker></defs><line x2='100%25' y1='100%25' stroke='black' stroke-width='.06em' marker-end='url(%23a)' vector-effect='non-scaling-stroke'/></svg>");
+  -webkit-mask-repeat: no-repeat;
+          mask-repeat: no-repeat;
+  -webkit-mask-size: 100% 100%;
+          mask-size: 100% 100%;
+  -webkit-mask-position: 0 0;
+          mask-position: 0 0;
+}
+
+@supports (-moz-appearance: none) {
+  /* \vec w/o italic correction for Firefox */
+  .tml-vec {
+    transform: scale(0.75)
+  }
+  /* Fix \cancelto in Firefox */
+  .ff-narrow {
+    width: 0em;
+  }
+  .ff-nudge-left {
+    margin-left: -0.2em;
+  }
+}
 
-export const MATH_CSS = `/* Temml's own class hooks — without these an aligned environment neither
-   aligns nor breathes. */
-.tml-right { text-align: right; }
-.tml-left { text-align: left; }
-.tml-sml-pad { padding-left: 0.05em; }
-/* Row spacing. The browser gives mtd no vertical padding, so state the
-   MathML-Core default here; Temml's own CSS only adjusts it for jot. */
-math mtd { padding-top: 0.5ex; padding-bottom: 0.5ex; }
-math mtable.tml-jot mtd { padding-top: 0.7ex; padding-bottom: 0.7ex; }
-/* AMS auto-numbering, for lanes that keep our CSS counter.
-
-   Scoped to :empty because the document lanes cannot rely on it -- Paged.js
-   rewrites counters for its own pagination and strips counter-increment, so
-   every equation rendered as "(0)" (measured 2026-07-31; the declaration
-   survives intact without the polyfill). press therefore writes the numbers
-   into the spans as text, and a span carrying a number is no longer :empty, so
-   the two can never both fire.
-
-   AMS auto-numbering. Which equations number is the AUTHOR's choice, made in
-   LaTeX: align and equation number, aligned and the starred forms do not.
-   Without these two rules that choice was discarded -- align and align-star
-   rendered identically, so an author who asked for numbers silently got none.
-   (No backticks in here: this string is a JS template literal.) */
+@supports (not (-moz-appearance: none)) {
+  /* Chromium and WebKit */
+  /* prime vertical alignment */
+  mo.tml-prime {
+    font-family: Temml;
+  }
+  /* Italic correction on superscripts */
+  .tml-sml-pad {
+    padding-left: 0.05em;
+  }
+  .tml-med-pad {
+    padding-left: 0.10em;
+  }
+  .tml-lrg-pad {
+    padding-left: 0.15em;
+  }
+}
+
+@supports (-webkit-backdrop-filter: blur(1px)) {
+  /* WebKit vertical & italic correction on accents */
+  .wbk-acc {
+    /* lower by x-height distance */
+    transform: translate(0em, 0.431em);
+  }
+  .wbk-sml {
+    transform: translate(0.07em, 0);
+  }
+  .wbk-sml-acc {
+    transform: translate(0.07em, 0.431em);
+  }
+  .wbk-sml-vec {
+    transform: scale(0.75) translate(0.07em, 0);
+  }
+  .wbk-med {
+    transform: translate(0.14em, 0);
+  }
+  .wbk-med-acc {
+    transform: translate(0.14em, 0.431em);
+  }
+  .wbk-med-vec {
+    transform: scale(0.75) translate(0.14em, 0);
+  }
+  .wbk-lrg {
+    transform: translate(0.21em, 0);
+  }
+  .wbk-lrg-acc {
+    transform: translate(0.21em, 0.431em);
+  }
+  .wbk-lrg-vec {
+    transform: scale(0.75) translate(0.21em, 0);
+  }
+}
+
+/* \cancel & \phase use background images. Get them to print. */
+menclose {
+  -webkit-print-color-adjust: exact;  /* Chrome & Edge */
+          print-color-adjust: exact;
+}
+
+/* Array cell justification in Firefox & WebKit */
+.tml-right {
+  text-align: right;
+}
+.tml-left {
+  text-align: left;
+}
+
+/* For CD labels that grow to the left in Firefox and WebKit */
+.tml-shift-left { margin-left:-200% }
+
+/* Styles for Chromium only */
+@supports (not (-webkit-backdrop-filter: blur(1px))) and (not (-moz-appearance: none)) {
+  /* Italic correction on accents */
+  .chr-sml {
+    transform: translate(0.07em, 0)
+  }
+  .chr-sml-vec {
+    transform: scale(0.75) translate(0.07em, 0)
+  }
+  .chr-med {
+    transform: translate(0.14em, 0)
+  }
+  .chr-med-vec {
+    transform: scale(0.75) translate(0.14em, 0)
+  }
+  .chr-lrg {
+    transform: translate(0.21em, 0)
+  }
+  .chr-lrg-vec {
+    transform: scale(0.75) translate(0.21em, 0)
+  }
+
+  /* For CD labels that grow to the left */
+  .tml-shift-left { margin-left:-100% }
+
+  /* MathML Core & Chromium do not support the MathML 3.0 element <menclose> attributes. */
+  /* So use styles. */
+  menclose {
+    position: relative;
+    padding: 0.5ex 0ex;
+  }
+  
+    .tml-overline {
+    padding: 0.1em 0 0 0;
+    border-top: 0.065em solid;
+  }
+
+  .tml-underline {
+    padding: 0 0 0.1em 0;
+    border-bottom: 0.065em solid;
+  }
+
+  .tml-cancel {
+    display: inline-block;
+    position: absolute;
+    left: 0.5px;
+    bottom: 0;
+    width: 100%;
+    height: 100%;
+    background-color: currentColor;
+  }
+  .upstrike {
+    clip-path: polygon(0.05em 100%, 0em calc(100% - 0.05em), calc(100% - 0.05em) 0em, 100% 0.05em);
+  }
+  .downstrike {
+    clip-path: polygon(0em 0.05em, 0.05em 0em, 100% calc(100% - 0.05em), calc(100% - 0.05em) 100%);
+  }
+  .sout {
+    clip-path: polygon(0em calc(55% + 0.0333em), 0em calc(55% - 0.0333em), 100% calc(55% - 0.0333em), 100% calc(55% + 0.0333em));
+  }
+  .tml-xcancel {
+    clip-path: polygon(0.05em 0em, 0em 0.05em, calc(50% - 0.05em) 50%, 0em calc(100% - 0.05em), 0.05em 100%, 50% calc(50% + 0.05em), calc(100% - 0.05em) 100%, 100% calc(100% - 0.05em), calc(50% + 0.05em) 50%, 100% 0.05em, calc(100% - 0.05em) 0%, 50% calc(50% - 0.05em));
+  }
+
+  .longdiv-top {
+    border-top: 0.067em solid;
+    padding: 0.1em 0.2em 0.2em 0.433em;
+  }
+  .longdiv-arc {
+    position: absolute;
+    top: 0;
+    bottom: 0.1em;
+    left: -0.4em;
+    width: 0.7em;
+    border: 0.067em solid;
+    transform: translateY(-0.067em);
+    border-radius: 70%;
+    clip-path: inset(0 0 0 0.4em);
+    box-sizing: border-box;}
+    .menclose {display: inline-block;
+    text-align: left;
+    position: relative;
+  }
+  
+  .phasor-bottom {
+    border-bottom: 0.067em solid;
+    padding: 0.2em 0.2em 0.1em 0.6em;
+  }
+  .phasor-angle {
+    display: inline-block;
+    position: absolute;
+    left: 0.5px;
+    bottom: -0.04em;
+    height: 100%;
+    aspect-ratio: 0.5;
+    background-color: currentColor;
+    clip-path: polygon(0.05em 100%, 0em calc(100% - 0.05em), calc(100% - 0.05em) 0em, 100% 0.05em);
+  }
+
+  .tml-fbox {
+    padding: 3pt;
+    border: 1px solid;
+  }
+
+  .circle-pad {
+    padding: 0.267em;
+  }
+  .textcircle {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    right: 0;
+    left: 0;
+    border: 0.067em solid;
+    border-radius: 50%;
+   }
+
+   .actuarial {
+    padding: 0.03889em 0.03889em 0 0.03889em;
+    border-width: 0.08em 0.08em 0em 0em;
+    border-style: solid;
+    margin-right: 0.03889em;
+   }
+
+   /* Stretch \widetilde */
+  .tml-crooked-2 {
+    transform: scale(2.0, 1.1)
+  }
+  .tml-crooked-3 {
+    transform: scale(3.0, 1.3)
+  }
+  .tml-crooked-4 {
+    transform: scale(4.0, 1.4)
+  }
+  /* set array cell justification */
+  .tml-right {
+    text-align: -webkit-right;
+  }
+  .tml-left {
+    text-align: -webkit-left;
+  }
+}
+
+.special-fraction {
+  font-family: 'STIX TWO', 'Times New Roman', Times, Tinos, serif;
+}
+
+/* flex-wrap for line-breaking in Chromium */
+math {
+  display: inline-flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+}
+math > mrow {
+  padding: 0.5ex 0ex;
+}
+
+/* Default mtd top padding is 0.5ex per MathML-Core and user-agent CSS */
+/* We adjust for jot and small */
+mtable.tml-jot mtd {
+  padding-top: 0.7ex;
+  padding-bottom: 0.7ex;
+}
+mtable.tml-small mtd {
+  padding-top: 0.35ex;
+  padding-bottom: 0.35ex;
+}
+
+/* Firefox */
+@-moz-document url-prefix() {
+  /* Avoid flex-wrap */
+  math { display: inline; }
+  math > mrow { padding: 0 }
+  /* Adjust Firefox spacing between array rows */
+  mtd, mtable.tml-small mtd { padding-top: 0; padding-bottom: 0; }
+  mtable.tml-jot mtd { padding-top: 0.2ex; padding-bottom: 0.ex; }
+}
+
+/* AMS environment auto-numbering via CSS counter. */
 .tml-eqn:empty::before {
   counter-increment: tmlEqnNo;
   content: "(" counter(tmlEqnNo) ")";
 }
+
 body {
   counter-reset: tmlEqnNo;
+}`
+
+/**
+ * What Temml does not have. Kept byte-identical to the rules in
+ * `@uniweb/kit/math-tokens.css`, which the parity test enforces.
+ *
+ * 1. `mtd` padding: Temml's sheet only ADJUSTS row spacing for jot and small,
+ *    on the stated assumption that "default mtd top padding is 0.5ex per
+ *    MathML-Core and user-agent CSS". Measured in Chrome (2026-07), a pristine
+ *    `mtd` gets 0px, and a `pmatrix` or `cases` carries no `tml-*` class at
+ *    all — so its rows touch. Guarded to exclude Firefox because Temml
+ *    deliberately ZEROES mtd padding there, and an unguarded `math mtd`
+ *    outranks it on specificity (0,0,2 vs 0,0,1) regardless of the at-rule.
+ *
+ * 2. Display math needs CSS block layout, not MathML layout, for an equation
+ *    TAG to reach the right margin. Temml already declares
+ *    `math.tml-display { display: block; width: 100% }` and cannot win: it emits
+ *    `style="display:block math"` inline on every display formula, and an
+ *    inline style beats any stylesheet rule. This restores Temml's own intent
+ *    with the `!important` its rule lacks, scoped with `:has()` so unnumbered
+ *    formulas keep MathML layout and stay centred.
+ */
+const UNIWEB_CORRECTIONS = `@supports (not (-moz-appearance: none)) {
+  math mtd { padding-top: 0.5ex; padding-bottom: 0.5ex; }
 }
-/* Display math needs CSS block layout, not MathML layout, for an equation TAG
-   to reach the right margin: the tag rides in an mtable whose width:100%
-   Chromium ignores under display: block math, collapsing the spacer cells so
-   "(1)" sits glued to the equation instead of at the margin.
-
-   !important is not decoration. Temml emits style=display:block math on
-   every display formula unconditionally — no option turns it off — so an inline
-   style beats any rule we write, including Temml's own math.tml-display { display: block }, which is exactly what this restores. Fixing it here
-   rather than in the generator also repairs math that was already built.
-
-   Scoped with :has() to formulas that actually carry a tag. Switching every
-   display formula to CSS block layout would left-align the lot -- MathML layout
-   is what centres them -- so an unnumbered derivation or matrix keeps
-   display: block math and stays centred. Where :has() is unsupported the tag
-   simply does not reach the margin; nothing else changes. */
 math.tml-display:has(.tml-eqn) {
   display: block !important;
   width: 100%;
 }`
 
+export const MATH_CSS = `${TEMML_BASE}\n${UNIWEB_CORRECTIONS}`
+
 /**
  * Write equation numbers into Temml's tag spans as text.
  *

package/src/docx/Link.jsx

@@ -1,11 +1,13 @@
 /**
  * Link component for document output.
  *
- * Auto-detects external (http) vs internal (anchor) hyperlinks.
+ * Emits an in-document anchor for a `#fragment` and a destination for
+ * everything else. See `classifyHref` for why that is the whole rule.
  *
  * @param {Object} props
  * @param {Object} props.data - Link data: { label, href }
  */
+import { classifyHref } from './classifyHref.js'
 
 export default function Link({ data, ...props }) {
     if (!data) return null
@@ -14,18 +16,11 @@ export default function Link({ data, ...props }) {
 
     if (!href) return null
 
-    const isExternal = href.startsWith('http')
+    const { anchor } = classifyHref(href)
 
-    if (isExternal) {
+    if (anchor !== null) {
         return (
-            <a
-                data-type="externalHyperlink"
-                data-link={href}
-                href={href}
-                target="_blank"
-                rel="noopener noreferrer"
-                {...props}
-            >
+            <a data-type="internalHyperlink" data-anchor={anchor} href={href} {...props}>
                 <span data-type="text" data-style="Hyperlink">
                     {label || href}
                 </span>
@@ -33,15 +28,20 @@ export default function Link({ data, ...props }) {
         )
     }
 
-    // The IR's anchor is a BARE bookmark name — `data-bookmark="x"` becomes
-    // `<w:bookmarkStart w:name="x"/>` — so a documented `href: '#section-3'`
-    // has to lose its '#' or `w:anchor="#section-3"` never matches
-    // `w:name="section-3"` and Word resolves nothing. `href` keeps the
-    // fragment form, which is what the browser preview needs.
-    const anchor = href.startsWith('#') ? href.slice(1) : href
+    // `target`/`rel` only affect the React preview, never the compiled
+    // document, so they stay on the narrower http test they have always
+    // used — opening a mailto: or a site path in a new tab is not what
+    // this component previously did and is not what this change is about.
+    const offSite = href.startsWith('http')
 
     return (
-        <a data-type="internalHyperlink" data-anchor={anchor} href={href} {...props}>
+        <a
+            data-type="externalHyperlink"
+            data-link={href}
+            href={href}
+            {...(offSite ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+            {...props}
+        >
             <span data-type="text" data-style="Hyperlink">
                 {label || href}
             </span>

package/src/docx/LinkPart.jsx

@@ -13,6 +13,7 @@
  * in-document anchor the same way (see below).
  */
 import TextRun from './TextRun.jsx'
+import { classifyHref } from './classifyHref.js'
 
 /** `parts` is absent only for a hand-built part; fall back to the label. */
 export function labelRuns(part) {
@@ -22,15 +23,15 @@ export function labelRuns(part) {
 export default function LinkPart({ part }) {
     const href = part.href || ''
 
-    // An href starting with '#' is an in-document anchor, not a destination.
-    // Emitting it as an external hyperlink produced a relationship to the
-    // literal '#id' and no jump at all. The IR's anchor is a BARE bookmark
-    // name — `data-bookmark="x"` becomes `<w:bookmarkStart w:name="x"/>` — so
-    // the '#' is dropped here rather than shipped into `w:anchor`.
-    const anchor = href.startsWith('#') ? href.slice(1) : null
-    const linkAttrs = anchor
-        ? { 'data-type': 'internalHyperlink', 'data-anchor': anchor }
-        : { 'data-type': 'externalHyperlink', 'data-link': href }
+    // Same rule as the <Link> builder, from the same module rather than a
+    // second copy of the condition — the two used to classify the same href
+    // differently, which is what let `mailto:` compile to a dead anchor on
+    // one path and a working link on the other.
+    const { anchor } = classifyHref(href)
+    const linkAttrs =
+        anchor !== null
+            ? { 'data-type': 'internalHyperlink', 'data-anchor': anchor }
+            : { 'data-type': 'externalHyperlink', 'data-link': href }
 
     return (
         <a {...linkAttrs} href={href}>

package/src/docx/classifyHref.js

@@ -0,0 +1,61 @@
+/**
+ * Decide what SHAPE a link takes in the compiled document. INTERNAL helper —
+ * not in the barrel.
+ *
+ * The whole rule: **a `#fragment` is an in-document anchor; everything else is
+ * a destination, emitted verbatim.**
+ *
+ * ## Why that is the whole rule
+ *
+ * A fragment means "within this document" in every hypertext format, so this
+ * is the one classification Press can make from the href alone without knowing
+ * anything about the caller. Everything else — `https://…`, `mailto:…`,
+ * `/about`, `../sibling`, `page:installation` — is a destination Press has no
+ * standing to interpret.
+ *
+ * What this replaced was a guess: `href.startsWith('http')` treated everything
+ * else as an in-document anchor, so `mailto:a@b.com` and `/about` compiled to
+ * `<w:hyperlink w:anchor="mailto:a@b.com">` — a reference to a bookmark that
+ * cannot exist. That does not merely fail to navigate: **an anchor name is not
+ * a URL, so the destination is destroyed** and nothing downstream can recover
+ * it. Emitting it as a destination keeps it in the file, where a wrong link is
+ * at least visible and diagnosable.
+ *
+ * ## Why a bare name is NOT accepted as an anchor
+ *
+ * `section-3` and `page.html` are indistinguishable. Any rule that reads a bare
+ * token as a bookmark name necessarily turns some page links into dead anchors
+ * — which is the bug above. `#` is the disambiguator; that is what fragments
+ * are for. An author writes `#section-3`.
+ *
+ * ## Resolution is NOT Press's job
+ *
+ * Press does not know what `page:installation` means and must not learn. That
+ * is the same boundary the LaTeX inset helpers state for cite keys and xref
+ * ids — *"Resolution stays foundation-side … the foundation passes
+ * already-resolved keys in; Press's job is the emission shape"* — and the same
+ * one `DocumentProvider` states for `basePath` (*"Press itself has no awareness
+ * of the host runtime"*). Press declares no `@uniweb/*` dependency, and
+ * resolving a framework reference here would mean duplicating a resolver that
+ * lives in the runtime, which is how two implementations drift apart.
+ *
+ * So an unresolved `page:` reference compiles to a link pointing at the literal
+ * string. That is intended: it is the caller's unresolved input, preserved
+ * rather than swallowed. Callers compiling Uniweb content resolve authored
+ * hrefs before handing strings to the builders.
+ *
+ * @param {string} href
+ * @returns {{ anchor: string | null }} `anchor` is the bare bookmark name for
+ *   an in-document reference, or null when the href is a destination.
+ */
+export function classifyHref(href) {
+    if (!href || typeof href !== 'string') return { anchor: null }
+
+    // The bookmark name carries no '#'. A paragraph's `data-bookmark="x"`
+    // becomes `<w:bookmarkStart w:name="x"/>`, and Word matches
+    // `<w:hyperlink w:anchor="x">` against that name, so the fragment marker
+    // has to come off or the two never meet.
+    if (href.startsWith('#')) return { anchor: href.slice(1) }
+
+    return { anchor: null }
+}