@changfenhuang/dsh-genui 0.9.1

package/lib/invariant.js

@@ -0,0 +1,19 @@
+//#region src/plugin/invariant.ts
+const PACKAGE_NAME = "@changfenhuang/dsh-genui";
+/** Cordis companion plugin name. */
+const name = "genui-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this host plugin only registers a static prompt
+* section; the section text is pinned by its own tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,4 @@
+import type { GenuiEChart } from './spec.ts';
+export declare function EChartNode({ node }: {
+    node: GenuiEChart;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,30 @@
+/**
+ * Rendering error boundary: a component render failure inside one GenUI
+ * block must never take down the whole chat surface (pre-2026-08-09 builds
+ * crashed the entire conversation tree on a missing API). Every fence,
+ * toolview card and panel body renders under this boundary; on error the
+ * block degrades to a compact inline alert instead of unmounting the tree.
+ * @module @changfenhuang/dsh-genui/client
+ */
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+interface ErrorBoundaryProps {
+    /** What the block is, shown in the fallback alert (fence / tool / panel). */
+    label?: string;
+    children: ReactNode;
+}
+interface ErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * Class boundary because function components cannot catch their own subtree
+ * errors. `getDerivedStateFromError` flips to the fallback render; the error
+ * itself is logged (and its message surfaced in the alert) so the user sees
+ * a hint instead of a silent white region.
+ */
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
+}
+export {};

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

@@ -0,0 +1,7 @@
+import type { GenuiBlockProps } from './blocks/state.ts';
+export declare const GENUI_ACTION_DEBOUNCE_MS = 300;
+/**
+ * Render a GenUI spec as an inline block. Falls back to nothing when the spec
+ * carries no items (the fence renderer already refused non-specs before us).
+ */
+export declare const GenuiBlock: import("react").NamedExoticComponent<GenuiBlockProps>;

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

@@ -0,0 +1,44 @@
+export interface PlotSeriesParam {
+    name: string;
+    value: number;
+    min?: number | undefined;
+    max?: number | undefined;
+    step?: number | undefined;
+    /** v1.5: animate this parameter from its initial value to this target. */
+    animateTo?: number | undefined;
+    /** Animation duration in ms (default 4000). */
+    durationMs?: number | undefined;
+    /** Loop the animation (default false). */
+    loop?: boolean | undefined;
+}
+export interface PlotSeries {
+    /** Math expression in x. */
+    expr: string;
+    /** Optional label shown in a legend row. */
+    label?: string | undefined;
+    /** Stroke color; defaults to the accent token (multi-series auto-assign). */
+    color?: string | undefined;
+    /** v2.9 draw shape: line (default), area (fill to baseline), scatter. */
+    kind?: 'line' | 'area' | 'scatter' | undefined;
+    /** v2: adjustable parameters, one slider each, live re-render. */
+    params?: PlotSeriesParam[] | undefined;
+}
+/** Categorical palette for multi-series plots: host static tokens only
+ * (design system v2 — same families as the chart/avatar palettes in
+ * GenuiBlock, no off-theme hexes). CSS custom properties resolve inside
+ * inline `style` on SVG strokes and legend swatches. */
+export declare const PLOT_COLORS: string[];
+export interface PlotBlockProps {
+    /** Functions to draw, in draw order. */
+    series: PlotSeries[];
+    /** Horizontal range, inclusive. */
+    xMin?: number | undefined;
+    xMax?: number | undefined;
+    /** Vertical bounds; omitted = auto-fit to the sampled data. */
+    yMin?: number | undefined;
+    yMax?: number | undefined;
+    /** Chart title. */
+    title?: string | undefined;
+}
+/** Render one plot: grid, axes, one polyline per series, legend, sliders. */
+export declare const PlotBlock: import("react").NamedExoticComponent<PlotBlockProps>;

package/lib/types/client/action-context.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from 'react';
+/** v2 action handler: component action + its collected data. */
+export type GenuiActionHandler = (action: string, payload: Record<string, unknown>) => void;
+/** Host-provided context when the deployment ships it, else the local one. */
+export declare const GenuiActionContext: Context<GenuiActionHandler | undefined>;
+/** Read the installed action handler, if any. */
+export declare function useGenuiAction(): GenuiActionHandler | undefined;

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

@@ -0,0 +1,15 @@
+/**
+ * ECharts asset-bundle entry: registers the echarts engine on
+ * `window.__GenuiAssets__.echarts`. Built as a standalone IIFE into
+ * `lib/assets/echarts.js` and served by the plugin's node-half route; loaded
+ * on demand by echarts-lazy when a spec contains an `echart` node.
+ * @module @changfenhuang/dsh-genui/client/asset-echarts
+ */
+import { type EChartsType, type EChartsCoreOption } from 'echarts';
+/** The engine surface registered by the echarts asset bundle. */
+export interface EChartsAssetApi {
+    /** Create an ECharts instance on `el`, apply `option`, return the instance. */
+    createChart: (el: HTMLElement, option: EChartsCoreOption, opts?: {
+        height?: number;
+    }) => EChartsType;
+}

package/lib/types/client/asset-loader.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Asset-bundle loader: fetches one of the plugin's lazy engine bundles
+ * (`lib/assets/mermaid.js` / `lib/assets/three.js`) by script injection and
+ * hands back the engine surface the bundle registered on
+ * `window.__GenuiAssets__`.
+ *
+ * The bundles are served by the plugin's OWN node-half HTTP route
+ * (`/plugins/@changfenhuang/dsh-genui/assets/*`), registered through the host
+ * webserver service — no host source change needed, and the longest-prefix
+ * rule lets this route win over the generic `/plugins` bundle route. Each
+ * file is loaded at most once per page (promise memoized); a rejection is
+ * final for the page (the node's fallback UI takes over).
+ *
+ * The rev query rides the boot graph: the plugin's own row in
+ * `window.__DSH_BOOT__` carries the client bundle rev, so a plugin rebuild
+ * busts the asset cache together with the main bundle. Absent graph = no
+ * query; the route serves no-cache anyway.
+ * @module @changfenhuang/dsh-genui/client/asset-loader
+ */
+/** Resolve an asset URL, appending the bundle rev for cache busting when the
+ * boot graph exposes it. */
+export declare function assetUrl(file: string): string;
+/**
+ * Load one asset bundle and return the engines it registered. Memoized per
+ * file: repeated requests (several mermaid nodes, re-renders) share one
+ * script load; a failed load stays failed for the page (the component shows
+ * its fallback).
+ * @param name - 'mermaid', 'three', or 'echarts'.
+ * @returns the registered engine surface.
+ */
+export declare function loadGenuiAsset<T>(name: 'mermaid' | 'three' | 'echarts'): Promise<T>;

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

@@ -0,0 +1 @@
+export {};

package/lib/types/client/asset-three.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/client/blocks/advanced.d.ts

@@ -0,0 +1,104 @@
+import type { AnswersState, GenuiBlockProps } from './state.ts';
+import type { GenuiAccordion, GenuiBreadcrumb, GenuiCallout, GenuiCode, GenuiCopy, GenuiDiff, GenuiFileTree, GenuiJson, GenuiKeyValue, GenuiMermaid, GenuiPlot, GenuiQuiz, GenuiScene3D, GenuiSteps, GenuiTabs, GenuiTimeline } from '../spec.ts';
+/** Callout: a tinted notice box with an optional heading. */
+export declare const CalloutNode: import("react").NamedExoticComponent<{
+    node: GenuiCallout;
+}>;
+/** Steps: a vertical progress checklist with an optional current index. */
+export declare const StepsNode: import("react").NamedExoticComponent<{
+    steps: GenuiSteps;
+}>;
+/** KeyValue: a definition list for configs and metadata. */
+export declare const KeyValueNode: import("react").NamedExoticComponent<{
+    node: GenuiKeyValue;
+}>;
+/** Plot: SVG function plot over the SafeMath evaluator. The series mapping
+ * is memoized on the stable spec node so the memo boundary actually skips
+ * sibling-state re-renders (a fresh mapped array would defeat it). */
+export declare const PlotNode: import("react").NamedExoticComponent<{
+    plot: GenuiPlot;
+}>;
+/** Diff: 收编 dsh DiffBlock (same path/oldText/newText shape as DiffHunk). */
+export declare const DiffNode: import("react").NamedExoticComponent<{
+    node: GenuiDiff;
+}>;
+/** Json: 收编 dsh JsonTree. */
+export declare const JsonNode: import("react").NamedExoticComponent<{
+    node: GenuiJson;
+}>;
+/** Code: 收编 dsh CodeBlock with explicit language. */
+export declare const CodeNode: import("react").NamedExoticComponent<{
+    node: GenuiCode;
+}>;
+/**
+ * Table: LOCAL sorting (v2.9) — click a header to sort ascending, click
+ * again for descending, a third click restores the spec order. Zero model
+ * round trip. Numeric cells (numbers or numeric strings) compare numerically;
+ * everything else compares as text.
+ */
+export declare function TabsNode({ tabs, onAction, depth, answers }: {
+    tabs: GenuiTabs;
+    onAction?: GenuiBlockProps['onAction'];
+    depth?: number;
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Radio: one option from a group; local selection state. The group name is
+ * useId-based so sibling groups never collide (deterministic per mount).
+ *
+ * v2.5 aggregation: when `group` is set, the selection is recorded into the
+ * block-wide answers registry instead of firing a per-click action — a
+ * sibling `submit` node then grades the paper IN PLACE (v2.6, questions
+ * carry `answer` data) or collects all groups in ONE action. Without
+ * `group`, the legacy per-click action fires. After a local grading the
+ * group locks until 重新作答 resets it. */
+export declare function AccordionNode({ node, onAction, depth, answers }: {
+    node: GenuiAccordion;
+    onAction?: GenuiBlockProps['onAction'];
+    depth?: number;
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Copy: a one-click copy chip. The live region is a visually-hidden SIBLING
+ * (not inside the button) — button content is atomic to screen readers, so a
+ * live region inside it would never announce. */
+export declare const CopyNode: import("react").NamedExoticComponent<{
+    node: GenuiCopy;
+}>;
+/** Mermaid: lazily loaded diagram renderer. */
+export declare const MermaidNode: import("react").NamedExoticComponent<{
+    node: GenuiMermaid;
+}>;
+/** Scene3D: three.js WebGL canvas, lazily imported. */
+export declare const Scene3DNode: import("react").NamedExoticComponent<{
+    node: GenuiScene3D;
+}>;
+/** Timeline: vertical event list with time markers. */
+export declare const TimelineNode: import("react").NamedExoticComponent<{
+    node: GenuiTimeline;
+}>;
+/** FileTree: indented tree of files and folders. Directory rows are LOCAL
+ * collapsible (spec.ts promised "collapsible children"; this makes it true)
+ * — click a dir to fold/unfold, default fully open. Zero model round trip. */
+export declare const FileTreeNode: import("react").NamedExoticComponent<{
+    node: GenuiFileTree;
+}>;
+/** Quiz: a self-contained teaching question. Selecting an option marks it
+ * correct/incorrect in place and reveals feedback + explanation. With
+ * `action`, the chosen answer is ALSO sent back to the model
+ * (`{type:'quiz', question, answer, correct}`) so the model can collect or
+ * grade it — the in-place judging stays local (no round trip needed). */
+export declare const QuizNode: import("react").NamedExoticComponent<{
+    node: GenuiQuiz;
+    onAction?: GenuiBlockProps["onAction"];
+}>;
+/** Breadcrumb: path-style navigation trail. */
+export declare const BreadcrumbNode: import("react").NamedExoticComponent<{
+    node: GenuiBreadcrumb;
+}>;
+/**
+ * Trailing debounce window (ms) for one `[genui-action]` name: rapid
+ * repeated interactions on one control (button mashing, switch flipping)
+ * collapse into a single action with the LAST payload. Different action
+ * names stay independent. The model round-trip takes seconds, so a few
+ * hundred ms of trailing delay is imperceptible — and it stops bursts of
+ * queued user turns.
+ */

package/lib/types/client/blocks/basic.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Basic display family: avatar palette, and the local click-feedback button
+ * (the actionable-button chip). Used by the render dispatcher.
+ * @module @changfenhuang/dsh-genui/client/blocks/basic
+ */
+import { type ReactNode } from 'react';
+import type { GenuiAudio, GenuiVideo } from '../spec.ts';
+export declare function avatarColor(name: string): string;
+/** Button with LOCAL click feedback: clicking an actionable button shows a
+ * brief "✓ 已触发" chip so the user sees the click registered even while the
+ * model round trip is in flight — no more "点了没反应" perception. The chip
+ * is purely cosmetic; the action fires through `onClick` as before. */
+export declare function ClickFeedbackButton({ className, disabled, onClick, children }: {
+    className: string;
+    disabled?: boolean;
+    onClick?: (() => void) | undefined;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Native controls intentionally own play/pause/seek/volume. Model-authored
+ * autoplay and controls hints are ignored: media starts only after the user
+ * asks for it. */
+export declare const AudioNode: import("react").NamedExoticComponent<{
+    node: GenuiAudio;
+}>;
+export declare const VideoNode: import("react").NamedExoticComponent<{
+    node: GenuiVideo;
+}>;

package/lib/types/client/blocks/charts.d.ts

@@ -0,0 +1,38 @@
+import type { GenuiChart, GenuiTable } from '../spec.ts';
+export declare const CHART_COLORS: string[];
+/**
+ * Sortable numeric value of a cell. Human-written table cells are rarely
+ * plain numbers, so the sort accepts the usual decorations:
+ * `1,234` / `1，234`（千分位）、`1.2k`/`3M`/`5b`、`3.5万`/`2亿`、`0.3%`、
+ * `¥99`/`$12`。A cell that cannot be read as a number returns NaN and the
+ * row falls back to the text comparison — mixed columns sort deterministically
+ * (numbers first, then text).
+ */
+export declare function parseSortableNumber(v: unknown): number;
+export declare const TableNode: import("react").NamedExoticComponent<{
+    node: GenuiTable;
+}>;
+/** Chart: bars (default), line (trend), or donut (share); multi-series bars via `series`.
+ *  memoized: the spec node is a stable reference, so a keystroke in a sibling
+ *  field no longer re-renders the whole chart. */
+export declare const ChartNode: import("react").NamedExoticComponent<{
+    chart: GenuiChart;
+}>;
+/** Bars: one column per datum (grouped bars when `series` is present). */
+export declare const BarsNode: import("react").NamedExoticComponent<{
+    chart: GenuiChart;
+}>;
+/** Line: polyline over a fixed-height plot area with a readable Y axis —
+ * four evenly spaced gridlines + tick labels (design system v2 skeleton). */
+export declare const LineChartNode: import("react").NamedExoticComponent<{
+    chart: GenuiChart;
+}>;
+/** Donut: share of total with a center total. Negative values contribute
+ * zero arc (a negative dasharray segment used to produce an invalid
+ * stroke-dasharray and the browser drew the FULL circle instead). */
+export declare const DonutNode: import("react").NamedExoticComponent<{
+    chart: GenuiChart;
+}>;
+/** Tab strip with local active-tab state. Keyboard: ArrowLeft/Right to move,
+ * Home/End to jump; ids wired via useId so `aria-controls` stays unique
+ * across fences and sessions. */

package/lib/types/client/blocks/diagram/geometry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Editorial diagram geometry: the mandatory orthogonal-connector system from
+ * diagram-design §6, ported to pure functions producing SVG path strings.
+ *
+ * Rules enforced here (the "non-negotiable" list):
+ *  1. Rounded right-angle (orthogonal) elbows with r=8 — never diagonal lines
+ *     between off-axis nodes.
+ *  2. Edge labels sit 6–10px off the stroke behind an opaque mask.
+ *  3. No two connectors share a path — parallel connectors offset ≥12px.
+ *  4. Shared-edge attach points fan ≥12px apart.
+ *  5. A connector never passes behind a non-endpoint box (dashed-transit
+ *     exception only when geometrically unavoidable).
+ *  6. Label masks never overlap nodes (nodes paint after labels).
+ * @module @changfenhuang/dsh-genui/client/blocks/diagram/geometry
+ */
+/** Axis-aligned box. */
+export interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export type Port = 'left' | 'right' | 'top' | 'bottom';
+/** Attachment on a box edge. */
+export interface Attach {
+    x: number;
+    y: number;
+    port: Port;
+}
+/** Center of a box. */
+export declare function center(b: Box): Point;
+/**
+ * Pick the attach point on `from` toward `to`. Port choice follows the
+ * dominant axis: mostly-horizontal travel uses left/right ports, mostly-
+ * vertical uses top/bottom. An explicit `prefer` overrides the heuristic.
+ */
+export declare function attachPoint(box: Box, toward: Box, prefer: Port | undefined): Attach;
+/**
+ * Build an orthogonal path between two attach points. Same-axis endpoints use
+ * a straight segment (the one sanctioned case); every bend is a quarter arc
+ * of radius R.
+ */
+export declare function orthogonalPath(a: Attach, b: Attach): string;
+/**
+ * Route a connector between two boxes with default port selection, returning
+ * the path plus both attach points (for label placement and fan offsets).
+ */
+export declare function routeEdge(from: Box, to: Box, opts?: {
+    fromPort?: Port;
+    toPort?: Port;
+}): {
+    d: string;
+    a: Attach;
+    b: Attach;
+};
+/** Fan an attach point along a box edge (≥12px apart via the (k+1)/(n+1) rule). */
+export declare function fanPoint(box: Box, edge: 'top' | 'bottom' | 'left' | 'right', index: number, count: number): Attach;
+/**
+ * Edge-label geometry: centered on the dominant segment, offset 6–10px from
+ * the stroke so the connector stays visible.
+ */
+export declare function labelGeometry(a: Attach, b: Attach): {
+    cx: number;
+    cy: number;
+    maskY: number;
+    vertical: boolean;
+};
+/** Hop / bridge arc for a crossing connector (applied to the less important edge). */
+export declare function bridgePath(cx: number, cy: number, horizontal: boolean): string;

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

@@ -0,0 +1,5 @@
+import type { GenuiDiagram } from '../../spec.ts';
+/** The `diagram` node renderer. */
+export declare function DiagramNode({ node }: {
+    node: GenuiDiagram;
+}): import("react").JSX.Element;

package/lib/types/client/blocks/diagram/layout.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Editorial diagram layout: resolves a `diagram` spec into positioned boxes
+ * and routed edges. Two layout modes mirror diagram-design's grammar:
+ *
+ *  - Coordinate kinds (architecture, it-state, high-level, process,
+ *    medallion, data-flow, dp-integration): the spec carries x/y/w/h per
+ *    node; this module passes them through (4px-grid already enforced by the
+ *    guard) and routes edges.
+ *  - Rule kinds (flowchart, sequence, state, er, timeline, swimlane,
+ *    quadrant, radar, loop, nested, tree, org-chart, layers, venn, pyramid,
+ *    bar, line, gantt, scatter, dp-security-matrix): the spec carries data
+ *    only; this module lays the nodes out on the editorial grid.
+ *
+ * The output is a plain layout object consumed by the SVG renderer — no
+ * React, no DOM, fully unit-testable.
+ * @module @changfenhuang/dsh-genui/client/blocks/diagram/layout
+ */
+import type { GenuiDiagram, GenuiDiagramEdge, GenuiDiagramNode } from '../../spec.ts';
+import { Box } from './geometry.ts';
+export interface LayoutNode {
+    node: GenuiDiagramNode;
+    box: Box;
+}
+export interface LayoutEdge {
+    edge: GenuiDiagramEdge;
+    /** Resolved box references for routing. */
+    fromId: string;
+    toId: string;
+}
+export interface DiagramLayout {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    /** Canvas size (width/height). */
+    width: number;
+    height: number;
+}
+/**
+ * Resolve a diagram spec into a positioned layout. `parentOf` lets tree-like
+ * kinds pass their hierarchy; other rule kinds use a generic grid.
+ */
+export declare function resolveLayout(diagram: GenuiDiagram, parentOf?: (id: string) => string | undefined): DiagramLayout;

package/lib/types/client/blocks/diagram/theme.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Editorial diagram theme: the diagram-design semantic-token system ported
+ * into the dsh-genui renderer. Every diagram draws from these roles — never
+ * from inline hex in the layout code — and a spec-level `theme` override
+ * merges over the defaults, mirroring diagram-design's style-guide.md.
+ *
+ * Two skins ship: light and dark (the dark palette is the jet-black
+ * inversion, same roles). The `editorial` variant is the full skin and
+ * defaults to light unless the host theme is dark.
+ * @module @changfenhuang/dsh-genui/client/blocks/diagram/theme
+ */
+import type { GenuiDiagramTheme, GenuiDiagramVariant } from '../../spec.ts';
+export interface DiagramPalette {
+    paper: string;
+    paper2: string;
+    ink: string;
+    muted: string;
+    soft: string;
+    rule: string;
+    accent: string;
+    accentTint: string;
+    link: string;
+}
+/** Resolve the active palette from variant + optional theme overrides. */
+export declare function resolvePalette(variant: GenuiDiagramVariant | undefined, theme: GenuiDiagramTheme | undefined): DiagramPalette;
+/** Node treatment → { fill, stroke, dashed } per diagram-design §5. */
+export declare function nodeTreatment(type: string | undefined, p: DiagramPalette): {
+    fill: string;
+    stroke: string;
+    dashed?: boolean;
+};
+/** Edge stroke color per semantic kind. */
+export declare function edgeStroke(kind: string | undefined, p: DiagramPalette): string;
+/** Helper: a color at a given opacity (accepts #hex and rgba() strings). */
+export declare function inkAt(color: string, opacity: number): string;

package/lib/types/client/blocks/forms.d.ts

@@ -0,0 +1,83 @@
+import type { AnswersState, GenuiBlockProps, QuestionMeta } from './state.ts';
+import type { GenuiInput, GenuiRadio, GenuiSelect, GenuiSlider, GenuiSubmit, GenuiSwitch, GenuiTextarea } from '../spec.ts';
+export declare function RadioNode({ node, onAction, answers }: {
+    node: GenuiRadio;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Resolve a question's correct label from its metadata. */
+export declare function correctLabelOf(m: QuestionMeta): string | undefined;
+/** Submit: the "交卷" control of a grouped-radio block. LOCAL-FIRST (v2.6):
+ * when at least one question carries `answer` data the click grades IN PLACE
+ * — score, per-question right/wrong, explanations — with zero model round
+ * trip, and locks the questions until 重新作答 resets them. Only when NO
+ * question has answers does it fall back to firing ONE action
+ * (`{type:'submit', answers, total, answered}`). Disabled until the
+ * selection criteria are met (all listed groups answered, or ≥1 answer
+ * without a group list); the hint shows the progress. */
+export declare function SubmitNode({ node, onAction, answers }: {
+    node: GenuiSubmit;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Switch: toggle with local state. */
+export declare function SwitchNode({ node, onAction }: {
+    node: GenuiSwitch;
+    onAction?: GenuiBlockProps['onAction'];
+}): import("react").JSX.Element;
+/** Slider: range input for numeric form values (v2.9). Field-aligned: with an
+ * `id` the value persists across refresh and joins the sibling submit's
+ * `fields` collection (stored as the numeric string); a model-provided
+ * default registers at mount; a restored durable value wins. Dragging fires
+ * the action (block-level debounce collapses the drag into one delivery). */
+export declare function SliderNode({ node, onAction, answers }: {
+    node: GenuiSlider;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Reuse the DSH main input's three-layer IME protection (verified in the
+ *  host InputBar): composition start arms a ref, composition end clears it
+ *  10ms later (Safari sends the closing keydown BEFORE compositionend), and
+ *  every submit keydown re-checks the ref, the native `isComposing` flag,
+ *  and `keyCode === 229`. A Chinese selection Enter must never submit. */
+export declare function useImeComposing(): {
+    isComposing: () => boolean;
+    onCompositionStart: () => void;
+    onCompositionEnd: () => void;
+};
+export declare function isImeSubmitKeydown(e: React.KeyboardEvent): boolean;
+/** Select: single choice from a dropdown, field-aligned (v2.8). With an `id`
+ * the chosen option persists across refresh and joins the sibling submit's
+ * `fields` collection; a model-provided `selected` default registers at
+ * mount; a restored durable value wins over both. Without any default a
+ * placeholder option shows — nothing is silently pre-registered (same
+ * philosophy as radio). */
+export declare function SelectNode({ node, onAction, answers }: {
+    node: GenuiSelect;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Input: single-line field. Controlled (value tracked for persistence and
+ *  submit collection when `id` is set). With `action`: Enter submits
+ *  immediately (`{type:'input', value, submit:true}`), blur sends too —
+ *  the user never has to click elsewhere for the value to reach the model.
+ *  Enter during IME composition never submits. `inputType: 'password'`
+ *  stays masked; its value is never persisted and never joins submit
+ *  collection (secrets stay out of localStorage), while its own `action`
+ *  still delivers on explicit user submit. */
+export declare function InputNode({ node, onAction, answers }: {
+    node: GenuiInput;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Textarea: multi-line input; with `action`, blurring sends the value and
+ *  Ctrl/Cmd+Enter submits immediately. Controlled when `id` is set (durable
+ *  value + submit collection). Ctrl/Cmd+Enter during IME composition never
+ *  submits. */
+export declare function TextareaNode({ node, onAction, answers }: {
+    node: GenuiTextarea;
+    onAction?: GenuiBlockProps['onAction'];
+    answers?: AnswersState | undefined;
+}): import("react").JSX.Element;
+/** Accordion: collapsible sections with local open state. Headings and
+ * bodies are wired via useId (`aria-controls`/`aria-labelledby`). */

package/lib/types/client/blocks/render-node.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The recursive render dispatcher: maps the white-listed GenuiNode union to
+ * concrete components. Leaf cases render inline; compound families live in
+ * the sibling block modules. Depth-guarded against pathological specs.
+ * @module @changfenhuang/dsh-genui/client/blocks/render-node
+ */
+import { type ReactNode } from 'react';
+import type { GenuiNode } from '../spec.ts';
+import type { AnswersState, GenuiBlockProps } from './state.ts';
+export declare function renderNode(node: GenuiNode, key: number, onAction: GenuiBlockProps['onAction'] | undefined, depth?: number, answers?: AnswersState): ReactNode;

package/lib/types/client/blocks/state.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared block-level state types: the block props contract and the answers
+ * registry (grouped radios → submit grading). Lives OUTSIDE GenuiBlock.tsx so
+ * the per-family block modules can import the types without a cycle back
+ * into the block shell.
+ * @module @changfenhuang/dsh-genui/client/blocks/state
+ */
+import type { GenuiSpec } from '../spec.ts';
+export interface GenuiBlockProps {
+    /** Parsed spec to render. */
+    spec: GenuiSpec;
+    /**
+     * v2: optional action callback. Interactive components carrying an
+     * `action` field fire it (button click, switch toggle, form submit);
+     * absent = components are display-only (v1 behavior).
+     */
+    onAction?: ((action: string, payload: Record<string, unknown>) => void) | undefined;
+    /**
+     * v2.7: durable-state key (session + slot + content fingerprint). When set,
+     * interaction state (radio answers, submit lock, field values) persists to
+     * localStorage and restores on refresh / re-render of the same content.
+     */
+    stateKey?: string | undefined;
+}
+/** Per-question metadata registered by grouped radios for local grading. */
+export interface QuestionMeta {
+    label: string;
+    options: string[];
+    /** Correct option: index (number) or label (string); absent = no local grading. */
+    answer?: number | string | undefined;
+    /** Shown after local grading. */
+    explanation?: string | undefined;
+}
+/** Block-wide answers registry (v2.5/v2.6): grouped radios record selections
+ * and register their question metadata here; a sibling `submit` node either
+ * grades IN PLACE (questions carry `answer` data) or collects everything
+ * into ONE action. Lives in GenuiBlock state so re-renders keep the
+ * selections, threaded down through the recursive render walk. Answers are
+ * plain group → chosen-option-label strings (the display label lives in
+ * QuestionMeta; localStorage stores the same string table — no migration). */
+export interface AnswersState {
+    answers: Record<string, string>;
+    /** Field values by id (input/textarea with an `id`), collected by submit. */
+    fields: Record<string, string>;
+    /** Field ids whose value must never be persisted or collected (secrets). */
+    secretFields: ReadonlySet<string>;
+    meta: Record<string, QuestionMeta>;
+    /** True after a local grading: questions are locked until 重新作答. */
+    locked: boolean;
+    /** Bumped by every reset; radios use it as their remount key. */
+    round: number;
+    setAnswer: (group: string, choice: string) => void;
+    setField: (id: string, value: string) => void;
+    registerSecretField: (id: string) => void;
+    registerMeta: (group: string, meta: QuestionMeta) => void;
+    clear: () => void;
+    setLocked: (locked: boolean) => void;
+}