@x1a0f3n9/dsh-client-ui-primitives 0.1.5-rc.3

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 @x1a0f3n9/dsh-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/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 @x1a0f3n9/dsh-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/user-text.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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](dsh-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 (`dsh-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 or folder path decoded from an `@` mention. */
+    openFile: (path: string, options?: {
+        readonly directory?: boolean;
+    }) => 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(--dsw-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(--dsw-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

@@ -0,0 +1,58 @@
+{
+  "name": "@x1a0f3n9/dsh-client-ui-primitives",
+  "description": "Pure React atoms for the dsh web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
+  "version": "0.1.5-rc.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-primitives"
+  },
+  "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": {
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "react": "^18.2.0",
+    "clsx": "^2.0.0",
+    "react-dom": "^18.2.0",
+    "anser": "^2.3.5",
+    "katex": "^0.16.47",
+    "micromark-core-commonmark": "^2.0.3",
+    "micromark-util-character": "^2.1.1",
+    "micromark-util-classify-character": "^2.0.1",
+    "micromark-util-symbol": "^2.0.1",
+    "micromark-util-types": "^2.0.2",
+    "shiki": "^4.3.1",
+    "@shikijs/langs": "^4.3.1",
+    "@types/mdast": "^4.0.4",
+    "micromark-factory-space": "^2.0.1",
+    "micromark-extension-math": "^3.1.0",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-gfm": "^3.1.0",
+    "mdast-util-math": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
+    "micromark-util-sanitize-uri": "^2.0.1",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/**/*.css",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}