@orbit-work/ui 0.1.0

package/src/components/domain/files/FileTree/index.tsx

@@ -0,0 +1,106 @@
+"use client"
+
+import RcTree from "rc-tree"
+import { useMemo } from "react"
+import { cn } from "../../../../lib/utils"
+import type { FileTreeNode, FileTreeProps } from "../../../../types/file-tree"
+import { ChevRight, Folder } from "../../../composite/Icons"
+import { EmptyState } from "../../../primitives"
+import { FileIcon } from "../FileIcon"
+
+/**
+ * FileTree — directory tree for file browsing, built on rc-tree.
+ *
+ * The component is fully controlled and app-agnostic: the consumer owns the
+ * data (lazy loading, caching, filtering) and passes a nested `treeData`;
+ * FileTree only renders it with Orbitwork styling — chevron toggle, folder/doc
+ * icons, selection highlight, and an empty placeholder.
+ *
+ * Lazy loading contract: when `loadData` is provided, expanding a node with
+ * `isLeaf: false` and no loaded `children` calls `loadData(node)`; the
+ * consumer merges the result into its own state and passes updated treeData
+ * back down.
+ */
+export function FileTree({
+  treeData,
+  expandedKeys,
+  onExpand,
+  selectedKey,
+  onSelect,
+  loadData,
+  emptyText = "空目录",
+  className = "",
+}: FileTreeProps) {
+  const rcTreeData = useMemo(() => treeData, [treeData])
+
+  if (treeData.length === 0) {
+    return (
+      <div
+        data-slot="file-tree"
+        data-ow-part="empty"
+        className={cn(
+          "flex flex-col flex-1 min-h-0 overflow-y-auto items-center justify-center font-normal text-ow-fs-caption leading-[1.6] text-ow-text",
+          className,
+        )}
+      >
+        {/* G5 空态：信标母题 ＋ 一句 text-2（EmptyState 原语）。原来是 text-3 灰字居中，
+            判断表「空态：灰字居中 → G5」。目录树坐在 240 侧栏里，母题收到 32、内距收紧。 */}
+        <EmptyState message={emptyText} markSize={32} className="px-3 py-6" />
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-slot="file-tree"
+      className={cn(
+        // 原型 2320：树行走 --ow-fs-caption（12），比 UI 密度档再小一级 —— 树是导航不是正文，
+        // 44% 的窄列里 13px 会把长文件名逼到省略号。字体随壳继承 sans（原来行内写死 mono，
+        // 与原型的 font-family:inherit 不符，也让中文目录名掉进等宽回退字形）。
+        "flex flex-col flex-1 min-h-0 overflow-y-auto font-normal text-ow-fs-caption leading-[1.6] text-ow-text",
+        className,
+      )}
+    >
+      <RcTree
+        prefixCls="ow-file-tree"
+        treeData={rcTreeData}
+        fieldNames={{ key: "key", title: "title", children: "children" }}
+        expandedKeys={expandedKeys}
+        onExpand={(keys) => onExpand?.(keys as string[])}
+        selectedKeys={selectedKey ? [selectedKey] : []}
+        onSelect={(keys, info) => {
+          if (keys.length > 0) onSelect?.(info.node as unknown as FileTreeNode)
+        }}
+        loadData={
+          loadData
+            ? async (node) => {
+                await loadData(node as unknown as FileTreeNode)
+              }
+            : undefined
+        }
+        switcherIcon={(props) => (
+          <ChevRight
+            className={cn(
+              "w-3.5 h-3.5 transition-transform duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+              props.expanded && "rotate-90",
+            )}
+          />
+        )}
+        titleRender={(node) => {
+          const item = node as unknown as FileTreeNode
+          return (
+            <span className="inline-flex items-center gap-1.5 min-w-0">
+              {item.isLeaf ? (
+                <FileIcon name={item.title} kind={item.kind} className="w-4 h-4 shrink-0 text-ow-text-3" />
+              ) : (
+                <Folder className="w-4 h-4 shrink-0 text-ow-text-3" />
+              )}
+              <span className="overflow-hidden text-ellipsis whitespace-nowrap">{item.title}</span>
+            </span>
+          )
+        }}
+        showIcon={false}
+      />
+    </div>
+  )
+}

package/src/components/domain/files/PreviewDialog/PreviewDialog.stories.tsx

@@ -0,0 +1,178 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { CodePreview } from "../../../composite/CodePreview"
+import type { FileReferenceMenuOption } from "../../../composite/FileReferenceCard"
+import { MarkdownPreview } from "../../../composite/MarkdownPreview"
+import { CsvPreview } from "../../office/CsvPreview"
+import { FilePreviewDialog } from "./index"
+
+const meta = {
+  title: "Domain/Files/PreviewDialog",
+  component: FilePreviewDialog,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof FilePreviewDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const openWith: FileReferenceMenuOption[] = [
+  { id: "hdr", kind: "header", name: "本机应用" },
+  { id: "vscode", name: "Visual Studio Code", isDefault: true },
+  { id: "typora", name: "Typora" },
+  { id: "div", kind: "divider" },
+  { id: "reveal", name: "在访达中显示", kind: "action" },
+]
+
+const shared = {
+  open: true,
+  onClose: () => {},
+  onDownload: () => {},
+  openWithOptions: openWith,
+  onOpenWith: () => {},
+}
+
+const code = `export function totalCost(runs: Run[]) {
+  return runs.reduce((sum, run) => sum + run.cost, 0)
+}
+
+// 结算口径：失败的运行不计费。
+export function billable(runs: Run[]) {
+  return runs.filter((run) => run.state !== "失败")
+}`
+
+const csv = `订单号,客户,金额,状态
+2026-0417,林筱,12480,已结清
+2026-0418,赵珩,3120,待付款
+2026-0419,陈屿,26900,已结清
+2026-0420,沈砚,890,已退款`
+
+const markdown = `# 季度销售复盘
+
+第三季度整体成交额比上季度高 18%，主要来自华东区的两个大单。
+
+## 待办
+
+- 把渠道口径统一到新的分区表
+- 复核 4 月的退款单据
+`
+
+const markdownHtml = `<h1>季度销售复盘</h1>
+<p>第三季度整体成交额比上季度高 18%，主要来自华东区的两个大单。</p>
+<h2>待办</h2>
+<ul><li>把渠道口径统一到新的分区表</li><li>复核 4 月的退款单据</li></ul>`
+
+/** 代码适配器：plain 衬底 —— CodeBlock 自带终端 chrome，壳不再叠一层底。 */
+export const Code: Story = {
+  name: "代码适配器（plain 衬底）",
+  args: {
+    ...shared,
+    fileName: "billing.ts",
+    meta: "132 行",
+    surface: "plain",
+    children: <CodePreview language="typescript" code={code} />,
+  },
+}
+
+/** 表格适配器：CsvPreview 走 DataTable 语法（表头 surface-2、密档行高 32、mono 单元格）。 */
+export const Csv: Story = {
+  name: "表格适配器（DataTable 语法）",
+  args: {
+    ...shared,
+    fileName: "orders-2026Q3.csv",
+    meta: "4 行 × 4 列",
+    surface: "plain",
+    children: <CsvPreview content={csv} fileName="orders-2026Q3.csv" />,
+  },
+}
+
+/** 文档适配器：paper 纸面 —— 恒白纸页 ＋ 局部浅档主题，暗主题下切过去纸仍是纸。 */
+export const Markdown: Story = {
+  name: "文档适配器（paper 纸面）",
+  args: {
+    ...shared,
+    fileName: "Q3-复盘.md",
+    meta: "2.1 KB",
+    surface: "paper",
+    children: <MarkdownPreview bare content={markdown} html={markdownHtml} />,
+  },
+}
+
+/** 媒体适配器：mat 深衬 —— 局部暗档 ＋ --ow-surface-2，图片居中不加纸。 */
+export const Image: Story = {
+  name: "媒体适配器（mat 深衬）",
+  args: {
+    ...shared,
+    fileName: "beacon-poster@2x.png",
+    meta: "1440 × 900",
+    surface: "mat",
+    children: (
+      <svg width="420" height="264" viewBox="0 0 420 264" role="img" aria-label="示意图占位">
+        <desc>媒体衬底演示用的占位图形，非真实资产。</desc>
+        <rect width="420" height="264" fill="var(--ow-surface)" />
+        <circle cx="210" cy="132" r="46" fill="var(--ow-text-3)" />
+        <rect x="96" y="206" width="228" height="10" rx="5" fill="var(--ow-border-strong)" />
+      </svg>
+    ),
+  },
+}
+
+export const Loading: Story = {
+  name: "加载态（Skeleton 呼吸）",
+  args: { ...shared, fileName: "Q3-复盘.md", surface: "paper", loading: true },
+}
+
+export const Failed: Story = {
+  name: "错误态（一句人话 ＋ mono 详情）",
+  args: {
+    ...shared,
+    fileName: "orders-2026Q3.csv",
+    surface: "plain",
+    error: "这个文件读不出来，可能已经被移动或删除了。",
+    errorDetail: "ENOENT: no such file or directory, open '/workspace/orders-2026Q3.csv'",
+  },
+}
+
+export const Empty: Story = {
+  name: "空态（信标母题）",
+  args: { ...shared, fileName: "notes.md", surface: "paper", children: undefined },
+}
+
+export const SurfaceComparison: Story = {
+  name: "三制式对照：paper / mat / plain",
+  args: { ...shared, fileName: "sample.md" },
+  render: (args) => {
+    const [surface, setSurface] = useState<"paper" | "mat" | "plain">("paper")
+    const body =
+      surface === "plain" ? (
+        <CodePreview language="typescript" code={code} />
+      ) : surface === "mat" ? (
+        <svg width="360" height="220" viewBox="0 0 360 220" role="img" aria-label="示意图占位">
+          <desc>媒体衬底演示用的占位图形，非真实资产。</desc>
+          <rect width="360" height="220" fill="var(--ow-surface)" />
+          <circle cx="180" cy="110" r="40" fill="var(--ow-text-3)" />
+        </svg>
+      ) : (
+        <MarkdownPreview bare content={markdown} html={markdownHtml} />
+      )
+    return (
+      <div className="p-6">
+        <div className="mb-4 flex gap-2">
+          {(["paper", "mat", "plain"] as const).map((key) => (
+            <button
+              key={key}
+              type="button"
+              className="h-8 [border-radius:var(--ow-radius-lg)] border border-[color:var(--ow-border)] px-4 text-ow-fs-ui text-[color:var(--ow-text)]"
+              onClick={() => setSurface(key)}
+            >
+              {key}
+            </button>
+          ))}
+        </div>
+        <FilePreviewDialog {...args} surface={surface} fileName={`sample.${surface}`}>
+          {body}
+        </FilePreviewDialog>
+      </div>
+    )
+  },
+}

package/src/components/domain/files/PreviewDialog/PreviewDialogSource.test.mjs

@@ -0,0 +1,92 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+const stories = await readFile(new URL("./PreviewDialog.stories.tsx", import.meta.url), "utf8")
+const allowlist = JSON.parse(
+  await readFile(new URL("../../../../../scripts/ds2-allowlist.json", import.meta.url), "utf8"),
+)
+
+test("预览壳坐 Dialog 裸壳档，不自造模态立面", () => {
+  assert.match(source, /import \{ Dialog \} from "\.\.\/\.\.\/\.\.\/composite\/Dialog"/)
+  assert.match(source, /<Dialog[\s\S]*?\bbare\b/)
+  // 遮罩/阴影/z 由 Dialog 单点承担，壳内不得再写一份（正文引用；文档注释里提到不算）
+  assert.doesNotMatch(source, /bg-\[var\(--ow-scrim\)\]|shadow-\[var\(--ow-shadow-modal\)\]|var\(--ow-z-modal\)/)
+})
+
+test("标题栏 48（--ow-titlebar-h），文件名 mono + tabular-nums（§7 读数）", () => {
+  assert.match(source, /height: "var\(--ow-titlebar-h\)"/)
+  assert.match(source, /data-ow-part="filename"/)
+  assert.match(source, /font-\[family-name:var\(--ow-font-mono\)\] \[font-variant-numeric:tabular-nums\]/)
+})
+
+test("动作组＝下载 / 打开方式（Menu 配方）/ 关闭", () => {
+  assert.match(source, /aria-label="下载"/)
+  assert.match(source, /aria-label="关闭预览"/)
+  assert.match(source, /<Menu[\s\S]*items=\{menuEntries\}/)
+  assert.match(source, /MENU_SEPARATOR/)
+})
+
+test('纸面 paper：恒白 --ow-paper ＋ 局部 data-theme="light"（禁白底浅字）＋ 页边距 ＋ §5 贴地零影', () => {
+  const paper = source.match(/if \(surface === "paper"\)[\s\S]*?\n {2}\}/)?.[0] ?? ""
+  assert.match(paper, /data-theme="light"/)
+  assert.match(paper, /bg-\[var\(--ow-paper\)\]/)
+  assert.match(paper, /text-\[color:var\(--ow-text\)\]/)
+  assert.match(paper, /padding: "var\(--ow-space-8\)"/)
+  // §5 贴地零影：纸页坐在滚动区里是贴地表面，不是弹层——层次靠 1px --ow-border 立边。
+  assert.doesNotMatch(paper, /shadow-\[var\(--ow-shadow-/)
+  assert.match(paper, /border border-\[color:var\(--ow-border\)\]/)
+})
+
+test('媒体 mat：局部 data-theme="dark"（§3 常暗域白名单）＋ 中性深衬 --ow-surface-2，不用纸', () => {
+  const mat = source.match(/if \(surface === "mat"\)[\s\S]*?\n {2}\}/)?.[0] ?? ""
+  assert.match(mat, /data-theme="dark"/)
+  assert.match(mat, /bg-\[var\(--ow-surface-2\)\]/)
+  assert.doesNotMatch(mat, /--ow-paper/)
+})
+
+test("plain 制式不叠衬底，只铺 --ow-bg", () => {
+  assert.match(source, /data-ow-surface="plain"[\s\S]*?bg-\[var\(--ow-bg\)\]/)
+})
+
+test("载/错/空三态落中性衬垫，纸面/媒体只服务真实内容", () => {
+  assert.match(
+    source,
+    /const effectiveSurface: PreviewSurface = loading \|\| error \|\| !hasContent \? "plain" : surface/,
+  )
+})
+
+test("容器三态齐（§6）：EmptyState 空 / Skeleton 呼吸载 / InlineMessage 一句人话＋mono 详情", () => {
+  assert.match(source, /<EmptyState message=\{emptyMessage\}/)
+  assert.match(source, /<Skeleton variant="line"/)
+  assert.match(source, /<InlineMessage variant="error" detail=\{errorDetail\}/)
+  assert.match(source, /role="status" aria-live="polite"/)
+})
+
+test("Tailwind 任意值 var() 全带类型标注（check-ds2 拦截口径）", () => {
+  const bare = source.match(/(?:text|border)-\[(?!color:)var\(/g)
+  assert.equal(bare, null)
+  const font = source.match(/font-\[(?!family-name:)var\(/g)
+  assert.equal(font, null)
+})
+
+test("R3 中性件：壳内无信标/荧黄任何形态", () => {
+  assert.doesNotMatch(source, /--ow-beacon|--ow-accent-dot|--ow-yellow|--ow-data-today/)
+})
+
+test("paper 豁免已登记 allowlist 并附旁注", () => {
+  const path = "src/components/domain/files/PreviewDialog/**"
+  assert.ok(allowlist.paper.includes(path))
+  assert.match(allowlist.$reasons[path], /^paper：/)
+})
+
+test("stories 覆盖壳＋四适配器＋加载/错误/空", () => {
+  assert.match(stories, /<CodePreview/)
+  assert.match(stories, /<CsvPreview/)
+  assert.match(stories, /<MarkdownPreview bare/)
+  assert.match(stories, /surface: "mat"/)
+  assert.match(stories, /loading: true/)
+  assert.match(stories, /errorDetail:/)
+  assert.match(stories, /children: undefined/)
+})

package/src/components/domain/files/PreviewDialog/index.tsx

@@ -0,0 +1,294 @@
+"use client"
+
+import { type ReactNode, useId } from "react"
+import { Dialog } from "../../../composite/Dialog"
+import type { FileReferenceMenuOption } from "../../../composite/FileReferenceCard"
+import { Close, Download } from "../../../composite/Icons"
+import { Skeleton } from "../../../composite/Skeleton"
+import { Button } from "../../../primitives"
+import { EmptyState } from "../../../primitives/EmptyState"
+import { InlineMessage } from "../../../primitives/InlineMessage"
+import { MENU_SEPARATOR, Menu, type MenuEntry } from "../../../primitives/Menu"
+
+/**
+ * FilePreviewDialog —— DS 2.0 预览壳（蓝图批次④ · preview 域）。
+ *
+ * 结构：Dialog `bare` 立面（§5 模态＝`--ow-scrim` ＋ `--ow-shadow-modal` ＋ 1px 边，
+ * 圆角 `--ow-radius-modal`）之上加一条 48（`--ow-titlebar-h`）标题栏：
+ * 左＝文件名 mono＋tabular-nums（§7 读数口径，文件名算读数），
+ * 右＝动作组「下载 / 打开方式（Menu 配方）/ 关闭」。标题带与地同色、无分隔线
+ * （口径与 ArtifactPreviewSidebarView 一致：横线只由页签行承担，壳不再叠边）；
+ * 图标钮一律走 Button 的 `icon` 槽（icon-only ＝ §7 28×28 方，图形由原语补 16 尺寸），
+ * 不把图标当 children 传（children 落 label 槽拿不到尺寸，会渲成 0×0）。
+ *
+ * 内容区两制式衬底（本组件唯一的品牌判断点）：
+ *  - **纸面 paper**（文档类：Markdown / PDF / Office）：页面本体恒白 `--ow-paper`，
+ *    局部 `data-theme="light"` 使纸上文字走浅档语义色（暗主题下纸页不会白底浅字，§14 已知坑），
+ *    页边距 `--ow-space-8`；纸页是贴地表面（§5 贴地零影），与衬垫的层次靠 1px `--ow-border` 立边，衬垫取 `--ow-bg`。
+ *  - **媒体 mat**（图片 / 视频）：中性深衬，局部 `data-theme="dark"`（§3 常暗域白名单含媒体查看器），
+ *    底取 `--ow-surface-2`，内容居中不加纸。
+ *  - **plain**：自带 chrome 的内容（CodeBlock/终端）直接铺满，壳不再叠衬底。
+ *
+ * 状态（§6 容器件三态）：空＝`EmptyState` 信标母题；载＝`Skeleton` 呼吸（禁 shimmer）；
+ * 错＝`InlineMessage` 一句人话 ＋ mono 详情。
+ * R3 中性件：壳与四个适配器都不带信标/荧黄元素。
+ */
+
+/** 内容区衬底制式：纸面（文档）· 媒体深衬 · 无衬（内容自带 chrome）。 */
+export type PreviewSurface = "paper" | "mat" | "plain"
+
+export interface FilePreviewDialogProps {
+  open: boolean
+  /** 文件名，标题栏 mono＋tabular-nums 显示 */
+  fileName: string
+  /** 文件名右侧的次要读数（大小/行数/页码等），mono */
+  meta?: ReactNode
+  /** 标题是否按读数走 mono（默认 true）；纯中文标题（非文件名）传 false 走正文字体 */
+  monoTitle?: boolean
+  /** 内容区衬底制式，默认 plain */
+  surface?: PreviewSurface
+  /** 预览内容 */
+  children?: ReactNode
+  /** 加载中：内容区换 Skeleton 呼吸 */
+  loading?: boolean
+  /** 错误一句人话；非空时替代内容 */
+  error?: string
+  /** 错误技术详情，mono ≤2 行 */
+  errorDetail?: string
+  /** 空内容一句话；children 为空且非载/错时显示 */
+  emptyMessage?: ReactNode
+  /** 下载动作；不传则不出下载钮 */
+  onDownload?: () => void
+  /** 「打开方式」菜单项；空数组/不传则不出该菜单 */
+  openWithOptions?: FileReferenceMenuOption[]
+  onOpenWith?: (option: FileReferenceMenuOption) => void
+  /** 打开方式按钮文案 */
+  openWithLabel?: string
+  /** 标题栏动作组里追加的自定义动作（排在下载之前） */
+  actions?: ReactNode
+  onClose: () => void
+  /** 壳宽，默认 min(920px, 90vw) */
+  width?: number | string
+  /** 内容区高度，默认 min(640px, 70vh) */
+  contentHeight?: number | string
+  className?: string
+}
+
+const ICON_BTN = "shrink-0"
+
+export function FilePreviewDialog({
+  open,
+  fileName,
+  meta,
+  monoTitle = true,
+  surface = "plain",
+  children,
+  loading = false,
+  error,
+  errorDetail,
+  emptyMessage = "这个文件没有可预览的内容。",
+  onDownload,
+  openWithOptions,
+  onOpenWith,
+  openWithLabel = "打开方式",
+  actions,
+  onClose,
+  width,
+  contentHeight,
+  className = "",
+}: FilePreviewDialogProps) {
+  const titleId = useId()
+  const hasOpenWith = !!openWithOptions?.length
+  // 「打开方式」按 Menu 配方摊平：divider→分隔项、header→分组标题、其余→可选行。
+  const menuEntries: MenuEntry[] = (openWithOptions ?? []).map((option) => {
+    if (option.kind === "divider") return { ...MENU_SEPARATOR, key: option.id }
+    if (option.kind === "header") return { type: "group", key: option.id, label: option.name }
+    return {
+      key: option.id,
+      label: option.name,
+      hint: option.isDefault ? "默认" : undefined,
+      disabled: option.disabled,
+    }
+  })
+
+  const hasContent = children !== undefined && children !== null && children !== false
+  let body: ReactNode
+  if (loading) {
+    body = (
+      <div data-ow-part="loading" role="status" aria-live="polite" className="flex flex-col gap-3 p-6">
+        <Skeleton variant="line" height={20} width="42%" />
+        <Skeleton variant="line" height={14} />
+        <Skeleton variant="line" height={14} />
+        <Skeleton variant="line" height={14} width="76%" />
+        <Skeleton variant="block" height={180} />
+      </div>
+    )
+  } else if (error) {
+    body = (
+      <div data-ow-part="error" className="p-6">
+        <InlineMessage variant="error" detail={errorDetail}>
+          {error}
+        </InlineMessage>
+      </div>
+    )
+  } else if (!hasContent) {
+    body = (
+      <div data-ow-part="empty" className="flex h-full items-center justify-center p-6">
+        <EmptyState message={emptyMessage} />
+      </div>
+    )
+  } else {
+    body = children
+  }
+
+  // 载/错/空三态一律落在中性衬垫上——纸面/媒体制式只服务真实内容。
+  const effectiveSurface: PreviewSurface = loading || error || !hasContent ? "plain" : surface
+
+  return (
+    <Dialog
+      open={open}
+      bare
+      onClose={onClose}
+      ariaLabel={fileName}
+      width={width ?? "min(920px, 90vw)"}
+      className={`flex flex-col overflow-hidden ${className}`}
+    >
+      <header
+        data-ow-part="titlebar"
+        className="flex shrink-0 items-center gap-3 px-4"
+        style={{ height: "var(--ow-titlebar-h)" }}
+      >
+        <span
+          id={titleId}
+          data-ow-part="filename"
+          title={fileName}
+          className={`min-w-0 flex-1 truncate text-ow-fs-ui font-medium text-[color:var(--ow-text)] ${
+            monoTitle ? "font-[family-name:var(--ow-font-mono)] [font-variant-numeric:tabular-nums]" : ""
+          }`}
+        >
+          {fileName}
+        </span>
+        {meta && (
+          <span
+            data-ow-part="meta"
+            className="shrink-0 font-[family-name:var(--ow-font-mono)] text-ow-fs-eyebrow [font-variant-numeric:tabular-nums] text-[color:var(--ow-text-3)]"
+          >
+            {meta}
+          </span>
+        )}
+        <div data-ow-part="actions" className="flex shrink-0 items-center gap-1">
+          {actions}
+          {onDownload && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className={ICON_BTN}
+              icon={<Download aria-hidden="true" />}
+              aria-label="下载"
+              title="下载"
+              onClick={onDownload}
+            />
+          )}
+          {hasOpenWith && (
+            <Menu
+              items={menuEntries}
+              width={220}
+              ariaLabel={openWithLabel}
+              onSelect={(key) => {
+                const option = openWithOptions?.find((o) => o.id === key)
+                if (option) onOpenWith?.(option)
+              }}
+              trigger={
+                <Button type="button" variant="ghost" size="sm" className={ICON_BTN}>
+                  {openWithLabel}
+                </Button>
+              }
+            />
+          )}
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className={ICON_BTN}
+            icon={<Close aria-hidden="true" />}
+            aria-label="关闭预览"
+            title="关闭预览"
+            onClick={onClose}
+          />
+        </div>
+      </header>
+
+      <PreviewSurfaceArea surface={effectiveSurface} height={contentHeight}>
+        {body}
+      </PreviewSurfaceArea>
+    </Dialog>
+  )
+}
+
+/**
+ * 衬底规范件：paper / mat / plain 三制式的唯一实现处。
+ * 单独导出，供不走模态的场景（侧栏预览、内联预览）复用同一套衬底口径。
+ */
+export function PreviewSurfaceArea({
+  surface = "plain",
+  height,
+  children,
+  className = "",
+}: {
+  surface?: PreviewSurface
+  height?: number | string
+  children?: ReactNode
+  className?: string
+}) {
+  const style = { height: height ?? "min(640px, 70vh)" }
+
+  if (surface === "paper") {
+    return (
+      <div
+        data-ow-part="content"
+        data-ow-surface="paper"
+        className={`min-h-0 flex-1 overflow-auto bg-[var(--ow-bg)] p-6 ${className}`}
+        style={style}
+      >
+        {/* 纸页：恒白 --ow-paper ＋ 局部浅档主题（暗主题下纸上文字仍取浅档墨色，禁白底浅字）。
+            §5 贴地零影：纸页是滚动区里的贴地表面、不是弹层，纸与衬垫的层次靠
+            1px --ow-border 立边表达（原来挂 --ow-shadow-pop 是把纸当浮层）。 */}
+        <div
+          data-theme="light"
+          data-ow-part="paper"
+          className="mx-auto w-full max-w-[760px] border border-[color:var(--ow-border)] bg-[var(--ow-paper)] text-[color:var(--ow-text)] [border-radius:var(--ow-radius-card)]"
+          style={{ padding: "var(--ow-space-8)" }}
+        >
+          {children}
+        </div>
+      </div>
+    )
+  }
+
+  if (surface === "mat") {
+    return (
+      // 媒体衬垫：§3 常暗域白名单（媒体查看器）局部暗档，底取嵌套井 --ow-surface-2。
+      <div
+        data-theme="dark"
+        data-ow-part="content"
+        data-ow-surface="mat"
+        className={`flex min-h-0 flex-1 items-center justify-center overflow-auto bg-[var(--ow-surface-2)] text-[color:var(--ow-text)] ${className}`}
+        style={style}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      data-ow-part="content"
+      data-ow-surface="plain"
+      className={`flex min-h-0 flex-1 flex-col overflow-auto bg-[var(--ow-bg)] ${className}`}
+      style={style}
+    >
+      {children}
+    </div>
+  )
+}

package/src/components/domain/files/index.ts

@@ -0,0 +1,5 @@
+export * from "./FileBrowser/index"
+export * from "./FileIcon/index"
+export * from "./FilePreviewContentView/index"
+export * from "./FileTree/index"
+export * from "./PreviewDialog/index"

package/src/components/domain/index.ts

@@ -0,0 +1,8 @@
+export * from "./artifacts"
+export * from "./browser"
+export * from "./chat"
+export * from "./desktop"
+export * from "./files"
+export * from "./office"
+export * from "./skills"
+export * from "./tasks"