@deepseek-ai/dsh-client-ui-primitives 0.1.1-rc.2 → 0.1.2-alpha.3

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

@@ -18,6 +18,12 @@
  * highlighting, still monospace) — never an error.
  */
 import type { CSSProperties } from 'react';
+/**
+ * Whether a language hint can use the shared syntax highlighter.
+ * @param lang - Language hint from a code surface.
+ * @returns Whether the hint resolves to a supported grammar.
+ */
+export declare function supportsHighlighting(lang: string | undefined): boolean;
 /**
  * Subscribe to lazy-grammar load completions; `listener` fires after a
  * {@link LAZY_GRAMMARS} grammar finishes registering on the singleton, so a
@@ -56,6 +62,66 @@ export interface HighlightSpan {
     text: string;
     style: CSSProperties;
 }
+/**
+ * Incremental highlighter for one growing streaming fence. TextMate
+ * tokenization is line-based and forward-only — a line's tokens depend only on
+ * its own text and the grammar state entering it — so appended text never
+ * changes a completed line's tokens. The session caches the spans of every
+ * completed line together with the grammar state after them;
+ * {@link updateFrame} reports only newly completed lines plus the still-growing
+ * last line, while {@link update} materializes the complete compatibility
+ * result. Per-call tokenization cost therefore excludes the completed prefix,
+ * and the result equals a from-scratch tokenization of the same code.
+ * Non-append input and a change of resolved grammar reset the cache and
+ * re-tokenize fully, so any input stays correct.
+ */
+export declare class StreamingHighlightSession {
+    /** Grammar id the cache was built with; a different resolution resets it. */
+    private resolved;
+    /** Newline-terminated source prefix covered by {@link spans}. */
+    private prefix;
+    /** Cached spans, one entry per completed line of {@link prefix}. */
+    private spans;
+    /** Grammar state after {@link prefix}; undefined = the grammar's initial state. */
+    private state;
+    private lastCode;
+    private lastLang;
+    private lastResult;
+    private generation;
+    private lastFrame;
+    private reset;
+    /** Tokenize `text` with `resolved`, resuming from the cached grammar state when one exists. */
+    private tokenize;
+    /**
+     * Tokenize one update as a delta for a retained renderer.
+     * @param code - the fence text accumulated so far.
+     * @param lang - the language hint.
+     * @returns Newly completed lines plus the current tail, or `undefined` for the plain arm.
+     */
+    updateFrame(code: string, lang: string | undefined): StreamingHighlightFrame | undefined;
+    /**
+     * Tokenize the fence's current text into per-line highlighted runs;
+     * `undefined` means the caller renders its plain fallback. Idempotent per
+     * (`code`, `lang`) input — repeated calls return the identical result array —
+     * and a retained line keeps its span-array identity across growing calls, so
+     * a React caller can reuse cached line elements. A lazy grammar not yet
+     * loaded returns `undefined` and loads in the background exactly as
+     * {@link highlightToHtml} does; the next call after it registers highlights.
+     * @param code - the fence text accumulated so far (display-trimmed, no synthetic trailing newline).
+     * @param lang - the language hint (a markdown fence info string).
+     * @returns one entry per line of `code` (each an array of runs), or `undefined` for unknown or not-yet-loaded languages.
+     */
+    update(code: string, lang: string | undefined): readonly HighlightSpan[][] | undefined;
+}
+/** One retained-renderer update from {@link StreamingHighlightSession.updateFrame}. */
+export interface StreamingHighlightFrame {
+    /** Changes whenever prior completed lines must be discarded. */
+    readonly generation: number;
+    /** Completed lines added since the preceding frame in this generation. */
+    readonly appended: readonly HighlightSpan[][];
+    /** The still-growing final line or lines, replaced by the next frame. */
+    readonly tail: readonly HighlightSpan[][];
+}
 /**
  * Tokenize `code` into per-line highlighted runs when `lang` maps to a
  * registered grammar; `undefined` means the caller renders its plain fallback.
@@ -64,8 +130,9 @@ export interface HighlightSpan {
  * so this returns shiki's own 2D line/token structure narrowed to what a run
  * renders. Each run's color is a `--shiki-*` custom property, keeping token
  * colors on the theme package's sheets exactly as the HTML path does; the
- * css-variables theme carries no font-style bits, matching that path's
- * color-only output. The trailing newline shiki appends as a final empty line
+ * markup font-style bits the theme lets through (bold/italic/underline in
+ * markdown scopes) are dropped — the line-numbered file view renders
+ * color-only runs. The trailing newline shiki appends as a final empty line
  * is dropped so the run count matches the caller's own line array.
  * @param code - the source text.
  * @param lang - the language hint (a file-extension-derived language id).

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

@@ -4,19 +4,23 @@
  * Re-parsing the whole accumulated document on every streaming chunk is
  * quadratic in the final reply length. CommonMark block parsing is line-based
  * and appended text can only reshape the parse frontier — the last top-level
- * block (a paragraph becoming a setext heading or a table, a list continuing
- * after a blank line, an unclosed fence swallowing lines) — so earlier blocks
- * are final. This parser therefore freezes all but the trailing
- * {@link UNSTABLE_TAIL_BLOCKS} blocks and re-parses only the source tail
- * behind them: each source region is parsed O(1) times over the stream
- * instead of once per chunk.
+ * block (a paragraph becoming a setext heading or a table, or a list
+ * continuing after a blank line) — so earlier blocks are final. This parser
+ * therefore freezes all but the trailing {@link UNSTABLE_TAIL_BLOCKS} blocks
+ * and re-parses only the source tail behind them. A final unclosed top-level
+ * fence cannot freeze as a block, so its completed content lines use a second
+ * frontier: only the last completed line and current partial line return
+ * through the caller's grammar. Each source region is therefore parsed a
+ * bounded number of times over the stream instead of once per chunk.
  *
- * The freeze boundary comes from the parser's own `position` offsets, never
- * from custom source scanning. The cut sits at the *end offset* of the last
- * frozen block (not the next block's start): a following block's start offset
- * excludes up to three spaces of insignificant leading indentation, which is
- * harmless to drop, but cutting at the previous end also keeps the
- * inter-block blank lines in the tail so the sliced source stays verbatim.
+ * The block freeze boundary comes from the parser's own `position` offsets.
+ * The cut sits at the *end offset* of the last frozen block (not the next
+ * block's start): a following block's start offset excludes up to three spaces
+ * of insignificant leading indentation, which is harmless to drop, but
+ * cutting at the previous end also keeps the inter-block blank lines in the
+ * tail so the sliced source stays verbatim. Fence scanning only recognizes a
+ * parser-confirmed code node and closing delimiter; ambiguous input returns to
+ * the normal tail parse.
  *
  * Known deviation, shared with any prefix-freeze scheme: micromark resolves
  * reference-style links and footnotes document-wide at parse time, so a
@@ -55,8 +59,15 @@ export declare class IncrementalMarkdownParser {
     private frozen;
     private generation;
     private cached;
+    private openFence;
     /** @param parse - Grammar shared with whatever renders the blocks, so boundaries agree. */
     constructor(parse: (text: string) => Root);
+    /** Parse one unclosed-fence content slice through the caller's grammar. */
+    private fenceValue;
+    /** Recognize the parsed tail's final unclosed fence and prepare its incremental content frontier. */
+    private openFenceState;
+    /** Extend a recognized unclosed fence without parsing its completed content prefix again. */
+    private updateOpenFence;
     /**
      * Fold the current accumulated text and return the frozen/tail split.
      * Idempotent for identical input (the previous result is returned as-is),

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

@@ -21,9 +21,14 @@ 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 | undefined;
+    copyLabel: string;
     /** Copy-button label during the post-copy confirmation window. */
-    copiedLabel?: string | undefined;
+    copiedLabel: string;
+}
+/** Localized chrome for a Markdown document. */
+export interface MarkdownLabels {
+    code: MarkdownCodeLabels;
+    footnotes: string;
 }
 /** Link/image reference targets collected from a document (first definition per identifier wins, as in CommonMark). */
 export interface ReferenceTargets {
@@ -67,10 +72,10 @@ export interface MarkdownFileMentions {
  * numbering accumulated in document order while references render.
  */
 export interface MarkdownRenderContext {
-    /** Streaming arm: fences render plain and TeX stays literal. */
+    /** 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 codeLabels: MarkdownCodeLabels | undefined;
+    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. */

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/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 @deepseek-ai/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/useAnchoredPosition.d.ts

@@ -3,10 +3,10 @@
  *
  * 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 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.
+ * 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 @deepseek-ai/dsh-client-ui-primitives/useAnchoredPosition
  */
 import { type CSSProperties, type RefObject } from 'react';
@@ -18,14 +18,16 @@ export interface AnchoredPositionOptions {
     anchorRef: RefObject<HTMLElement | null>;
     /** The floating element, measured so the clamp uses real dimensions. */
     panelRef: RefObject<HTMLElement | null>;
-    /** Distance kept between the anchor's bottom edge and the panel's top. */
+    /** 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, and the gap/margin distances.
+ * @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;

package/lib/types/useDismissOnOutsidePointer.d.ts

@@ -4,6 +4,8 @@ import type { RefObject } from 'react';
  * @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): void;
+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,19 @@
+/**
+ * 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. Three 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; and
+ * plain `/name` / `@name` word-boundary tokens decorate by shape alone (sent
+ * tokens were validated at compose time).
+ */
+import type { ReactNode } from 'react';
+/**
+ * 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.
+ * @returns inline nodes covering the whole text.
+ */
+export declare function projectUserText(text: string, sessionLabels: readonly string[]): ReactNode;
+//# sourceMappingURL=user-text.d.ts.map

package/lib/user-text.module.css

@@ -0,0 +1,35 @@
+/* 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;
+}
+
+/* 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,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-primitives",
   "description": "Pure React atoms for the dsh web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -51,8 +51,8 @@
   "devDependencies": {
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "files": [
     "lib/index.js",
@@ -61,7 +61,6 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }

package/lib/ConnectionBanner.module.css

@@ -1,13 +0,0 @@
-.banner {
-  position: fixed;
-  top: 0;
-  left: 0;
-  right: 0;
-  z-index: 100;
-  padding: 4px 12px;
-  text-align: center;
-  font-size: 12px;
-  line-height: 18px;
-  background: var(--dsw-alias-state-error-primary);
-  color: var(--dsw-alias-label-primary-foreground);
-}

package/lib/types/ConnectionBanner.d.ts

@@ -1,12 +0,0 @@
-/**
- * Render the reconnecting banner.
- * @param props.reconnecting - true while the connection is in backoff/retry.
- * @param props.label - banner text; the owner passes localized copy (this
- * package is cordis-free, so copy arrives via props).
- * @returns the banner, or null when connected.
- */
-export declare function ConnectionBanner({ reconnecting, label }: {
-    reconnecting: boolean;
-    label?: string | undefined;
-}): import("react").JSX.Element | null;
-//# sourceMappingURL=ConnectionBanner.d.ts.map