@mohou/ui 1.0.20

package/lib/types/products/sortable-list.d.ts

@@ -0,0 +1,16 @@
+export type SortableItem = {
+    id: string;
+    label: string;
+};
+/**
+ * Drag-to-reorder list.
+ * @when Priority queues / column order. Read-only ordered events → `Timeline`.
+ * @example
+ * <SortableList items={items} onChange={(next) => set(next)} />
+ * @family Data & tables
+ */
+export declare function SortableList({ items, onChange, }: {
+    items: SortableItem[];
+    onChange?: (items: SortableItem[]) => void;
+}): import("react").JSX.Element;
+//# sourceMappingURL=sortable-list.d.ts.map

package/lib/types/products/sortable-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortable-list.d.ts","sourceRoot":"","sources":["../../../src/products/sortable-list.tsx"],"names":[],"mappings":"AAeA,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAmBxD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,IAAI,CAAA;CAC3C,+BAmBA"}

package/lib/types/products/stepper.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+export type StepStatus = 'default' | 'active' | 'completed';
+export interface StepperProps {
+    /** StepperItem elements. */
+    children: React.ReactNode;
+    /** Layout direction. Defaults to "vertical". */
+    orientation?: 'vertical' | 'horizontal' | undefined;
+    className?: string | undefined;
+}
+export interface StepperItemProps {
+    /** Step heading text. */
+    title: string;
+    /** Optional description below the title. */
+    description?: string | undefined;
+    /** Override the auto-incremented step number. */
+    step?: number | undefined;
+    /** Visual status of this step. Defaults to "default". */
+    status?: StepStatus | undefined;
+    /** Custom icon to replace the step number circle. */
+    icon?: React.ReactNode | undefined;
+    /** Content rendered below the step header (code blocks, text, etc.). */
+    children?: React.ReactNode | undefined;
+    className?: string | undefined;
+}
+/**
+ * One step inside `Stepper` (title, description, status).
+ * @family Feedback & status
+ * @when As a child of `Stepper` only — status is `default | active | completed` (lowercase).
+ */
+export declare function StepperItem({ title, description, step, status, icon, children, className, }: StepperItemProps): React.JSX.Element;
+/**
+ * Numbered steps with status; children are `StepperItem`.
+ * @family Feedback & status
+ * @when Wizard/progress of an ordered process. Time axis → `RunTimeline`.
+ * @example
+ * <Stepper><StepperItem title="上传" status="pass" /><StepperItem title="校验" status="running" /></Stepper>
+ */
+export declare function Stepper({ children, orientation, className, }: StepperProps): React.JSX.Element;
+//# sourceMappingURL=stepper.d.ts.map

package/lib/types/products/stepper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepper.d.ts","sourceRoot":"","sources":["../../../src/products/stepper.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,CAAA;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,yDAAyD;IACzD,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAA;IAC/B,qDAAqD;IACrD,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IAClC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,SAAS,CAAA;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,WAAW,EACX,IAAI,EACJ,MAAkB,EAClB,IAAI,EACJ,QAAQ,EACR,SAAS,GACV,EAAE,gBAAgB,qBAwDlB;AAqHD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,EACtB,QAAQ,EACR,WAAwB,EACxB,SAAS,GACV,EAAE,YAAY,qBAOd"}

package/lib/types/products/timeline.d.ts

@@ -0,0 +1,17 @@
+export type TimelineItem = {
+    id: string;
+    title: string;
+    description?: string;
+    time?: string;
+};
+/**
+ * Vertical ordered events.
+ * @when Statuses/history without durations. Durations → `RunTimeline`.
+ * @example
+ * <Timeline items={[{ id: "1", title: "已创建", time: "09:00" }]} />
+ * @family Realtime
+ */
+export declare function Timeline({ items }: {
+    items: TimelineItem[];
+}): import("react").JSX.Element;
+//# sourceMappingURL=timeline.d.ts.map

package/lib/types/products/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../../src/products/timeline.tsx"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,+BAsB5D"}

package/lib/types/products/tree-view.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+export type TreeNode = {
+    id: string;
+    label: string;
+    children?: TreeNode[];
+};
+/**
+ * Generic expandable node list.
+ * @when Any hierarchy without file semantics. Files → `FileTree`.
+ * @example
+ * <TreeView nodes={[{ id: "a", label: "华东" }]} />
+ * @family Data & tables
+ */
+export declare function TreeView({ nodes }: {
+    nodes: TreeNode[];
+}): React.JSX.Element;
+//# sourceMappingURL=tree-view.d.ts.map

package/lib/types/products/tree-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-view.d.ts","sourceRoot":"","sources":["../../../src/products/tree-view.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAA;CACtB,CAAA;AAoCD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,qBAQxD"}

package/lib/types/sdk/app-error-boundary.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+/** Where a captured failure came from — drives the hint the human sees. */
+export type AppErrorKind = 'render' | 'module' | 'uncaught' | 'async';
+export type ReportedAppError = {
+    kind: AppErrorKind;
+    message: string;
+    file?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    stack?: string | undefined;
+    componentStack?: string | undefined;
+};
+/**
+ * Hand an error to the host so `mini_app_errors` can see it.
+ *
+ * The app iframe is same-origin with the host, but the panel embedding it is not — so the
+ * only channel that works in both directions is the iframe POSTing to its own host. This
+ * is deliberately fire-and-forget: a diagnostic path must never be able to break the app
+ * that is reporting through it.
+ */
+export declare function reportAppError(appId: string, err: ReportedAppError): void;
+/**
+ * Runtime crash guard for a mini-app UI. The host injects this around the app entry when
+ * it compiles `ui.tsx`, so authors never have to add it — and an app that throws during
+ * render shows a real message instead of a blank iframe.
+ *
+ * @when Not used from mini-app code: it is already wrapped around your `ui.tsx` by the host.
+ * @family Feedback & status
+ */
+export declare function AppErrorBoundary(props: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+//# sourceMappingURL=app-error-boundary.d.ts.map

package/lib/types/sdk/app-error-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error-boundary.d.ts","sourceRoot":"","sources":["../../../src/sdk/app-error-boundary.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,2EAA2E;AAC3E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,YAAY,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAmBzE;AAuLD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;CAAE,qBAGpE"}

package/lib/types/sdk/app-id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * App id injected by `<AppRuntime>`. Its own module so the error boundary can read it
+ * without importing `use-app` (which would make the two mutually dependent).
+ */
+export declare const AppIdContext: import("react").Context<string>;
+//# sourceMappingURL=app-id.d.ts.map

package/lib/types/sdk/app-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-id.d.ts","sourceRoot":"","sources":["../../../src/sdk/app-id.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,eAAO,MAAM,YAAY,iCAAoB,CAAC"}

package/lib/types/sdk/use-app.d.ts

@@ -0,0 +1,32 @@
+import type { AppAgentEvent, AppLlmEvent } from '@mohou/contract';
+import { agentEventType, eventType, llmEventType } from '@mohou/contract/event-type';
+import { type ReactNode } from 'react';
+export type AppEvent = {
+    name: string;
+    data: unknown;
+};
+export { agentEventType, eventType, llmEventType };
+/** `ctx.llm` observation. Same union the host writes. */
+export type LlmEvent = AppLlmEvent;
+/** `ctx.agent` observation. Same union the host writes. */
+export type AgentEvent = AppAgentEvent;
+export interface AppHandle {
+    call: (method: string, args?: unknown) => Promise<unknown>;
+    /** Yields what the method yields. Awaiting the same object is the method return. */
+    streamCall: (method: string, args?: unknown) => AsyncIterable<unknown> & Promise<unknown>;
+    on: (name: string, cb: (data: unknown) => void) => () => void;
+    onAny: (cb: (event: AppEvent) => void) => () => void;
+    /** URL for a file under `assets/`. Throws `asset-invalid` when the path is not that tree. */
+    resolveAssetUrl: (path: string) => string;
+}
+/** Host runner still wraps the tree. Authors do not construct this. */
+export declare function AppRuntime(props: {
+    appId: string;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<string>>;
+/**
+ * App UI handle. `call` throws outside the host wrapper.
+ * The wrapper installs the live handle on `globalThis.miniAppHost`.
+ */
+export declare function useApp(): AppHandle;
+//# sourceMappingURL=use-app.d.ts.map

package/lib/types/sdk/use-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-app.d.ts","sourceRoot":"","sources":["../../../src/sdk/use-app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AACpF,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIrD,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAEtD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA;AAElD,yDAAyD;AACzD,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAA;AAElC,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,aAAa,CAAA;AAEtC,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,oFAAoF;IACpF,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzF,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAC7D,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IACpD,6FAA6F;IAC7F,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CAC1C;AAID,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE,mFAEvE;AAED;;;GAGG;AACH,wBAAgB,MAAM,IAAI,SAAS,CAKlC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@mohou/ui",
+  "version": "1.0.20",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "lib/types",
+    "README.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./src/index.ts",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@shadcn/react": "^0.3.1",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.12",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
+    "diff": "^9.0.0",
+    "lodash-es": "^4.18.1",
+    "lucide-react": "^0.544.0",
+    "motion": "^12.23.12",
+    "react": "^19.2.0",
+    "react-day-picker": "^10.0.1",
+    "react-dom": "^19.2.0",
+    "react-is": "^19.2.0",
+    "react-dropzone": "^20.1.1",
+    "react-markdown": "^10.1.0",
+    "react-resizable-panels": "^4.12.3",
+    "recharts": "^3.8.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.6.0",
+    "zod": "^4.4.3",
+    "@mohou/app-view": "^1.0.20",
+    "@mohou/contract": "^1.0.20"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.8.0",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/diff": "^8.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0"
+  }
+}

package/src/blocks/activity-feed.tsx

@@ -0,0 +1,16 @@
+import { Timeline, type TimelineItem } from '@mohou/ui/products/timeline'
+
+/**
+ * Chronological activity list (avatar + text + time).
+ * @when Read-only “who did what when” — commits, deploys, agent runs. For steps with status use `RunTimeline`.
+ * @example
+ * <ActivityFeed items={[{ id: "1", title: "部署完成", time: "10:24" }]} />
+ * @family Realtime
+ */
+export function ActivityFeed({ items }: { items: TimelineItem[] }) {
+  return (
+    <div data-testid="activity-feed">
+      <Timeline items={items} />
+    </div>
+  )
+}

package/src/blocks/app-shell.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+
+import { cn } from '@mohou/ui/lib/utils'
+
+/**
+ * App frame: optional sidebar + header + main.
+ * @when Root layout for a mini-app page
+ * @example
+ * <AppShell sidebar={<nav />} header={<PageHeader title="Home" />}>
+ *   {children}
+ * </AppShell>
+ * @family Layout & structure
+ */
+export function AppShell({
+  sidebar,
+  header,
+  children,
+  className,
+}: {
+  sidebar?: ReactNode
+  header?: ReactNode
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <div className={cn('flex min-h-svh w-full', className)} data-testid="app-shell">
+      {sidebar ? (
+        <aside className="w-56 shrink-0 border-r bg-background p-3">{sidebar}</aside>
+      ) : null}
+      <div className="flex min-w-0 flex-1 flex-col">
+        {header ? (
+          <header className="border-b px-4 py-3">{header}</header>
+        ) : null}
+        <main className="flex-1 p-4">{children}</main>
+      </div>
+    </div>
+  )
+}

package/src/blocks/attachment-gallery.tsx

@@ -0,0 +1,36 @@
+
+import {
+  Attachment,
+  AttachmentContent,
+  AttachmentGroup,
+  AttachmentMedia,
+  AttachmentTitle,
+} from '@mohou/ui/components/attachment'
+
+export type GalleryFile = { name: string; url?: string }
+
+/**
+ * Thumbnail grid of files with open/copy.
+ * @when A record has N files/images and you show them as tiles, not a table.
+ * @example
+ * <AttachmentGallery files={[{ name: "log.txt", url: "https://…" }]} />
+ * @family Discovery & inspect
+ */
+export function AttachmentGallery({ files }: { files: GalleryFile[] }) {
+  return (
+    <AttachmentGroup data-testid="attachment-gallery">
+      {files.map(file => (
+        <Attachment key={file.name}>
+          {file.url ? (
+            <AttachmentMedia>
+              <img src={file.url} alt={file.name} className="size-10 object-cover" />
+            </AttachmentMedia>
+          ) : null}
+          <AttachmentContent>
+            <AttachmentTitle>{file.name}</AttachmentTitle>
+          </AttachmentContent>
+        </Attachment>
+      ))}
+    </AttachmentGroup>
+  )
+}

package/src/blocks/bar-chart.tsx

@@ -0,0 +1,46 @@
+
+import { Bar, BarChart as ReBar, CartesianGrid, XAxis } from 'recharts'
+
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from '@mohou/ui/components/chart'
+import { cn } from '@mohou/ui/lib/utils'
+
+/**
+ * Stacked bar chart over flat rows.
+ * @family Chart & data
+ * @when Comparing several series across categories (pass/fail per day). Single ratio → `DonutChart`; trend → `Sparkline`.
+ * @example
+ * <StackedBarChart
+ *   data={[{ label: "09-01", ok: 12, fail: 2 }]}
+ *   keys={["ok", "fail"]}
+ *   config={{ ok: { label: "通过", color: "var(--primary)" }, fail: { label: "失败", color: "var(--destructive)" } }}
+ * />
+ */
+export function StackedBarChart({
+  data,
+  config,
+  keys,
+  className,
+}: {
+  data: Record<string, string | number>[]
+  config: ChartConfig
+  keys: string[]
+  className?: string
+}) {
+  return (
+    <ChartContainer config={config} className={cn('aspect-video w-full', className)} data-testid="bar-chart">
+      <ReBar accessibilityLayer data={data}>
+        <CartesianGrid vertical={false} />
+        <XAxis dataKey="label" tickLine={false} axisLine={false} />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        {keys.map(key => (
+          <Bar key={key} dataKey={key} stackId="a" fill={`var(--color-${key})`} />
+        ))}
+      </ReBar>
+    </ChartContainer>
+  )
+}

package/src/blocks/comment-thread.tsx

@@ -0,0 +1,37 @@
+import { Avatar, AvatarFallback } from '@mohou/ui/components/avatar'
+
+export type Comment = { id: string; author: string; body: string; time?: string | undefined }
+
+/**
+ * Nested comments with author + time.
+ * @when Issue/ticket discussion, review comments. Editing a comment is your job, not the component's.
+ * @example
+ * <CommentThread comments={[{ id: "c1", author: "P.Wang", text: "这里再确认下" }]} />
+ * @family Realtime
+ */
+export function CommentThread({ comments }: { comments: Comment[] }) {
+  return (
+    <div className="flex flex-col gap-3" data-testid="comment-thread">
+      {comments.map(comment => (
+        <div key={comment.id} className="flex gap-2">
+          <Avatar className="size-7">
+            <AvatarFallback className="text-[10px]">
+              {comment.author.slice(0, 2).toUpperCase()}
+            </AvatarFallback>
+          </Avatar>
+          <div>
+            <div className="text-sm font-medium">
+              {comment.author}
+              {comment.time ? (
+                <span className="text-muted-foreground ml-2 text-xs font-normal">
+                  {comment.time}
+                </span>
+              ) : null}
+            </div>
+            <p className="text-sm">{comment.body}</p>
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/blocks/dashboard-shell.tsx

@@ -0,0 +1,108 @@
+
+import type { ReactNode } from 'react';
+
+import { useIsMobile } from '@mohou/ui/hooks/use-mobile';
+import { cn } from '@mohou/ui/lib/utils';
+
+export type DashboardShellProps = {
+  /** Title row / `PageHeader`. Pinned: it stays while the content scrolls under it. */
+  header?: ReactNode
+  /** KPI strip. Pinned with the header — the point of a dashboard is that the numbers hold. */
+  kpis?: ReactNode
+  /** Charts and tables. The scrolling body. */
+  main: ReactNode
+  /** Activity feed / top offenders. Sits beside `main` on wide screens, stacks under it when narrow. */
+  aside?: ReactNode
+  /** Aside width in px on wide screens. Default 320. */
+  asideWidth?: number
+  className?: string
+}
+
+/**
+ * Overview page with a pinned header + KPI strip and exactly one scrolling body.
+ *
+ * The failure this exists for: the page is a plain column, `overflow-auto` ends up on the
+ * outermost div, and the first chart the user scrolls past takes the header and the KPI row
+ * with it — a dashboard whose numbers scroll away is not a dashboard. The aside gets its own
+ * scroller when there is room for two, and folds under `main` into the single body scroller
+ * when there is not, rather than becoming a third half-height pane.
+ *
+ * @when Page shape: metrics up top, charts below, optional activity rail — ops overviews, monitor walls
+ * @example
+ * <DashboardShell
+ *   header={<PageHeader title="值班" description="每 5 秒" />}
+ *   kpis={<div className="grid grid-cols-4 gap-3">{cards}</div>}
+ *   main={<Charts />}
+ *   aside={<ActivityFeed items={items} />}
+ * />
+ * @family Layout & structure
+ */
+export function DashboardShell({
+  header,
+  kpis,
+  main,
+  aside,
+  asideWidth = 320,
+  className,
+}: DashboardShellProps) {
+  const isNarrow = useIsMobile()
+
+  const pinned = (
+    <>
+      {header ? (
+        <div className="shrink-0" data-testid="dashboard-header">
+          {header}
+        </div>
+      ) : null}
+      {kpis ? (
+        <div className="shrink-0" data-testid="dashboard-kpis">
+          {kpis}
+        </div>
+      ) : null}
+    </>
+  )
+
+  return (
+    <div
+      className={cn('flex h-full min-h-0 w-full flex-col', className)}
+      data-testid="dashboard-shell"
+    >
+      {pinned}
+
+      {aside && !isNarrow ? (
+        // Room for two panes: each scrolls on its own, neither can push the other.
+        <div className="flex min-h-0 flex-1" data-testid="dashboard-body">
+          <div
+            className="min-h-0 flex-1 overflow-y-auto"
+            data-testid="dashboard-main"
+          >
+            {main}
+          </div>
+          <div
+            className="border-border bg-muted/30 min-h-0 shrink-0 overflow-y-auto border-l"
+            data-testid="dashboard-aside"
+            style={{ width: asideWidth }}
+          >
+            {aside}
+          </div>
+        </div>
+      ) : (
+        // One body scroller; the aside folds to the bottom of it instead of a squeezed pane.
+        <div
+          className="min-h-0 flex-1 overflow-y-auto"
+          data-testid="dashboard-body"
+        >
+          <div data-testid="dashboard-main">{main}</div>
+          {aside ? (
+            <div
+              className="border-border border-t px-4 py-4"
+              data-testid="dashboard-aside"
+            >
+              {aside}
+            </div>
+          ) : null}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/blocks/description-list.tsx

@@ -0,0 +1,23 @@
+/**
+ * Label/value pairs, two columns.
+ * @when Detail/inspector panel of a selected row — the default “show one record” view.
+ * @example
+ * <DescriptionList items={[{ label: "状态", value: "运行中" }]} />
+ * @family Layout & structure
+ */
+export function DescriptionList({
+  items,
+}: {
+  items: { label: string; value: string }[]
+}) {
+  return (
+    <dl className="grid grid-cols-[8rem_1fr] gap-x-3 gap-y-2 text-sm" data-testid="description-list">
+      {items.map(item => (
+        <div key={item.label} className="contents">
+          <dt className="text-muted-foreground">{item.label}</dt>
+          <dd>{item.value}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}

package/src/blocks/detail-panel.tsx

@@ -0,0 +1,43 @@
+
+import type { ReactNode } from 'react'
+
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from '@mohou/ui/components/sheet'
+
+/**
+ * Right-side inspector Sheet for a selected row/entity.
+ * @when Master-detail after row/card click
+ * @example
+ * <DetailPanel open={!!id} onOpenChange={() => setId(null)} title="Run #12">{body}</DetailPanel>
+ * @family Surface
+ */
+export function DetailPanel({
+  open,
+  onOpenChange,
+  title,
+  description,
+  children,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  title: string
+  description?: string
+  children?: ReactNode
+}) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent data-testid="detail-panel">
+        <SheetHeader>
+          <SheetTitle>{title}</SheetTitle>
+          {description ? <SheetDescription>{description}</SheetDescription> : null}
+        </SheetHeader>
+        <div className="px-4 pb-4">{children}</div>
+      </SheetContent>
+    </Sheet>
+  )
+}