@celestia-island/hikari 0.55.283 → 0.55.285

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.283",
+  "version": "0.55.285",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkAmbientLayer.styles.test.ts

@@ -35,6 +35,25 @@ describe("HkAmbientLayer pointer contract", () => {
     const blockStart = declarations.lastIndexOf('[data-pointer-events="auto"]', autoAt);
     expect(blockStart).toBeGreaterThan(-1);
     expect(declarations.slice(blockStart, autoAt)).toContain("> *");
+    // EVERY ruleset is checked by SCOPE, not proximity: any block that
+    // states pointer-events:auto must be the child-scoped opt-in, and any
+    // other block stating pointer-events at all must say none (an earlier
+    // round flagged both the first-only and the proximity-based shapes).
+    const rulesets = [...declarations.matchAll(/([^{}]+)\{([^{}]*)\}/g)].map(
+      ([, selector, body]) => ({ selector: selector.trim(), body }),
+    );
+    expect(rulesets.length).toBeGreaterThan(0);
+    for (const { selector, body } of rulesets) {
+      if (!/pointer-events/.test(body)) continue;
+      if (/pointer-events:\s*auto/.test(body)) {
+        expect(selector).toContain('[data-pointer-events="auto"]');
+        expect(selector).toContain("> *");
+      } else {
+        expect(body).toMatch(/pointer-events:\s*none/);
+      }
+    }
+    // The wrapper's own block states the ghost rule exactly once.
+    expect(declarations.match(/pointer-events:\s*none/g)).toHaveLength(1);
   });
 
   it("sits on the HUD ordinal band, below its root's document elevation", () => {

package/src/components/HkCalendarHeatmap.scss

@@ -42,12 +42,20 @@
   }
 
   // Weekday rail: the first (Monday) and last (Sunday) rows carry the
-  // labels (the wowsp convention); sticky so it survives horizontal
-  // scroll on narrow screens.
+  // labels (the wowsp convention). `align-self: flex-end` rows-aligns
+  // the rail with the GRID, not with the -cells box: -cells is one
+  // marker strip taller than the grid (the month labels ride above
+  // it), so a stretched rail started its seven rows on the markers and
+  // every label sat one strip too high (2026-11-05 user report from
+  // the chest quota card). The rail's natural height (7 cells + 6
+  // gaps) equals the grid's exactly, so end-alignment is row-exact.
+  // No sticky mask on purpose: a hard-coded surface can't match every
+  // host card (it painted a visible stripe behind the labels), and
+  // sticky without a mask lets cells slide beneath the labels during
+  // horizontal scroll — the rail scrolls with the calendar instead
+  // (the GitHub convention).
   &-rail {
-    position: sticky;
-    left: 0;
-    z-index: 1;
+    align-self: flex-end;
     display: flex;
     flex-direction: column;
     flex-shrink: 0;
@@ -55,7 +63,6 @@
     font-size: 10px;
     line-height: 14px;
     color: var(--hi-color-muted);
-    background: var(--hi-color-surface);
 
     > span {
       white-space: nowrap;

package/src/components/HkMarkdownRenderer.chips.test.tsx

@@ -0,0 +1,178 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HkMarkdownRenderer from "./HkMarkdownRenderer";
+import { applyInlineChipsToBody, inlineChipDisplay, parseInlineChips } from "./inlineChips";
+
+/**
+ * Inline chip pass contract tests (the opt-in `inlineChips` mode):
+ * - the parser splits `{{ token }}` / `@ref` forms and preserves the
+ *   accessible text (tokens canonicalize their spacing, refs stay raw,
+ *   plain runs round-trip byte-exactly)
+ * - the boundary guards hold: emails, doubled `@`, code spans, code
+ *   fences and link text never chip
+ * - the component applies the pass only when the prop is on
+ *
+ * House style: raw createApp mounts torn down after each case; the
+ * async marked/DOMPurify settle uses a bounded poll.
+ */
+
+const mounts: { app: ReturnType<typeof createApp>; container: HTMLElement }[] = [];
+
+function mount(props: Record<string, unknown>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => h(HkMarkdownRenderer, props as never) });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+async function settleFor(root: HTMLElement, selector: string, tries = 100): Promise<void> {
+  for (let i = 0; i < tries; i += 1) {
+    if (root.querySelector(selector)) return;
+    await new Promise((r) => setTimeout(r, 5));
+    await nextTick();
+  }
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts) {
+    app.unmount();
+    container.remove();
+  }
+  mounts.length = 0;
+});
+
+describe("parseInlineChips", () => {
+  it("splits tokens, refs and plain runs in source order", () => {
+    expect(parseInlineChips("Badge: {{container_badge}} then @system/permission-mode")).toEqual([
+      { kind: "text", text: "Badge: " },
+      { kind: "token", token: "container_badge" },
+      { kind: "text", text: " then " },
+      { kind: "ref", raw: "@system/permission-mode" },
+    ]);
+  });
+
+  it("tokenizes with the shared grammar rules (bare ids only)", () => {
+    // Richer engine grammars stay literal — same rule as HkTemplateText.
+    expect(parseInlineChips("{{ a.b }} {{ x | filter }} {{ ok }}")).toEqual([
+      { kind: "text", text: "{{ a.b }} {{ x | filter }} " },
+      { kind: "token", token: "ok" },
+    ]);
+  });
+
+  it("guards the @ boundary: emails and doubled @ stay text", () => {
+    expect(parseInlineChips("mail foo@bar.com now")).toEqual([
+      { kind: "text", text: "mail foo@bar.com now" },
+    ]);
+    expect(parseInlineChips("user@@host")).toEqual([{ kind: "text", text: "user@@host" }]);
+    expect(parseInlineChips("word@notachip")).toEqual([{ kind: "text", text: "word@notachip" }]);
+  });
+
+  it("refs stop at punctuation and match bare handles", () => {
+    expect(parseInlineChips("see @system/x, then @demiurge.")).toEqual([
+      { kind: "text", text: "see " },
+      { kind: "ref", raw: "@system/x" },
+      { kind: "text", text: ", then " },
+      { kind: "ref", raw: "@demiurge" },
+      { kind: "text", text: "." },
+    ]);
+  });
+
+  it("chip display canonicalizes tokens and keeps refs raw", () => {
+    expect(inlineChipDisplay({ kind: "token", token: "current_datetime" })).toBe("{{ current_datetime }}");
+    expect(inlineChipDisplay({ kind: "ref", raw: "@system/related-todos" })).toBe("@system/related-todos");
+  });
+});
+
+describe("applyInlineChipsToBody", () => {
+  it("chips prose but never enters code, pre or links", () => {
+    const root = document.createElement("div");
+    root.innerHTML =
+      "<p>Badge {{container_badge}} ref @system/permission-mode mail a@b.com</p>" +
+      "<pre><code>{{ keep_literal }}</code></pre>" +
+      "<p><a href=\"https://x/@at/in-url\">link @text</a></p>";
+    const chips = applyInlineChipsToBody(root);
+    const chipEls = [...root.querySelectorAll("span.hk-tpl-chip")];
+    // Two prose chips only: the token and the ref (email, code, link excluded).
+    expect(chips).toBe(2);
+    expect(chipEls.map((el) => el.textContent)).toEqual(["{{ container_badge }}", "@system/permission-mode"]);
+    expect(chipEls[0]!.hasAttribute("data-ref")).toBe(false);
+    expect(chipEls[1]!.hasAttribute("data-ref")).toBe(true);
+    // Literal surfaces untouched.
+    expect(root.querySelector("code")!.textContent).toBe("{{ keep_literal }}");
+    expect(root.querySelector("a")!.textContent).toBe("link @text");
+    // Idempotent: a second pass finds nothing new to chip.
+    expect(applyInlineChipsToBody(root)).toBe(0);
+  });
+});
+
+describe("HkMarkdownRenderer inlineChips", () => {
+  it("chips tokens and refs when the prop is on", async () => {
+    const container = mount({
+      content: "Badge: {{container_badge}}\n\nRead @system/related-todos first.",
+      inlineChips: true,
+    });
+    await settleFor(container, ".hk-tpl-chip");
+    const chips = [...container.querySelectorAll("span.hk-tpl-chip")];
+    expect(chips.map((el) => el.textContent)).toEqual(["{{ container_badge }}", "@system/related-todos"]);
+  });
+
+  it("renders no chips by default (existing consumers unchanged)", async () => {
+    const container = mount({ content: "Badge: {{container_badge}} ref @system/related-todos" });
+    await settleFor(container, ".hk-markdown-body p");
+    await new Promise((r) => setTimeout(r, 10));
+    await nextTick();
+    expect(container.querySelectorAll(".hk-tpl-chip").length).toBe(0);
+    expect(container.textContent).toContain("{{container_badge}}");
+    expect(container.textContent).toContain("@system/related-todos");
+  });
+
+  it("guards the grammar boundaries the two implementations must share", () => {
+    // Multi-level refs, `@` at either end, a leading `_`/`-` segment.
+    expect(parseInlineChips("@a/b/c")).toEqual([{ kind: "ref", raw: "@a/b/c" }]);
+    expect(parseInlineChips("@sole")).toEqual([{ kind: "ref", raw: "@sole" }]);
+    expect(parseInlineChips("mail @")).toEqual([{ kind: "text", text: "mail @" }]);
+    expect(parseInlineChips("@_private @-x @--flag")).toEqual([
+      { kind: "text", text: "@_private @-x @--flag" },
+    ]);
+    // Never chips inside a bare URL (npm-scoped packages are common in
+    // prompt prose) — the Rust mirror guards this too.
+    expect(parseInlineChips("see https://www.npmjs.com/package/@celestia-island/hikari")).toEqual([
+      { kind: "text", text: "see https://www.npmjs.com/package/@celestia-island/hikari" },
+    ]);
+    // Carriage returns inside the braces are still the same token.
+    expect(parseInlineChips("{{\rname\r}}")).toEqual([{ kind: "token", token: "name" }]);
+  });
+
+  it("un-chips when the prop flips back off (same mount)", async () => {
+    // The chip pass mutates the DOM in place, so a naive watcher leaves the
+    // chips behind when the prop goes back to false — this drives the real
+    // toggle on ONE mounted instance.
+    const flag = ref(true);
+    const content = "Badge {{x}} and @a/b";
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({ render: () => h(HkMarkdownRenderer, { content, inlineChips: flag.value }) });
+    app.mount(container);
+    mounts.push({ app, container });
+
+    await settleFor(container, ".hk-tpl-chip");
+    expect(container.querySelectorAll(".hk-tpl-chip").length).toBe(2);
+
+    flag.value = false;
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 10));
+    await nextTick();
+    expect(container.querySelectorAll(".hk-tpl-chip").length).toBe(0);
+    expect(container.textContent).toContain("{{x}}");
+    expect(container.textContent).toContain("@a/b");
+
+    // ...and back on, still one mount.
+    flag.value = true;
+    await nextTick();
+    await settleFor(container, ".hk-tpl-chip");
+    expect(container.querySelectorAll(".hk-tpl-chip").length).toBe(2);
+  });
+});

package/src/components/HkMarkdownRenderer.scss

@@ -207,3 +207,41 @@
   @include backdrop-filter(blur(4px));
   z-index: 10;
 }
+
+/* ── Inline chips (opt-in `inlineChips` prop) ────────────────────────
+   Fill-template tokens (`{{ name }}`) and asset references (`@level/name`,
+   bare `@name`) chipped inside rendered prose. The look is the family's
+   `.hk-tpl-chip` (HkTemplateField.scss is canonical); duplicated here
+   SCOPED to the markdown body so a markdown-only consumer does not pull
+   the template editor's sheet. Refs take the muted variant: a reference
+   points elsewhere, it is not a fillable value, so it must not read as
+   a template token. */
+.hk-markdown-body .hk-tpl-chip {
+  display: inline-flex;
+  align-items: center;
+  padding: 0 var(--space-6, 6px);
+  border-radius: var(--radius-sm, 4px);
+  border: 1px solid color-mix(in srgb, var(--hi-color-primary) 32%, transparent);
+  background: color-mix(in srgb, var(--hi-color-primary) 12%, transparent);
+  color: color-mix(in srgb, var(--hi-color-primary) 70%, rgb(0 0 0));
+  font-family: var(--font-mono, monospace);
+  font-size: 0.8em;
+  line-height: 1.5;
+  white-space: nowrap;
+  /* NO user-select here: rendered prose IS content (see the sheet's own
+   * `user-select(text)` policy at the top and styles/selection.scss's
+   * "markdown body" content container). The editor chip in
+   * HkTemplateField.scss disables selection for caret/click handling;
+   * copying a PROMPT BODY must keep every `{{token}}` / `@ref` in the
+   * clipboard, so this scoped copy must not carry that rule. */
+
+  [data-theme="dark"] & {
+    color: color-mix(in srgb, var(--hi-color-primary) 60%, rgb(255 255 255));
+  }
+
+  &[data-ref] {
+    border-color: color-mix(in srgb, var(--hi-color-muted, #6c6c6c) 40%, transparent);
+    background: color-mix(in srgb, var(--hi-color-muted, #6c6c6c) 10%, transparent);
+    color: var(--hi-color-muted, #6c6c6c);
+  }
+}

package/src/components/HkMarkdownRenderer.tsx

@@ -1,6 +1,7 @@
 import { computed, defineComponent, nextTick, onBeforeUnmount, ref, watch } from "vue";
 import type { Renderer, Tokens } from "marked";
 import HSpinner from "./HkSpinner";
+import { applyInlineChipsToBody } from "./inlineChips";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { asIndexable } from "../utils/typing";
 import "./HkMarkdownRenderer.scss";
@@ -118,10 +119,26 @@ export default defineComponent({
     content: { type: String, required: true },
     loading: { type: Boolean, default: false },
     plain: { type: Boolean, default: false },
+    /**
+     * Opt-in inline chip pass: fill-template tokens (`{{ name }}`) and
+     * asset references (`@level/name`, bare `@name`) inside the
+     * rendered prose chip up as `.hk-tpl-chip` spans (refs carry
+     * `data-ref`, the muted variant). Applied AFTER sanitize, as pure
+     * DOM surgery with `textContent` only — the pass cannot introduce
+     * markup, and `code`/`pre`/`a` subtrees are skipped so literal
+     * code and link text stay verbatim. Off by default: every existing
+     * consumer renders exactly as before.
+     */
+    inlineChips: { type: Boolean, default: false },
   },
   setup(props) {
     const renderedHtml = ref("");
     const parseError = ref(false);
+    // Monotonic parse counter: `renderedHtml` does not change when the
+    // SAME body is re-parsed for a prop flip, so a watch on it would never
+    // fire — and the chip pass mutates the DOM in place, leaving chips
+    // behind after `inlineChips` goes back to false.
+    const parseSeq = ref(0);
 
     async function parse() {
       if (!props.content) {
@@ -138,11 +155,13 @@ export default defineComponent({
       } catch {
         parseError.value = true;
         renderedHtml.value = renderPlain(props.content);
+      } finally {
+        parseSeq.value += 1;
       }
     }
 
     watch(
-      () => [props.content, props.plain],
+      () => [props.content, props.plain, props.inlineChips],
       () => { void parse(); },
       { immediate: true },
     );
@@ -168,8 +187,20 @@ export default defineComponent({
       }
     }
 
-    watch(renderedHtml, () => {
-      void nextTick(syncOverlayScrollbars);
+    watch(parseSeq, () => {
+      void nextTick(() => {
+        const body = bodyRef.value;
+        if (!body) return;
+        // Re-seat the DOM on the pristine rendered HTML first: the chip
+        // pass mutates it in place, so a prop flip must start from the
+        // un-chipped markup (assigning the string Vue already patched is
+        // idempotent; when the body did not change it is the only write).
+        body.innerHTML = renderedHtml.value;
+        // The chip pass runs BEFORE the overlay scan: it splits text
+        // nodes, so the scan must reconcile against the final DOM.
+        if (props.inlineChips) applyInlineChipsToBody(body);
+        syncOverlayScrollbars();
+      });
     });
 
     onBeforeUnmount(() => {

package/src/components/HkScreenIdentifyCard.styles.test.ts

@@ -54,12 +54,35 @@ describe("HkScreenIdentifyCard layout contract", () => {
   });
 
   it("parks the card in every corner through placement attributes", () => {
-    for (const placement of ["bottom-right", "top-left", "top-right"]) {
-      expect(scss).toContain(`&[data-placement="${placement}"]`);
+    // Each non-default corner must OVERRIDE the exact edges that move it
+    // there — an earlier round flagged this guard as presence-only, so a
+    // placement block that forgot its edge rule stayed green.
+    const corners: Array<[string, RegExp[]]> = [
+      // End-side corners must ALSO release the logical start edge — an
+      // over-constrained inset would resolve to the start edge and leave
+      // the card bottom-left no matter the placement (R1 V-3 probe).
+      ["bottom-right", [/inset-inline-end:\s*var\(--space-16/, /inset-inline-start:\s*auto/]],
+      ["top-left", [/top:\s*var\(--space-16/, /bottom:\s*auto/]],
+      [
+        "top-right",
+        [
+          /inset-inline-end:\s*var\(--space-16/,
+          /inset-inline-start:\s*auto/,
+          /top:\s*var\(--space-16[\s\S]*bottom:\s*auto/,
+        ],
+      ],
+    ];
+    for (const [placement, edges] of corners) {
+      const block = ruleBlock(`&[data-placement="${placement}"]`);
+      for (const edge of edges) {
+        expect(block).toMatch(edge);
+      }
     }
-    // Left/right use logical properties so RTL mirrors the pair while
-    // the card stays at the same corner of the glass.
-    expect(ruleBlock(".hk-screen-identify")).toMatch(/inset-inline-start:/);
+    // The default corner's own block must not have been turned into a
+    // catch-all: it keeps the bottom-left seat via the logical edge only.
+    const card = ruleBlock(".hk-screen-identify");
+    expect(card).toMatch(/inset-inline-start:\s*var\(--space-16/);
+    expect(card).toMatch(/bottom:\s*var\(--space-16/);
   });
 
   it("rides hikari text tokens for every font size except the numeral", () => {

package/src/components/calendarHeatmapRail.contract.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Source contract for the HkCalendarHeatmap weekday rail geometry
+ * (2026-11-05 user report from the chest quota card: the Monday/Sunday
+ * labels sat one marker strip too high, and a hard-coded surface fill
+ * painted a visible stripe behind them).
+ *
+ * jsdom does no layout, so the row alignment itself cannot be asserted
+ * here; these pins hold the two sheet decisions the fix rests on:
+ *
+ * 1. `align-self: flex-end` — the -cells box is one marker strip taller
+ *    than the grid (the month labels ride above it); a stretched rail
+ *    starts its seven rows on the markers. The rail's natural height
+ *    (7 cells + 6 gaps) equals the grid's exactly, so end-alignment is
+ *    row-exact. This also assumes the grid stays the LAST child of
+ *    -cells with no trailing padding — the third pin below.
+ * 2. no sticky mask — a hard-coded surface can't match every host
+ *    card, and sticky without a mask lets cells slide beneath the
+ *    labels during horizontal scroll. The rail scrolls with the
+ *    calendar (the GitHub convention).
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const sheet = readFileSync(join(here, "HkCalendarHeatmap.scss"), "utf-8");
+
+// The `&-rail` rule up to its closing brace (two-space indent inside
+// the `.hk-calendar-heatmap` block) — keeps the assertions scoped to
+// the rail (a background elsewhere in the sheet is legitimate).
+const rail = sheet.match(/&-rail \{[\s\S]*?\n  \}/)?.[0] ?? "";
+// Same for `-cells`, whose last-child geometry the alignment relies on.
+const cells = sheet.match(/&-cells \{[\s\S]*?\n  \}/)?.[0] ?? "";
+
+describe("HkCalendarHeatmap weekday rail contract", () => {
+  it("extracts the rail rule from the sheet", () => {
+    expect(rail, "the &-rail rule must exist").toContain("&-rail {");
+  });
+
+  it("bottom-aligns the rail with the grid, not the markers row", () => {
+    expect(rail, "rail must carry align-self: flex-end").toContain(
+      "align-self: flex-end",
+    );
+  });
+
+  it("carries no sticky mask (no hard-coded surface fill)", () => {
+    expect(rail, "rail must not paint a hard-coded surface").not.toContain(
+      "background:",
+    );
+    expect(rail, "rail must not go sticky").not.toContain("position: sticky");
+    expect(rail, "sticky's scroll pin has no business left behind").not.toContain(
+      "z-index",
+    );
+  });
+
+  it("keeps the grid the flush last child of -cells", () => {
+    expect(cells, "the &-cells rule must exist").toContain("&-cells {");
+    expect(cells, "trailing padding would break the end-alignment").not.toContain(
+      "padding",
+    );
+  });
+});

package/src/components/inlineChips.ts

@@ -0,0 +1,170 @@
+/**
+ * inlineChips — the read-only chip pass for markdown-embedded prompt
+ * text (`HkMarkdownRenderer`'s opt-in `inlineChips` mode).
+ *
+ * Prompt assets (entelecheia's five prompt levels) embed two reference
+ * forms in their prose:
+ *   - fill-template tokens `{{ name }}` — the shared fill-template
+ *     grammar (`templateGrammar.ts` parses them; only bare
+ *     `[A-Za-z0-9_]+` identifiers are tokens, everything richer stays
+ *     literal);
+ *   - asset references `@level/name` (`@system/permission-mode`) and
+ *     bare `@name` handles — the engine's cross-asset mention form.
+ *
+ * This module splits a plain-text run into literal text and chip
+ * segments; the caller renders chips as `.hk-tpl-chip` spans (the
+ * family's chip look). Chips preserve the REFERENCE, not the exact
+ * bytes: tokens render the canonical `{{ name }}` spelling (so `{{name}}`
+ * displays as `{{ name }}` — the same rule HkTemplateText applies, and
+ * `parseTemplate`/`serializeTemplate` remain byte-exact for the value
+ * itself) while refs render their raw matched text.
+ *
+ * Boundary guards (an `@` must NOT chip):
+ *   - preceded by a word character (`foo@bar.com` — emails stay text);
+ *   - preceded by another `@` (`user@@host` stays text);
+ * refs never absorb trailing punctuation (`.`/`'`/`,` are not in the
+ * charset) and never match inside `code`/`pre`/links — the renderer's
+ * DOM walk skips those subtrees.
+ */
+
+import { parseTemplate, formatTokenDisplay } from "./templateGrammar";
+
+export interface HkInlineChipTextSegment {
+  kind: "text";
+  text: string;
+}
+
+export interface HkInlineChipTokenSegment {
+  kind: "token";
+  /** The bare identifier (`container_badge`). */
+  token: string;
+}
+
+export interface HkInlineChipRefSegment {
+  kind: "ref";
+  /** The exact raw matched text (`@system/permission-mode`). */
+  raw: string;
+}
+
+export type HkInlineChipSegment =
+  | HkInlineChipTextSegment
+  | HkInlineChipTokenSegment
+  | HkInlineChipRefSegment;
+
+/** `@ref` grammar: `@` (not preceded by a word char or another `@`),
+ *  one path segment, then `/segment` repeats. Punctuation ends the
+ *  match naturally (dot and quote are outside the charset). */
+const REF_RE = /(?<![A-Za-z0-9_@])@[A-Za-z0-9][A-Za-z0-9_-]*(?:\/[A-Za-z0-9][A-Za-z0-9_-]*)*/g;
+
+/** Split literal text runs into text + `@ref` segments (tokens are
+ *  already extracted by the template pass before this runs). */
+function splitRefs(text: string, push: (seg: HkInlineChipSegment) => void): void {
+  let cursor = 0;
+  REF_RE.lastIndex = 0;
+  for (let m = REF_RE.exec(text); m; m = REF_RE.exec(text)) {
+    if (m.index > cursor) {
+      push({ kind: "text", text: text.slice(cursor, m.index) });
+    }
+    // URL guard: an `@` inside a bare URL is part of the URL. marked
+    // autolinks most of these (and `<a>` is a chip skip surface), but the
+    // rule must not depend on the engine's autolink heuristic — npm-scoped
+    // package URLs are common in prompt prose.
+    let tokenStart = m.index;
+    while (tokenStart > 0 && !/\s/.test(text[tokenStart - 1]!)) tokenStart -= 1;
+    if (text.slice(tokenStart, m.index).includes("://")) {
+      push({ kind: "text", text: m[0] });
+      cursor = m.index + m[0].length;
+      continue;
+    }
+    push({ kind: "ref", raw: m[0] });
+    cursor = m.index + m[0].length;
+  }
+  if (cursor < text.length) {
+    push({ kind: "text", text: text.slice(cursor) });
+  }
+}
+
+/**
+ * Split a plain-text run into literal text, `{{ token }}` and `@ref`
+ * segments, in source order. The empty string parses to an empty list;
+ * a run with no chip forms round-trips as one text segment.
+ */
+export function parseInlineChips(text: string): HkInlineChipSegment[] {
+  const out: HkInlineChipSegment[] = [];
+  const push = (seg: HkInlineChipSegment) => {
+    // Merge adjacent text runs so the caller can cheaply detect the
+    // "nothing to chip" case (one text segment).
+    const last = out[out.length - 1];
+    if (seg.kind === "text" && last?.kind === "text") {
+      last.text += seg.text;
+      return;
+    }
+    out.push(seg);
+  };
+  for (const seg of parseTemplate(text)) {
+    if (seg.kind === "token") {
+      push({ kind: "token", token: seg.token });
+    } else {
+      splitRefs(seg.text, push);
+    }
+  }
+  return out;
+}
+
+/** The canonical chip text for a segment (tokens spell `{{ name }}`,
+ *  refs keep their raw form — both copy back to the source). */
+export function inlineChipDisplay(seg: HkInlineChipTokenSegment | HkInlineChipRefSegment): string {
+  return seg.kind === "token" ? formatTokenDisplay(seg.token) : seg.raw;
+}
+
+/** Subtrees the chip pass must never enter: literal code (the token is
+ *  documentation there, not a live form), links (the `@` may be part of
+ *  a URL or handle path the anchor already contextualizes) and chips
+ *  themselves (idempotency — a second pass must not re-chip). */
+const CHIP_SKIP_SELECTOR = "code, pre, a, script, style, textarea, .hk-tpl-chip";
+
+/**
+ * Walk `root`'s text nodes and wrap chip forms in `.hk-tpl-chip`
+ * spans. Pure DOM surgery on already-sanitized markup: the only nodes
+ * created are spans + text, built with `textContent` (no HTML
+ * parsing), so the pass cannot reintroduce markup. Tokens get the
+ * canonical `{{ name }}` spelling; refs carry `data-ref` (the muted
+ * chip variant) and their exact raw text.
+ *
+ * Returns the number of chips created (0 when the mode is off or the
+ * body carries no chip forms) — a cheap assertion hook for tests.
+ */
+export function applyInlineChipsToBody(root: HTMLElement | null | undefined): number {
+  if (!root) return 0;
+  const walker = document.createTreeWalker(root, 4 /* NodeFilter.SHOW_TEXT */);
+  const targets: Text[] = [];
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const value = node.nodeValue ?? "";
+    // Cheap prefilter: chips only ever introduce `{` or `@`.
+    if (!/[{@]/.test(value)) continue;
+    const parent = (node as Text).parentElement;
+    if (parent?.closest?.(CHIP_SKIP_SELECTOR)) continue;
+    targets.push(node as Text);
+  }
+  let chips = 0;
+  for (const node of targets) {
+    const segments = parseInlineChips(node.nodeValue ?? "");
+    if (segments.length === 0 || segments.every((seg) => seg.kind === "text")) continue;
+    const frag = document.createDocumentFragment();
+    for (const seg of segments) {
+      if (seg.kind === "text") {
+        frag.append(seg.text);
+        continue;
+      }
+      chips += 1;
+      const chip = document.createElement("span");
+      chip.className = "hk-tpl-chip";
+      chip.setAttribute("data-static", "");
+      chip.textContent = inlineChipDisplay(seg);
+      if (seg.kind === "ref") chip.setAttribute("data-ref", "");
+      frag.append(chip);
+    }
+    node.replaceWith(frag);
+  }
+  return chips;
+}

package/src/index.ts

@@ -913,6 +913,17 @@ export {
   type HkTemplateSegment,
   type HkTemplateTokenDef,
 } from "./components/templateGrammar";
+// The chip grammar lives beside the fill-template grammar it reuses; both
+// are exported so hosts can reason about (and test) reference forms
+// without mounting a renderer.
+export {
+  parseInlineChips,
+  inlineChipDisplay,
+  applyInlineChipsToBody,
+  type HkInlineChipSegment,
+  type HkInlineChipTokenSegment,
+  type HkInlineChipRefSegment,
+} from "./components/inlineChips";
 export { HkErrorLanding as HkErrorLanding } from "./components/HkErrorLanding";
 export { HkErrorReportingOverlay as HkErrorReportingOverlay } from "./errorReporting";
 export { HkAdminShell as HkAdminShell } from "./components/HkAdminShell";

package/src/theme/useSolarTime.test.ts

@@ -514,6 +514,20 @@ describe("solar IP insight (the strategy dialog's readout)", () => {
     expect(mod.solarIpInsightFresh(insight.fetchedAt + 11 * 60 * 1000)).toBe(false);
   });
 
+  it("a probe and the ip cascade's geo resolution racing share one lookup GET", async () => {
+    mod.setSolarLocationStrategy("ip");
+    mod.setGeolocationProvider(async () => null);
+    const fetchMock = lookupFetch();
+    vi.stubGlobal("fetch", fetchMock);
+    // The dialog probe and the theme clock's resolution race the same
+    // lookup — the body fetch dedupes them into one network request and
+    // both consumers converge on the same insight.
+    await Promise.all([mod.probeSolarIpInsight(), mod.getGeolocation()]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(mod.solarIpInsight.value?.ip).toBe("203.0.113.7");
+    expect(mod.solarIpProbeState.value).toBe("ok");
+  });
+
   it("the ip strategy's own geo resolution records the insight from the same body", async () => {
     mod.setSolarLocationStrategy("ip");
     mod.setGeolocationProvider(async () => null);

package/src/theme/useSolarTime.ts

@@ -330,16 +330,30 @@ const GEO_API_TIMEOUT_MS = 4000;
 /** One fetch of the lookup body with the shared timeout — the single
  *  network path for both consumers (the "ip" strategy's geo resolution
  *  and the strategy dialog's insight readout), so narrowing, abort
- *  handling and the no-store contract live in exactly one place. */
+ *  handling and the no-store contract live in exactly one place.
+ *  Concurrent callers SHARE the in-flight GET (a probe and an apply's
+ *  geo resolution racing each other used to issue two identical
+ *  requests); failures propagate to every joiner. */
+let ipBodyInflight: Promise<unknown> | null = null;
+
 async function fetchIpLookupBody(): Promise<unknown> {
-  const controller = new AbortController();
-  const timer = scheduleCronAfter(() => controller.abort(), GEO_API_TIMEOUT_MS);
-  return fetch(GEO_API_URL, {
-    signal: controller.signal,
-    cache: "no-store",
-  })
-    .then((r) => (r.ok ? r.json() : null))
-    .finally(() => timer.disconnect());
+  if (ipBodyInflight) return ipBodyInflight;
+  const inflight = (async () => {
+    const controller = new AbortController();
+    const timer = scheduleCronAfter(() => controller.abort(), GEO_API_TIMEOUT_MS);
+    return fetch(GEO_API_URL, {
+      signal: controller.signal,
+      cache: "no-store",
+    })
+      .then((r) => (r.ok ? r.json() : null))
+      .finally(() => timer.disconnect());
+  })();
+  ipBodyInflight = inflight;
+  try {
+    return await inflight;
+  } finally {
+    ipBodyInflight = null;
+  }
 }
 
 /** The trimmed-string guard for the untrusted lookup body: only a