@qilin-agent/client-ui-primitives 0.0.0-stage → 3.1.3

package/lib/types/markdown/render.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Direct mdast→React markdown renderer. Replaces the react-markdown /
+ * remark-rehype pipeline with one switch over parsed nodes so streaming can
+ * cache frozen blocks as React elements; the rendered DOM is pinned
+ * byte-for-byte by `tests/fixtures/markdown-dom` and must not drift.
+ *
+ * External link and image destinations pass a protocol allowlist; settled
+ * local file links use an explicit owner callback. Images additionally require
+ * absolute HTTP(S), raw HTML renders as literal text (no HTML enters the
+ * DOM), and KaTeX runs without trusted commands. Fragment-anchor URLs fail
+ * the allowlist, so footnote references and back-references render as plain
+ * text rather than in-page links.
+ *
+ * Merge-extensible node unions fall through the documented default (render
+ * nothing) rather than ending in assertNever: grammars registered elsewhere
+ * may add node types this renderer has no mapping for.
+ */
+import type { ReactNode } from 'react';
+import type * as Md from 'mdast';
+import type { PositionedBlock } from './incremental.ts';
+/** Copy-button labels forwarded to fence CodeBlocks (this package is cordis-free, so copy arrives via props). */
+export interface MarkdownCodeLabels {
+    /** Copy-button idle label. */
+    copyLabel: string;
+    /** Copy-button label during the post-copy confirmation window. */
+    copiedLabel: string;
+}
+/** Localized alt text for a rendered Mermaid diagram. */
+export interface MarkdownMermaidLabels {
+    /** Alt text naming the on-page diagram stage. */
+    diagramLabel: string;
+    /** Alt text naming the enlarged overlay copy. */
+    enlargedLabel: string;
+}
+/** Localized chrome for a Markdown document. */
+export interface MarkdownLabels {
+    code: MarkdownCodeLabels;
+    mermaid: MarkdownMermaidLabels;
+    footnotes: string;
+}
+/** Link/image reference targets collected from a document (first definition per identifier wins, as in CommonMark). */
+export interface ReferenceTargets {
+    /** Link/image definitions keyed by upper-cased identifier. */
+    definitions: Map<string, Md.Definition>;
+    /** Footnote definitions keyed by upper-cased identifier. */
+    footnotes: Map<string, Md.FootnoteDefinition>;
+}
+/**
+ * Create an empty {@link ReferenceTargets}.
+ * @returns Fresh empty maps.
+ */
+export declare function createReferenceTargets(): ReferenceTargets;
+/**
+ * Record every definition and footnote definition under `nodes` into
+ * `targets`, depth-first, keeping the first definition per identifier.
+ * @param nodes - Subtrees to walk (top-level blocks or any nested children).
+ * @param targets - Accumulator, typically shared across incremental segments.
+ */
+export declare function collectReferenceTargets(nodes: readonly Md.RootContent[], targets: ReferenceTargets): void;
+/**
+ * Local-path image vocabulary for image destinations: the owner maps an
+ * authored destination that fails the remote-URL allowlist (an absolute local
+ * file path, for example) to a displayable URL it can vouch for. Absent
+ * wherever no such vocabulary exists, authored local destinations keep their
+ * documented fallback (the image's alt text). Rewritten destinations must be
+ * absolute; the renderer re-checks their protocol before emitting them.
+ */
+export interface MarkdownPathImages {
+    /**
+     * Resolve one authored image destination.
+     * @param value - The destination exactly as the markdown author wrote it.
+     * @returns A displayable absolute URL, or undefined when the destination
+     * names no displayable image — it then stays inert alt text.
+     */
+    resolve(value: string): string | undefined;
+}
+/**
+ * File-mention affordance for inline code: the owner resolves an authored
+ * token to the file it names, using its own vocabulary of real files — the
+ * renderer never guesses at what looks like a path.
+ */
+export interface MarkdownFileMentions {
+    /**
+     * Resolve one inline-code token.
+     * @param value - The authored token, exactly as written.
+     * @returns The opener with its accessible label and full-path title, or
+     * undefined when the token names no known file — it then stays inert code.
+     */
+    resolve(value: string): {
+        open: () => void;
+        label: string;
+        title: string;
+    } | undefined;
+}
+/**
+ * One render pass's state: immutable options and targets plus the footnote
+ * numbering accumulated in document order while references render.
+ */
+export interface MarkdownRenderContext {
+    /** Streaming arm: fences highlight incrementally as they grow; TeX (including ```math fences) stays literal until the settled pass. */
+    readonly streaming: boolean;
+    /** Localized fence copy-button labels. */
+    readonly labels: MarkdownLabels;
+    /** Inside a blockquote's children: tables there always fill the quote's width. */
+    readonly inBlockquote?: boolean;
+    /** Inline-code file mentions; absent wherever no opener vocabulary exists. */
+    readonly fileMentions: MarkdownFileMentions | undefined;
+    /** Local-path image vocabulary; absent wherever no rewriting owner exists. */
+    readonly pathImages: MarkdownPathImages | undefined;
+    /**
+     * Owner-supplied renderer for one authored raw-HTML run. Absent — the default
+     * — keeps the run as literal text, which is what every consumer that renders
+     * untrusted model output gets unless it installs a sanitizer of its own.
+     */
+    readonly html: MarkdownHtmlRenderer | undefined;
+    /** Inside an anchor's children: interactive mentions must not nest there. */
+    readonly inLink?: boolean;
+    /** Reference targets visible to this pass. */
+    readonly targets: ReferenceTargets;
+    /** Footnote identifiers in first-reference order; a footnote's number is its 1-based index here. */
+    readonly footnoteOrder: string[];
+    /** References rendered per identifier; drives the section's back-reference count. */
+    readonly footnoteCounts: Map<string, number>;
+}
+/**
+ * Owner-side renderer for authored raw HTML in a Markdown source.
+ * @param source - the raw HTML run exactly as the stream carried it.
+ * @returns the element to render in the run's place.
+ */
+export type MarkdownHtmlRenderer = (source: string) => ReactNode;
+/**
+ * Render top-level blocks. Nodes that render nothing (definitions, unmapped
+ * types) are dropped rather than kept as null placeholders, matching the
+ * replaced pipeline's child lists so separator newlines land identically.
+ * @param blocks - Blocks with their stream-stable render keys.
+ * @param context - The pass state; footnote numbering mutates in document order.
+ * @returns One React node per rendered block.
+ */
+export declare function renderBlocks(blocks: readonly PositionedBlock[], context: MarkdownRenderContext): ReactNode[];
+/**
+ * Interleave the newline text nodes the replaced pipeline emitted between
+ * block-level children. They are invisible between elements but coalesce
+ * into adjacent literal raw-HTML text, where the DOM parity fixtures pin
+ * them.
+ * @param elements - Rendered block children with empty renders already dropped.
+ * @param edges - Also emit the leading and trailing newline (hast's loose wrap).
+ * @returns The interleaved children.
+ */
+export declare function wrapBlockChildren(elements: readonly ReactNode[], edges: boolean): ReactNode[];
+/**
+ * Render the trailing footnote section for every footnote referenced during
+ * the pass, in first-reference order, with one plain-text back-reference
+ * marker per rendered reference.
+ * @param context - The pass state after all blocks rendered.
+ * @returns The section, or null when no referenced footnote has a definition.
+ */
+export declare function renderFootnoteSection(context: MarkdownRenderContext): ReactNode | null;
+//# sourceMappingURL=render.d.ts.map

package/lib/types/markdown/useViewportHighlighting.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/**
+ * Activate one supported code surface when it first intersects the viewport.
+ * Activation lasts for the component lifetime; browsers without
+ * IntersectionObserver activate immediately.
+ * @param target - Code surface whose plain rendering reserves its geometry.
+ * @param lang - Optional language hint.
+ * @returns Whether this component may build highlighted output.
+ */
+export declare function useViewportHighlighting(target: RefObject<Element>, lang: string | undefined): boolean;
+//# sourceMappingURL=useViewportHighlighting.d.ts.map

package/lib/types/overlay-top-margin.d.ts

@@ -0,0 +1,8 @@
+/** Shared viewport inset for overlays, derived from the desktop frame's reserved top strip. */
+/**
+ * Resolve the top margin an overlay keeps from the viewport edge.
+ * @param min - the overlay's own viewport margin in px, used as the floor.
+ * @returns the larger of `min` and the frame clearance plus 20px; fullscreen keeps only the 20px gap.
+ */
+export declare function overlayTopMargin(min: number): number;
+//# sourceMappingURL=overlay-top-margin.d.ts.map

package/lib/types/pointer-grace.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Grace before a pointer-dismissed popup closes. Covers the anchor->popup gap
+ * (8px for HoverCard, 4px for Menu) at a hand's travel speed without leaving a
+ * popup lingering once the pointer has genuinely moved on.
+ */
+export declare const POINTER_GRACE_MS = 200;
+/** Cancelable delayed close for a pointer-dismissed popup. */
+export interface PointerGrace {
+    /** Schedule the close {@link POINTER_GRACE_MS} from now, replacing any pending one. */
+    arm: () => void;
+    /** Abort a pending close (the pointer came back). */
+    cancel: () => void;
+}
+/**
+ * Delay a pointer-dismissed popup's close so the pointer can cross the gap
+ * between anchor and popup. A pending close is dropped on unmount.
+ * @param close - runs when the grace elapses with no re-entry; read at fire
+ * time, so callers may pass a fresh closure each render.
+ * @returns the {@link PointerGrace} handle.
+ */
+export declare function usePointerGrace(close: () => void): PointerGrace;
+//# sourceMappingURL=pointer-grace.d.ts.map

package/lib/types/rank-by-name.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared ranking for `/` menu candidates: the query must be a
+ * case-insensitive ordered subsequence of the candidate name or, when the
+ * candidate carries one, of its display label (a localized title). Prefix
+ * hits rank first, then the strongest alignment score over either key, then
+ * the source order of the input. Decision record:
+ * .agents/notes/archived/feature/2026-08-04-web-slash-command-fuzzy-discovery.md
+ */
+/**
+ * Rank named items by a menu query.
+ * @param items - candidates in source order (a host catalog, then client
+ * contributions); an item's optional `label` is a second search key beside
+ * its name.
+ * @param rawQuery - the text typed after the trigger, matched case-insensitively.
+ * @returns the matching items: prefix hits first, then by alignment score,
+ * then in source order. The input list itself for an empty query.
+ */
+export declare function rankByName<T extends {
+    readonly name: string;
+    readonly label?: string;
+}>(items: readonly T[], rawQuery: string): readonly T[];
+//# sourceMappingURL=rank-by-name.d.ts.map

package/lib/types/relative-time.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compact relative-time bucketing shared by every surface that dates a
+ * session. Bucketing is here so two surfaces naming the same session agree;
+ * the words stay in each plugin's own dictionary, per locale-owned copy.
+ *
+ * @module @qilin-agent/client-ui-primitives/relative-time
+ */
+/** Relative-time bucket of a dated row's trailing label. */
+export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+/** Structured relative time: the bucket plus its magnitude (0 for 'now'). */
+export interface RelativeTime {
+    unit: RelativeTimeUnit;
+    n: number;
+}
+/**
+ * Compact relative time, as a structured bucket the renderer localizes
+ * ("now"/"5min"/"3h"/"2d"/"4mo"/"1y" in en).
+ * @param at - epoch ms of the dated moment.
+ * @param now - current epoch ms (injected for pure rendering).
+ * @returns the row's trailing time bucket and magnitude.
+ */
+export declare function relativeTime(at: number, now: number): RelativeTime;
+//# sourceMappingURL=relative-time.d.ts.map

package/lib/types/seal-geometry.d.ts

@@ -0,0 +1,27 @@
+/** Seal geometry: the cinnabar body, its gold hairline ring, and the two glyph cells. */
+/** The seal body: a rounded square filling the viewBox. */
+export declare const SEAL_BODY: {
+    readonly inset: 0;
+    readonly side: 24;
+    readonly radius: 5.2;
+};
+/** The gold hairline ring inside the body, close to its edge. */
+export declare const SEAL_RING: {
+    readonly inset: 0.94;
+    readonly side: 22.13;
+    readonly radius: 4.31;
+    readonly stroke: 0.375;
+};
+/** The glyph cells: side by side and centered vertically in the body. */
+export declare const SEAL_CELL: {
+    size: number;
+    top: number;
+    lefts: readonly [2.28, 12.12];
+};
+/**
+ * Placement transform for one glyph cell.
+ * @param left - left edge of the cell in viewBox units.
+ * @returns the transform placing the unit-box outline into that cell.
+ */
+export declare function cellTransform(left: number): string;
+//# sourceMappingURL=seal-geometry.d.ts.map

package/lib/types/seal-glyphs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Glyph outlines for the QiLin seal, extracted once from a system CJK face
+ * and normalized to a unit box so the mark carries no runtime font dependency.
+ */
+/** 麒 (U+9E92), normalized to a unit box. */
+export declare const SEAL_GLYPH_QI = "M0.42 0.84Q0.42 0.86 0.45 0.86Q0.47 0.86 0.48 0.86Q0.49 0.86 0.5 0.85Q0.5 0.84 0.51 0.83Q0.51 0.81 0.51 0.79Q0.53 0.81 0.55 0.81Q0.56 0.82 0.59 0.82Q0.57 0.85 0.56 0.88Q0.55 0.9 0.53 0.91Q0.52 0.93 0.49 0.93Q0.47 0.94 0.44 0.94Q0.41 0.94 0.39 0.93Q0.38 0.93 0.37 0.92Q0.36 0.92 0.35 0.91Q0.35 0.9 0.35 0.89V0.63Q0.35 0.61 0.35 0.59Q0.35 0.58 0.35 0.57Q0.35 0.56 0.35 0.55Q0.35 0.54 0.34 0.54Q0.37 0.54 0.39 0.54Q0.4 0.54 0.42 0.54Q0.44 0.54 0.44 0.55Q0.44 0.55 0.43 0.56Q0.42 0.57 0.42 0.61V0.68Q0.44 0.65 0.46 0.63Q0.47 0.61 0.48 0.59Q0.49 0.61 0.51 0.62Q0.52 0.63 0.54 0.64Q0.55 0.64 0.55 0.65Q0.54 0.65 0.54 0.65Q0.53 0.65 0.53 0.66Q0.52 0.66 0.51 0.67Q0.5 0.68 0.48 0.7Q0.45 0.73 0.42 0.76ZM0.92 0.99Q0.9 0.95 0.87 0.9Q0.84 0.85 0.79 0.8L0.86 0.76Q0.9 0.81 0.94 0.86Q0.97 0.9 1 0.94ZM0.74 0.81Q0.74 0.81 0.73 0.82Q0.72 0.83 0.7 0.85Q0.68 0.87 0.66 0.91Q0.63 0.94 0.59 1Q0.57 0.98 0.55 0.97Q0.54 0.96 0.51 0.95Q0.54 0.93 0.56 0.91Q0.58 0.89 0.6 0.86Q0.62 0.84 0.63 0.82Q0.65 0.79 0.66 0.76Q0.68 0.77 0.7 0.78Q0.72 0.79 0.74 0.79Q0.75 0.8 0.75 0.8Q0.75 0.81 0.74 0.81ZM0.25 0.84Q0.26 0.83 0.28 0.82Q0.29 0.81 0.3 0.8Q0.3 0.81 0.31 0.83Q0.32 0.84 0.33 0.86L0.25 0.92Q0.23 0.93 0.21 0.95Q0.19 0.97 0.18 0.97Q0.17 0.96 0.16 0.94Q0.15 0.92 0.14 0.91Q0.15 0.9 0.16 0.9Q0.17 0.89 0.18 0.89V0.65Q0.18 0.58 0.18 0.55Q0.2 0.55 0.22 0.55Q0.24 0.55 0.26 0.55Q0.27 0.55 0.27 0.55Q0.27 0.56 0.27 0.56Q0.26 0.57 0.25 0.58Q0.25 0.58 0.25 0.59V0.64Q0.29 0.64 0.31 0.64Q0.32 0.64 0.33 0.64V0.71Q0.32 0.71 0.3 0.71Q0.28 0.71 0.25 0.71ZM0.61 0.15Q0.61 0.11 0.61 0.07Q0.61 0.03 0.6 0.01Q0.63 0.01 0.65 0.01Q0.67 0.01 0.69 0.01Q0.7 0.01 0.7 0.01Q0.71 0.02 0.7 0.03Q0.69 0.03 0.69 0.04Q0.68 0.05 0.68 0.06V0.15H0.84Q0.84 0.09 0.84 0.05Q0.83 0.02 0.83 0Q0.86 0.01 0.88 0.01Q0.9 0.01 0.93 0.01Q0.94 0.01 0.94 0.01Q0.95 0.02 0.94 0.02Q0.93 0.03 0.92 0.04Q0.92 0.05 0.92 0.06V0.15Q0.93 0.15 0.95 0.14Q0.97 0.14 0.99 0.14V0.21Q0.97 0.21 0.95 0.21Q0.93 0.21 0.92 0.21V0.67Q0.93 0.67 0.96 0.67Q0.98 0.67 1 0.67V0.75Q0.98 0.74 0.97 0.74Q0.95 0.74 0.92 0.74Q0.9 0.74 0.86 0.74Q0.82 0.74 0.76 0.74Q0.7 0.74 0.67 0.74Q0.63 0.74 0.6 0.74Q0.58 0.74 0.56 0.74Q0.55 0.74 0.53 0.75V0.67Q0.55 0.67 0.57 0.67Q0.6 0.67 0.61 0.67V0.21Q0.6 0.21 0.58 0.21Q0.56 0.21 0.54 0.21V0.14Q0.56 0.14 0.58 0.14Q0.6 0.15 0.61 0.15ZM0.68 0.67H0.84V0.55H0.68ZM0.84 0.31V0.21H0.68V0.31ZM0.68 0.38V0.49H0.84V0.38ZM0.49 0.47V0.35H0.42V0.47ZM0.35 0.47V0.35H0.28V0.47ZM0.13 0.35Q0.13 0.38 0.13 0.41Q0.13 0.44 0.13 0.47H0.22V0.35ZM0.13 0.17V0.3H0.22V0.17ZM0.42 0.3Q0.44 0.3 0.46 0.3Q0.48 0.29 0.49 0.29Q0.51 0.29 0.53 0.29Q0.54 0.29 0.55 0.29Q0.55 0.3 0.55 0.34Q0.55 0.37 0.55 0.41Q0.55 0.45 0.55 0.48Q0.55 0.52 0.55 0.53Q0.53 0.53 0.48 0.53Q0.43 0.52 0.38 0.52H0.13Q0.13 0.61 0.12 0.68Q0.12 0.74 0.11 0.79Q0.1 0.84 0.09 0.88Q0.08 0.92 0.06 0.96Q0.04 0.94 0.03 0.92Q0.01 0.91 0 0.89Q0.02 0.86 0.03 0.83Q0.04 0.8 0.05 0.76Q0.06 0.72 0.06 0.67Q0.06 0.62 0.07 0.54Q0.07 0.46 0.07 0.36Q0.07 0.25 0.06 0.11Q0.08 0.11 0.14 0.11Q0.19 0.11 0.27 0.11Q0.26 0.09 0.25 0.06Q0.24 0.04 0.22 0.02L0.32 0Q0.32 0.02 0.33 0.05Q0.34 0.08 0.35 0.11Q0.39 0.11 0.42 0.11Q0.45 0.11 0.47 0.11Q0.49 0.11 0.5 0.11Q0.51 0.1 0.52 0.1V0.18Q0.51 0.18 0.48 0.18Q0.45 0.18 0.42 0.18ZM0.28 0.17V0.3H0.35V0.17Z";
+/** 麟 (U+9E9F), normalized to a unit box. */
+export declare const SEAL_GLYPH_LIN = "M0.53 0.66Q0.55 0.68 0.57 0.71Q0.59 0.73 0.6 0.74Q0.61 0.71 0.61 0.68Q0.61 0.65 0.61 0.62H0.55Q0.54 0.63 0.54 0.64Q0.53 0.65 0.53 0.66ZM0.25 0.18V0.28H0.31V0.18ZM0.13 0.18V0.28H0.19V0.18ZM0.13 0.44H0.19V0.34H0.13ZM0.31 0.44V0.34H0.25V0.44ZM0.42 0.44V0.34H0.37V0.44ZM0.83 0.76V0.62Q0.79 0.62 0.76 0.62Q0.74 0.63 0.72 0.63V0.55Q0.76 0.56 0.83 0.56Q0.83 0.52 0.83 0.5Q0.83 0.48 0.82 0.47Q0.87 0.48 0.9 0.47Q0.92 0.47 0.92 0.48Q0.92 0.48 0.91 0.49Q0.9 0.5 0.9 0.5Q0.9 0.51 0.9 0.52V0.56Q0.92 0.56 0.94 0.56Q0.97 0.56 0.99 0.55V0.63Q0.97 0.63 0.95 0.63Q0.93 0.62 0.9 0.62V0.76Q0.92 0.76 0.95 0.75Q0.98 0.75 1 0.75V0.83Q0.99 0.83 0.96 0.82Q0.93 0.82 0.9 0.82Q0.9 0.85 0.9 0.88Q0.9 0.9 0.9 0.92Q0.9 0.93 0.9 0.95Q0.9 0.96 0.91 0.98H0.82Q0.83 0.96 0.83 0.95Q0.83 0.94 0.83 0.92Q0.83 0.9 0.83 0.88Q0.83 0.86 0.83 0.82H0.77Q0.77 0.83 0.77 0.83Q0.77 0.83 0.77 0.84L0.7 0.84Q0.71 0.78 0.71 0.74Q0.71 0.7 0.71 0.66Q0.74 0.67 0.78 0.67Q0.79 0.66 0.79 0.67Q0.79 0.67 0.78 0.68Q0.78 0.69 0.78 0.7Q0.78 0.72 0.77 0.76ZM0.37 0.62Q0.39 0.6 0.41 0.59Q0.43 0.58 0.44 0.56Q0.46 0.59 0.48 0.61Q0.5 0.58 0.51 0.55Q0.52 0.52 0.53 0.48Q0.57 0.49 0.6 0.5Q0.62 0.5 0.6 0.52Q0.59 0.52 0.59 0.53Q0.58 0.54 0.58 0.56Q0.63 0.56 0.65 0.56Q0.67 0.55 0.68 0.55Q0.68 0.64 0.67 0.7Q0.66 0.77 0.64 0.82Q0.62 0.87 0.58 0.91Q0.54 0.96 0.47 0.99Q0.46 0.97 0.44 0.96Q0.43 0.94 0.41 0.93Q0.47 0.91 0.51 0.88Q0.55 0.85 0.57 0.81Q0.56 0.79 0.54 0.77Q0.52 0.74 0.49 0.72Q0.49 0.72 0.49 0.73Q0.49 0.73 0.48 0.73Q0.47 0.72 0.46 0.71Q0.45 0.7 0.43 0.7Q0.46 0.66 0.47 0.63Q0.46 0.64 0.43 0.65Q0.41 0.66 0.37 0.68V0.81Q0.37 0.83 0.38 0.83Q0.39 0.84 0.41 0.84Q0.42 0.84 0.43 0.83Q0.44 0.81 0.45 0.78Q0.46 0.79 0.47 0.8Q0.49 0.8 0.51 0.81Q0.5 0.84 0.49 0.85Q0.48 0.87 0.46 0.88Q0.45 0.89 0.44 0.9Q0.43 0.9 0.41 0.9Q0.38 0.9 0.36 0.9Q0.34 0.89 0.33 0.89Q0.32 0.88 0.31 0.86Q0.31 0.85 0.31 0.82V0.51H0.12Q0.12 0.61 0.12 0.68Q0.12 0.75 0.11 0.79Q0.1 0.84 0.09 0.87Q0.08 0.91 0.07 0.95Q0.05 0.91 0.03 0.9Q0.02 0.88 0 0.88Q0.05 0.79 0.06 0.59Q0.07 0.4 0.05 0.11Q0.06 0.11 0.11 0.12Q0.16 0.12 0.25 0.12Q0.24 0.1 0.23 0.08Q0.22 0.06 0.2 0.04L0.3 0.01Q0.31 0.04 0.32 0.06Q0.33 0.09 0.34 0.12Q0.39 0.12 0.44 0.12Q0.48 0.11 0.5 0.11V0.19Q0.49 0.19 0.47 0.19Q0.46 0.18 0.44 0.18Q0.42 0.18 0.4 0.18Q0.38 0.18 0.37 0.18V0.28Q0.4 0.28 0.43 0.27Q0.47 0.27 0.48 0.27Q0.48 0.28 0.48 0.29Q0.48 0.3 0.48 0.31Q0.48 0.32 0.48 0.34Q0.48 0.36 0.48 0.39Q0.48 0.42 0.48 0.44Q0.48 0.46 0.48 0.48Q0.48 0.49 0.48 0.5Q0.48 0.51 0.48 0.52Q0.45 0.51 0.37 0.51ZM0.22 0.62Q0.25 0.62 0.27 0.62Q0.28 0.62 0.3 0.62Q0.3 0.63 0.3 0.65Q0.3 0.66 0.3 0.68Q0.28 0.68 0.27 0.68Q0.25 0.68 0.22 0.68V0.82Q0.24 0.81 0.26 0.8Q0.28 0.79 0.3 0.78Q0.3 0.8 0.3 0.81Q0.3 0.82 0.31 0.84L0.21 0.89Q0.19 0.9 0.18 0.91Q0.16 0.92 0.15 0.93Q0.15 0.91 0.14 0.9Q0.13 0.88 0.12 0.85Q0.14 0.85 0.16 0.84V0.65Q0.16 0.54 0.15 0.51Q0.19 0.52 0.22 0.52Q0.23 0.52 0.23 0.52Q0.23 0.53 0.23 0.53Q0.22 0.54 0.22 0.55Q0.22 0.55 0.22 0.56ZM0.57 0.04Q0.59 0.07 0.61 0.1Q0.63 0.14 0.64 0.17L0.57 0.2Q0.56 0.14 0.51 0.08ZM0.93 0.06Q0.94 0.06 0.94 0.07Q0.94 0.08 0.93 0.08Q0.92 0.08 0.92 0.08Q0.91 0.09 0.9 0.1Q0.89 0.11 0.88 0.14Q0.87 0.16 0.85 0.19Q0.83 0.18 0.82 0.17Q0.8 0.17 0.78 0.16Q0.8 0.13 0.82 0.1Q0.83 0.07 0.84 0.03Q0.85 0.03 0.86 0.04Q0.87 0.04 0.89 0.05Q0.9 0.05 0.91 0.05Q0.92 0.06 0.93 0.06ZM0.68 0.27Q0.66 0.31 0.65 0.33Q0.64 0.36 0.63 0.38Q0.61 0.4 0.59 0.42Q0.57 0.44 0.53 0.47Q0.52 0.45 0.52 0.44Q0.51 0.43 0.49 0.42Q0.51 0.4 0.53 0.39Q0.55 0.37 0.57 0.35Q0.58 0.33 0.6 0.31Q0.61 0.29 0.63 0.27Q0.61 0.27 0.59 0.27Q0.57 0.27 0.56 0.27Q0.54 0.27 0.52 0.27Q0.51 0.28 0.5 0.28V0.2Q0.51 0.2 0.52 0.21Q0.53 0.21 0.55 0.21Q0.57 0.21 0.6 0.21Q0.63 0.21 0.68 0.21V0.15Q0.68 0.09 0.68 0.07Q0.67 0.04 0.67 0.02Q0.69 0.02 0.71 0.02Q0.74 0.02 0.75 0.02Q0.76 0.02 0.77 0.03Q0.77 0.03 0.76 0.04Q0.75 0.05 0.75 0.06Q0.75 0.07 0.75 0.09V0.21Q0.81 0.21 0.85 0.21Q0.9 0.21 0.92 0.21Q0.94 0.21 0.95 0.21Q0.97 0.2 0.97 0.2V0.28Q0.97 0.27 0.95 0.27Q0.94 0.27 0.92 0.27Q0.9 0.27 0.87 0.27Q0.85 0.27 0.81 0.27Q0.83 0.29 0.84 0.31Q0.86 0.32 0.88 0.34Q0.9 0.35 0.93 0.36Q0.95 0.37 0.99 0.37Q0.97 0.39 0.96 0.41Q0.95 0.43 0.94 0.46Q0.87 0.43 0.83 0.38Q0.78 0.34 0.75 0.27H0.75V0.35Q0.75 0.4 0.75 0.44Q0.75 0.47 0.75 0.5H0.67Q0.67 0.47 0.68 0.43Q0.68 0.4 0.68 0.35Z";
+//# sourceMappingURL=seal-glyphs.d.ts.map

package/lib/types/use-copy-feedback.d.ts

@@ -0,0 +1,14 @@
+/** The copy-feedback hook's return: the transient flag and the copy handler. */
+export interface CopyFeedback {
+    /** True for {@link COPIED_FEEDBACK_MS} after a successful write; render the success label off it. */
+    copied: boolean;
+    /** Copy the hook's text; no-op while `copied` is still true, silent on a refused write. */
+    onCopy: () => void;
+}
+/**
+ * Copy `text` to the clipboard with one-second success feedback.
+ * @param text - the text to write on copy.
+ * @returns the `copied` flag and the `onCopy` handler.
+ */
+export declare function useCopyFeedback(text: string): CopyFeedback;
+//# sourceMappingURL=use-copy-feedback.d.ts.map

package/lib/types/useAnchoredMaxHeight.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/**
+ * Clamp a bottom-anchored overlay's max-height to the viewport.
+ * @param ref - the overlay element; a null current (overlay closed) skips measuring.
+ * @param cap - design max-height in px (the clamp never exceeds it).
+ * @param signal - re-measure trigger: pass the overlay's render state so anchor
+ *   moves (composer growth) re-fit; resize/scroll re-fit while mounted.
+ * @returns the max-height to apply inline, in px.
+ */
+export declare function useAnchoredMaxHeight(ref: RefObject<HTMLElement>, cap: number, signal: unknown): number;
+//# sourceMappingURL=useAnchoredMaxHeight.d.ts.map

package/lib/types/useAnchoredPosition.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Keep a fixed-position floating element anchored to a trigger.
+ *
+ * A portaled panel is positioned from its anchor's viewport rect, which stops
+ * being true the moment anything scrolls or the window resizes. This owns that
+ * one concern: measure the anchor, offset the panel below or above it, clamp
+ * the result inside the viewport, and re-run on scroll (capture phase, so
+ * scrollers nested inside the page are caught too), on resize, and on the
+ * panel's own size changes while the element is open.
+ * @module @qilin-agent/client-ui-primitives/useAnchoredPosition
+ */
+import { type CSSProperties, type RefObject } from 'react';
+/** Inputs for {@link useAnchoredPosition}. */
+export interface AnchoredPositionOptions {
+    /** Whether the floating element is mounted and should track its anchor. */
+    open: boolean;
+    /** The element the panel is placed from. */
+    anchorRef: RefObject<HTMLElement | null>;
+    /** The floating element, measured so the clamp uses real dimensions. */
+    panelRef: RefObject<HTMLElement | null>;
+    /** Which anchor edge the panel hangs from: below it (`bottom`, the default) or above it (`top`). */
+    side?: 'top' | 'bottom';
+    /** Distance kept between the anchor edge named by `side` and the panel. */
+    gap: number;
+    /** Distance kept between the panel and each viewport edge. */
+    margin: number;
+}
+/**
+ * Track an anchor and return the panel's fixed coordinates.
+ * @param options - the open state, the two refs, the placement side, and the gap/margin distances.
+ * @returns `left`/`top` for the panel, or `null` before the first measurement.
+ */
+export declare function useAnchoredPosition(options: AnchoredPositionOptions): CSSProperties | null;
+//# sourceMappingURL=useAnchoredPosition.d.ts.map

package/lib/types/useDismissOnOutsidePointer.d.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from 'react';
+/**
+ * Close an open popover when a pointerdown lands outside its root element.
+ * @param root - element containing both the trigger and the open surface.
+ * @param open - whether the surface is showing; false detaches the listener.
+ * @param setOpen - state setter invoked with false on an outside pointerdown.
+ * @param portal - surface portaled outside the root (a `document.body` dialog)
+ * that also counts as inside; omit when the root contains the whole popover.
+ */
+export declare function useDismissOnOutsidePointer(root: RefObject<HTMLElement | null>, open: boolean, setOpen: (open: boolean) => void, portal?: RefObject<HTMLElement | null>): void;
+//# sourceMappingURL=useDismissOnOutsidePointer.d.ts.map

package/lib/types/useModalLayer.d.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from 'react';
+/** Dialog and menu elements whose document order determines foreground shortcut ownership. */
+export declare const modalSelector = "[role=\"dialog\"][aria-modal=\"true\"], [role=\"menu\"]";
+/**
+ * Request closure of the foreground registered modal using its current onClose callback.
+ * A newer menu or unregistered dialog blocks dismissal of the modal behind it.
+ * @param document - product document whose modal owns the close command.
+ */
+export declare function closeTopModal(document: Document): void;
+/**
+ * Whether an anchor belongs behind the current modal and must yield keyboard input.
+ * @param anchor - local control owning the input handler.
+ * @returns true when another modal owns the foreground.
+ */
+export declare function isBehindModal(anchor: HTMLElement | null): boolean;
+/**
+ * Give only the top modal Escape and Tab ownership, then restore its previous focus.
+ * Automatic entry and return focus omit outlines; keyboard traversal retains its indicators.
+ * Controls mounted with the dialog use data-modal-autofocus for initial focus;
+ * React autoFocus runs before this layer can capture the invoking control.
+ * Local menus handle their Escape during capture before this bubble listener.
+ * @param dialog - mounted dialog element.
+ * @param open - whether this layer is active.
+ * @param onClose - top-layer Escape or application close action.
+ */
+export declare function useModalLayer(dialog: RefObject<HTMLElement | null>, open: boolean, onClose: () => void): void;
+//# sourceMappingURL=useModalLayer.d.ts.map

package/lib/types/user-text.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Display projection of reference forms in sent user text (bubble and queue
+ * rows). The logged model text remains the single truth; this is presentation
+ * only, and every part renders inline so a single-line message never breaks
+ * across lines. Four decoration sources, by precedence: the wire session form
+ * `@[label](qilin-session:...)` folds to its label; exact session labels
+ * supplied by an adjacent recall decorate their bare `@label` mention; plain
+ * `@name` word-boundary tokens decorate by shape alone; and a plain `/name`
+ * token decorates only when the caller names it — a skill the host actually
+ * loaded for that message (ui-chat reads the step's `skill-invocation`
+ * injections) or the command a command-input bubble echoes — so `/123` or a
+ * stray `/word` stays plain text. A `/name` token is whitespace-bounded like
+ * the host skill gesture (`qilin-tool-skill`): it ends at whitespace or the
+ * text end, so slash paths (`/nfs-hg/xxx`, `/plan.md`) and punctuation-glued
+ * tokens (`/plan。`) stay plain even for a loaded name.
+ */
+import type { ReactNode } from 'react';
+/** Optional navigation supplied by consumers that can preview references. */
+export interface UserTextReferences {
+    /** Open a file path decoded from an `@` mention. */
+    openFile: (path: string) => void;
+    /** Open the source of a skill loaded for this message. */
+    openSkill: (name: string) => void;
+}
+/**
+ * Split one sent text into inline plain runs and reference chips.
+ * @param text - the logged model text of the message or queue row.
+ * @param sessionLabels - exact session mention labels associated by an adjacent recall.
+ * @param slashNames - names a `/name` token may decorate as: the skills the
+ * host loaded for this message, or the command a command bubble echoes
+ * (unsent queue rows pass none).
+ * @param slashKind - the chip kind those tokens render as.
+ * @param references - optional file and skill preview actions; session and command tokens stay labels.
+ * @returns inline nodes covering the whole text.
+ */
+export declare function projectUserText(text: string, sessionLabels: readonly string[], slashNames?: readonly string[], slashKind?: 'skill' | 'command', references?: UserTextReferences): ReactNode;
+//# sourceMappingURL=user-text.d.ts.map

package/lib/user-text.module.css

@@ -0,0 +1,43 @@
+/* Inline projection of sent user text: plain runs and reference chips flow in
+   the consumer's own line box (bubble or queue row); nothing here is block.
+   White-space policy stays with the consumer: the bubble wraps with pre-wrap,
+   the queue preview keeps its single nowrap/ellipsis line. */
+
+.plainRun {
+  font-size: inherit;
+  line-height: inherit;
+}
+
+.refChip {
+  /* Plain inline, NOT inline-flex: a flex container takes its baseline from
+     its first flex item — the icon svg, which has no text baseline — so the
+     chip's label rode ~3px above the surrounding text in both surfaces. An
+     inline chip shares the consumer's baseline by construction. */
+  display: inline;
+  margin: 0 2px;
+  color: var(--qilin-alias-state-business-primary);
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+/* Skill and command tokens read as code: the theme's code family at the
+   consumer's own size and line height, so the chip sits on the bubble line
+   like the plain runs around it. `@` chips keep the body face — a file or
+   session name is a label, not code. */
+.slashChip {
+  font-family: var(--qilin-font-markdown-code-font-family);
+}
+
+/* Inline reference glyphs (always ReferenceIcon svgs) ride the consumer's own
+   font: 1em keeps the glyph at the text's size in the bubble (14px + user
+   setting), the queue preview's fixed 13px line, and any future consumer — a
+   px+delta size followed only the bubble axis and left the glyph oversized in
+   the queue row. */
+.refIcon {
+  width: 1em;
+  height: 1em;
+  margin-right: 4px;
+  /* Optical centering against the text: drops the glyph below the baseline by
+     a font-relative amount, so it holds across the font axis. */
+  vertical-align: -0.125em;
+}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@qilin-agent/client-ui-primitives",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Pure React atoms for the qilin web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-primitives"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@shikijs/langs": "^4.3.1",
+    "@types/mdast": "^4.0.4",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "anser": "^2.3.5",
+    "clsx": "^2.0.0",
+    "diff": "^9.0.0",
+    "katex": "^0.16.47",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "mermaid": "11.17.2",
+    "micromark-core-commonmark": "^2.0.3",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-extension-math": "^3.1.0",
+    "micromark-factory-space": "^2.0.1",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "shiki": "^4.3.1",
+    "simple-icons": "16.31.0",
+    "@qilin-agent/util-workspace-path": "3.1.3",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }