@orbit-work/ui 0.1.0

package/src/components/Layout/SidebarShell/SidebarShellSource.test.mjs

@@ -0,0 +1,161 @@
+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 compat = await readFile(new URL("../Sidebar/index.tsx", import.meta.url), "utf8")
+const stories = await readFile(new URL("./SidebarShell.stories.tsx", import.meta.url), "utf8")
+
+test("resize handle hover keeps a stable class and does not rerender the sidebar", () => {
+  assert.equal((source.match(/data-slot="sidebar-resize-handle"/g) ?? []).length, 2)
+  assert.doesNotMatch(source, /hoverEdge|setHoverEdge/)
+  assert.doesNotMatch(source, /data-ow-state="active"/)
+  assert.doesNotMatch(source, /onMouseEnter=|onMouseLeave=/)
+})
+
+test("SidebarShell 是定稿名，Sidebar 只是薄兼容导出", () => {
+  assert.match(source, /export function SidebarShell\(/)
+  assert.match(source, /export interface SidebarShellProps/)
+  assert.match(compat, /@deprecated/)
+  assert.match(compat, /export const Sidebar = SidebarShell/)
+})
+
+test("展开宽走 var(--ow-sidebar-w)，不写死 240 进样式", () => {
+  assert.match(source, /width \?\? "var\(--ow-sidebar-w\)"/)
+  assert.match(source, /const SIDEBAR_DEFAULT_WIDTH = 240/)
+  assert.doesNotMatch(source, /w-\[240px\]|width: 240/)
+})
+
+// 裁决 11（原型 680/815）：那条 1px 挂在内容区 border-left，不挂侧栏 border-right——
+// 挂在侧栏上时折叠到 0 宽会剩一条悬空孤线（实测 aside 计算宽 1px）。
+test("立面按 §5：壳贴地 0 影 0 边；1px 分隔线归内容区左沿", () => {
+  assert.match(source, /flex-shrink-0 relative bg-ow-bg shadow-none/)
+  assert.doesNotMatch(source, /border-r border-\[color:var\(--ow-border\)\]|border-r-transparent/)
+  assert.doesNotMatch(source, /shadow-\[var\(--ow-shadow-pop\)\]/)
+  assert.doesNotMatch(source, /shadow-ow-shadow-2|shadow-\[var\(--ow-shadow-modal\)\]/)
+})
+
+test("分区滚动：只有 body 滚，header/footer 固定", () => {
+  assert.match(source, /sidebarBodyVariants = cva\(\s*"flex-1 min-h-0 overflow-y-auto/)
+  assert.match(source, /sidebarHeaderVariants = cva\("flex-shrink-0/)
+  assert.match(source, /sidebarFooterVariants = cva\("flex-shrink-0/)
+})
+
+// ── R2（Terry 2026-09-03 第 1 条）：通栏带只属 windows；mac/linux/web 的折叠钮住进侧栏顶行 ──
+
+test("顶行是新槽 sidebar-toprow：复用带里那枚钮，旧的 top-bar / 浮钮 / 48 预留一概不回来", () => {
+  // 顶行本身
+  assert.match(source, /data-slot="sidebar-toprow"/)
+  assert.match(source, /const sidebarTopRowVariants = cva\(/)
+  assert.match(source, /h-\[var\(--ow-titlebar-h\)\] min-h-\[var\(--ow-titlebar-h\)\]/)
+  assert.match(source, /gap-\[var\(--ow-titlebar-gap\)\] px-\[var\(--ow-titlebar-pad-x\)\]/)
+  // 钮不许在这里重造：只能 import 带里那一枚预制件
+  assert.match(source, /import \{ SidebarToggle \} from "\.\.\/\.\.\/composite\/TitleBar"/)
+  assert.match(
+    source,
+    /<SidebarToggle collapsed=\{collapsed\} onToggle=\{\(\) => onCollapsedChange\?\.\(!collapsed\)\} \/>/,
+  )
+  assert.doesNotMatch(source, /PanelSidebar|展开侧边栏|折叠侧边栏/)
+  // 旧机制的残件一律不许回来
+  assert.doesNotMatch(source, /sidebarTopBarVariants|sidebarExpandVariants|sidebarToggleVariants/)
+  assert.doesNotMatch(source, /data-slot="sidebar-top-bar"/)
+  assert.doesNotMatch(source, /reserveToggle/)
+  assert.doesNotMatch(source, /pt-\[var\(--ow-titlebar-h\)\]/)
+  // 折叠钮的坐标常量（mac 76/9、win 100/6、浮钮 18/17）全部随之消失
+  assert.doesNotMatch(source, /left-\[76px\]|left-\[100px\]|left-\[18px\]/)
+})
+
+// windows 是 frame:false、三键必须自绘，那条通栏带留着、钮在带里 → 侧栏无顶行；
+// 未给 platform＝不是窗口壳语境（通用消费方 / 文档壳），同样不出顶行。
+test("顶行有无一律由 platform 派生：windows 与未给平台都不出（showToggle 已删）", () => {
+  assert.match(source, /const showTopRow = platform != null && platform !== "windows"/)
+  assert.match(source, /\{showTopRow && \(/)
+  // showToggle 这枚 prop 已整枚删除（只在文档注释里留一句「已删」的碑文）
+  assert.doesNotMatch(source, /showToggle\?: boolean|showToggle,|showToggle=\{/)
+})
+
+// mac 让位块是**块不是 padding**：只有用块，行的 gap 才参与，钮才落在 8+68+4 = 80。
+test("mac 让位块与 composite/TitleBar 同一口径，全屏收 0", () => {
+  assert.match(source, /const showTrafficInset = platform === "mac" && !fullscreen/)
+  assert.match(source, /data-slot="sidebar-traffic-inset"/)
+  assert.match(source, /w-\[var\(--ow-traffic-inset\)\] h-full flex-shrink-0/)
+  assert.match(source, /fullscreen\?: boolean/)
+})
+
+test("平台是受控 prop，库侧不嗅探 userAgent，也不做平台偏移", () => {
+  assert.doesNotMatch(source, /navigator\.userAgent/)
+  assert.match(source, /export type SidebarShellPlatform = "mac" \| "windows" \| "linux" \| "web"/)
+  assert.match(source, /data-ow-platform=\{platform\}/)
+})
+
+// 折叠宽按平台派生：mac 116（8+68+4+28+8）、linux/web/mac 全屏 44（8+28+8）、
+// windows 与未给平台 0（inner 整块不渲染，不留 1px 孤线）。消费方传 collapsedWidth 则覆盖。
+test("折叠宽走 token 派生：mac rail 116 / 其余 rail 44 / windows 0", () => {
+  assert.match(source, /"var\(--ow-sidebar-collapsed-w-mac\)"/)
+  assert.match(source, /"var\(--ow-sidebar-collapsed-w\)"/)
+  assert.match(source, /const isPlatformRail = collapsed && showTopRow && !isCustomRail && !fullHide/)
+  assert.match(source, /const isHidden = collapsed && !isCustomRail && !isPlatformRail/)
+  // rail 态只出顶行：inner 三块整体不渲染
+  assert.match(source, /\{!isHidden && !isPlatformRail && \(/)
+  assert.doesNotMatch(source, /invisible/)
+  assert.doesNotMatch(source, /@deprecated 折叠钮已迁出侧栏/)
+})
+
+// 显式 collapsedWidth=0＝整条卸载（桌面宿主「折叠＝全部折叠」）：根宽归 0、inner 不渲染，
+// 顶行折成幽灵钮坐在窗口左上角原坐标——透明底（mac 惯例：红绿灯与钮直接浮在内容面上，
+// 不铺角块底色）、撤拖拽域、整行 pointer-events-none 只留钮可点；mac 非全屏钮仍落 x=80。
+// 层序不抬在 TSX（壳内不抬 z 的口径），由 desktop-surfaces.css 的 [data-ow-floating] 给。
+test("显式 collapsedWidth=0：整条卸载，顶行折成幽灵钮供重新展开", () => {
+  assert.match(source, /const fullHide = collapsed && collapsedWidth === 0/)
+  assert.match(source, /const currentWidth = fullHide/)
+  assert.match(source, /data-ow-floating=\{isHidden \? "" : undefined\}/)
+  assert.match(source, /absolute top-0 left-0 w-max/)
+  assert.match(source, /pointer-events-none/)
+  assert.match(source, /\[\&_\[data-slot=sidebar-toggle\]\]:pointer-events-auto/)
+})
+
+test("动效只用 ease-beacon + 120/200 档；不写裸 z / 裸时长", () => {
+  assert.match(source, /duration-\[var\(--ow-dur-2\)\] ease-\[var\(--ow-ease-beacon\)\]/)
+  assert.match(source, /duration-\[var\(--ow-dur-1\)\] ease-\[var\(--ow-ease-beacon\)\]/)
+  // 层序随折叠钮一并搬走：壳里已无需要抬 z 的元素（拖拽把手的 z 在 desktop-surfaces.css）
+  assert.doesNotMatch(source, /\bz-\[|\bz-50\b|duration-200\b/)
+})
+
+test("中性件：禁信标/荧黄（R3）；无 Tailwind 歧义任意值", () => {
+  assert.doesNotMatch(source, /--ow-yellow|--ow-beacon|--ow-accent-dot/)
+  assert.doesNotMatch(source, /(?:text|border)-\[var\(--ow-/)
+})
+
+// ── R2 修补（口径已随裁决 11 更新：静区整条撤除，钮归窗口带） ──
+
+test("侧栏首行就是内容本身：header/body 都不再让出 48 静区", () => {
+  assert.match(source, /const sidebarHeaderVariants = cva\("flex-shrink-0 px-3 pt-2 pb-2"\)/)
+  assert.match(source, /sidebarHeaderVariants\(\)/)
+  assert.match(source, /sidebarBodyVariants\(\)/)
+})
+
+// A1-B6：body 左右内距原为 pl-4 / pr-1（16 / 4），栏内每一行的左沿比右沿多 12px。
+// 并轨到 8/8＝原型 680 的 aside 横向内距；desktop-surfaces.css 的同名覆写取同值。
+test("A1-B6：body 左右内距对称 8/8，上沿仍为 0", () => {
+  assert.match(source, /overflow-x-hidden pt-0 px-2 pb-3 flex flex-col/)
+  assert.doesNotMatch(source, /pr-1 pb-3 pl-4/)
+})
+
+// 故事按 R2 新口径：带只属 windows（那张 story 里壳与带成对出现、钮由带承载）；
+// mac/linux 的钮由壳自己的顶行承载，story 直接传 platform。
+test("story fixture：windows 才配 WindowBand，mac/linux 走 platform 顶行", () => {
+  assert.match(stories, /import \{ WindowBand \} from "\.\.\/\.\.\/composite\/TitleBar"/)
+  assert.match(stories, /<WindowBand platform="windows" collapsed=\{collapsed\} onToggle=/)
+  assert.doesNotMatch(stories, /<WindowBand platform="mac"/)
+  assert.match(stories, /platform="mac"/)
+  assert.match(stories, /platform="linux"/)
+  assert.match(stories, /fullscreen/)
+  assert.doesNotMatch(stories, /showToggle/)
+})
+
+// 判据 7：品牌外渐变一律清除——含 Storybook 里的可见面。
+test("story fixture 无 V1 蓝紫渐变，缓动走唯一 ease-beacon", () => {
+  assert.doesNotMatch(stories, /linear-gradient/)
+  assert.doesNotMatch(stories, /var\(--ow-ease\)/)
+  assert.doesNotMatch(stories, /蓝色指示线/)
+})

package/src/components/Layout/SidebarShell/index.tsx

@@ -0,0 +1,326 @@
+"use client"
+
+import { cva } from "class-variance-authority"
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react"
+import { cn } from "../../../lib/utils"
+import { SidebarToggle } from "../../composite/TitleBar"
+
+/* 立面（§5）：壳贴地 —— 0 影，且**不画右边线**。
+   原型（模板 680/815）把侧栏与内容区之间那条 1px 挂在 `main` 的 border-left 上，
+   不挂 aside 的 border-right：只有这样折叠到 0 宽时才不会剩一条悬空的孤线
+   （旧做法实测折叠后 aside 计算宽 = 1px）。壳侧的对应实现见 desktop-surfaces.css
+   `.owcenter { border-left: 1px solid var(--ow-border) }`。 */
+const sidebarVariants = cva(
+  [
+    "flex-shrink-0 relative bg-ow-bg shadow-none",
+    "transition-[width,min-width] duration-[var(--ow-dur-2)] ease-[var(--ow-ease-beacon)]",
+  ].join(" "),
+  {
+    variants: {
+      dragging: {
+        true: "transition-none",
+        false: "",
+      },
+      /* 出顶行时 aside 变成竖向两段（顶行 ＋ inner），inner 吃余量；
+         不出顶行时保持原来的单孩子块，几何逐像素不变。 */
+      stacked: {
+        true: "flex flex-col",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      dragging: false,
+      stacked: false,
+    },
+  },
+)
+
+const sidebarInnerVariants = cva("flex flex-col overflow-hidden", {
+  variants: {
+    /* 顶行占掉 48 之后 inner 只能吃余量：h-full 会算成 aside 全高而溢出。 */
+    fill: {
+      true: "flex-1 min-h-0",
+      false: "h-full",
+    },
+  },
+  defaultVariants: { fill: false },
+})
+
+/* 侧栏顶行（R2）：与 windows 的通栏带同高（--ow-titlebar-h=48）、同内距
+   （--ow-titlebar-pad-x=8）、同间距（--ow-titlebar-gap=4）、同地色（--ow-bg），
+   整行是拖拽域（Electron 的 -webkit-app-region 无 Tailwind 工具类，用任意属性写；
+   壳侧对应声明见 styles/electron-shell.css）。行内＝mac 红绿灯让位块 ＋ 折叠钮，
+   钮因此落在 8+68+4 = 80 —— 与旧通栏带里的坐标一字不差。 */
+const sidebarTopRowVariants = cva(
+  [
+    "flex items-center flex-shrink-0 select-none",
+    "h-[var(--ow-titlebar-h)] min-h-[var(--ow-titlebar-h)]",
+    "gap-[var(--ow-titlebar-gap)] px-[var(--ow-titlebar-pad-x)]",
+    "bg-ow-bg",
+    "[-webkit-app-region:drag]",
+  ].join(" "),
+)
+
+/* 分区：header / footer 固定不滚，只有 body 滚动（§6 容器分区）。
+   R2 裁决（Terry 2026-09-03 第 1 条）：**通栏窗口带只属 windows**（frameless 必须自绘三键）；
+   mac/linux/web 的折叠钮住进侧栏自己的**顶行**（`data-slot="sidebar-toprow"`，高
+   --ow-titlebar-h=48）。顶行是 aside 的第一个孩子、在 sidebar-inner 之上，所以 header
+   本身仍不为按钮预留任何净空：inner 首行直接就是品牌 lockup（原型 682–684）。 */
+const sidebarHeaderVariants = cva("flex-shrink-0 px-3 pt-2 pb-2")
+/* A1-B6：横向内距原为 pl-4 / pr-1 的不对称（16 / 4），栏内每一行的左沿比右沿多 12px。
+   两侧并轨到 8（原型 680 的 aside `padding: 0 8px 10px`）。上沿仍是 0（折叠钮迁出后
+   首行直接是 lockup）。壳层与 `styles/desktop-surfaces.css` 的
+   `[data-slot="sidebar-body"]` 覆写同值，两处一起改，谁先落地都不掉档。 */
+const sidebarBodyVariants = cva("flex-1 min-h-0 overflow-y-auto overflow-x-hidden pt-0 px-2 pb-3 flex flex-col")
+const sidebarFooterVariants = cva("flex-shrink-0 px-3 py-2 border-t border-[color:var(--ow-border)]")
+
+const sidebarResizeHandleVariants = cva(
+  "absolute top-0 right-0 w-1 h-full cursor-col-resize hover:bg-[var(--ow-border-strong)] transition-colors duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+)
+
+/** 平台（受控）。壳本身两平台同形，此值只作 `data-ow-platform` 出参供消费方定位，不产生任何偏移。 */
+export type SidebarShellPlatform = "mac" | "windows" | "linux" | "web"
+
+export interface SidebarShellProps {
+  /** 是否折叠 */
+  collapsed?: boolean
+  /**
+   * 折叠状态变化回调。R2 起本壳**重新成为触发方**：mac/linux/web 的折叠钮就在侧栏顶行里，
+   * 点它即回调本函数；windows 无顶行，触发方仍是通栏带里的那枚钮（同一个 `SidebarToggle` 预制件）。
+   */
+  onCollapsedChange?: (collapsed: boolean) => void
+  /** 展开时宽度；未传时用 var(--ow-sidebar-w)（240） */
+  width?: number
+  /** 宽度变化回调（拖拽调整时） */
+  onWidthChange?: (width: number) => void
+  /**
+   * 折叠后宽度（消费方自定 icon rail）。**缺省不传时按 `platform` 派生**：
+   * mac 非全屏 `var(--ow-sidebar-collapsed-w-mac)`（116＝8+68+4+28+8）、
+   * linux/web/mac 全屏 `var(--ow-sidebar-collapsed-w)`（44＝8+28+8）、
+   * windows 与未给平台 0（整条卸载）。传数值即覆盖派生值，inner 按 rail 宽渲染；
+   * **显式传 0 也是覆盖**：整条卸载（连平台 rail 都不留），顶行折成浮块坐在窗口左上角原坐标，
+   * 供用户重新展开——桌面宿主「折叠＝全部折叠」走这一档。
+   */
+  collapsedWidth?: number
+  /** 最小宽度（默认 200） */
+  minWidth?: number
+  /** 最大宽度（默认 480） */
+  maxWidth?: number
+  /** 是否可拖拽调整宽度（默认 true） */
+  resizable?: boolean
+  /**
+   * 平台（受控，权威值来自主进程；库侧**不**嗅探 userAgent）。
+   * R2 起这枚值是「顶行有无」的**唯一**开关（旧的 `showToggle` 已删）：
+   * `windows` 无顶行（钮在通栏带里）、未给平台＝非窗口壳语境也无顶行，其余一律出顶行。
+   * 同时反射为 `data-ow-platform`。
+   */
+  platform?: SidebarShellPlatform
+  /** mac 全屏：红绿灯消失 → 顶行的让位块收 0，折叠钮回到左内距 8；折叠 rail 宽随之收到 44。 */
+  fullscreen?: boolean
+  /** 无样式模式：不加 ow-sidebar class，布局由消费方 className 控制。仅保留拖拽/折叠逻辑。 */
+  unstyled?: boolean
+  /** 顶部区域（Logo、品牌等） */
+  header?: ReactNode
+  /** 底部区域（用户信息等） */
+  footer?: ReactNode
+  /** 主体内容（导航、列表等） */
+  children: ReactNode
+  /** 额外 className */
+  className?: string
+}
+
+/** var(--ow-sidebar-w) 的数值兜底（styles/tokens.css: 240px）——拖拽起点等 JS 计算用。 */
+const SIDEBAR_DEFAULT_WIDTH = 240
+
+/**
+ * SidebarShell — 侧栏壳（DS 2.0 模式层，原 Layout/Sidebar 定稿件）
+ *
+ * 规格（COMPONENT-RULES §5/§6/§7 + 原型模板 677–812，裁决 11 · R2 改判）：
+ * - 展开宽 `var(--ow-sidebar-w)`（240）；受控传 width 后按数值走，拖拽区间 [minWidth, maxWidth]。
+ * - **折叠钮住在哪由平台决定**（R2）：windows 是 frameless、三键必须自绘，所以那条通栏带留着、
+ *   钮在带里（本壳不出顶行）；mac/linux/web 没有通栏带，钮住进本壳的**顶行**
+ *   `data-slot="sidebar-toprow"`（48 高、与地同色、整行 drag）。两处是同一枚
+ *   `composite/TitleBar` 的 `SidebarToggle` 预制件，折叠/展开同一坐标：
+ *   mac 8+68(让位块)+4 = **80**；linux/web/mac 全屏 = **8**；windows（带里）= 8。
+ * - 贴地立面：0 影、**0 边**。侧栏与内容区之间那条 1px 由内容区 `border-left` 承担，
+ *   折叠到 0 宽时不留孤线；mac 顶行让内容面从 y=0 起，那条左沿线因此贯到窗口顶。
+ * - 折叠：出顶行的平台收成 **rail**（mac 116 / linux·web·mac 全屏 44）——只渲染顶行，
+ *   header/body/footer 三块整体不渲染；windows 与未给平台仍是「根宽 0 ＋ inner 不渲染」。
+ *   消费方显式传 `collapsedWidth > 0` 则是自定 icon rail（inner 按 rail 宽渲染），与平台无关。
+ * - 分区滚动：header / footer 固定不滚，只有 body 滚。
+ * - 平台是受控 prop，库侧不嗅探 userAgent；除顶行与折叠宽外不做任何平台偏移。
+ * - 当前项（位置极）语法属 SidebarCurrent 品牌锁定件，不在本壳内实现。
+ */
+export function SidebarShell({
+  collapsed = false,
+  onCollapsedChange,
+  width,
+  onWidthChange,
+  collapsedWidth,
+  minWidth = 200,
+  maxWidth = 480,
+  resizable = true,
+  platform,
+  fullscreen = false,
+  unstyled = false,
+  header,
+  footer,
+  children,
+  className = "",
+}: SidebarShellProps) {
+  const [dragging, setDragging] = useState(false)
+  const startX = useRef(0)
+  const startWidth = useRef(width ?? SIDEBAR_DEFAULT_WIDTH)
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      if (!resizable || collapsed) return
+      e.preventDefault()
+      setDragging(true)
+      startX.current = e.clientX
+      startWidth.current = width ?? SIDEBAR_DEFAULT_WIDTH
+    },
+    [resizable, collapsed, width],
+  )
+
+  useEffect(() => {
+    if (!dragging) return
+
+    const handleMouseMove = (e: MouseEvent) => {
+      const delta = e.clientX - startX.current
+      const newWidth = Math.min(maxWidth, Math.max(minWidth, startWidth.current + delta))
+      onWidthChange?.(newWidth)
+    }
+
+    const handleMouseUp = () => setDragging(false)
+
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+    document.body.style.cursor = "col-resize"
+    document.body.style.userSelect = "none"
+
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+      document.body.style.cursor = ""
+      document.body.style.userSelect = ""
+    }
+  }, [dragging, maxWidth, minWidth, onWidthChange])
+
+  // 展开宽度：消费方未受控时引用 token var(--ow-sidebar-w)（240），受控后用传入数值
+  const expandedWidth: number | string = width ?? "var(--ow-sidebar-w)"
+  /* 顶行只属「有窗口壳但没有通栏带」的平台：windows 的钮在带里，未给平台＝不是窗口语境
+     （通用消费方 / 文档壳），两者都不出顶行。这是 R2 后「顶行有无」的唯一判据。 */
+  const showTopRow = platform != null && platform !== "windows"
+  /* mac 让位块：宽 --ow-traffic-inset 的空块（非 padding），全屏红绿灯消失时整块不出——
+     与 composite/TitleBar 的 showTrafficInset 同一口径，两处同改。 */
+  const showTrafficInset = platform === "mac" && !fullscreen
+  /* 平台派生的折叠宽：mac 116（8+68+4+28+8）、linux/web/mac 全屏 44（8+28+8）、其余 0。 */
+  const platformCollapsedWidth: number | string = showTrafficInset
+    ? "var(--ow-sidebar-collapsed-w-mac)"
+    : showTopRow
+      ? "var(--ow-sidebar-collapsed-w)"
+      : 0
+  // 消费方自定 icon rail（collapsedWidth > 0）优先于平台派生
+  const isCustomRail = collapsed && collapsedWidth != null && collapsedWidth > 0
+  // 消费方显式 collapsedWidth=0＝整条卸载：折叠后侧栏全让位给内容，连平台 rail 都不留；
+  // 顶行折成浮块（见下方 data-ow-floating）供重新展开；mac 非全屏时壳侧只给页首/会话头
+  // 的首行内容让出这块角，不出通栏带（desktop-surfaces.css）。
+  const fullHide = collapsed && collapsedWidth === 0
+  // 平台 rail：只渲染顶行，header/body/footer 三块整体不出
+  const isPlatformRail = collapsed && showTopRow && !isCustomRail && !fullHide
+  // 完全隐藏：根宽 0、inner 整块不渲染 —— 折叠后侧栏干净归零，不留 1px 孤线
+  const isHidden = collapsed && !isCustomRail && !isPlatformRail
+  const currentWidth = fullHide
+    ? 0
+    : collapsed
+      ? isCustomRail
+        ? (collapsedWidth as number)
+        : platformCollapsedWidth
+      : expandedWidth
+  // 内部内容宽度：rail 模式用折叠宽度，其余按展开宽度
+  const innerWidth = isCustomRail ? (collapsedWidth as number) : expandedWidth
+
+  const asideClass = unstyled ? className : cn(sidebarVariants({ dragging, stacked: showTopRow }), className)
+
+  return (
+    <aside
+      data-slot="sidebar"
+      data-ow-platform={platform}
+      data-ow-collapsed={collapsed ? "" : undefined}
+      className={asideClass}
+      style={unstyled ? undefined : { width: currentWidth, minWidth: currentWidth }}
+    >
+      {unstyled ? (
+        /* unstyled 模式：不渲染内部结构，children 直接放入，仅保留拖拽手柄 */
+        <>
+          {children}
+          {resizable && !collapsed && (
+            <div
+              data-slot="sidebar-resize-handle"
+              className={sidebarResizeHandleVariants()}
+              onMouseDown={handleMouseDown}
+            />
+          )}
+        </>
+      ) : (
+        /* styled 模式：顶行（按平台）＋ 完整内部结构；折叠成 rail 或完全折叠时 inner 不渲染 */
+        <>
+          {showTopRow && (
+            <div
+              data-slot="sidebar-toprow"
+              data-ow-floating={isHidden ? "" : undefined}
+              className={
+                isHidden
+                  ? /* 整条卸载（fullHide）：aside 宽归 0，顶行折成**幽灵钮**坐在原坐标——
+                       透明底、撤拖拽域、整行不抢指针（mac 惯例：红绿灯与这枚钮直接浮在
+                       内容面上，不铺角块底色），只有钮本身可点；mac 非全屏仍落 x=80。
+                       层序在壳侧 desktop-surfaces.css 的 [data-ow-floating] 规则里抬。 */
+                  "absolute top-0 left-0 w-max flex items-center flex-shrink-0 select-none h-[var(--ow-titlebar-h)] min-h-[var(--ow-titlebar-h)] gap-[var(--ow-titlebar-gap)] px-[var(--ow-titlebar-pad-x)] pointer-events-none [&_[data-slot=sidebar-toggle]]:pointer-events-auto"
+                  : sidebarTopRowVariants()
+              }
+            >
+              {showTrafficInset && (
+                <div
+                  aria-hidden="true"
+                  data-slot="sidebar-traffic-inset"
+                  className="w-[var(--ow-traffic-inset)] h-full flex-shrink-0"
+                />
+              )}
+              <SidebarToggle collapsed={collapsed} onToggle={() => onCollapsedChange?.(!collapsed)} />
+            </div>
+          )}
+          {!isHidden && !isPlatformRail && (
+            <div
+              data-slot="sidebar-inner"
+              className={sidebarInnerVariants({ fill: showTopRow })}
+              style={{ width: innerWidth }}
+            >
+              {header && (
+                <div data-slot="sidebar-header" className={sidebarHeaderVariants()}>
+                  {header}
+                </div>
+              )}
+              <div data-slot="sidebar-body" className={sidebarBodyVariants()}>
+                {children}
+              </div>
+              {footer && (
+                <div data-slot="sidebar-footer" className={sidebarFooterVariants()}>
+                  {footer}
+                </div>
+              )}
+            </div>
+          )}
+
+          {resizable && !collapsed && (
+            <div
+              data-slot="sidebar-resize-handle"
+              className={sidebarResizeHandleVariants()}
+              onMouseDown={handleMouseDown}
+            />
+          )}
+        </>
+      )}
+    </aside>
+  )
+}

package/src/components/Layout/index.ts

@@ -0,0 +1,10 @@
+export { AppLayout } from "./AppLayout"
+export type { AppLayoutProps } from "./AppLayout"
+
+export { SidebarShell } from "./SidebarShell"
+export type { SidebarShellProps } from "./SidebarShell"
+
+/** @deprecated 旧名，改用 SidebarShell。薄兼容导出，供包外渐进迁移。 */
+export { Sidebar } from "./Sidebar"
+/** @deprecated 旧名，改用 SidebarShellProps。 */
+export type { SidebarProps } from "./Sidebar"

package/src/components/composite/ActionBar/ActionBar.stories.tsx

@@ -0,0 +1,26 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { ActionBar } from "./index"
+
+/**
+ * @deprecated 消息操作行已并入 `Chat/MessageActions`。本组只保留兼容层证明：
+ * 旧调用点拿到的是常显（visible）的 MessageActions。
+ */
+const meta = {
+  title: "Composite/ActionBar (deprecated)",
+  component: ActionBar,
+  parameters: { layout: "padded" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof ActionBar>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** 六件预设，常显。 */
+export const Compat: Story = {
+  args: {},
+}
+
+/** 子集：只留复制与重新生成。 */
+export const Subset: Story = {
+  args: { actions: ["copy", "regenerate"] },
+}

package/src/components/composite/ActionBar/index.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import { MessageActions } from "../../domain/chat/MessageActions"
+
+export type ActionBarAction = "copy" | "regenerate" | "speak" | "like" | "dislike" | "share"
+
+export type ActionBarProps = {
+  /** Which actions to show (defaults to all 6) */
+  actions?: ActionBarAction[]
+  onAction?: (action: ActionBarAction) => void
+  className?: string
+}
+
+const ALL_ACTIONS: ActionBarAction[] = ["copy", "regenerate", "speak", "like", "dislike", "share"]
+
+/**
+ * @deprecated DS2 已把消息操作行并入 `MessageActions`（蓝图批次③：ActionBar +
+ * ChatActionbar + ChatActionRowView → MessageActions）。本件只作薄兼容层，
+ * 以常显（`visible`）方式渲染新件；新代码直接用 `MessageActions`，
+ * 并优先走 hover 浮现的缺省形态。
+ */
+export function ActionBar({ actions = ALL_ACTIONS, onAction, className = "" }: ActionBarProps) {
+  return (
+    <MessageActions
+      actions={actions}
+      onAction={(kind) => onAction?.(kind as ActionBarAction)}
+      visible
+      className={`mt-1 ${className}`}
+    />
+  )
+}

package/src/components/composite/ActionStatus/ActionStatus.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { ActionStatus } from "./index"
+
+const meta = {
+  title: "Composite/ActionStatus",
+  component: ActionStatus,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof ActionStatus>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Idle: Story = {
+  args: {
+    running: false,
+    children: "Waiting for input",
+  },
+}
+
+export const Running: Story = {
+  args: {
+    running: true,
+    children: "Thinking",
+  },
+}
+
+export const ToolRunning: Story = {
+  args: {
+    running: true,
+    children: "Reading file",
+  },
+}
+
+export const ToolCompleted: Story = {
+  args: {
+    running: false,
+    children: "File read successfully",
+  },
+}
+
+export const MultipleStates: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+      <ActionStatus running={true}>Searching files</ActionStatus>
+      <ActionStatus running={true}>Running tests</ActionStatus>
+      <ActionStatus running={false}>Build completed</ActionStatus>
+      <ActionStatus running={false}>All tests passed</ActionStatus>
+    </div>
+  ),
+}
+
+export const LongText: Story = {
+  args: {
+    running: true,
+    children: "Analyzing codebase and generating comprehensive documentation",
+  },
+}

package/src/components/composite/ActionStatus/index.tsx

@@ -0,0 +1,21 @@
+import type { HTMLAttributes, ReactNode } from "react"
+import { cn } from "../../../lib/utils"
+
+export type ActionStatusProps = HTMLAttributes<HTMLSpanElement> & {
+  running?: boolean
+  children: ReactNode
+}
+
+/** Shared status text for thinking and all tool-driven actions. */
+export function ActionStatus({ running = false, className = "", children, ...props }: ActionStatusProps) {
+  return (
+    <span
+      data-slot="action-status"
+      data-ow-state={running ? "running" : undefined}
+      className={cn("text-ow-text-3 font-normal font-[family-name:var(--ow-font-sans)]", className)}
+      {...props}
+    >
+      {children}
+    </span>
+  )
+}