@celestia-island/hikari 0.55.284 → 0.55.285

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.284",
+  "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/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/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";