@nuucognition/ncm-ui 0.1.0-dev.1 → 0.1.1-beta.1

package/dist/styles/nuu.css

@@ -8,10 +8,25 @@
  * Selectors target the data attributes emitted by ncm-ui block components.
  */
 
+/*
+ * Read mode and edit mode are ONE document at two moments, so they render at
+ * one size. The base and the heading ladder below are copied from the editor's
+ * own scale (`@nuucognition/nuu-editor`, `src/nuu-editor/nuu-editor.scss`):
+ * 1rem body at 1.65, headings 1.75 / 1.56 / 1.39 / 1.24 / 1.1em. Switching
+ * view must not resize a single glyph. Since the flow-block rhythm pass, the
+ * MARGINS are part of the same contract: the editor states this file's block
+ * gaps (1rem between siblings, per-level rem heading margins, the 1.5rem /
+ * 0.125rem list geometry) per element on its side. If one side of that pair
+ * moves, move the other in the same change.
+ *
+ * `--surf-reading-scale` is the reader's own text-size setting and stays on
+ * the base alone; everything under it is expressed in `em`, so one multiply
+ * carries the whole document.
+ */
 [data-ncm-document].ncm-theme-nuu {
   font-family: var(--font-sans);
-  font-size: calc(0.875rem * var(--surf-reading-scale, 1));
-  line-height: 1.55;
+  font-size: calc(1rem * var(--surf-reading-scale, 1));
+  line-height: 1.65;
   color: var(--foreground);
 }
 
@@ -19,7 +34,7 @@
   margin-top: 1rem;
 }
 
-/* Headings — Geist Sans, tracking-tight, normal weight on h1–h3 */
+/* Headings — the editor ladder: one 1.12 ratio, h5 a clear step above body */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"] {
   font-family: var(--font-heading);
   color: var(--foreground);
@@ -28,10 +43,10 @@
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"][data-ncm-level="1"] {
-  font-size: calc(1.875rem * var(--surf-reading-scale, 1));
-  line-height: 2.25rem;
-  letter-spacing: -0.025em;
-  font-weight: 400;
+  font-size: 1.75em;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  font-weight: 700;
   margin-top: 1.5rem;
 }
 
@@ -40,41 +55,105 @@
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"][data-ncm-level="2"] {
-  font-size: calc(1.5rem * var(--surf-reading-scale, 1));
-  line-height: 2rem;
-  letter-spacing: -0.025em;
-  font-weight: 400;
+  font-size: 1.56em;
+  line-height: 1.3;
+  letter-spacing: -0.01em;
+  font-weight: 660;
   margin-top: 1.25rem;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"][data-ncm-level="3"] {
-  font-size: calc(1.25rem * var(--surf-reading-scale, 1));
-  line-height: 1.75rem;
-  letter-spacing: -0.025em;
-  font-weight: 400;
+  font-size: 1.39em;
+  line-height: 1.3;
+  font-weight: 620;
   margin-top: 1rem;
 }
 
+/* h4/h5 open at 1.25rem, above the 1rem gap that follows them: a heading must
+   sit closer to the section it introduces than to the text it ends. At the
+   old 0.75rem the binding was inverted. */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"][data-ncm-level="4"] {
-  font-size: calc(0.875rem * var(--surf-reading-scale, 1));
-  line-height: 1.25rem;
-  font-weight: 500;
-  margin-top: 0.75rem;
+  font-size: 1.24em;
+  line-height: 1.3;
+  font-weight: 600;
+  margin-top: 1.25rem;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="header"][data-ncm-level="5"] {
-  font-size: calc(0.75rem * var(--surf-reading-scale, 1));
-  line-height: 1rem;
-  font-weight: 500;
-  letter-spacing: 0.05em;
-  text-transform: uppercase;
-  margin-top: 0.75rem;
+  font-size: 1.1em;
+  line-height: 1.3;
+  font-weight: 600;
+  margin-top: 1.25rem;
 }
 
 /* Paragraph */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="paragraph"] {
   color: var(--foreground);
-  line-height: 1.55;
+  line-height: 1.65;
+}
+
+/*
+ * Callout content keeps its line breaks. NCM parses a callout's quoted lines
+ * into paragraph content WITH the newlines preserved ("line one\nline two"),
+ * and default HTML whitespace collapsing was rendering them as one
+ * space-joined line — an author who wrote three lines in a callout saw one.
+ * Scoped to admonitions: everywhere else soft-wrapped source keeps its
+ * CommonMark space-join.
+ */
+[data-ncm-document].ncm-theme-nuu [data-ncm-admonition] [data-ncm-type="paragraph"] {
+  white-space: pre-wrap;
+}
+
+/*
+ * Callout (admonition) — a quiet card: rounded `md` corners (the NUU chrome
+ * step, stated as radius × 0.8 so a host's `--radius` carries through), 1px
+ * hairline border, a 2px colored left edge (the blockquote's own weight),
+ * tight padding. Rounded since (Task) 581, superseding the sharp-corner line
+ * of the minimalist pass — everything else from that pass stands. The type
+ * supplies only colors, through the `--ncm-callout-*` hooks; a host assigns
+ * them per `data-ncm-admonition-type` (Onyx does, from its palette
+ * families). Unset, every hook falls back to the neutral hairline card, so
+ * a host with no callout stylesheet — and any type a host does not cover —
+ * renders the same quiet shell with no color.
+ *
+ * These rules override the component's own rounded-card utilities
+ * (`rounded-lg bg-card p-4`): this file is unlayered and Tailwind utilities
+ * are layered, so the unlayered declarations win regardless of specificity.
+ * The hooks are set by hosts at ANY specificity — this file deliberately
+ * never assigns them, only reads them with fallbacks.
+ */
+[data-ncm-document].ncm-theme-nuu [data-ncm-admonition] {
+  border: 1px solid var(--ncm-callout-border, var(--border));
+  border-left: 2px solid var(--ncm-callout-edge, var(--border));
+  border-radius: calc(var(--radius, 0.625rem) * 0.8);
+  padding: 0.625rem 0.875rem;
+  background-color: var(--ncm-callout-tint, transparent);
+  /*
+   * An unbroken word must stay inside the card. Hosts lay the title out as a
+   * flex row (glyph + text), and a flex item's min-content size is the whole
+   * unbreakable word — the text ran past the card edge. `anywhere`, not
+   * `break-word`: only `anywhere` lets the break point count toward the
+   * min-content size, which is what the flex layout measures. Inherited, so
+   * the title and every content paragraph get it. ((Task) 581)
+   */
+  overflow-wrap: anywhere;
+}
+
+/*
+ * One gap for both title shapes. The static `<p>` title ships `mb-2` and the
+ * collapsible variant instead puts `mt-2` on the content that follows the
+ * `<summary>` — two different gaps for one anatomy. Zero the title's own
+ * margin and state the gap once on whatever follows the title; a collapsed
+ * `<details>` renders no content and so gets no stray bottom space.
+ */
+[data-ncm-document].ncm-theme-nuu [data-ncm-admonition] > [data-ncm-admonition-title] {
+  margin-bottom: 0;
+  color: var(--ncm-callout-title, var(--foreground));
+  font-weight: 600;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-admonition] > [data-ncm-admonition-title] + * {
+  margin-top: 0.375rem;
 }
 
 /* Blockquote */
@@ -82,7 +161,7 @@
   border-left: 2px solid var(--border);
   padding-left: 0.875rem;
   color: color-mix(in srgb, var(--foreground) 80%, transparent);
-  line-height: 1.55;
+  line-height: 1.65;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="blockquote"] p + p {
@@ -90,11 +169,16 @@
 }
 
 /* Lists */
+/*
+ * 1.5rem is the ONE marker-slot width all three list kinds share — disc,
+ * decimal, and the task checkbox (1em box + 0.5rem gap) — so the text column
+ * is identical across them at every depth.
+ */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_ordered"],
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_unordered"] {
-  padding-left: 1.25rem;
+  padding-left: 1.5rem;
   color: var(--foreground);
-  line-height: 1.55;
+  line-height: 1.65;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_ordered"] {
@@ -115,7 +199,7 @@
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_unordered"] ol,
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_unordered"] ul {
   margin-top: 0.125rem;
-  padding-left: 1.25rem;
+  padding-left: 1.5rem;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="list_ordered"] li::marker,
@@ -136,6 +220,90 @@
   list-style-type: decimal;
 }
 
+/*
+ * Task list — one spec with the editor's `ul[data-type="taskList"]` block in
+ * `@nuucognition/nuu-editor` (`src/nuu-editor/nuu-editor.scss`): flush-left
+ * rows 0.125rem apart, a 1em checkbox rounded 0.25rem (the nuu-ui Checkbox
+ * radius) drawn from theme tokens (border-token box, foreground fill when
+ * checked, background-coloured check), 0.5rem to the text — 1em + 0.5rem =
+ * the shared 1.5rem marker slot that lines task text up with disc and
+ * decimal text. Checked text dims to the muted tone with NO strike-through.
+ * A nested task list carries NO indent of its own: the checkbox slot IS the
+ * indent, the same 1.5rem step the other list kinds get from padding. If one
+ * side of that pair moves, move the other in the same change.
+ *
+ * The checkbox is drawn with `appearance: none` because the native control
+ * neither themes nor matches the editor's; the input stays a real (disabled)
+ * checkbox for the accessibility tree. The `> li` rule neutralizes the
+ * component's own Tailwind row gap so the 0.125rem list rhythm is the one
+ * answer.
+ */
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-list] {
+  padding-left: 0;
+  color: var(--foreground);
+  line-height: 1.65;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-list] > li:not(:last-child) {
+  margin-bottom: 0;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-list] li + li {
+  margin-top: 0.125rem;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-list] [data-ncm-list-nested] {
+  /* No margin: the nested row's own checkbox slot (1em + 0.5rem) is the
+     1.5rem indent, the same step disc and decimal get from padding. */
+  margin-left: 0;
+  margin-top: 0.125rem;
+}
+
+/* Top-aligned like the editor (whose checkbox sits 0.375rem into the row):
+   on a wrapped item the box stays on the first line instead of centring
+   across the whole item. */
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-item] > span {
+  gap: 0.5rem;
+  align-items: flex-start;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-item] input[type="checkbox"] {
+  appearance: none;
+  -webkit-appearance: none;
+  width: 1em;
+  height: 1em;
+  margin: 0.375rem 0 0;
+  border: 1px solid var(--border);
+  /* nuu-ui's Checkbox radius (rounded-[4px]). */
+  border-radius: 0.25rem;
+  background-color: transparent;
+  position: relative;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-item] input[type="checkbox"]:checked {
+  background-color: var(--foreground);
+  border-color: var(--foreground);
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-item] input[type="checkbox"]:checked::before {
+  content: "";
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  width: 0.75em;
+  height: 0.75em;
+  background-color: var(--background);
+  -webkit-mask: url("data:image/svg+xml,%3Csvg%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22currentColor%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%3Cpath%20fill-rule%3D%22evenodd%22%20clip-rule%3D%22evenodd%22%20d%3D%22M21.4142%204.58579C22.1953%205.36683%2022.1953%206.63317%2021.4142%207.41421L10.4142%2018.4142C9.63317%2019.1953%208.36684%2019.1953%207.58579%2018.4142L2.58579%2013.4142C1.80474%2012.6332%201.80474%2011.3668%202.58579%2010.5858C3.36683%209.80474%204.63317%209.80474%205.41421%2010.5858L9%2014.1716L18.5858%204.58579C19.3668%203.80474%2020.6332%203.80474%2021.4142%204.58579Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E")
+    center/contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22currentColor%22%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%3E%3Cpath%20fill-rule%3D%22evenodd%22%20clip-rule%3D%22evenodd%22%20d%3D%22M21.4142%204.58579C22.1953%205.36683%2022.1953%206.63317%2021.4142%207.41421L10.4142%2018.4142C9.63317%2019.1953%208.36684%2019.1953%207.58579%2018.4142L2.58579%2013.4142C1.80474%2012.6332%201.80474%2011.3668%202.58579%2010.5858C3.36683%209.80474%204.63317%209.80474%205.41421%2010.5858L9%2014.1716L18.5858%204.58579C19.3668%203.80474%2020.6332%203.80474%2021.4142%204.58579Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E")
+    center/contain no-repeat;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-task-item][data-ncm-checked="true"] > span > span {
+  color: var(--muted-foreground);
+}
+
 /* Tables */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="table"] {
   width: 100%;
@@ -145,7 +313,7 @@
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="table"] table {
   width: 100%;
   border-collapse: collapse;
-  font-size: calc(0.75rem * var(--surf-reading-scale, 1));
+  font-size: 0.857em;
 }
 
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="table"] th {
@@ -168,27 +336,50 @@
   background-color: color-mix(in srgb, var(--muted) 50%, transparent);
 }
 
+/* An empty cell keeps its line box, so an entirely blank row renders at full
+   height instead of collapsing to its padding. */
+[data-ncm-document].ncm-theme-nuu [data-ncm-type="table"] th:empty::after,
+[data-ncm-document].ncm-theme-nuu [data-ncm-type="table"] td:empty::after {
+  content: "\00a0";
+}
+
 /* Code (block) */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="code"] {
   position: relative;
 }
 
+/* Minimalist, matching the editor's code block at rest: bare text — no fill,
+   no visible box. The border keeps its 1px width as transparent so the text
+   sits at exactly the editor's inset (its border reveals on hover/caret). The
+   editor's `pre` rule mirrors this — move both together. */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="code"] pre {
   overflow-x: auto;
-  border: 1px solid var(--border);
-  border-radius: var(--radius, 0.625rem);
+  border: 1px solid transparent;
+  border-radius: 0;
   padding: 0.75rem;
-  background-color: var(--muted);
+  background-color: transparent;
   color: var(--foreground);
   font-family: var(--font-mono);
-  font-size: calc(0.875rem * var(--surf-reading-scale, 1));
-  line-height: 1.6;
+  font-size: 0.875em;
+  line-height: 1.55;
+}
+
+/* Parse warning (NcmBlockPreview) — the reader-mode display for a block
+   source that cannot be parsed as its block type. Minimalist: muted text,
+   hairline border, sharp corners. */
+[data-ncm-parse-warning] {
+  border: 1px solid var(--border);
+  padding: 0.5rem 0.75rem;
+  color: var(--muted-foreground);
+  font-family: var(--font-sans);
+  font-size: 0.857em;
+  line-height: 1.5;
 }
 
 /* Inline code */
 [data-ncm-document].ncm-theme-nuu [data-ncm-token="code"] {
   font-family: var(--font-mono);
-  font-size: calc(0.75rem * var(--surf-reading-scale, 1));
+  font-size: 0.857em;
   padding: 0.125rem 0.25rem;
   border-radius: 0.25rem;
   background-color: var(--muted);
@@ -212,17 +403,111 @@
   text-underline-offset: 4px;
 }
 
+/*
+ * AMBIGUOUS IS A WARNING, NOT A FAILURE — and this rule used to say otherwise.
+ *
+ * It painted `--fire-text`/`--destructive`, i.e. RED, while the EDIT surface
+ * paints red for a MISSING link and amber for an ambiguous one. The same hue
+ * therefore carried two different facts depending on which mode the reader was
+ * in, which is worse than either surface being wrong on its own: a reader who
+ * learns what red means in one mode is actively misled by the other.
+ *
+ * The vocabulary this settles on, ruled in room `onyx-uiux` on 2026-07-31 and
+ * applied across both surfaces:
+ *
+ *   missing    pending — muted foreground, dashed. A link to a document that
+ *              is not in this mesh is very often a PLAN, not a mistake; that is
+ *              also the Obsidian benchmark, where an unresolved link is the
+ *              link colour faded and never red.
+ *   ambiguous  warning — amber, dotted. Several targets match; the author has
+ *              something to decide, but nothing has failed.
+ *   red        reserved for GENUINE FAILURE — in this package, an embed whose
+ *              bytes did not arrive (see `renderImageError`).
+ *
+ * A DELIBERATE VISUAL CHANGE FOR EVERY EMBEDDER, not just for Onyx: an
+ * ambiguous reference stops being drawn as an error. Recorded in the README.
+ */
 [data-ncm-document].ncm-theme-nuu [data-ncm-token="wiki_link"][data-ncm-wikilink-status="ambiguous"],
 [data-ncm-document].ncm-theme-nuu [data-ncm-token="wiki_embed"][data-ncm-wikiembed-status="ambiguous"] {
-  color: var(--fire-text, var(--destructive));
+  color: var(--sun-text, var(--warning, #b45309));
+  text-decoration: underline dotted;
+  text-underline-offset: 4px;
+}
+
+/*
+ * Wikilink focus ring.
+ *
+ * `renderer.tsx` already emits a real <a> or <button> for an actionable
+ * wikilink, so read-mode links have ALWAYS been in the tab order — a keyboard
+ * user could reach them and had no way to see that they had. Measured on the
+ * Onyx read surface in both themes: outline-style none, box-shadow none, while
+ * the surrounding chrome buttons showed a ring. That is the whole of
+ * known-adopted issue 095#5, and it belongs here rather than in a host: an
+ * embedder gets no focus affordance for these elements from anywhere else.
+ *
+ * A NEW rule, touching no existing selector. It paints only when a host has
+ * made the link actionable AND the browser is in keyboard-focus mode, so no
+ * rendering that exists today changes.
+ *
+ * (Landed as the negotiated ncm-ui freeze exception for Task 507, approved in
+ * room `onyx-uiux` on 2026-07-31. The TSX half of the original proposal was
+ * withdrawn: the button is focusable by construction and needed nothing.)
+ */
+[data-ncm-document].ncm-theme-nuu [data-ncm-token="wiki_link"]:focus-visible {
+  outline: 2px solid var(--ring, currentColor);
+  outline-offset: 2px;
+  border-radius: 0.1875rem;
+}
+
+/*
+ * Pointer cursor for the ACTIONABLE wikilink elements — the <a> a host's
+ * `resolveWikiLinkHref` produces and the <button> a bare `onWikiLinkClick`
+ * produces. The anchor has the pointer from the user agent already; the button
+ * does not — Tailwind v4's preflight leaves buttons on the default arrow, so in
+ * Onyx a clickable wikilink did not read as clickable. The element selectors
+ * exclude the inert <span> a host with neither config gets, which stays on the
+ * text cursor on purpose. (Task 558.)
+ */
+[data-ncm-document].ncm-theme-nuu a[data-ncm-token="wiki_link"],
+[data-ncm-document].ncm-theme-nuu button[data-ncm-token="wiki_link"] {
+  cursor: pointer;
 }
 
-/* Horizontal rule */
+/*
+ * The embed BUTTON — the element `EmbeddingsConfig.onEmbedClick` produces.
+ *
+ * Both rules below can only ever match an element that does not exist unless a
+ * host opted in, so neither can change a rendering that ships today.
+ *
+ * The reset first: a `<button>` in the middle of a sentence arrives wearing the
+ * user agent's chrome — its own background, border, padding and font — and an
+ * embedded document is a piece of the prose, not a form control. Onyx never saw
+ * this because Tailwind's preflight resets buttons app-wide; an embedder
+ * without one would have. Then the ring, the sibling of the wikilink rule
+ * directly above: the button is a tab stop by construction, so it needs to be
+ * able to say when it has been reached.
+ */
+[data-ncm-document].ncm-theme-nuu button[data-ncm-token="wiki_embed"] {
+  appearance: none;
+  padding: 0;
+  border: 0;
+  background: none;
+  font: inherit;
+  cursor: pointer;
+}
+
+[data-ncm-document].ncm-theme-nuu [data-ncm-token="wiki_embed"]:focus-visible {
+  outline: 2px solid var(--ring, currentColor);
+  outline-offset: 2px;
+  border-radius: 0.1875rem;
+}
+
+/* Horizontal rule — 1em on both sides, matching the editor's hr rule. */
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="horizontal_rule"] {
   border: 0;
   border-top: 1px solid var(--border);
-  margin-top: 1.25rem;
-  margin-bottom: 1.25rem;
+  margin-top: 1em;
+  margin-bottom: 1em;
 }
 
 /* Embeddings */
@@ -235,7 +520,7 @@
 [data-ncm-document].ncm-theme-nuu [data-ncm-type="embedding"] figcaption {
   margin-top: 0.5rem;
   text-align: left;
-  font-size: 0.75rem;
+  font-size: 0.857em;
   color: var(--muted-foreground);
 }
 
@@ -253,7 +538,7 @@
   background-color: var(--muted);
   color: var(--foreground);
   font-family: var(--font-mono);
-  font-size: 0.875rem;
+  font-size: 1em;
 }
 
 /* OpenDyslexic3 — newest, refined letterforms of the OpenDyslexic family
@@ -344,7 +629,7 @@
   background: var(--popover, var(--background, var(--muted)));
   color: var(--popover-foreground, var(--foreground));
   box-shadow: 0 4px 12px rgb(0 0 0 / 0.12);
-  font-size: calc(0.8125rem * var(--surf-reading-scale, 1));
+  font-size: 0.929em;
   font-weight: 400;
   line-height: 1.5;
   white-space: normal;

package/dist/styles/paper.css

@@ -172,6 +172,13 @@
   color: var(--muted-foreground);
 }
 
+/* An empty cell keeps its line box, so an entirely blank row renders at full
+   height instead of collapsing to its padding. */
+[data-ncm-document].ncm-theme-paper [data-ncm-type="table"] th:empty::after,
+[data-ncm-document].ncm-theme-paper [data-ncm-type="table"] td:empty::after {
+  content: "\00a0";
+}
+
 /* Code (block) */
 [data-ncm-document].ncm-theme-paper [data-ncm-type="code"] {
   position: relative;
@@ -218,9 +225,63 @@
   text-underline-offset: 3px;
 }
 
+/*
+ * Ambiguous is a warning, not a failure — the paper sibling of the rule in
+ * `nuu.css`, where the whole vocabulary argument is written down. Same change,
+ * same reason, kept in step so the two themes cannot disagree about what a
+ * colour means. Paper's dotted underline is 1px-thin and offset 3px like every
+ * other decoration in this sheet.
+ */
 [data-ncm-document].ncm-theme-paper [data-ncm-token="wiki_link"][data-ncm-wikilink-status="ambiguous"],
 [data-ncm-document].ncm-theme-paper [data-ncm-token="wiki_embed"][data-ncm-wikiembed-status="ambiguous"] {
-  color: var(--fire-text, var(--destructive));
+  color: var(--sun-text, var(--warning, #b45309));
+  text-decoration: underline dotted;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+}
+
+/*
+ * Wikilink focus ring — the paper sibling of the rule in `nuu.css`; see that
+ * file for the full reasoning. Kept in step deliberately: a focus affordance
+ * that exists in one theme and not the other is a keyboard user's experience
+ * changing with a setting that is supposed to be about typography.
+ *
+ * `--ring` with a `currentColor` fallback, so a paper host that defines no ring
+ * token still gets a visible ring in the link's own ink rather than nothing.
+ */
+[data-ncm-document].ncm-theme-paper [data-ncm-token="wiki_link"]:focus-visible {
+  outline: 2px solid var(--ring, currentColor);
+  outline-offset: 2px;
+  border-radius: 0.1875rem;
+}
+
+/*
+ * Pointer cursor for the actionable wikilink elements — the paper sibling of
+ * the rule in `nuu.css`; that file carries the reasoning. (Task 558.)
+ */
+[data-ncm-document].ncm-theme-paper a[data-ncm-token="wiki_link"],
+[data-ncm-document].ncm-theme-paper button[data-ncm-token="wiki_link"] {
+  cursor: pointer;
+}
+
+/*
+ * The embed button — paper siblings of the two rules in `nuu.css`; that file
+ * carries the reasoning. Both can only match an element a host opted into, so
+ * neither changes anything that renders today.
+ */
+[data-ncm-document].ncm-theme-paper button[data-ncm-token="wiki_embed"] {
+  appearance: none;
+  padding: 0;
+  border: 0;
+  background: none;
+  font: inherit;
+  cursor: pointer;
+}
+
+[data-ncm-document].ncm-theme-paper [data-ncm-token="wiki_embed"]:focus-visible {
+  outline: 2px solid var(--ring, currentColor);
+  outline-offset: 2px;
+  border-radius: 0.1875rem;
 }
 
 /* Horizontal rule */

package/dist/{use-ncm-config-D0doMYTH.d.ts → use-ncm-config-CnntcShj.d.ts}

@@ -1,6 +1,6 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { MeshResolveLinkResult, MeshHydrationContext } from '@nuucognition/mesh-core';
+import { MeshResolveEmbedResult, MeshResolveLinkResult, MeshHydrationContext } from '@nuucognition/mesh-core';
 import { EmbedType } from '@nuucognition/ncm';
 import { c as EmbeddingRendererRegistry, b as BlockRendererRegistry } from './renderers-C5f41FCy.js';
 
@@ -23,6 +23,28 @@ interface InlineConfig {
      */
     referencePopover?: boolean;
 }
+/**
+ * What a host draws in place of an image whose bytes never arrived.
+ *
+ * The renderer cannot answer this itself. Whether an `<img src>` actually
+ * loads is only learned by trying, and what to SAY about the failure is the
+ * host's vocabulary — a mesh embedder can offer a retry against its own blob
+ * cache, a static-site embedder has nothing to retry and should say so.
+ */
+interface ImageErrorProps {
+    /** The embed target exactly as the author wrote it (`logo.png`, a URL). */
+    target: string;
+    /** The URL that was handed to `<img src>` and did not load. */
+    src: string;
+    /** The alt text from the source, if the author wrote one. */
+    alt?: string;
+    /**
+     * Re-attempt the load. The `<img>` is re-keyed, so this is a real second
+     * fetch rather than the browser's cached failure. A host that owns the URL
+     * (a blob cache) should refresh it first and then call this.
+     */
+    retry: () => void;
+}
 /**
  * Configuration for embedding rendering
  */
@@ -32,6 +54,34 @@ interface EmbeddingsConfig {
     imageClassName?: string;
     videoClassName?: string;
     audioClassName?: string;
+    /**
+     * Render a failed image instead of leaving the browser's broken-image box.
+     *
+     * OPT-IN, and strictly so: with no renderer supplied the `<img>` carries no
+     * `onError` handler at all, so the emitted DOM is identical to what every
+     * consumer gets today — not merely visually identical. Supplying one is what
+     * turns an unloadable image into a state with a name and a way out.
+     *
+     * Applies to both spellings of an inline image — `![alt](url)` and an
+     * `![[target]]` that resolves to one.
+     */
+    renderImageError?: ComponentType<ImageErrorProps>;
+    /**
+     * Handle a click on a non-media embed — an embedded DOCUMENT, or any target
+     * whose type has no player.
+     *
+     * WITHOUT THIS the renderer emits `<a href={resolveUrl(...)}>`, which is only
+     * honest when the target really has a URL. A document in a title-addressed
+     * mesh does not: the host navigates in its own state, so the href ends up
+     * being the raw target, a relative URL that leads nowhere and copies as
+     * nonsense from the context menu.
+     *
+     * Supplying this renders the same content as a `<button>` instead, which
+     * claims nothing about URLs and is a real control — exactly the shape
+     * {@link InlineConfig.onWikiLinkClick} already produces for a wikilink with
+     * no href. Absent, nothing changes.
+     */
+    onEmbedClick?: (target: string, result: MeshResolveEmbedResult | null, event: React.MouseEvent) => void;
 }
 /**
  * Code rendering configuration
@@ -43,6 +93,7 @@ interface CodeConfig {
         className?: string;
     }>;
     lineNumbers?: boolean;
+    /** Opt-in since the minimalist block pass: the button renders only on `true`. */
     copyButton?: boolean;
 }
 /**
@@ -109,6 +160,6 @@ interface NcmProviderProps {
  * </NcmProvider>
  * ```
  */
-declare function NcmProvider({ config, children }: NcmProviderProps): react_jsx_runtime.JSX.Element;
+declare function NcmProvider({ config, children }: NcmProviderProps): react.JSX.Element;
 
-export { type CodeConfig as C, type EmbeddingsConfig as E, type InlineConfig as I, type NcmConfig as N, NcmProvider as a, type NcmProviderProps as b, useNcmConfig as u };
+export { type CodeConfig as C, type EmbeddingsConfig as E, type ImageErrorProps as I, type NcmConfig as N, type InlineConfig as a, NcmProvider as b, type NcmProviderProps as c, useNcmConfig as u };