@linhey/rhine-design 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 版本记录
 
+## 0.9.0（2026-10-24）
+
+- #17：OrbitBackdrop 新增 controls、composition 和 framed；背景画布与静态降级同置右下角，新增按容器宽度重排的入口组合，保留输入和减少动态。
+- #19：新增 ListFilterBar，最多两个主筛选，超出进入 Drawer；保留可见搜索标签，统一条件摘要、清除、重置、刷新和请求反馈，业务查询与权限由宿主管理。
+- 修复原生日期未完成片段被当作空值提交的问题；DateRangePicker 清空和同值预设可恢复本地草稿；有效输入继续服从宿主受控值。展台整体重置清除同值日期的未完成草稿。清除最后一个不可聚焦字段的摘要后，焦点保留在筛选区域。
+- 独立验收覆盖三主题、窄容器与 200% CSS zoom、抽屉焦点、日期键盘、真实 GPU 播放与动态偏好、静态降级及卸载清理。
+
+## 0.8.0（2026-10-24）
+
+- 审查修复：保留 Tooltip 与嵌套 Dialog 的 Escape 层级；主题元数据独立于可选 CSS；设置示例保存中重开时同步已保存值并保留后续编辑。
+- 对应 #18：Dialog 新增 `navigation` 插槽，提供按实际容器宽度重排的设置导航布局，保留嵌套焦点、草稿与宿主状态，并修复快速打开内层后 Escape 误关外层。
+- 对应 #20：新增受控原生单选 `ThemePicker` 和静态 `ThemePreview`；三套官方组件缩略图随包提供，覆盖加载/失败/禁用，主题切换不重挂载业务子树。
+
+- 修复 #16：Popover、Menu、Tooltip 和时间轴共用浮层 CSS zoom 归一化；保留文字与点击目标放大，并在边缘限制实际浮层边界。新增文档/主题根/正文缩放的独立文档展台。
+
+### 承接未发布的 0.7.0 候选
+
+0.7.0 未成功发布至 npm；下列已接受功能随 0.8.0 一并交付，历史候选制品保持不变。
+
+- 橙趣草莓甜甜圈增强为按需加载的 Three.js 艺术：立体糖霜、程序烘焙纹理、280 根糖针、110 颗糖珠、100 根环绕糖粒与 460 颗糖尘；共用原版倾角、62%/57%中心与缩放，校准主体尺寸，保留环面旋转、共享暂停与减少动态时钟，并提供 Canvas2D 降级和 GPU 清理。
+- OrbitBackdrop 新增 `appearance="theme" | "original"`：莱茵为折纸鸟（578 个三角折面、扇形褶皱与叠层双翼、暖白纸纹、弧线飞行和随行纸屑），战术为源石晶簇（倒角晶面、矿物纹理、琥珀裂纹和漂浮碎片），橙趣为草莓甜甜圈。三套物品均按需加载 Three.js；窄屏也可播放，共用暂停、减少动态和可见性时钟，切换主题复用已创建的绘制器。WebGL 失败回退 Canvas2D，Canvas 不可用时展示本地 SVG。`original` 保留初版完整深色轨道。
+- 莱茵纸鸟在同一组折面上连续变形成四瓣纸蝴蝶：单程 14 秒，依次收翼、松折、展平停顿、重新折叠，翼根至翼尖错开动作；全周期 42 秒。变形中暂缓扑翼，暂停或减少动态冻结当前形态，恢复后接续；WebGL 与 Canvas2D 共用几何、变形和飞行姿态，静态 SVG 保留初始纸鸟。
+- 新增 `StatusTimelineList` 多条健康历史组合；与 `AppShellToggle`、`NeutronStarBackdrop`、`ButtonLink` 一起将公共组件增至 64。
+- AppShell 新增可选 `contentHeader` 导航插槽，位于正文滚动区外；展台按应用栏模式组合当前页、侧栏入口与上下文操作，窄窗使用菜单入口，保留草稿和焦点。三主题边界同步；默认 header 模式保持兼容。
+- 重做媒体卡片与查看器：卡片边框、类型标签、选中态及独立操作区跟随三套主题；查看器仅画布保持中性深色，工具栏和信息栏使用宿主主题。展台改为自适应资源网格并单列异常状态，修复 CSS zoom 下查看器高度重复放大。
+- 补齐 Neo Brutalism 的 Badge 墨色描边与字重，中性标签使用主题文字色。
+
+- 对应 [#14](https://github.com/linhay/rhine-design/issues/14)：新增原生 anchor 语义的 `ButtonLink`，复用 Button 视觉及 busy/disabled；移交 `StatusTimelineList` 稳定行/互斥详情组合，并扩展 `TimelineLegend compact/items` 为一行短标签与悬停、键盘、触屏规则详情。无参图例保持兼容。
+- 时间轴与图例详情在祖先 CSS zoom 下归一化定位包装层，保留正文放大与视口内滚动；鼠标离开跨卡详情延迟关闭，移入浮层可继续阅读，不更改键盘或触屏入口。
+- 新增[紧凑摘要与凭证操作](docs/COMPACT_ACCOUNT_PATTERNS.md)及 `#compact-account` 真实样机：无框额度摘要、配对事实、短必要提示、按需历史；消融不减小业务字体、不隐藏未知/失败或混淆不同成本与到期。以上能力随 0.8.0 提供。
+
+- AppShell 新增可选 inline 控制模式与 AppShellToggle：侧栏品牌区收起、正文导航区展开/打开抽屉，不再强制独立顶部横栏；默认 header 模式保持兼容。补充焦点迁移、断点和 Escape 回归及真实展台。
+- 对应 [#12](https://github.com/linhay/rhine-design/issues/12)：新增 `NeutronStarBackdrop`，承接完整中子星艺术：28 条磁场线、560 个流动粒子、700 颗星尘、极向喷流与星核；星系以 28 秒有效播放时间完成一轮深度公转，镜头固定。默认跟随现有主题 tokens，`appearance="original"` 保留原始深空；主题切换不重置时间，正文与实体控件保持清晰。
+- Three.js 绘制按需加载，内置暂停 / 继续，系统、显式、祖先减少动态及隐藏 / 离屏 / 零尺寸停帧，恢复不追赶。SSR 安全结构、异步卸载保护、GPU 资源清理与静态降级；无 WebGL、导入失败和 context lost 不影响内容，context restored 按当前偏好恢复。
+- 外层流粒与对应磁场线对齐，避免使用生成参数的错误边界裁剪粒子；暂停控件的焦点框绘制于按钮内部，保持原始深空下的键盘焦点可见。
+- 修复长页窄屏中星核随公转移出画幅：艺术层独立限高并渐隐，窄画幅由库内相机取景适配；保留原始几何与时间公式，正文和控件布局不受艺术高度限制。
+- 新增艺术优先的 `#neutron-star` 真实展台，演示控制与内容组合默认折叠；重播不丢表单草稿。[组件契约](docs/NEUTRON_STAR_BACKDROP.md)、API / 任务索引及回归测试同步。此 API 自 0.8.0 提供。
+- 对应 [#10](https://github.com/linhay/rhine-design/issues/10)：新增[日期筛选组合规范](docs/DATE_RANGE_FILTER.md)与 `#date-range-filter` 真实展台；复用 0.6.0 已发布的 SegmentedControl、Button、Popover、DateRangePicker 和布局组件。快捷项共用分段边界，日期持续可见，预设即时应用、自定义确认后应用，取消和关闭不提交。包含跨年、长标签、禁用、键盘和三主题验证；仅组合已有 API，不新增独立日期筛选组件。
+
 ## 0.6.0（2026-10-24）
 
 - 对应 [#8](https://github.com/linhay/rhine-design/issues/8)：新增 `OrbitBackdrop`，将授权移交的轨道艺术维护为公共组件，保留 420 个环节点、185 条空间曲线、箭头、光晕与透视；公共组件增至 60 个，无新增运行时依赖。

package/README.md

@@ -16,10 +16,10 @@
   <a href="CHANGELOG.md">版本记录</a>
 </p>
 
-Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、60 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
+Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、66 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
 
 - **一致的视觉语言**：色彩、字体、文字层级、间距、几何与焦点规则。
-- **60 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
+- **66 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
 - **可验证的动效**：12 组播放 / 重播 / 复位演示，以及三角构架启动编排。
 - **面向开发协作**：组件契约、交互展台和 AI skill 帮助设计与实现保持一致。
 
@@ -29,12 +29,16 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 
 **0.5.0 新增能力**：新增背景与多侧栏、复杂表单、受控数据表、媒体与监控图表，共 59 个组件。API、最小接入与版本边界见[应用组件契约](docs/APPLICATION_COMPONENTS.md)。npm 0.4.0 不含这些能力。
 
-**0.6.0 新增能力**：新增 `OrbitBackdrop` 轨道艺术组件，提供暂停、减少动态与静态降级，总数增至 60。安装前核对[版本记录](CHANGELOG.md)与 registry；在线展台跟随 main。
+**0.8.0 新增能力**：三主题 Three.js 艺术分别为折纸鸟、源石晶簇与草莓甜甜圈，保留原始轨道切换；新增 `NeutronStarBackdrop`、`StatusTimelineList` 、`AppShellToggle` 与 `ButtonLink`，公共组件总数为 66。包含暂停、减少动态、静态降级与资源清理。安装前核对[版本记录](CHANGELOG.md)与 registry；在线展台跟随 main。
+
+0.8.0 同时提供 `ButtonLink` 与可传规则的一行 `TimelineLegend`；[紧凑摘要与凭证操作规范](docs/COMPACT_ACCOUNT_PATTERNS.md)说明无框摘要、历史详情与必要操作的组合。真实展台为 `/#compact-account`。
 
 本轮新增 API 与交互已逐项核对 Ant Design / MUI，修复及明确保留的差异见[对标清单](docs/ANTD_MUI_AUDIT.md)。
 
 <a id="quick-start"></a>
 
+**0.8.0 新增**：新增 [主题预览与选择](docs/THEME_PICKER.md)、[设置弹窗导航](docs/SETTINGS_DIALOG.md)及[浮层缩放修复](docs/FLOATING_OVERLAYS.md)。0.7.0 候选未发布；本版承接其全部已接受功能。
+
 ## 快速接入
 
 需要 **React 19**。当前已验证的构建环境为 **Vite**，开发建议使用 **Node 24**。
@@ -42,7 +46,7 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 在你的 React 项目中安装：
 
 ```sh
-npm install --save-exact @linhey/rhine-design@0.6.0
+npm install --save-exact @linhey/rhine-design@0.8.0
 ```
 
 包与版本信息见 [npm](https://www.npmjs.com/package/@linhey/rhine-design)。如需使用未发版的源码，可安装 `git+https://github.com/linhay/rhine-design.git#<commit>`；建议固定版本并提交 lockfile。
@@ -79,6 +83,10 @@ export function Welcome() {
 
 OrbitBackdrop 承接授权移交的轨道动画，保留环节点、曲线、箭头、光晕与透视，并提供暂停、减少动态和离屏停帧。它是纯装饰，不表示加载或业务进度。契约与接入见[轨道背景](docs/ORBIT_BACKDROP.md)，真实展台见[轨道星空](https://linhay.github.io/rhine-design/#orbit)。
 
+### 中子星背景（0.8.0）
+
+NeutronStarBackdrop 承接另一套独立的中子星艺术，使用按需加载的 Three.js 绘制；内置暂停、减少动态、离屏停帧与静态降级。主题切换不重播，正文与控件不模糊。最小接入、生命周期及版本边界见[中子星契约](docs/NEUTRON_STAR_BACKDROP.md)，源码展台入口为 `/#neutron-star`。不要用轨道组件替换中子星的原视觉配方。
+
 ### 一键切换主题（0.4.0）
 
 展台右上角可切换并记忆主题。新增 **橙趣 · 粗描边**：浅灰蓝点阵背景、米白圆角卡片、黑色粗边、向右下偏移的硬阴影与亮橙主按钮。打开 [在线订阅管理示例](https://linhay.github.io/rhine-design/?theme=neo-brutalism#subscriptions)，体验卡片详情、管理菜单与演示表单；本地开发访问 `http://127.0.0.1:18309/?theme=neo-brutalism#subscriptions`。
@@ -123,15 +131,15 @@ export function App() {
 | 类别 | 组件 |
 | --- | --- |
 | 品牌与文字 | Logo · Text |
-| 操作 | Button · Icon · IconButton · Link · CopyButton |
-| 布局与背景 | Surface · Toolbar · Divider · Stack · Inline · Grid · Background² · AppShell² · OrbitBackdrop³ |
+| 操作 | Button · ButtonLink⁴ · Icon · IconButton · Link · CopyButton |
+| 布局与背景 | Surface · Toolbar · Divider · Stack · Inline · Grid · Background² · AppShell² · AppShellToggle⁴ · OrbitBackdrop³ · NeutronStarBackdrop⁴ |
 | 表单与选择 | TextField · Fieldset¹ · ErrorSummary¹ · Textarea · Select · Checkbox · RadioGroup · Switch · SearchField · Combobox · SelectionCard · DateField² · DateRangePicker² · NumberField² · TreeSelect² · RemoteMultiSelect² |
 | 导航与展开 | SideNav¹ · Breadcrumbs¹ · Steps¹ · Tabs · SegmentedControl · Disclosure |
-| 数据与媒体 | Metric · KeyValue · DataTable · Pagination · StatusTimeline¹ · TimelineLegend¹ · TrendChart² · StackedBar² · MediaCard² · MediaViewer² |
+| 数据与媒体 | Metric · KeyValue · DataTable · Pagination · StatusTimeline¹ · StatusTimelineList⁴ · TimelineLegend¹ · TrendChart² · StackedBar² · MediaCard² · MediaViewer² |
 | 浮层 | Drawer¹ · Dialog · ConfirmDialog · Popover · Menu · Tooltip |
 | 状态与反馈 | Badge · Notice · Toast · Progress · Skeleton · EmptyState |
 
-¹ 自 0.4.0 提供。² 自 0.5.0 提供。³ 自 0.6.0 提供。
+¹ 自 0.4.0 提供。² 自 0.5.0 提供。³ 自 0.6.0 提供。⁴ 自 0.8.0 提供。
 
 参数、状态和组合示例见[组件 API](components/README.md)与[常用组件契约](components/COMMON_COMPONENTS.md)。
 
@@ -150,7 +158,10 @@ export function App() {
 | 动效、交互与减少动态 | [Motion](components/MOTION.md) | [动效实验室](https://linhay.github.io/rhine-design/#motion) |
 | 启动动画与就绪衔接 | [Startup](components/STARTUP.md) | [启动动画](https://linhay.github.io/rhine-design/#startup) |
 | 轨道装饰、暂停与静态降级 | [OrbitBackdrop](docs/ORBIT_BACKDROP.md) | [轨道星空](https://linhay.github.io/rhine-design/#orbit) |
+| 中子星艺术、主题与 WebGL 生命周期 | [NeutronStarBackdrop（0.8.0）](docs/NEUTRON_STAR_BACKDROP.md) | [中子星展台](https://linhay.github.io/rhine-design/#neutron-star) |
 | 场景与交互选型 | [使用规范](docs/INTERACTION_PATTERNS.md) | [场景指南](https://linhay.github.io/rhine-design/#patterns) |
+| 日期快捷项、范围草稿与确认 | [日期筛选组合](docs/DATE_RANGE_FILTER.md) | [日期筛选](https://linhay.github.io/rhine-design/#date-range-filter) |
+| 无框摘要、一行图例与凭证操作消融 | [紧凑组合](docs/COMPACT_ACCOUNT_PATTERNS.md) | [紧凑账号](https://linhay.github.io/rhine-design/#compact-account) |
 | 导航与表单流程 | [组件契约](docs/INTERACTION_PATTERNS.md#新组件契约) | [导航](https://linhay.github.io/rhine-design/#navigation) · [表单](https://linhay.github.io/rhine-design/#form-workflow) |
 | 系统覆盖与演进方向 | [组件系统对照](docs/DESIGN_SYSTEM_AUDIT.md) | — |
 

package/components/Actions.tsx

@@ -1,7 +1,8 @@
 import { forwardRef, useEffect, useRef, useState, type AnchorHTMLAttributes, type ButtonHTMLAttributes } from 'react';
-import { Button } from './components';
+import { Button, type ButtonProps } from './components';
 
 const paths = {
+  menu: 'M3 5h14M3 10h14M3 15h14',
   close: 'm5 5 10 10M15 5 5 15',
   chevronDown: 'm5 8 5 5 5-5',
   chevronLeft: 'm12 5-5 5 5 5',
@@ -26,6 +27,22 @@ export const IconButton = forwardRef<HTMLButtonElement, ButtonHTMLAttributes<HTM
 export function Link({ children, className = '', target, rel, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }) {
   return <a {...props} target={target} rel={target === '_blank' ? `${rel || ''} noopener noreferrer`.trim() : rel} className={`rhine-link ${className}`}>{children}{target === '_blank' && <><Icon name="external" size={16} /><span className="rhine-sr-only">（新窗口打开）</span></>}</a>;
 }
+export interface ButtonLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement>, Pick<ButtonProps, 'variant' | 'busy' | 'busyLabel'> {
+  href: string;
+  disabled?: boolean;
+}
+export const ButtonLink = forwardRef<HTMLAnchorElement, ButtonLinkProps>(function ButtonLink({ href, variant = 'primary', busy = false, busyLabel = '处理中', disabled = false, className = '', children, tabIndex, onClick, onAuxClick, ...props }, ref) {
+  const unavailable = disabled || busy;
+  // Removing href also prevents context-menu and modified-click navigation while unavailable.
+  return <a {...props} ref={ref} href={unavailable ? undefined : href} role="link"
+    tabIndex={disabled ? -1 : tabIndex ?? (busy ? 0 : undefined)} aria-disabled={unavailable || undefined}
+    aria-busy={busy || undefined} data-disabled={disabled || undefined} className={`rhine-button rhine-button--${variant} rhine-button-link ${className}`}
+    onClick={event => { if (unavailable) { event.preventDefault(); event.stopPropagation(); return; } onClick?.(event); }}
+    onAuxClick={event => { if (unavailable) { event.preventDefault(); event.stopPropagation(); return; } onAuxClick?.(event); }}>
+    <span className={busy ? 'rhine-button__ghost' : undefined} aria-hidden={busy || undefined}>{children}</span>
+    {busy && <span className="rhine-button__busy"><span className="rhine-spinner" aria-hidden="true" /><span className="rhine-sr-only">{busyLabel}</span></span>}
+  </a>;
+});
 export function CopyButton({ value, label = '复制', copy = text => navigator.clipboard.writeText(text) }: { value: string; label?: string; copy?: (value: string) => Promise<void> }) {
   const [status, setStatus] = useState<'idle' | 'busy' | 'success' | 'error'>('idle');
   const pending = useRef(false);

package/components/AdvancedForms.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useLayoutEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { useEffect, useId, useLayoutEffect, useRef, useState, type KeyboardEvent, type SyntheticEvent } from 'react';
 import { Button, TextField, type Choice } from './components';
 import { Combobox } from './Forms';
 
@@ -23,9 +23,31 @@ function useDateValidation(error: string | undefined, onValidationChange?: (erro
 }
 /** Date-only ISO strings: conversion to timestamps and time zones belongs to the host. */
 export function DateField({ onValueChange, onValidationChange, error, ...props }: DateFieldProps) {
-  const invalid = error || dateError(props.value, props.min, props.max);
+  const [editing, setEditing] = useState({ accepted: props.value, draft: props.value, badInput: false });
+  const lastEvent = useRef<Event | null>(null);
+  const nativeBadInput = useRef(false);
+  let current = editing;
+  if (editing.accepted !== props.value) {
+    current = { accepted: props.value, draft: props.value, badInput: false };
+    nativeBadInput.current = false;
+    setEditing(current);
+  }
+  const invalid = error || (current.badInput ? '请填写完整有效的日期。' : dateError(current.draft, props.min, props.max));
   useDateValidation(invalid, onValidationChange);
-  return <TextField {...props} error={invalid} type="date" onChange={event => { if (!props.disabled && !props.readOnly) onValueChange(event.target.value); }} />;
+  const change = (event: SyntheticEvent<HTMLInputElement>) => {
+    if (props.disabled || props.readOnly || lastEvent.current === event.nativeEvent) return;
+    lastEvent.current = event.nativeEvent;
+    const { value, validity } = event.currentTarget;
+    nativeBadInput.current = validity.badInput;
+    // Native date fragments also expose an empty value; they are not a cleared boundary.
+    // Only incomplete native fragments are local drafts. Valid values remain
+    // controlled by the host, which may reject a proposed change.
+    setEditing({ accepted: props.value, draft: validity.badInput ? value : props.value, badInput: validity.badInput });
+    if (!validity.badInput) onValueChange(value);
+  };
+  // Chromium can change an empty calendar fragment without firing input/change.
+  const checkFragments = (event: SyntheticEvent<HTMLInputElement>) => { if (event.currentTarget.validity.badInput !== nativeBadInput.current) change(event); };
+  return <TextField {...props} value={current.draft} error={invalid} type="date" onInput={change} onChange={change} onKeyUp={checkFragments} onBlur={checkFragments} />;
 }
 export interface DateRange { start: string; end: string }
 export interface DateRangePickerProps {
@@ -38,16 +60,24 @@ export interface DateRangePickerProps {
 }
 export function DateRangePicker({ label, value, onValueChange, min, max, disabled, error, presets = [], readOnly = false, required, clearable = true, hint, startLabel = '开始日期', endLabel = '结束日期', startName, endName, onValidationChange }: DateRangePickerProps) {
   const id = useId();
+  const [fieldErrors, setFieldErrors] = useState<{ start: string | null; end: string | null }>({ start: null, end: null });
+  const [resetRevision, setResetRevision] = useState(0);
   const rangeError = (range: DateRange) => dateError(range.start, min, max) || dateError(range.end, min, max) || (range.start && range.end && range.start > range.end ? '结束日期不能早于开始日期。' : undefined);
-  const invalid = error || rangeError(value);
+  const invalid = error || rangeError(value) || fieldErrors.start || fieldErrors.end || undefined;
   useDateValidation(invalid, onValidationChange);
+  const fieldValidation = (field: 'start' | 'end', message: string | null) => setFieldErrors(current => current[field] === message ? current : { ...current, [field]: message });
+  const replace = (next: DateRange) => {
+    setFieldErrors({ start: null, end: null });
+    setResetRevision(revision => revision + 1);
+    onValueChange(next);
+  };
   return <fieldset className="rhine-date-range" disabled={disabled} aria-describedby={[hint && `${id}-hint`, invalid && id].filter(Boolean).join(' ') || undefined}>
     <legend>{label}</legend><div className="rhine-date-range__fields">
-      <DateField label={startLabel} name={startName} value={value.start} min={min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={start => onValueChange({ ...value, start })} error={invalid ? '请检查日期范围' : undefined} />
-      <DateField label={endLabel} name={endName} value={value.end} min={value.start && (!min || value.start > min) ? value.start : min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={end => onValueChange({ ...value, end })} />
+      <DateField key={`start-${resetRevision}`} label={startLabel} name={startName} value={value.start} min={min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={start => onValueChange({ ...value, start })} onValidationChange={message => fieldValidation('start', message)} />
+      <DateField key={`end-${resetRevision}`} label={endLabel} name={endName} value={value.end} min={value.start && (!min || value.start > min) ? value.start : min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={end => onValueChange({ ...value, end })} onValidationChange={message => fieldValidation('end', message)} />
     </div><div className="rhine-inline">
-      {presets.map(preset => <Button key={preset.label} variant="secondary" disabled={disabled || readOnly || !!rangeError(preset.value) || !!(required && (!preset.value.start || !preset.value.end))} onClick={() => onValueChange(preset.value)}>{preset.label}</Button>)}
-      {clearable && <Button variant="quiet" disabled={disabled || readOnly || (!value.start && !value.end)} onClick={() => onValueChange({ start: '', end: '' })}>清空日期</Button>}
+      {presets.map(preset => <Button key={preset.label} variant="secondary" disabled={disabled || readOnly || !!rangeError(preset.value) || !!(required && (!preset.value.start || !preset.value.end))} onClick={() => replace(preset.value)}>{preset.label}</Button>)}
+      {clearable && <Button variant="quiet" disabled={disabled || readOnly || (!value.start && !value.end && !fieldErrors.start && !fieldErrors.end)} onClick={() => replace({ start: '', end: '' })}>清空日期</Button>}
     </div>{hint && <p id={`${id}-hint`} className="rhine-field__hint">{hint}</p>}{invalid && <p id={id} role="alert" className="rhine-field__error">{invalid}</p>}
   </fieldset>;
 }

package/components/AppShell.tsx

@@ -1,5 +1,6 @@
-import { useId, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { createContext, useContext, useId, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
 import { Button } from './components';
+import { IconButton } from './Actions';
 import { Drawer } from './Overlays';
 import { Background, type BackgroundDecoration } from './Background';
 
@@ -11,22 +12,43 @@ export interface ShellPanel {
 export interface AppShellProps {
   layout: 'single' | 'double-left' | 'left-right';
   navigation: ShellPanel; secondary?: ShellPanel;
-  header?: ReactNode; children: ReactNode; label?: string; decoration?: BackgroundDecoration;
+  header?: ReactNode; contentHeader?: ReactNode; children: ReactNode; label?: string; decoration?: BackgroundDecoration;
   className?: string; style?: CSSProperties;
+  controls?: 'header' | 'inline';
 }
 
-function Panel({ panel, overlay, side, id, drawerOpen, setDrawerOpen }: { panel: ShellPanel; overlay: boolean; side: 'left' | 'right'; id: string; drawerOpen: boolean; setDrawerOpen: (open: boolean) => void }) {
+interface PanelControl { panel: ShellPanel; overlay: boolean; side: 'left' | 'right'; id: string; drawerOpen: boolean; setDrawerOpen: (open: boolean) => void }
+const ShellControls = createContext<{ navigation: PanelControl; secondary?: PanelControl } | null>(null);
+export interface AppShellToggleProps { panel?: 'navigation' | 'secondary'; placement: 'panel' | 'content'; iconOnly?: boolean }
+
+export function AppShellToggle({ panel = 'navigation', placement, iconOnly = false }: AppShellToggleProps) {
+  const controls = useContext(ShellControls);
+  const control = controls?.[panel];
+  if (!control) return null;
+  const expanded = !control.overlay && !control.drawerOpen && control.panel.open;
+  if (placement === 'content') return <Panel {...control} hidden={expanded} iconOnly={iconOnly} />;
+  if (!expanded) return null;
+  const label = `收起${control.panel.label}`;
+  const props = { id: `${control.id}-collapse`, 'aria-controls': control.id, 'aria-expanded': true, onClick: () => control.panel.onOpenChange(false) };
+  return iconOnly ? <IconButton {...props} icon="chevronLeft" label={label} title={label} /> : <Button {...props} variant="secondary">{label}</Button>;
+}
+
+function Panel({ panel, overlay, side, id, drawerOpen, setDrawerOpen, hidden = false, iconOnly = false }: PanelControl & { hidden?: boolean; iconOnly?: boolean }) {
   const floating = overlay || drawerOpen;
-  return <div className="rhine-shell__panel-control">
+  const label = `${floating ? '' : panel.open ? '收起' : '展开'}${panel.label}`;
+  const props = { id: `${id}-toggle`, hidden, 'aria-controls': floating ? undefined : id, 'aria-expanded': floating ? drawerOpen : panel.open,
+    onClick: (event: React.MouseEvent<HTMLButtonElement>) => { if (!floating) { event.preventDefault(); panel.onOpenChange(!panel.open); } } };
+  return <div className="rhine-shell__panel-control" hidden={hidden}>
     <Drawer title={panel.label} description="关闭后返回当前任务。" side={side} open={drawerOpen} onOpenChange={setDrawerOpen}
-      trigger={<Button id={`${id}-toggle`} variant="secondary" aria-controls={floating ? undefined : id} aria-expanded={floating ? drawerOpen : panel.open}
-        onClick={event => { if (!floating) { event.preventDefault(); panel.onOpenChange(!panel.open); } }}>{floating ? '' : panel.open ? '收起' : '展开'}{panel.label}</Button>}>{panel.content}</Drawer>
+      onCloseAutoFocus={event => { if (document.getElementById(`${id}-toggle`)?.hidden) { event.preventDefault(); document.getElementById(`${id}-collapse`)?.focus(); } }}
+      trigger={iconOnly ? <IconButton {...props} icon={floating && side === 'left' ? 'menu' : 'chevronRight'} label={label} title={label} /> : <Button {...props} variant="secondary">{label}</Button>}>{panel.content}</Drawer>
   </div>;
 }
 
-export function AppShell({ layout, navigation, secondary, header, children, label = '应用工作区', decoration = 'auto', className = '', style }: AppShellProps) {
+export function AppShell({ layout, navigation, secondary, header, contentHeader, children, label = '应用工作区', decoration = 'auto', className = '', style, controls = 'header' }: AppShellProps) {
   const ref = useRef<HTMLDivElement>(null);
   const focusedPanel = useRef<'nav' | 'secondary' | null>(null);
+  const focusedToggle = useRef<string | null>(null);
   const [width, setWidth] = useState(0);
   const [localNavigationDrawer, setLocalNavigationDrawer] = useState(navigation.defaultDrawerOpen ?? false), [localSecondaryDrawer, setLocalSecondaryDrawer] = useState(secondary?.defaultDrawerOpen ?? false);
   const navigationDrawer = navigation.drawerOpen ?? localNavigationDrawer, secondaryDrawer = secondary?.drawerOpen ?? localSecondaryDrawer;
@@ -45,6 +67,11 @@ export function AppShell({ layout, navigation, secondary, header, children, labe
   const navOverlay = width < (navigation.breakpoint ?? 760), secondaryOverlay = width < (secondary?.breakpoint ?? 1120);
   const hasSecondary = layout !== 'single' && !!secondary;
   useLayoutEffect(() => {
+    // Inline restore controls disappear after expansion; keep keyboard focus reachable.
+    if (controls === 'inline') for (const suffix of ['nav', 'secondary']) {
+      const toggle = document.getElementById(`${id}-${suffix}-toggle`);
+      if (toggle?.hidden && focusedToggle.current === toggle.id && (document.activeElement === toggle || document.activeElement === document.body)) document.getElementById(`${id}-${suffix}-collapse`)?.focus();
+    }
     const suffix = focusedPanel.current;
     if (suffix) {
       const pane = document.getElementById(`${id}-${suffix}`);
@@ -53,19 +80,21 @@ export function AppShell({ layout, navigation, secondary, header, children, labe
         focusedPanel.current = null;
       }
     }
-  }, [id, navOverlay, secondaryOverlay, hasSecondary, navigation.open, secondary?.open]);
-  return <div className={`rhine-shell ${className}`} style={style} ref={ref} role="region" aria-label={label} data-layout={layout}
-    onFocusCapture={event => { focusedPanel.current = document.getElementById(`${id}-nav`)?.contains(event.target) ? 'nav' : document.getElementById(`${id}-secondary`)?.contains(event.target) ? 'secondary' : null; }}
-    onBlurCapture={event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget)) focusedPanel.current = null; }}>
-    <header className="rhine-shell__header">
-      <Panel panel={navigation} overlay={navOverlay} side="left" id={`${id}-nav`} drawerOpen={navigationDrawer} setDrawerOpen={setNavigationDrawer} />
-      {hasSecondary && <Panel panel={secondary} overlay={secondaryOverlay} side={layout === 'left-right' ? 'right' : 'left'} id={`${id}-secondary`} drawerOpen={secondaryDrawer} setDrawerOpen={setSecondaryDrawer} />}
+  }, [id, controls, navOverlay, secondaryOverlay, hasSecondary, navigation.open, secondary?.open, navigationDrawer, secondaryDrawer]);
+  const navigationControl: PanelControl = { panel: navigation, overlay: navOverlay, side: 'left', id: `${id}-nav`, drawerOpen: navigationDrawer, setDrawerOpen: setNavigationDrawer };
+  const secondaryControl: PanelControl | undefined = hasSecondary ? { panel: secondary, overlay: secondaryOverlay, side: layout === 'left-right' ? 'right' : 'left', id: `${id}-secondary`, drawerOpen: secondaryDrawer, setDrawerOpen: setSecondaryDrawer } : undefined;
+  return <ShellControls.Provider value={{ navigation: navigationControl, secondary: secondaryControl }}><div className={`rhine-shell ${className}`} style={style} ref={ref} role="region" aria-label={label} data-layout={layout}
+    onFocusCapture={event => { focusedToggle.current = event.target.id.endsWith('-toggle') ? event.target.id : null; focusedPanel.current = document.getElementById(`${id}-nav`)?.contains(event.target) ? 'nav' : document.getElementById(`${id}-secondary`)?.contains(event.target) ? 'secondary' : null; }}
+    onBlurCapture={event => { if (event.relatedTarget && event.relatedTarget !== document.body && !event.currentTarget.contains(event.relatedTarget)) { focusedPanel.current = null; focusedToggle.current = null; } }}>
+    {(controls === 'header' || header) && <header className="rhine-shell__header">
+      {controls === 'header' && <><Panel {...navigationControl} />{secondaryControl && <Panel {...secondaryControl} />}</>}
       {header}
-    </header>
+    </header>}
     <div className="rhine-shell__body">
       <aside id={`${id}-nav`} className="rhine-shell__nav" style={{ flexBasis: navigation.width }} aria-label={navigation.label} hidden={navOverlay || navigationDrawer || !navigation.open}>{!navigationDrawer && navigation.content}</aside>
       <aside id={`${id}-secondary`} className="rhine-shell__secondary" style={{ flexBasis: secondary?.width }} aria-label={secondary?.label} hidden={!hasSecondary || secondaryOverlay || secondaryDrawer || !secondary?.open}>{hasSecondary && !secondaryDrawer && secondary?.content}</aside>
-      <Background className="rhine-shell__content" decoration={decoration} tabIndex={0} role="region" aria-label="正文">{children}</Background>
+      <div className="rhine-shell__main">{contentHeader != null && <header className="rhine-shell__content-header">{contentHeader}</header>}
+      <Background className="rhine-shell__content" decoration={decoration} tabIndex={0} role="region" aria-label="正文">{children}</Background></div>
     </div>
-  </div>;
+  </div></ShellControls.Provider>;
 }

package/components/ListFilterBar.tsx

@@ -0,0 +1,104 @@
+import { useRef, useState, type InputHTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { Button, Notice, Surface, TextField } from './components';
+import { Drawer } from './Overlays';
+import './list-filter-bar.css';
+
+export interface ListFilterField {
+  id: string;
+  label: string;
+  control: ReactNode;
+  activeLabel?: string;
+  onClear?: () => void;
+}
+
+export interface ListFilterBarProps {
+  label: string;
+  search?: InputHTMLAttributes<HTMLInputElement> & { label: string };
+  primary?: readonly ListFilterField[];
+  filters?: readonly ListFilterField[];
+  onReset?: () => void;
+  refresh?: { onClick: () => void; busy?: boolean; disabled?: boolean };
+  action?: ReactElement;
+  result?: ReactNode;
+  pending?: boolean;
+  error?: string;
+  className?: string;
+}
+
+function Feedback({ result, pending, error, announce = true }: Pick<ListFilterBarProps, 'result' | 'pending' | 'error'> & { announce?: boolean }) {
+  return <>
+    {(result != null || pending) && <div className="rhine-list-filter-bar__feedback" role="status" aria-live={announce ? 'polite' : 'off'}>
+      {pending && <span>正在更新结果…</span>}
+      {result != null && <div>{result}</div>}
+    </div>}
+    {error && <Notice tone="error" title="未能更新结果">{error}</Notice>}
+  </>;
+}
+
+const focusable = 'input:not(:disabled):not([type="hidden"]), select:not(:disabled), textarea:not(:disabled), button:not(:disabled), a[href]';
+
+export function ListFilterBar({ label, search, primary = [], filters = [], onReset, refresh, action, result, pending = false, error, className = '' }: ListFilterBarProps) {
+  const [open, setOpen] = useState(false);
+  const root = useRef<HTMLDivElement>(null);
+  const drawerBody = useRef<HTMLDivElement>(null);
+  const visibleFields = primary.slice(0, 2);
+  const drawerFields = [...primary.slice(2), ...filters];
+  const activeFields = [...primary, ...filters].filter(field => field.activeLabel?.trim());
+  const activeDrawerCount = activeFields.filter(field => drawerFields.some(item => item.id === field.id)).length;
+  const hasQuery = search?.value != null && String(search.value).trim() !== '';
+  const canReset = Boolean(onReset && (activeFields.length > 0 || hasQuery));
+
+  function stableFocus() {
+    const scope = open ? drawerBody.current : root.current?.querySelector('.rhine-list-filter-bar__main');
+    const target = scope?.querySelector<HTMLElement>(focusable);
+    (target ?? root.current)?.focus();
+  }
+
+  function reset() {
+    stableFocus();
+    onReset?.();
+  }
+
+  function clear(field: ListFilterField) {
+    // A removed chip must not leave keyboard focus on the document body.
+    const control = Array.from(root.current?.querySelectorAll<HTMLElement>('[data-filter-id]') ?? [])
+      .find(node => node.dataset.filterId === field.id)?.querySelector<HTMLElement>(focusable);
+    if (control) control.focus(); else stableFocus();
+    field.onClear?.();
+  }
+
+  return <div ref={root} tabIndex={-1} className={`rhine-list-filter-bar ${className}`}>
+    <Surface role="group" aria-label={label} className="rhine-list-filter-bar__surface">
+      <div className="rhine-list-filter-bar__main">
+        {search && <div className="rhine-list-filter-bar__search"><TextField type="search" {...search} /></div>}
+        {visibleFields.length > 0 && <div className="rhine-list-filter-bar__primary">
+          {visibleFields.map(field => <div key={field.id} data-filter-id={field.id} className="rhine-list-filter-bar__field" role="group" aria-label={field.label}>{field.control}</div>)}
+        </div>}
+        {(drawerFields.length > 0 || refresh || action) && <div className="rhine-list-filter-bar__actions">
+          {drawerFields.length > 0 && <Drawer
+            title={label}
+            description="更改后立即更新结果。"
+            open={open}
+            onOpenChange={setOpen}
+            trigger={<Button variant="secondary" aria-label={activeDrawerCount > 0 ? `更多筛选，已选 ${activeDrawerCount} 项` : undefined}>更多筛选{activeDrawerCount > 0 && <span className="rhine-list-filter-bar__count" aria-hidden="true">{activeDrawerCount}</span>}</Button>}
+          >
+            <div ref={drawerBody} className="rhine-list-filter-bar__drawer">
+              <Feedback result={result} pending={pending} error={error} />
+              {drawerFields.map(field => <div key={field.id} data-filter-id={field.id} className="rhine-list-filter-bar__field" role="group" aria-label={field.label}>{field.control}</div>)}
+              {canReset && <div className="rhine-list-filter-bar__drawer-actions"><Button variant="quiet" onClick={reset}>重置筛选</Button></div>}
+            </div>
+          </Drawer>}
+          {refresh && <Button variant="secondary" onClick={refresh.onClick} busy={refresh.busy} disabled={refresh.disabled} busyLabel="正在刷新">刷新</Button>}
+          {action && <div className="rhine-list-filter-bar__action">{action}</div>}
+        </div>}
+      </div>
+      {(activeFields.length > 0 || canReset) && <div className="rhine-list-filter-bar__active" role="group" aria-label="已选条件">
+        {activeFields.map(field => field.onClear
+          ? <Button key={field.id} variant="quiet" className="rhine-list-filter-bar__chip" onClick={() => clear(field)} aria-label={`清除${field.label}：${field.activeLabel}`}><span>{field.label}：{field.activeLabel}</span><span aria-hidden="true">×</span></Button>
+          : <span key={field.id} className="rhine-list-filter-bar__summary">{field.label}：{field.activeLabel}</span>)}
+        {canReset && <Button variant="quiet" onClick={reset}>重置筛选</Button>}
+      </div>}
+      <Feedback result={result} pending={pending} error={error} announce={!open} />
+    </Surface>
+  </div>;
+}

package/components/Media.tsx

@@ -11,17 +11,17 @@ export interface MediaCardProps extends Omit<ComponentPropsWithRef<'article'>, '
 }
 export function MediaCard({ title, date, kind, preview, state = preview != null && preview !== false ? 'ready' : 'empty', aspectRatio = '4 / 3', onOpen, selected = false, onSelectedChange, disabled, actions, className = '', ...props }: MediaCardProps) {
   const statusId = useId();
-  return <article {...props} className={`rhine-media-card ${className}`} data-selected={selected}>
+  return <article {...props} className={`rhine-media-card ${className}`} data-selected={selected} data-state={state} data-disabled={disabled || undefined}>
     <button type="button" className="rhine-media-card__open" onClick={event => { event.currentTarget.focus({ preventScroll: true }); onOpen(); }} disabled={disabled} aria-label={`打开${title}`} aria-describedby={statusId}>
       <span className="rhine-media-card__preview" style={{ aspectRatio }} aria-busy={state === 'loading'}>
         {(state === 'ready' || state === 'loading') && <span className="rhine-media-card__asset" hidden={state === 'loading'}>{preview}</span>}
-        {state !== 'ready' && <span>{state === 'loading' ? '正在加载预览…' : state === 'error' ? '预览无法解码' : '暂无预览'}</span>}
+        {state !== 'ready' && <span className="rhine-media-card__status"><span aria-hidden="true" className="rhine-media-card__status-mark">{state === 'error' ? '!' : state === 'loading' ? '···' : '—'}</span><span>{state === 'loading' ? '正在加载预览…' : state === 'error' ? '预览无法解码' : '暂无预览'}</span></span>}
         <span className="rhine-media-card__kind">{kind === 'photo' ? '照片' : kind === 'video' ? '视频' : kind}</span>
       </span><span className="rhine-media-card__caption"><strong>{title}</strong><span>{date || '日期未知'}</span></span>
     </button>
     <span id={statusId} role="status" className="rhine-sr-only">{state === 'loading' ? `${title}：预览加载中` : state === 'error' ? `${title}：预览失败` : state === 'empty' ? `${title}：缺少预览` : ''}</span>
-    {onSelectedChange && <Checkbox label={`选择${title}`} checked={selected} disabled={disabled} onChange={event => onSelectedChange(event.target.checked)} />}
-    {actions != null && <div className="rhine-media-card__actions">{actions}</div>}
+    {(onSelectedChange || actions != null) && <div className="rhine-media-card__footer">{onSelectedChange && <Checkbox label={`选择${title}`} checked={selected} disabled={disabled} onChange={event => onSelectedChange(event.target.checked)} />}
+    {actions != null && <div className="rhine-media-card__actions">{actions}</div>}</div>}
   </article>;
 }
 
@@ -70,9 +70,9 @@ export function MediaViewer({ trigger, title, description, children, open, defau
           if (event.key === 'ArrowRight' && nextEnabled) { event.preventDefault(); onNext?.(); }
         }}>
         <header className="rhine-media-viewer__header"><div><DialogBase.Title>{title}</DialogBase.Title><DialogBase.Description>{description}</DialogBase.Description></div>
-          <div className="rhine-media-viewer__actions"><button ref={previousRef} type="button" disabled={!previousEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowLeft' : undefined} onClick={onPrevious}>上一项</button><button ref={nextRef} type="button" disabled={!nextEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowRight' : undefined} onClick={onNext}>下一项</button>
-            {hasMetadata && <button type="button" aria-controls={metadataId} aria-expanded={showMetadata} onClick={changeMetadata}>{showMetadata ? '收起信息' : '显示信息'}</button>}
-            {actions}<DialogBase.Close asChild><button type="button" aria-label="关闭媒体查看器">关闭</button></DialogBase.Close>
+          <div className="rhine-media-viewer__actions"><button className="rhine-button rhine-button--secondary" ref={previousRef} type="button" disabled={!previousEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowLeft' : undefined} onClick={onPrevious}>上一项</button><button className="rhine-button rhine-button--secondary" ref={nextRef} type="button" disabled={!nextEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowRight' : undefined} onClick={onNext}>下一项</button>
+            {hasMetadata && <button className="rhine-button rhine-button--secondary" type="button" aria-controls={metadataId} aria-expanded={showMetadata} onClick={changeMetadata}>{showMetadata ? '收起信息' : '显示信息'}</button>}
+            {actions}<DialogBase.Close asChild><button className="rhine-button rhine-button--primary" type="button" aria-label="关闭媒体查看器">关闭</button></DialogBase.Close>
           </div>
         </header>
         <div className="rhine-media-viewer__body"><div className="rhine-media-viewer__canvas">{children}</div>{hasMetadata && <aside id={metadataId} hidden={!showMetadata} className="rhine-media-viewer__metadata" aria-label="媒体信息">{metadata}</aside>}</div>

package/components/NeutronStarBackdrop.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useRef, useState, type HTMLAttributes } from 'react';
+import { Button } from './components';
+import type { NeutronRenderer, NeutronState } from './neutronRenderer';
+
+export interface NeutronStarBackdropProps extends HTMLAttributes<HTMLDivElement> {
+  /** Adds a static preference; false never overrides the system or an ancestor. */
+  reducedMotion?: boolean;
+  /** Theme follows the host palette; original preserves the initial deep-space artwork. */
+  appearance?: 'theme' | 'original';
+}
+
+export function NeutronStarBackdrop({ reducedMotion = false, appearance = 'theme', children, className = '', ...props }: NeutronStarBackdropProps) {
+  const art = useRef<HTMLDivElement>(null);
+  const renderer = useRef<NeutronRenderer | null>(null);
+  const options = useRef({ paused: false, reducedMotion, appearance });
+  const [paused, setPaused] = useState(false);
+  const [state, setState] = useState<NeutronState>('loading');
+  options.current = { paused, reducedMotion, appearance };
+
+  useEffect(() => {
+    let disposed = false;
+    if (!window.WebGL2RenderingContext) { setState('unavailable'); return; }
+    // The heavy renderer is loaded only for a mounted, WebGL-capable artwork.
+    import('./neutronRenderer').then(({ mountNeutron }) => {
+      if (disposed) return;
+      renderer.current = mountNeutron(art.current!, setState, options.current);
+    }).catch(() => { if (!disposed) setState('unavailable'); });
+    return () => { disposed = true; renderer.current?.dispose(); renderer.current = null; };
+  }, []);
+  useEffect(() => { renderer.current?.setPaused(paused); }, [paused]);
+  useEffect(() => { renderer.current?.setReducedMotion(reducedMotion); }, [reducedMotion]);
+  useEffect(() => { renderer.current?.setAppearance(appearance); }, [appearance]);
+
+  const canControl = state === 'playing' || state === 'paused';
+  const label = state === 'reduced' ? '已减少动态' : canControl ? paused ? '继续动效' : '暂停动效' : '静态画面';
+  return <div {...props} className={`rhine-neutron ${className}`} data-rhine-neutron-state={state} data-rhine-neutron-appearance={appearance}>
+    <div ref={art} className="rhine-neutron-art" aria-hidden="true">
+      <span className="rhine-neutron-fallback"><i /><b /></span>
+    </div>
+    <div className="rhine-neutron-content">{children}</div>
+    <div className="rhine-neutron-controls"><Button variant="secondary" disabled={!canControl} onClick={() => setPaused(value => !value)}>{label}</Button></div>
+  </div>;
+}

package/components/OrbitBackdrop.tsx

@@ -3,11 +3,19 @@ import { Button } from './components';
 import { mountOrbit, type OrbitRenderer, type OrbitState } from './orbitRenderer';
 
 export interface OrbitBackdropProps extends HTMLAttributes<HTMLDivElement> {
+  /** Follows the host theme by default; original preserves the initial dark artwork. */
+  appearance?: 'theme' | 'original';
   /** Adds a static preference; false never overrides the system or an ancestor. */
   reducedMotion?: boolean;
+  /** Omits the local pause control without changing motion preferences. */
+  controls?: boolean;
+  /** Reserves the upper content area by moving the artwork into the lower right. */
+  composition?: 'full' | 'corner';
+  /** Removes panel decoration when used as a page background. */
+  framed?: boolean;
 }
 
-export function OrbitBackdrop({ reducedMotion = false, children, className = '', ...props }: OrbitBackdropProps) {
+export function OrbitBackdrop({ appearance = 'theme', reducedMotion = false, controls = true, composition = 'full', framed = true, children, className = '', ...props }: OrbitBackdropProps) {
   const canvas = useRef<HTMLCanvasElement>(null);
   const renderer = useRef<OrbitRenderer | null>(null);
   const [paused, setPaused] = useState(false);
@@ -25,9 +33,9 @@ export function OrbitBackdrop({ reducedMotion = false, children, className = '',
   const label = state === 'reduced' ? '已减少动态' : state === 'compact' ? '窄屏静态画面'
     : canControl ? paused ? '继续动效' : '暂停动效' : '静态画面';
 
-  return <div {...props} className={`rhine-orbit ${className}`} data-rhine-orbit-state={state}>
+  return <div {...props} className={`rhine-orbit ${className}`} data-rhine-orbit-appearance={appearance} data-rhine-orbit-state={state} data-rhine-orbit-controls={controls} data-rhine-orbit-composition={composition} data-rhine-orbit-framed={framed}>
     <canvas ref={canvas} className="rhine-orbit-canvas" aria-hidden="true" />
     <div className="rhine-orbit-content">{children}</div>
-    <div className="rhine-orbit-controls"><Button variant="secondary" disabled={!canControl} onClick={() => setPaused(value => !value)}>{label}</Button></div>
+    {controls && <div className="rhine-orbit-controls"><Button variant="secondary" disabled={!canControl} onClick={() => setPaused(value => !value)}>{label}</Button></div>}
   </div>;
 }