@changfenhuang/dsh-genui 0.9.1

package/lib/types/client/dom-fence.d.ts

@@ -0,0 +1,14 @@
+import { type Root } from 'react-dom/client';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client';
+/** Override the React root factory (tests / tuning). */
+export declare function setDomRootFactory(factory: (container: HTMLElement) => Root): void;
+/**
+ * Install the DOM render channel. Returns a disposer that restores every
+ * taken-over block and disconnects the observers.
+ *
+ * @param ctx - the client context (sessions service for the current session).
+ * @param sendAction - plugin-owned relay: (sessionId, action, payload) → the
+ *   scoped conversation send carrying the `[genui-action]` prompt.
+ */
+export declare function installDomFenceRenderer(ctx: Context, sendAction: (sessionId: SessionId, action: string, payload: Record<string, unknown>) => void): () => void;

package/lib/types/client/echarts-lazy.d.ts

@@ -0,0 +1,17 @@
+/** The ECharts instance surface (the subset the component uses). */
+export interface EChartsInstance {
+    setOption: (opt: unknown, notMerge?: boolean) => void;
+    resize: () => void;
+    dispose: () => void;
+}
+/**
+ * Create an ECharts instance on `el` with the given option (engine loaded on
+ * demand). The caller owns the returned instance and must dispose it.
+ * @param el - the DOM node to host the chart canvas.
+ * @param option - the ECharts option object.
+ * @param opts - optional height override.
+ * @returns the ECharts instance (setOption/resize/dispose).
+ */
+export declare function createChart(el: HTMLElement, option: unknown, opts?: {
+    height?: number;
+}): Promise<EChartsInstance>;

package/lib/types/client/fence-render.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The dsh-ui fence render pipeline, shared by both render channels:
+ *
+ * - **Registry channel** (contract hosts): the host's MarkdownText resolves
+ *   ```dsh-ui fences through the fence-registry extension point and calls
+ *   {@link renderGenuiFence} with a session-scoped context (sessionId + the
+ *   settled source identity). An unrepairable body renders {@link FenceFallback}.
+ * - **DOM channel** (pristine hosts, no extension point): the DOM observer
+ *   (`dom-fence.ts`) finds stock code blocks labelled `dsh-ui` and mounts
+ *   {@link renderResolvedFenceNode} into its own React root, wrapped in the
+ *   plugin-owned action context. An unrepairable body returns `null` so the
+ *   stock code block stays visible.
+ *
+ * Structural types are declared locally on purpose: the context contract is
+ * a data shape, and pristine hosts do not export the host-side type names.
+ */
+import { type Key, type ReactNode } from 'react';
+import type { GenuiSpec } from './spec.ts';
+/** Settled fence source identity (data shape, host-independent). */
+export interface GenuiFenceSource {
+    /** Stable structural id, e.g. `['assistant', seq, block, fence]` or `dom:<anchor>:<i>`. */
+    readonly id: string;
+    /** Three-part order: [messageSeq, textBlockIndex, fenceIndex]. */
+    readonly order: readonly [number, number, number];
+}
+/** Context a fence renderer receives beside the raw source and React key. */
+export interface GenuiFenceContext {
+    /** Owning session route; absent outside a session-scoped render. */
+    readonly sessionId?: string;
+    /** Present only for settled/interrupted renders with a stable identity. */
+    readonly source?: GenuiFenceSource;
+}
+/**
+ * Resolve a raw fence body to a guarded spec.
+ *
+ * - Tier-1 repair (quote escape + trailing commas): safe at any time —
+ *   adopted only when the whole body parses, so a still-growing streaming
+ *   half keeps falling back to the code block, never flashing a banner.
+ * - Tier-2 completion (missing quotes/brackets): settled renders only —
+ *   `context.source` exists exclusively once the message finished, so
+ *   streaming halves are never completed early.
+ */
+export declare function resolveGenuiSpec(raw: string, context?: GenuiFenceContext): GenuiSpec | null;
+/**
+ * The resolved fence render for the DOM channel: `null` when the body is
+ * unrepairable (the stock code block stays visible), otherwise the panel
+ * publisher (`panel:true`; renders nothing in the flow — mounted as an empty
+ * root so the taken-over block is hidden) or the inline GenuiBlock tree.
+ * Shared verbatim by both channels.
+ */
+export declare function renderResolvedFenceNode(raw: string, key: Key, context?: GenuiFenceContext): ReactNode | null;
+/**
+ * Registry-channel fence renderer (contract hosts): like the resolved node,
+ * but an unrepairable body renders the fallback code block + settled
+ * diagnostic — the host replaced its own block with our output — and an
+ * unpublishable `panel:true` fence renders `null` (nothing in the flow).
+ */
+export declare function renderGenuiFence(raw: string, key: Key, context?: GenuiFenceContext): ReactNode;

package/lib/types/client/gallery.d.ts

@@ -0,0 +1,9 @@
+/**
+ * GenUI gallery: one spec exercising every white-listed node type, used as
+ * the canonical full-vocabulary sample (tests render it and assert every
+ * component family appears; docs and demos reuse it as the "show everything"
+ * fence).
+ */
+import type { GenuiSpec } from './spec.ts';
+/** A single spec covering all 40 node types in the vocabulary. */
+export declare const gallerySpec: GenuiSpec;

package/lib/types/client/guard.d.ts

@@ -0,0 +1,126 @@
+/**
+ * GenUI spec guard: resource limits, structural validation, and deterministic
+ * repair for ```dsh-ui fence specs.
+ *
+ * The renderer path runs every fence body through `repairGenuiSpec` before
+ * rendering, so a pathological or hostile spec — deep nesting, thousands of
+ * nodes, oversized strings, out-of-range numbers — degrades gracefully instead
+ * of stalling the UI. Repair is deterministic and prefix-stable: a component
+ * that survives repair of a partial stream keeps its position when later
+ * chunks arrive, so streaming re-renders stay consistent.
+ *
+ * Policy:
+ * - Unknown node `type`s pass through untouched (plugin-registered custom
+ *   components via `registerGenuiComponent` are opaque to this package).
+ * - Known types: required fields must have the right type or the node is
+ *   dropped; numbers are clamped into range; strings truncated; arrays
+ *   sliced to their caps; containers recursed with a depth budget.
+ * - The whole spec carries a node budget; once exhausted, remaining siblings
+ *   are elided.
+ */
+import type { GenuiSpec } from './spec.ts';
+/** Hard resource limits enforced by repair (and mirrored at render time). */
+export declare const GENUI_LIMITS: {
+    /** Maximum nesting depth of the component tree. */
+    readonly maxDepth: 8;
+    /** Maximum total nodes across the whole spec. */
+    readonly maxNodes: 200;
+    /** Maximum length of any plain string field. */
+    readonly maxString: 2000;
+    /** Maximum length of a `code` body. */
+    readonly maxCode: 12000;
+    /** Maximum length of a mermaid source. */
+    readonly maxMermaid: 8000;
+    /** Maximum `grid` columns. */
+    readonly maxGridCols: 12;
+    /** Maximum `tabs` count. */
+    readonly maxTabs: 12;
+    /** Maximum `accordion` items. */
+    readonly maxAccordionItems: 24;
+    /** Maximum `list` items. */
+    readonly maxListItems: 50;
+    /** Maximum `select`/`radio` options. */
+    readonly maxOptions: 50;
+    /** Maximum `table` rows / columns. */
+    readonly maxTableRows: 50;
+    readonly maxTableCols: 12;
+    /** Maximum `chart` data points per series. */
+    readonly maxChartPoints: 60;
+    /** Maximum `plot` series and per-series parameters. */
+    readonly maxPlotSeries: 8;
+    readonly maxPlotParams: 6;
+    /** Maximum `scene3d` meshes. */
+    readonly maxMeshes: 5;
+    /** Maximum `quiz` options. */
+    readonly maxQuizOptions: 8;
+    /** Maximum `steps` / `timeline` / `breadcrumb` / `keyvalue` entries. */
+    readonly maxSteps: 24;
+    readonly maxTimelineItems: 24;
+    readonly maxBreadcrumbItems: 12;
+    readonly maxKeyValuePairs: 24;
+    /** Maximum `file-tree` nesting. */
+    readonly maxTreeDepth: 6;
+    /** Maximum `diagram` nodes / edges / zones / focal accents (editorial
+     * complexity budget, mirroring diagram-design's §7 limits). */
+    readonly maxDiagramNodes: 9;
+    readonly maxDiagramEdges: 12;
+    readonly maxDiagramZones: 3;
+    readonly maxDiagramFocal: 2;
+    readonly maxDiagramLabel: 14;
+    /** Maximum depth of an `echart` option object (prevents pathological nested
+     * ECharts configs from stalling the guard walk). */
+    readonly maxEChartOptionDepth: 10;
+    /** Maximum length of any single array inside an `echart` option (prevents
+     * a model from stalling rendering with `series.data` of hundreds of
+     * thousands of points). */
+    readonly maxEChartArrayLen: 500;
+    /** Maximum total entries (object keys + array elements) traversed while
+     * sanitizing an `echart` option. Bounds the walk so a pathologically
+     * large option object cannot stall the guard. */
+    readonly maxEChartOptionNodes: 2000;
+};
+/** Result of `validateGenuiSpec`. */
+export interface GenuiValidation {
+    ok: boolean;
+    /** Human-readable problems, empty when `ok`. */
+    errors: string[];
+}
+/**
+ * Deterministically repair a raw spec value into a renderable GenuiSpec.
+ * Returns null only when the root is not an object with an `items` array
+ * (a bare component root is wrapped into a col first — the documented fence
+ * vocabulary allows single-component bodies); every other defect is healed by
+ * dropping/clamping/truncating. Idempotent: repairing a repaired spec is a
+ * no-op.
+ */
+export declare function repairGenuiSpec(value: unknown): GenuiSpec | null;
+/**
+ * Count the nodes of a spec tree (every item, descending into tabs /
+ * accordion / file-tree / list containers — the same descent
+ * `validateGenuiSpec` walks). Shared by the panel fold (node-budget gate)
+ * and validation, so the panel never runs a second, divergent traversal.
+ * `cap` bounds the walk for hostile inputs; the panel passes
+ * `PANEL_LIMITS.maxNodes + 1` to detect overflow without counting the whole
+ * tree.
+ */
+export declare function countGenuiNodes(value: unknown, cap?: number): number;
+/** Every white-listed node `type`. Keep in sync with the repairNode switch —
+ * validate_dsh_ui uses it to tell declared GenUI nodes apart from unrelated
+ * `"type"` strings (e.g. file-tree's `{type:'file'}` children). */
+export declare const GENUI_NODE_TYPES: ReadonlySet<string>;
+/**
+ * Count DECLARED nodes in a raw spec tree: objects whose `type` is a
+ * white-listed string, descending the same containers `countGenuiNodes`
+ * walks. `validate_dsh_ui` compares this with the repaired count to surface
+ * children the repair silently dropped (blank-render class of bugs, issue
+ * #42) instead of reporting a green check on a half-empty tree.
+ */
+export declare function countDeclaredGenuiNodes(value: unknown, cap?: number): number;
+/**
+ * Validate a raw spec value against the white list and limits, collecting
+ * human-readable problems. Unlike repair this never mutates: it is a
+ * diagnostic for tests and tooling. Unknown `type`s are reported (a plugin
+ * custom type is valid only when a renderer is registered — the guard cannot
+ * know, so it flags them as warnings).
+ */
+export declare function validateGenuiSpec(value: unknown): GenuiValidation;

package/lib/types/client/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-genui browser half: the ```dsh-ui fence renderer, the keyed toolview
+ * for the `render_ui` tool, and the session panel dock.
+ *
+ * Fence rendering is dual-mode, chosen at boot:
+ * - **Registry channel** (contract hosts): the host's MarkdownText resolves
+ *   ```dsh-ui fences through the fence-registry extension point; this package
+ *   registers `renderGenuiFence`. Action callbacks ride the host-installed
+ *   GenuiActionContext.
+ * - **DOM channel** (pristine hosts): no extension point exists, so
+ *   `dom-fence.ts` observes the conversation DOM, finds settled stock code
+ *   blocks labelled `dsh-ui`, and mounts the same render pipeline in its own
+ *   React roots — wrapped in the plugin-owned GenuiActionContext that relays
+ *   `[genui-action]` through the scoped conversation send. Either way the
+ *   deployment is the STOCK DSH snapshot plus this plugin.
+ *
+ * The renderer parses the fence body with the partial parser: while the reply
+ * streams, every FINISHED component appears the moment its JSON object
+ * closes, so the UI assembles top-down before the fence (or reply) completes.
+ * A body with no finished component yet falls back to a plain code block.
+ * @module @changfenhuang/dsh-genui/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { renderGenuiFence } from './fence-render.tsx';
+/** Add low-priority prefetch links for the lazy engine assets (mermaid/three).
+ * Browser-dependent: some engines ignore `<link rel=prefetch>`; harmless
+ * either way — the on-demand loader still covers a cache miss. Exported for
+ * tests. */
+export declare function prefetchGenuiAssets(): void;
+/** Cordis client entry: register the fence renderer on boot, the keyed
+ * toolview for the render_ui tool, and the session panel dock; returning the
+ * disposers lets cordis tear all registrations down on plugin unload. */
+export declare function apply(ctx: Context): () => void;
+export declare const inject: string[];
+export { renderGenuiFence };
+export type { GenuiFenceContext } from './fence-render.tsx';

package/lib/types/client/interaction-store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Interaction-state store: durable per-block GenUI interaction state
+ * (radio answers, submit lock, input/textarea values) in localStorage.
+ *
+ * LOCAL-FIRST persistence: a ```dsh-ui block's interactive state survives
+ * page refresh and session reopen because it is keyed by
+ * `session + block slot + content fingerprint` — replaying the same message
+ * (same content) restores the exact state, while NEW content (换题, edited
+ * spec) gets a fresh key and thus a clean slate. Different messages never
+ * share state because their content fingerprints differ.
+ *
+ * Bounded: at most MAX_BLOCKS entries, LRU-evicted on write; each block's
+ * payload is small (answers map + a few field values).
+ * @module @changfenhuang/dsh-genui/client/interaction-store
+ */
+/** Durable state of one UI block. */
+export interface BlockInteractionState {
+    /** group → chosen option label (radio aggregation answers). */
+    answers?: Record<string, string>;
+    /** True after a local grading: the paper stays graded across refresh. */
+    locked?: boolean;
+    /** field id → current value (input/textarea with an `id`). */
+    fields?: Record<string, string>;
+}
+/** Load a block's durable state, or null when absent/corrupt. */
+export declare function loadBlockState(stateKey: string): BlockInteractionState | null;
+/** Save a block's durable state (LRU: touched keys move to the front). */
+export declare function saveBlockState(stateKey: string, state: BlockInteractionState): void;
+/** Forget a block's durable state (e.g. after a reset-to-empty). */
+export declare function clearBlockState(stateKey: string): void;
+/**
+ * Deterministic content fingerprint (djb2) for a block's raw fence body.
+ * Two render passes of the SAME content share a fingerprint (state restores);
+ * edited content gets a new one (fresh state). Not a security hash — the
+ * store only uses it for equality/identity.
+ */
+export declare function fingerprint(raw: string): string;
+/** Build the durable state key for a fence block: session + fence slot + content fingerprint. */
+export declare function fenceStateKey(sessionId: string, fenceKey: number | string, raw: string): string;
+/** Build the durable state key for a panel publish (content-keyed). */
+export declare function panelStateKey(sessionId: string, raw: string): string;
+/** Build the durable state key for a render_ui tool card (call-keyed). */
+export declare function toolStateKey(sessionId: string, callId: string): string;

package/lib/types/client/mermaid-core.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Render mermaid source to an SVG string.
+ * @param code - the mermaid diagram source.
+ * @returns the rendered SVG markup (verified free of script/event handlers).
+ * @throws when the kind is not whitelisted, rendering fails, or the output
+ *   fails the sanitization check.
+ */
+export declare function renderMermaid(code: string): Promise<string>;

package/lib/types/client/mermaid-lazy.d.ts

@@ -0,0 +1,9 @@
+export { assertSafeSvg, ensureFlowchartKind, repairMermaidSource } from './mermaid-safe.ts';
+/**
+ * Render mermaid source to an SVG string (engine loaded on demand).
+ * @param code - the mermaid diagram source.
+ * @returns the rendered SVG markup (verified free of script/event handlers).
+ * @throws when the asset cannot load, the kind is not whitelisted, rendering
+ *   fails, or the output fails the sanitization check.
+ */
+export declare function renderMermaid(code: string): Promise<string>;

package/lib/types/client/mermaid-safe.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure mermaid source utilities — no mermaid import, so this module can ship
+ * in the main client bundle while the heavy mermaid engine lives in a lazy
+ * asset bundle (`lib/assets/mermaid.js`, loaded on demand by mermaid-lazy).
+ * @module @changfenhuang/dsh-genui/client/mermaid-safe
+ */
+/** Throws when `svg` carries script, event-handler attributes, or
+ * `javascript:` URIs. Exported for tests; `renderMermaid` is the only caller
+ * in production. */
+export declare function assertSafeSvg(svg: string): void;
+/**
+ * Best-effort repair of common model-authored label mistakes in graph /
+ * flowchart sources, used only when the original fails to render:
+ * - drop backticks — lexically illegal in mermaid labels (models embed
+ *   ```dsh-ui style fences, which break the parser with "Lexical error");
+ * - strip `<br/>` tags, which require htmlLabels (never enabled here);
+ * - quote unquoted node labels containing CJK, spaces, or other characters
+ *   mermaid's bare-label grammar rejects (observed live: `A[模型生成 spec]`).
+ * Conservative by design: already-quoted labels, plain ASCII labels without
+ * spaces, and non-flowchart kinds are left untouched (apart from the
+ * backtick/`<br/>` sanitation above, which is harmless everywhere in a
+ * flowchart).
+ *
+ * Labeled-edge spans (`-- 文本 -->`, `== 文本 ==>`, `-. 文本 .->`) are free
+ * text and must never be quoted: wrapping them breaks the parser
+ * ("Expecting 'LINK' … got 'STR'"), observed live with
+ * `H -- 否(流式中) --> J`. Each span is swapped for a bracket-free
+ * placeholder before quoting and restored verbatim afterwards, so the quote
+ * pass can neither corrupt it nor be thrown off by inserted quotes
+ * elsewhere on the line.
+ *
+ * Pipe-style edge labels (`-->|文本|`) are the opposite: an UNQUOTED pipe
+ * label containing `[` or `]` breaks the parser ("Parse error", observed
+ * live with `-->|6. 用户交互 → [genui-action]|`) because the brackets are
+ * node grammar. Quoting the label text is display-neutral (mermaid renders
+ * `-->|"文本"|` without the quotes) and parses. These spans are masked too,
+ * so the node-label quote pass below cannot reach inside them and produce
+ * nested quotes, and restored last.
+ */
+export declare function repairMermaidSource(code: string): string;
+/**
+ * Lenient repair for sources that omit the mandatory diagram-type
+ * declaration line — the #1 failure mode of model-generated mermaid (chat
+ * assistants routinely emit `A --> B` without the leading `graph TD`).
+ *
+ * When the first token is not an already-declared `graph`/`flowchart` kind
+ * but the body contains flowchart edge arrows, prepend `graph TD` so the
+ * diagram renders instead of tripping the kind gate. Anything else — an
+ * explicitly declared kind, a sequence/gantt/pie body (no flowchart edges),
+ * or plain text — is returned unchanged: we never guess at the diagram type.
+ */
+export declare function ensureFlowchartKind(code: string): string;

package/lib/types/client/panel-command.d.ts

@@ -0,0 +1,29 @@
+/**
+ * /panel slash command + the default panel spec.
+ *
+ * The session panel dock is an always-present seat, but it only becomes
+ * visible once a spec has been published — both existing publish paths
+ * (render_ui tool result, panel:true fence) are model-driven. The /panel
+ * command gives a deterministic, client-side entry point:
+ * - `/panel` — publishes the default spec and requests the dock to expand
+ *   instantly, with zero model round-trip;
+ * - `/panel clear` (off/close) — empties the panel so the dock retracts;
+ * - `/panel <指令>` — shows the default spec for immediate feedback, then
+ *   relays the instruction to the model, which replaces the panel with
+ *   content tailored to the request (panel:true fence).
+ * Panel updates afterwards still flow through the model (say "更新面板" or
+ * re-run render_ui) or through another /panel.
+ */
+import type { InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client';
+import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client';
+import type { GenuiSpec } from './spec.ts';
+/** Default panel content published by `/panel`: the component overview. */
+export declare const DEFAULT_PANEL_SPEC: GenuiSpec;
+/**
+ * The /panel source. Menu group `genui` under the '/' trigger; the panel
+ * candidate claims the line so both the menu pick and a bare `/panel` enter
+ * resolve to the same command. `matchEnter` is implemented so the command
+ * works without opening the menu (leading-token adjudication), and it also
+ * catches `/panel clear` style args.
+ */
+export declare function createPanelSlashSource(sendInstruction: (sessionId: SessionId, instruction: string) => void): InputTriggerSource;

package/lib/types/client/panel-store.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Session GenUI panel store: folds stable per-source panel operations into
+ * one read-only snapshot per session. The toolview and the settled-fence
+ * publisher submit operations (`replace`/`append`) carrying a stable
+ * sourceId and a three-part order; the store deduplicates by source, sorts
+ * by order, applies a deterministic fold under a node/append budget, and
+ * notifies subscribers only when the folded snapshot actually changes.
+ *
+ * Ordering: no "last caller wins", no Infinity. Operations from DIFFERENT
+ * sources always both apply; replays of the same source are idempotent; a
+ * later replace resets everything earlier; an append beyond the budget is
+ * remembered as an overflow barrier so an out-of-order earlier replace can
+ * re-fold deterministically. A local `/panel` override (default panel or
+ * clear) is the fold base and blocks every replay at/below the highest
+ * message seq seen so far — old history can never resurrect the panel.
+ *
+ * Scale limits live in `PANEL_LIMITS` (adjustable defaults, not law — see
+ * docs/plans/2026-08-12-dsh-genui-design-optimization.md). Budget
+ * rejections are DETERMINISTIC (no LRU eviction: eviction would make the
+ * fold depend on arrival order).
+ *
+ */
+import type { GenuiSpec } from './spec.ts';
+/** Panel scale limits — adjustable defaults (design doc: scale limits are
+ *  configurable, not law). Folds read the CURRENT limits, so tuning applies
+ *  from the next operation on. */
+export declare const PANEL_LIMITS: {
+    /** Max nodes in the folded panel snapshot. */
+    readonly maxNodes: 200;
+    /** Max append operations kept after the latest replace. */
+    readonly maxAppends: 200;
+};
+type PanelLimits = {
+    maxNodes: number;
+    maxAppends: number;
+};
+/** Override the panel limits (operator tuning / tests). Applied at the next fold. */
+export declare function setPanelLimits(next: Partial<PanelLimits>): void;
+/** Three-part stable order: [messageSeq, textBlockIndex, fenceIndex]. */
+export type PanelOrder = readonly [number, number, number];
+/** One persistent panel operation from a settled source. */
+export interface PanelOperation {
+    /** Stable source identity (fence source id or `['render_ui', callId]`). */
+    sourceId: string;
+    order: PanelOrder;
+    mode: 'replace' | 'append';
+    spec: GenuiSpec;
+}
+export type PanelOperationStatus = 'accepted' | 'idempotent' | 'blocked' | 'overflow';
+/**
+ * Submit one panel operation. Idempotent per sourceId; ordering and budget
+ * per the module doc. Returns the outcome so callers can diagnose once per
+ * source (e.g. "panel at its node/appends budget — send a replace").
+ */
+export declare function applyPanelOperation(sessionId: string, op: PanelOperation): PanelOperationStatus;
+/**
+ * Apply the local `/panel` override: `spec` (the default panel) or null
+ * (clear) becomes the fold base, and every operation at/below the highest
+ * message seq seen so far is dead — old history replays cannot resurrect
+ * the panel. A later real operation (order[0] > barrier) replaces or merges
+ * into the override as usual.
+ */
+export declare function setLocalPanel(sessionId: string, spec: GenuiSpec | null): void;
+/** Log one budget-overflow diagnostic per source (replays stay silent). */
+export declare function diagnosePanelBudget(sessionId: string, sourceId: string): void;
+/** Tear down a session's panel state (session destroy / hard clear). Memory
+ * only: drops the in-memory record, the session's expand token, and overflow
+ * diagnostics, so a long-lived app never accumulates per-session state for
+ * closed sessions. The localStorage entry SURVIVES — reopening the session
+ * restores the panel instantly (that is the persistence feature); an explicit
+ * user clear goes through setLocalPanel(null), which persists the cleared
+ * state + barrier. */
+export declare function clearSessionPanel(sessionId: string): void;
+/** Current folded spec for a session (useSyncExternalStore getSnapshot).
+ * Lazily hydrates from localStorage on first access after a reload. */
+export declare function getPanelSpec(sessionId: string): GenuiSpec | null;
+/** Subscribe to panel changes. Returns the disposer. */
+export declare function subscribePanel(listener: () => void): () => void;
+/**
+ * Merge an `append` spec into the current panel spec:
+ * - both sides single-tabs containers → merge BY TAB LABEL: items of
+ *   same-labelled tabs are appended, new labels are added (order preserved);
+ * - otherwise → plain item lists are appended to the tail.
+ * The previous title wins unless it was absent. `next` is returned as-is when
+ * there is nothing to merge into. Export for tests.
+ */
+export declare function mergePanelSpecs(prev: GenuiSpec | null, next: GenuiSpec): GenuiSpec;
+/** Request the panel dock to expand for a session (e.g. the /panel command). */
+export declare function requestPanelExpand(sessionId: string): void;
+/** Current expand token for a session (useSyncExternalStore getSnapshot). */
+export declare function getPanelExpandToken(sessionId: string): number;
+/** Subscribe to expand requests. Returns the disposer. */
+export declare function subscribePanelExpand(listener: () => void): () => void;
+export {};

package/lib/types/client/panel.d.ts

@@ -0,0 +1,15 @@
+import { type GenuiActionHandler } from './action-context.ts';
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+/** Injection face built per session in apply (scoped conversation send). */
+export interface GenuiPanelInjected {
+    sessionId: string;
+    sendGenuiAction: GenuiActionHandler;
+}
+export type GenuiPanelProps = PropsRuntime<'conversation.input.dock'> & GenuiPanelInjected;
+/**
+ * Panel dock entry. Renders nothing until the session's toolview published a
+ * spec; afterwards the SAME block re-renders on every publish. Collapsed by
+ * default so the dock never steals the message flow's scroll room; the
+ * header always shows the current panel title.
+ */
+export declare function GenuiPanel({ sessionId, sendGenuiAction }: GenuiPanelProps): import("react").JSX.Element | null;

package/lib/types/client/parse-partial.d.ts

@@ -0,0 +1,37 @@
+import { type GenuiSpec } from './spec.ts';
+/** Default repair-candidate budget (adjustable; see the design doc). */
+export declare const MAX_PARTIAL_REPAIR_ATTEMPTS = 32;
+/** Override the repair-candidate budget (tests / tuning). */
+export declare function setMaxPartialRepairAttempts(n: number): void;
+/** One repair candidate: a balanced prefix of the body ending at `end`,
+ *  plus the closing brackets to append (empty when already balanced). */
+export interface PartialCandidate {
+    end: number;
+    closingSuffix: string;
+}
+/** Single left-to-right pass over the raw body. Tracks the bracket stack
+ *  (skipping strings/escapes correctly) and records:
+ *  - every position where the prefix is fully balanced (trailing comma or
+ *    fence tail) — candidate with an empty closing suffix;
+ *  - every `}` object close whose remaining depth fits the spec budget —
+ *    candidate with the remaining brackets closed (an unfinished trailing
+ *    element).
+ *  Candidates are ring-buffered to the attempts budget (the LAST pushes are
+ *  the longest), then returned longest-first, deduplicated by end. The scan
+ *  stops at the first unbalanced close — earlier balanced prefixes remain
+ *  valid candidates.
+ *
+ * Exposed for tests (the `scannedChars` diagnostic); not exported from the
+ * package entry. The parser calls this exactly once per parse.
+ */
+export declare function collectPartialCandidates(raw: string): {
+    candidates: PartialCandidate[];
+    scannedChars: number;
+};
+/**
+ * Parse a possibly incomplete genui spec body.
+ * @param raw - the fence body as accumulated so far.
+ * @returns a spec containing only finished components, or null when nothing
+ *   usable has been written yet.
+ */
+export declare function parsePartialGenuiSpec(raw: string): GenuiSpec | null;

package/lib/types/client/safe-math.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SafeMath: a restricted math expression evaluator for GenUI plot specs.
+ *
+ * The model supplies an expression string like "sin(x) * 2 + 1". It is parsed
+ * and evaluated here WITHOUT eval / new Function: a hand-written recursive
+ * descent parser over a white-listed function/constant vocabulary. Unknown
+ * identifiers, object property access, and call syntax other than the
+ * white-listed functions are parse errors, so an adversarial expression
+ * cannot reach globals, prototypes, or side effects.
+ *
+ * Supported grammar:
+ *   expr    := term (('+' | '-') term)*
+ *   term    := unary (('*' | '/' | '%') unary)*
+ *   unary   := ('-' | '+') unary | power
+ *   power   := atom ('^' atom)?
+ *   atom    := number | variable | constant | func '(' expr ')' | '(' expr ')'
+ *   variable: 'x' (and any single-letter variable present in vars)
+ *   constant: 'pi' | 'e' | 'tau'
+ *   func    : sin cos tan asin acos atan sqrt cbrt exp log ln abs floor ceil round min max pow
+ */
+export interface SafeMathOptions {
+    /** Variable values; only names present here may be referenced as variables. */
+    vars?: Record<string, number>;
+}
+/**
+ * Compile an expression into an evaluable function.
+ * @param expr - the math expression. `x` is the sampling variable; any other
+ *   name in `vars` is a parameter whose captured value the evaluator returns
+ *   (recompile with new vars to change a parameter — expressions are short).
+ * @param options - parameter values; `x` is reserved and ignored here.
+ * @returns evaluator, or null when the expression is invalid.
+ */
+export declare function compileMathExpr(expr: string, options?: SafeMathOptions): ((x: number) => number) | null;
+/**
+ * Sample an expression over a range.
+ * @param expr - math expression in x, with optional parameters.
+ * @param xMin - inclusive start.
+ * @param xMax - inclusive end.
+ * @param samples - number of samples (>= 2).
+ * @param params - parameter values (e.g. { a: 2, b: 3 }); recompile per change.
+ * @returns [x, y] pairs; non-finite samples are dropped.
+ */
+export declare function sampleExpr(expr: string, xMin: number, xMax: number, samples?: number, params?: Record<string, number>): Array<[number, number]>;

package/lib/types/client/scene3d-core.d.ts

@@ -0,0 +1,21 @@
+/**
+ * three.js scene renderer — the HEAVY half. This module imports three and is
+ * bundled ONLY into the lazy asset bundle `lib/assets/three.js`, loaded on
+ * demand by the scene3d-lazy loader when a spec contains a `scene3d` node;
+ * the main client bundle stays small.
+ *
+ * Security: the model only supplies white-listed primitive shapes, numeric
+ * transforms, and colors. No textures, no external URLs, no scripts, no
+ * custom shaders — everything is geometry + material colors constructed
+ * locally. The renderer mounts into a caller-owned container and returns a
+ * disposer that tears down the WebGL context.
+ * @module @changfenhuang/dsh-genui/client/scene3d-core
+ */
+import type { GenuiScene3D } from './spec.ts';
+/**
+ * Mount a GenUI 3D scene into `container`.
+ * @param container - the DOM node to host the WebGL canvas.
+ * @param scene - the declarative scene spec.
+ * @returns a disposer that removes the renderer and its context.
+ */
+export declare function mountScene(container: HTMLElement, scene: GenuiScene3D): Promise<() => void>;

package/lib/types/client/scene3d-lazy.d.ts

@@ -0,0 +1,8 @@
+import type { GenuiScene3D } from './spec.ts';
+/**
+ * Mount a GenUI 3D scene into `container` (engine loaded on demand).
+ * @param container - the DOM node to host the WebGL canvas.
+ * @param scene - the declarative scene spec.
+ * @returns a disposer that removes the renderer and its context.
+ */
+export declare function mountScene(container: HTMLElement, scene: GenuiScene3D): Promise<() => void>;