@linhey/rhine-design 0.9.1 → 0.11.0

package/preview/SummaryTabsGallery.tsx

@@ -0,0 +1,37 @@
+import { useState } from 'react';
+import { Badge, KeyValue, Select, Stack, Surface, Tabs, Text, TextField, Toolbar } from '../components';
+
+export function SummaryTabsGallery() {
+  const [width, setWidth] = useState('520');
+  const [scenario, setScenario] = useState('normal');
+  const [selected, setSelected] = useState('primary');
+  const pending = scenario === 'loading', failed = scenario === 'error';
+  return <section id="summary-tabs"><Stack gap={6}>
+    <Toolbar title="带摘要的页签" description="名称与状态在同一组，身份摘要紧随；每个对象的状态始终可见。">
+      <Select label="局部容器宽度" value={width} onChange={event => setWidth(event.target.value)}>
+        <option value="320">320px · 窄容器</option><option value="520">520px · 标准</option><option value="100%">自适应</option>
+      </Select>
+      <Select label="摘要页签场景" value={scenario} onChange={event => {setScenario(event.target.value); if(event.target.value === 'disabled') setSelected('primary');}}>
+        <option value="normal">正常</option><option value="loading">读取中</option><option value="error">读取失败</option><option value="disabled">禁用</option><option value="long">长身份与名称</option>
+      </Select>
+    </Toolbar>
+    <Surface><Stack gap={6}>
+      <div style={{width: width === '100%' ? width : `${width}px`, maxWidth:'100%'}}>
+        <Tabs label="摘要页签规范示例" value={selected} onValueChange={setSelected} items={[
+          {value:'primary',label:scenario === 'long' ? '跨部门联合研究工作区' : '主工作区',description:pending ? '尚未读取当前身份' : scenario === 'long' ? '研究项目 · 跨区域联合研发与长期设计验证团队' : '研发 · 研究项目',
+            status:<Badge tone={failed ? 'error' : pending ? 'neutral' : 'success'}>{failed ? '读取失败' : pending ? '读取中' : '同步中'}</Badge>,
+            content:<Stack gap={4}><Text>主工作区内容</Text><TextField label="主工作区草稿" placeholder="切换后保留已输入内容"/></Stack>},
+          {value:'team',label:'协作工作区',description:'协作 · 设计项目',disabled:scenario === 'disabled',status:<Badge>{scenario === 'disabled' ? '暂不可用' : '已停止'}</Badge>,
+            content:<Stack gap={4}><Text>协作工作区内容</Text><TextField label="协作工作区草稿" placeholder="与另一页签独立"/></Stack>},
+        ]}/>
+      </div>
+      <Text variant="caption" tone="muted">先输入草稿，再使用左右方向键或 Home / End 切换。场景与主题变化不清空面板。</Text>
+    </Stack></Surface>
+    <Surface><Stack gap={4}><Text as="h2" variant="heading">尺寸与层级</Text><KeyValue items={[
+      {key:'title',label:'名称',value:'14 / 22 · 600'}, {key:'description',label:'身份摘要',value:'12 / 18 · 400'},
+      {key:'padding',label:'上下内距',value:'12px / 12px'}, {key:'status',label:'名称到状态',value:'8px'},
+      {key:'identity',label:'名称组到摘要',value:'4px'}, {key:'tabs',label:'页签之间',value:'16px'},
+      {key:'panel',label:'分隔线到面板',value:'24px'}, {key:'selected',label:'选中指示线',value:'2px，覆盖当前页签宽度'},
+    ]}/><Text variant="caption" tone="muted">状态复用 Badge，各主题保留自己的文字与边框；不固定总高度。</Text></Stack></Surface>
+  </Stack></section>;
+}

package/preview/main.tsx

@@ -1,7 +1,7 @@
 import { BackgroundFiltersFixture } from './BackgroundFiltersFixture';
 import { StrictMode, useEffect, useRef, useState } from 'react';
 import { createRoot } from 'react-dom/client';
-import { Badge, Button, Checkbox, Disclosure, EmptyState, Logo, Notice, Progress, SegmentedControl, Select, SelectionCard, Skeleton, Surface, Tabs, Text, TextField, Toolbar, type TextVariant } from '../components/index';
+import { Badge, Button, Checkbox, Disclosure, EmptyState, Link, Logo, Notice, Progress, SegmentedControl, Select, SelectionCard, Skeleton, Surface, Tabs, Text, TextField, Toolbar, type TextVariant } from '../components/index';
 import './preview.css';
 import { OverlayBoundsFixture, OverlayBoundsGallery } from './OverlayBoundsGallery';
 import { SettingsDialogGallery, SettingsDialogFixture } from './SettingsDialogGallery';
@@ -11,6 +11,7 @@ import { MotionGallery } from './MotionGallery';
 import { StartupGallery } from './StartupGallery';
 import { PatternGallery } from './PatternGallery';
 import { GalleryShell } from './GalleryShell';
+import { componentCount } from './packageInfo';
 import { SpacingGallery } from './SpacingGallery';
 import { LineHeightGallery } from './LineHeightGallery';
 import { SubscriptionGallery } from './SubscriptionGallery';
@@ -22,6 +23,11 @@ import { MonitoringGallery } from './MonitoringGallery';
 import { DateRangeFilterGallery } from './DateRangeFilterGallery';
 import { ListFilterBarGallery } from './ListFilterBarGallery';
 import { CompactAccountGallery } from './CompactAccountGallery';
+import { CompactFilterBarGallery } from './CompactFilterBarGallery';
+import { DenseFilterControlsGallery } from './DenseFilterControlsGallery';
+import { CheckboxRowGallery } from './CheckboxRowGallery';
+import { ComponentTypographyGallery } from './ComponentTypographyGallery';
+import { SummaryTabsGallery } from './SummaryTabsGallery';
 
 function Gallery() {
   const [motion, setMotion] = useState('system');
@@ -48,6 +54,10 @@ function Gallery() {
     {section === 'date-range-filter' && <DateRangeFilterGallery />}
     {section === 'list-filter-bar' && <ListFilterBarGallery />}
     {section === 'compact-account' && <CompactAccountGallery />}
+    {section === 'compact-filters' && <><CompactFilterBarGallery /><DenseFilterControlsGallery /></>}
+    {section === 'checkbox-rows' && <CheckboxRowGallery />}
+    {section === 'component-typography' && <ComponentTypographyGallery />}
+    {section === 'summary-tabs' && <SummaryTabsGallery />}
     {section === 'backgrounds' && <BackgroundGallery />}
     {section === 'app-shell' && <ShellGallery />}
     {section === 'orbit' && <OrbitGallery />}
@@ -57,7 +67,7 @@ function Gallery() {
     {section === 'media' && <MediaGallery />}
     {section === 'subscriptions' && <SubscriptionGallery />}
     {section === 'top' && <>
-      <div className="ds-hero"><div><p className="ds-kicker">FOUNDATIONS / COMPONENTS / MOTION</p><h1>精密，有序。<br /><span>每一次交互都有回应。</span></h1><p>60 个通用组件，共用一套视觉变量和动效规则。<br />这里运行的就是后续业务页面可直接导入的 React 组件。</p></div></div>
+      <div className="ds-hero"><div><p className="ds-kicker">FOUNDATIONS / COMPONENTS / MOTION</p><h1>精密，有序。<br /><span>每一次交互都有回应。</span></h1><p>{componentCount} 个通用组件，共用一套视觉变量和动效规则。<br />展台运行当前源码，可能包含未发布能力；接入前请核对安装版本与<Link href="https://github.com/linhay/rhine-design/blob/main/CHANGELOG.md">版本记录</Link>。</p></div></div>
       <div className="ds-overview-links">{[
         ['foundation','视觉基础','从色彩、间距与材质开始。'],
         ['typography','字体与文字','清晰的层级，稳定的阅读节奏。'],
@@ -118,6 +128,7 @@ function Gallery() {
         <div className="ds-grid"><div><Checkbox label="显示卡片勾选框" checked={showSelectionIndicator} onChange={event => setShowSelectionIndicator(event.target.checked)} /><SelectionCard showIndicator={showSelectionIndicator} label="可选择容器" selected={selected} onSelectedChange={setSelected}><span className="ds-caption">适用于账号、模板或可取消选择项。<br />同一位置切换底色与边框，不抬升卡片。</span><div className="ds-gap-top"><Badge tone={selected?'success':'neutral'}>{selected?'已选择':'未选择'}</Badge></div></SelectionCard><p className="ds-caption">SelectionCard · 背景与边界 120ms</p></div>
         <Surface><div className="ds-component-title"><h3>SegmentedControl</h3><span>原生单选 / 120ms</span></div><SegmentedControl label="展示指标" items={[{value:'tokens',label:'Token'},{value:'requests',label:'请求数'},{value:'cost',label:'费用',disabled:true}]} value={metric} onValueChange={setMetric} /><p className="ds-caption">当前指标：{metric==='tokens'?'Token':'请求数'}。方向键切换，自动跳过禁用项。</p></Surface></div>
         <Surface className="ds-gap-top"><div className="ds-component-title"><h3>Tabs</h3><span>下划线与内容进入 180ms</span></div><Tabs label="组件说明" value={tab} onValueChange={setTab} items={[{value:'tokens',label:'视觉变量',content:<p>颜色、间距、字体与动效集中定义。业务页面只消费语义变量。</p>},{value:'disabled',label:'预留示例',disabled:true,content:null},{value:'motion',label:'动效规则',content:<p>内容进入最多移动 3px。保留隐藏面板状态，切换不触发重复业务操作。</p>}]} /></Surface>
+        <Text className="ds-gap-top">需要同时展示对象身份和状态时，查看<a href="#summary-tabs">带摘要的页签规范与交互展台</a>。</Text>
       </section>}
 
       {section === 'feedback' && <section id="feedback"><div className="ds-section-title"><span>04</span><h2>告诉用户发生了什么</h2></div>
@@ -130,7 +141,7 @@ function Gallery() {
       </section>}
 
       {section === 'disclosure' && <section id="disclosure"><div className="ds-section-title"><span>05</span><h2>逐步展开，保持可读</h2></div>
-        <div className="ds-grid"><Surface><div className="ds-component-title"><h3>Disclosure</h3><span>实测高度 / 200ms</span></div><Disclosure title="查看组件动画规则"><p>展开和收起都支持中途反向。关闭后内容不参与 Tab 导航。</p><Button variant="secondary" onClick={()=>setNotice(true)}>内容内操作</Button><p>减少动态模式直接到达最终状态，信息不会丢失。</p></Disclosure></Surface>
+        <div className="ds-grid"><Surface><div className="ds-component-title"><h3>Disclosure</h3><span>实测高度 / 200ms</span></div><Disclosure title="查看组件动画规则"><p>展开和收起都支持中途反向。关闭后内容不参与 Tab 导航。</p><Button variant="secondary" onClick={()=>setNotice(true)}>内容内操作</Button><p>减少动态模式直接到达最终状态，信息不会丢失。</p></Disclosure><Disclosure title="相邻分组共用一条分隔线"><p>分组连续排列，不加组间 gap；相邻边框合并，展开和收起各自独立。</p></Disclosure></Surface>
         <EmptyState title="暂无记录" description="用一句话说明当前状态，按业务需要提供一个下一步操作。" action={<Button variant="secondary" onClick={()=>setNotice(true)}>演示下一步</Button>} /></div>
       </section>}
       {['data','forms','utilities','overlays'].includes(section) && <CommonGallery key={section} section={section} />}

package/preview/packageInfo.ts

@@ -0,0 +1,5 @@
+import { version } from '../package.json';
+
+export const packageVersion = version;
+// Public components in components/index.ts; excludes types and the separate theme entry.
+export const componentCount = 67;

package/review/canvas.tsx

@@ -0,0 +1,107 @@
+import { Component, useEffect, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { flushSync } from 'react-dom';
+import { ThemeProvider } from '../components/theme';
+import { Notice } from '../components';
+import { defineReview, catalogInfo, parseReviewState, serializeReviewState } from './state';
+import { createMockFetch, installIsolation, type ReviewHttpHandler } from './isolation';
+import { ReviewLifecycle } from './lifecycle';
+import { isReviewMessage, sendReview } from './protocol';
+import type { ReviewCatalog, ReviewEnvironment, ReviewScene, ReviewSelection, ReviewSession } from './types';
+import './review.css';
+
+class RenderBoundary extends Component<{ children: ReactNode; report(message: string): void }, { error: boolean }> {
+  state = { error: false };
+  static getDerivedStateFromError() { return { error: true }; }
+  componentDidCatch(error: Error) { this.props.report(`场景渲染失败：${error.message}`); }
+  render() { return this.state.error ? <p role="alert">场景渲染失败，请查看评审反馈并重置。</p> : this.props.children; }
+}
+
+export async function mountReviewCanvas(loadCatalog: () => Promise<{ default: ReviewCatalog }>) {
+  let state: ReviewSelection | undefined;
+  let requestId = 0;
+  const report = (message: string, kind = 'info', scene = state?.scene) => sendReview(parent, { type: 'feedback', message, kind, scene });
+  const failed = () => sendReview(parent, { type: 'failed', requestId });
+  const isolation = installIsolation(message => report(message, 'error'));
+  // The handler slot is changed only by the currently active setup context.
+  let http: ReviewHttpHandler | undefined;
+  let requestSignal = AbortSignal.abort();
+  window.fetch = createMockFetch(() => http, () => requestSignal, message => report(message, 'error'));
+  const root = createRoot(document.getElementById('root')!);
+  const media = matchMedia('(prefers-reduced-motion: reduce)');
+  let session: ReviewSession | undefined;
+  let scene: ReviewScene | undefined;
+  let renderGeneration = 0;
+  const environment = (): ReviewEnvironment => ({
+    theme: state!.theme, motion: state!.motion,
+    reducedMotion: state!.motion === 'reduced' || (state!.motion === 'system' && media.matches),
+    paused: state!.motion === 'paused',
+  });
+  const render = () => {
+    if (!session || !scene || !state) return;
+    const env = environment();
+    document.documentElement.style.zoom = String(state.zoom);
+    document.documentElement.dataset.rhineMotion = env.reducedMotion ? 'reduced' : env.paused ? 'paused' : 'full';
+    const committedRequest = requestId;
+    const renderedScene = scene.id;
+    const content = <RenderBoundary key={renderGeneration} report={message => { report(message, 'error', renderedScene); failed(); }}>
+      <SceneContent session={session} environment={env} committed={() => sendReview(parent, { type: 'rendered', requestId: committedRequest })} />
+    </RenderBoundary>;
+    root.render(scene.themeRoot === 'host' ? content : <ThemeProvider theme={env.theme} data-rhine-motion={env.reducedMotion ? 'reduced' : env.paused ? 'paused' : 'full'}>{content}</ThemeProvider>);
+  };
+  let catalog: ReviewCatalog;
+  try { catalog = defineReview((await loadCatalog()).default); }
+  catch (error) { report(`场景目录加载失败：${String(error)}`, 'error'); failed(); root.render(<Notice title="场景目录加载失败" />); return; }
+  const info = catalogInfo(catalog);
+  const lifecycle = new ReviewLifecycle({
+    clear() {
+      session = undefined; scene = undefined; renderGeneration++;
+      flushSync(() => root.render(null));
+    },
+    context(signal, selected) {
+      isolation.reset();
+      requestSignal = signal;
+      http = undefined;
+      return {
+        mockHttp(next) { signal.throwIfAborted(); http = next; },
+        report(message, kind) { if (!signal.aborted) report(message, kind, selected.id); },
+      };
+    },
+    ready(next, selected) { session = next; scene = selected; render(); },
+    error(error, selected) { report(`场景生命周期失败：${String(error)}`, 'error', selected); },
+    failed,
+  });
+  const ready = () => sendReview(parent, { type: 'ready', catalog: info });
+  let selectionKey = '';
+  const receive = (event: MessageEvent) => {
+    if (!isReviewMessage(event, parent)) return;
+    if (event.data.type === 'hello') { ready(); return; }
+    if (event.data.type !== 'select' || typeof event.data.hash !== 'string' || !Number.isSafeInteger(event.data.requestId)) return;
+    requestId = event.data.requestId;
+    state = parseReviewState(event.data.hash, info);
+    const selection = state;
+    // Canonicalizing in both documents prevents unsupported values from crossing the boundary.
+    const key = JSON.stringify([state.scene, state.dimensions]);
+    if (key !== selectionKey || event.data.reset === true) {
+      selectionKey = key;
+      report('正在初始化合成场景…');
+      void lifecycle.select(catalog.scenes.find(s => s.id === selection.scene)!, selection.dimensions, event.data.reset ? 'reset' : 'select');
+    } else render();
+    sendReview(parent, { type: 'state', hash: serializeReviewState(state) });
+  };
+  window.addEventListener('message', receive);
+  media.addEventListener('change', render);
+  const rejection = (event: PromiseRejectionEvent) => { if (event.reason?.name !== 'AbortError') report(`异步操作失败：${String(event.reason)}`, 'error'); };
+  window.addEventListener('unhandledrejection', rejection);
+  window.addEventListener('pagehide', () => {
+    window.removeEventListener('message', receive);
+    media.removeEventListener('change', render);
+    window.removeEventListener('unhandledrejection', rejection);
+    void lifecycle.dispose();
+  }, { once: true });
+  ready();
+}
+function SceneContent({ session, environment, committed }: { session: ReviewSession; environment: ReviewEnvironment; committed(): void }) {
+  useEffect(committed, [committed]);
+  return session.render(environment);
+}

package/review/dev-client.mjs

@@ -0,0 +1,17 @@
+// Style-only development client. The review server intentionally has no HMR transport.
+// CSS transformed by Vite 6/8 imports these helpers even with server.hmr:false.
+const styles = new Map();
+export function updateStyle(id, content) {
+  let style = styles.get(id);
+  if (!style) { style = document.createElement('style'); style.dataset.reviewStyle = id; document.head.append(style); styles.set(id, style); }
+  style.textContent = content;
+}
+export function removeStyle(id) { styles.get(id)?.remove(); styles.delete(id); }
+export function createHotContext() {
+  const noop = () => {};
+  return { data: {}, accept: noop, acceptExports: noop, dispose: noop, prune: noop, decline: noop, invalidate: noop, on: noop, off: noop, send: noop };
+}
+export function injectQuery(url, query) {
+  const [path, hash] = url.split('#');
+  return `${path}${path.includes('?') ? '&' : '?'}${query}${hash === undefined ? '' : `#${hash}`}`;
+}

package/review/feedback.ts

@@ -0,0 +1,17 @@
+export interface ReviewFeedback {
+  id: number;
+  scene: string;
+  message: string;
+  kind: 'info' | 'error';
+}
+export interface ReviewFeedbackLog {
+  entries: ReviewFeedback[];
+  errors: number;
+  omittedErrors: number;
+}
+export const emptyFeedback = (): ReviewFeedbackLog => ({ entries: [], errors: 0, omittedErrors: 0 });
+export function appendFeedback(log: ReviewFeedbackLog, entry: ReviewFeedback): ReviewFeedbackLog {
+  const entries = [...log.entries, { ...entry, message: entry.message.slice(0, 2000) }];
+  const omitted = entries.splice(0, Math.max(0, entries.length - 20));
+  return { entries, errors: log.errors + Number(entry.kind === 'error'), omittedErrors: log.omittedErrors + omitted.filter(item => item.kind === 'error').length };
+}

package/review/index.ts

@@ -0,0 +1,2 @@
+export { defineReview, parseReviewState, serializeReviewState } from './state';
+export type { ReviewCatalog, ReviewCatalogInfo, ReviewContext, ReviewDimension, ReviewEnvironment, ReviewMotion, ReviewOption, ReviewScene, ReviewSceneInfo, ReviewSelection, ReviewSession } from './types';

package/review/isolation.ts

@@ -0,0 +1,64 @@
+export type ReviewHttpHandler = (request: Request) => Response | undefined | Promise<Response | undefined>;
+export class MemoryStorage implements Storage {
+  private values = new Map<string, string>();
+  get length() { return this.values.size; }
+  clear() { this.values.clear(); }
+  getItem(key: string) { return this.values.get(String(key)) ?? null; }
+  key(index: number) { return [...this.values.keys()][index] ?? null; }
+  removeItem(key: string) { this.values.delete(String(key)); }
+  setItem(key: string, value: string) { this.values.set(String(key), String(value)); }
+}
+export function createMockFetch(getHandler: () => ReviewHttpHandler | undefined, getSignal: () => AbortSignal, report: (message: string) => void): typeof fetch {
+  return async (input, init) => {
+    const url = typeof input === 'string' ? new URL(input, location.href).href : input;
+    const request = new Request(url, init);
+    const signal = AbortSignal.any([request.signal, getSignal()]);
+    signal.throwIfAborted();
+    const scoped = new Request(request, { signal, credentials: 'omit' });
+    const handler = getHandler();
+    // Race cancellation even if a product handler ignores its signal or never resolves.
+    return new Promise<Response>((resolve, reject) => {
+      const abort = () => reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+      signal.addEventListener('abort', abort, { once: true });
+      Promise.resolve().then(() => { signal.throwIfAborted(); return handler?.(scoped); }).then(response => {
+        signal.throwIfAborted();
+        if (!response) {
+          const message = `未实现模拟请求：${scoped.method} ${new URL(scoped.url).pathname}`;
+          report(message);
+          throw new Error(message);
+        }
+        resolve(response);
+      }).catch(reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+  };
+}
+/** Defense in depth for trusted synthetic product code; not an untrusted-code sandbox. */
+export function installIsolation(report: (message: string) => void) {
+  const storage = [new MemoryStorage(), new MemoryStorage()];
+  Object.defineProperty(window, 'localStorage', { configurable: true, value: storage[0] });
+  Object.defineProperty(window, 'sessionStorage', { configurable: true, value: storage[1] });
+  Object.defineProperty(document, 'cookie', { configurable: true, get: () => '', set: () => { report('预览不写入会话 Cookie'); } });
+  const blocked = (name: string) => { const message = `预览未实现操作：${name}`; report(message); throw new Error(message); };
+  for (const name of ['XMLHttpRequest', 'WebSocket', 'EventSource', 'Worker', 'SharedWorker'] as const) {
+    Object.defineProperty(window, name, { configurable: true, value: function () { return blocked(name); } });
+  }
+  Object.defineProperty(window, 'indexedDB', { configurable: true, get: () => blocked('IndexedDB') });
+  Object.defineProperty(window, 'caches', { configurable: true, get: () => blocked('CacheStorage') });
+  Object.defineProperty(navigator, 'serviceWorker', { configurable: true, get: () => blocked('ServiceWorker') });
+  Object.defineProperty(navigator, 'sendBeacon', { configurable: true, value: () => { report('预览不发送 Beacon'); return false; } });
+  Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText: async () => blocked('Clipboard'), readText: async () => blocked('Clipboard') } });
+  window.open = () => { report('预览不打开外部窗口'); return null; };
+  document.addEventListener('click', event => {
+    const link = (event.target as Element)?.closest?.('a');
+    if (!link || event.defaultPrevented) return;
+    const url = new URL(link.href);
+    const localHash = url.origin === location.origin && url.pathname === location.pathname && url.search === location.search && Boolean(url.hash);
+    if (link.hasAttribute('download') || link.target || !localHash) {
+      event.preventDefault(); report('预览不执行下载或整页跳转；产品路由需使用 SPA 导航适配');
+    }
+  });
+  document.addEventListener('submit', event => {
+    if (!event.defaultPrevented) { event.preventDefault(); report('预览表单需要产品 onSubmit 模拟适配'); }
+  });
+  return { reset: () => storage.forEach(item => item.clear()) };
+}

package/review/lifecycle.ts

@@ -0,0 +1,59 @@
+import type { ReviewContext, ReviewScene, ReviewSession } from './types';
+
+export class ReviewLifecycle {
+  private generation = 0;
+  private active?: { scene: string; abort: AbortController; cleanups: (() => void | Promise<void>)[]; session?: ReviewSession; disposed: boolean; disposal?: Promise<void> };
+  constructor(private readonly hooks: {
+    clear(): void;
+    ready(session: ReviewSession, scene: ReviewScene): void;
+    error(error: unknown, scene?: string): void;
+    failed?(scene: string): void;
+    context(signal: AbortSignal, scene: ReviewScene): Pick<ReviewContext, 'mockHttp' | 'report'>;
+  }) {}
+  private cleanup(run: NonNullable<ReviewLifecycle['active']>, reset: boolean): Promise<void> {
+    if (run.disposal) return run.disposal;
+    run.disposed = true;
+    run.abort.abort();
+    const operations = [...run.cleanups.reverse()];
+    if (run.session) {
+      if (reset && run.session.reset) operations.unshift(() => run.session!.reset!());
+      operations.push(() => run.session!.dispose());
+    }
+    run.disposal = (async () => {
+      for (const operation of operations) {
+        try { await operation(); } catch (error) { this.hooks.error(error, run.scene); }
+      }
+    })();
+    return run.disposal;
+  }
+  async select(scene: ReviewScene, dimensions: Record<string, string>, reason: 'select' | 'reset' = 'select') {
+    const generation = ++this.generation;
+    const previous = this.active;
+    try { this.hooks.clear(); } catch (error) { this.hooks.error(error, previous?.scene); }
+    if (previous) await this.cleanup(previous, reason === 'reset');
+    if (generation !== this.generation) return;
+    const run = { scene: scene.id, abort: new AbortController(), cleanups: [] as (() => void | Promise<void>)[], session: undefined as ReviewSession | undefined, disposed: false };
+    this.active = run;
+    const context: ReviewContext = {
+      ...this.hooks.context(run.abort.signal, scene), dimensions: Object.freeze({ ...dimensions }), signal: run.abort.signal, reason,
+      onDispose: cleanup => {
+        if (run.disposed) void Promise.resolve().then(cleanup).catch(error => this.hooks.error(error, scene.id));
+        else run.cleanups.push(cleanup);
+      },
+    };
+    try {
+      const session = await scene.setup(context);
+      if (generation !== this.generation || run.disposed) { await session.dispose(); return; }
+      run.session = session;
+      this.hooks.ready(session, scene);
+    } catch (error) {
+      if (!run.abort.signal.aborted) { this.hooks.error(error, scene.id); this.hooks.failed?.(scene.id); }
+      await this.cleanup(run, false);
+    }
+  }
+  async dispose() {
+    ++this.generation;
+    try { this.hooks.clear(); } catch (error) { this.hooks.error(error, this.active?.scene); }
+    if (this.active) await this.cleanup(this.active, false);
+  }
+}

package/review/protocol.ts

@@ -0,0 +1,7 @@
+export const protocol = 'rhine-review/2';
+export function isReviewMessage(event: MessageEvent, source: Window | null): boolean {
+  return event.origin === location.origin && event.source === source && event.data?.protocol === protocol;
+}
+export function sendReview(target: Window, data: Record<string, unknown>) {
+  target.postMessage({ ...data, protocol }, location.origin);
+}

package/review/review.css

@@ -0,0 +1,41 @@
+html, body, #root { margin: 0; min-height: 100%; }
+.rhine-review-shell { min-height: 100vh; background: var(--rhine-bg); color: var(--rhine-ink); }
+.rhine-review-header { display: flex; gap: 12px; align-items: center; padding: 16px 24px; border-bottom: 1px solid var(--rhine-line); flex-wrap: wrap; }
+.rhine-review-brand { display: flex; align-items: center; gap: 12px; margin-right: auto; }
+.rhine-review-brand strong { display: block; font-size: 16px; line-height: 24px; font-weight: 600; }
+.rhine-review-brand small { display: block; font-size: 12px; line-height: 18px; font-weight: 400; opacity: .7; }
+.rhine-review-menu { display: none; }
+.rhine-review-body { display: grid; grid-template-columns: 232px minmax(0, 1fr); }
+.rhine-review-directory { padding: 20px; border-right: 1px solid var(--rhine-line); }
+.rhine-review-directory h2 { margin-top: 24px; font-size: 12px; line-height: 18px; font-weight: 600; opacity: .7; }
+.rhine-review-directory a { display: block; padding: 10px 12px; color: inherit; text-decoration: none; font-size: 14px; line-height: 22px; font-weight: 400; overflow-wrap: anywhere; }
+.rhine-review-directory a[aria-current] { background: var(--rhine-selected); font-weight: 600; box-shadow: inset 3px 0 var(--rhine-green); }
+.rhine-review-main { min-width: 0; }
+.rhine-review-controls { display: flex; flex-wrap: wrap; align-items: end; gap: 12px; padding: 20px; }
+.rhine-review-controls > .rhine-field { flex: 1 1 140px; min-width: 0; }
+.rhine-review-feedback, .rhine-review-notes { padding: 12px 20px; font-size: 13px; line-height: 20px; font-weight: 400; overflow-wrap: anywhere; }
+.rhine-review-feedback[role=alert] { border-left: 3px solid var(--rhine-error); }
+.rhine-review-feedback p { margin: 0 0 8px; }
+.rhine-review-feedback [role=alert] { border-left: 3px solid var(--rhine-error); padding-left: 10px; }
+.rhine-review-options { margin: 0 20px; padding: 0 0 8px; font-size: 13px; line-height: 20px; font-weight: 400; }
+.rhine-review-options summary, .rhine-review-log summary { cursor: pointer; padding: 10px 0; }
+.rhine-review-options .rhine-review-controls { padding: 12px 0; }
+.rhine-review-options p { color: var(--rhine-muted); margin: 0; }
+.rhine-review-recovery { display: flex; align-items: center; flex-wrap: wrap; gap: 12px; margin: 12px 0; }
+.rhine-review-log ol { max-height: 240px; overflow: auto; padding-left: 24px; }
+.rhine-review-log li { padding: 8px 0; }
+.rhine-review-log li strong, .rhine-review-log li span { display: block; }
+.rhine-review-log li[data-kind=error] { color: var(--rhine-error); }
+.rhine-review-size { margin: 0; padding: 8px 20px; color: var(--rhine-muted); font-size: 12px; line-height: 18px; font-weight: 400; }
+.rhine-review-viewport { overflow: auto; padding: 16px; background: var(--rhine-surface); }
+.rhine-review-viewport iframe { display: block; border: 1px solid var(--rhine-line); min-height: 650px; height: 72vh; margin: 0 auto; background: var(--rhine-bg); box-sizing: border-box; }
+.rhine-review-notes summary { cursor: pointer; min-height: 32px; }
+[data-rhine-motion=paused] *, [data-rhine-motion=paused] *::before, [data-rhine-motion=paused] *::after { animation-play-state: paused !important; }
+@media (max-width: 760px) {
+  .rhine-review-menu { display: inline-flex; }
+  .rhine-review-body { grid-template-columns: minmax(0, 1fr); }
+  .rhine-review-directory { display: none; border-bottom: 1px solid var(--rhine-line); }
+  .rhine-review-directory[data-open=true] { display: block; }
+  .rhine-review-header { padding: 12px; }
+  .rhine-review-controls { padding: 12px; }
+}

package/review/shell.tsx

@@ -0,0 +1,165 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { Button, Logo, Select, TextField } from '../components';
+import { ThemeProvider, themes } from '../components/theme';
+import { defaultWidths, parseReviewState, serializeReviewState } from './state';
+import { isReviewMessage, sendReview } from './protocol';
+import { appendFeedback, emptyFeedback, type ReviewFeedback } from './feedback';
+import type { ReviewCatalogInfo, ReviewSelection } from './types';
+import './review.css';
+
+type Phase = 'connecting' | 'loading' | 'ready' | 'failed' | 'timed-out';
+export const reviewWaitMs = 10_000;
+
+export function ReviewShell() {
+  const frame = useRef<HTMLIFrameElement>(null);
+  const [frameEpoch, setFrameEpoch] = useState(0);
+  const [catalog, setCatalog] = useState<ReviewCatalogInfo>();
+  const [state, setState] = useState<ReviewSelection>();
+  const [query, setQuery] = useState('');
+  const [log, setLog] = useState(emptyFeedback);
+  const [phase, setPhase] = useState<Phase>('connecting');
+  const [menu, setMenu] = useState(false);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const stateRef = useRef(state);
+  const connected = useRef(false);
+  const sequence = useRef(0);
+  const pendingRequest = useRef(0);
+  const feedbackSequence = useRef(0);
+  const timeout = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  stateRef.current = state;
+  const record = useCallback((message: string, kind: ReviewFeedback['kind'] = 'info', scene = '画布') => {
+    const entry = { id: ++feedbackSequence.current, message, kind, scene };
+    setLog(previous => appendFeedback(previous, entry));
+  }, []);
+  const stopWaiting = useCallback(() => { clearTimeout(timeout.current); timeout.current = undefined; }, []);
+  const waitFor = useCallback((next: 'connecting' | 'loading') => {
+    stopWaiting(); setPhase(next);
+    timeout.current = setTimeout(() => {
+      setPhase('timed-out');
+      record(next === 'connecting' ? '连接画布超时，请检查资源加载后重新载入画布。' : '场景初始化或清理超过 10 秒，尚未确认完成。可继续等待，或重新载入画布。', 'error', next === 'connecting' ? '画布' : stateRef.current?.scene);
+    }, reviewWaitMs);
+  }, [record, stopWaiting]);
+  const select = useCallback((selection: ReviewSelection, reset = false) => {
+    if (!connected.current || !frame.current?.contentWindow) return;
+    pendingRequest.current = ++sequence.current;
+    waitFor('loading');
+    sendReview(frame.current.contentWindow, { type: 'select', hash: serializeReviewState(selection), requestId: pendingRequest.current, reset });
+  }, [waitFor]);
+  useEffect(() => {
+    connected.current = false; pendingRequest.current = 0;
+    waitFor('connecting');
+    const receive = (event: MessageEvent) => {
+      if (!isReviewMessage(event, frame.current?.contentWindow ?? null)) return;
+      if (event.data.type === 'ready') {
+        // Repeated hello acknowledgements must not restart a pending initialization.
+        if (connected.current) return;
+        connected.current = true;
+        const next = event.data.catalog as ReviewCatalogInfo;
+        setCatalog(next);
+        const selection = parseReviewState(location.hash, next);
+        history.replaceState(null, '', serializeReviewState(selection));
+        setState(selection);
+        document.title = `${next.title} · Rhine Review`;
+      } else if (event.data.type === 'feedback' && typeof event.data.message === 'string') {
+        record(event.data.message, event.data.kind === 'error' ? 'error' : 'info', typeof event.data.scene === 'string' ? event.data.scene : '画布');
+      } else if ((event.data.type === 'rendered' || event.data.type === 'failed') && event.data.requestId === pendingRequest.current) {
+        stopWaiting(); setPhase(event.data.type === 'rendered' ? 'ready' : 'failed');
+      }
+    };
+    window.addEventListener('message', receive);
+    const handshake = setInterval(() => {
+      if (!connected.current && frame.current?.contentWindow) sendReview(frame.current.contentWindow, { type: 'hello' });
+    }, 500);
+    return () => { window.removeEventListener('message', receive); clearInterval(handshake); stopWaiting(); };
+  }, [frameEpoch, record, stopWaiting, waitFor]);
+  useEffect(() => {
+    if (!catalog) return;
+    const navigate = () => {
+      const next = parseReviewState(location.hash, catalog);
+      history.replaceState(null, '', serializeReviewState(next)); setState(next);
+    };
+    window.addEventListener('popstate', navigate); window.addEventListener('hashchange', navigate);
+    return () => { window.removeEventListener('popstate', navigate); window.removeEventListener('hashchange', navigate); };
+  }, [catalog]);
+  useEffect(() => { if (state) select(state); }, [state, select]);
+  useEffect(() => {
+    const element = frame.current;
+    if (!element) return;
+    const measure = () => setSize({ width: element.clientWidth, height: element.clientHeight });
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(measure); observer.observe(element);
+    return () => observer.disconnect();
+  }, [frameEpoch]);
+  const update = (patch: Partial<ReviewSelection>) => {
+    if (!state || !catalog) return;
+    const next = parseReviewState(serializeReviewState({ ...state, ...patch }), catalog);
+    history.pushState(null, '', serializeReviewState(next)); setState(next);
+  };
+  const reload = () => {
+    // A new browsing context terminates noncooperative code; never start new setup in a stuck context.
+    stopWaiting(); connected.current = false;
+    record('已重新载入画布；旧会话与未保存草稿已清空，评审条件保留。', 'info', state?.scene);
+    setFrameEpoch(value => value + 1);
+  };
+  const scene = catalog?.scenes.find(item => item.id === state?.scene);
+  const matching = catalog?.scenes.filter(item => `${item.title} ${item.group ?? ''} ${item.id}`.toLocaleLowerCase().includes(query.toLocaleLowerCase())) ?? [];
+  const trouble = phase === 'failed' || phase === 'timed-out';
+  const lastError = [...log.entries].reverse().find(entry => entry.kind === 'error');
+  const phaseLabel = { connecting: '正在连接场景画布…', loading: '正在初始化或清理合成场景…', ready: '合成场景已就绪 · 无业务后端', failed: '场景未能完成，请查看反馈或重新载入画布。', 'timed-out': '画布响应较慢，尚未确认完成。' }[phase];
+  return <ThemeProvider theme={state?.theme ?? 'rhine'} className="rhine-review-shell">
+    <header className="rhine-review-header">
+      <div className="rhine-review-brand"><Logo size={28} /><div><strong>{catalog?.title ?? 'Rhine Review'}</strong><small>产品设计评审 · 合成数据</small></div></div>
+      <Button id="review-menu" className="rhine-review-menu" variant="secondary" aria-expanded={menu} aria-controls="review-directory" onClick={() => setMenu(!menu)}>场景目录</Button>
+      <Button variant="secondary" disabled={!state} onClick={async () => {
+        try { await navigator.clipboard.writeText(location.href); record('评审链接已复制'); }
+        catch { record('复制未完成，请复制浏览器地址', 'error'); }
+      }}>复制链接</Button>
+    </header>
+    <div className="rhine-review-body">
+      <aside id="review-directory" className="rhine-review-directory" data-open={menu} onKeyDown={event => {
+        if (event.key === 'Escape' && menu) { setMenu(false); document.getElementById('review-menu')?.focus(); }
+      }}>
+        <TextField label="搜索场景" value={query} onChange={event => setQuery(event.target.value)} />
+        <nav aria-label="评审场景">{[...new Set(matching.map(item => item.group ?? '场景'))].map(group => <section key={group}><h2>{group}</h2>{matching.filter(item => (item.group ?? '场景') === group).map(item => <a key={item.id} aria-current={item.id === scene?.id ? 'page' : undefined} href={state ? serializeReviewState({ ...state, scene: item.id, dimensions: {} }) : '#'} onClick={event => { event.preventDefault(); update({ scene: item.id, dimensions: {} }); setMenu(false); if (menu) document.getElementById('review-menu')?.focus(); }}>{item.title}</a>)}</section>)}</nav>
+        {catalog && !matching.length && <p>没有匹配场景</p>}
+      </aside>
+      <main className="rhine-review-main">
+        {state && <>
+          <div className="rhine-review-controls" aria-label="评审设置">
+            <Select label="界面主题" value={state.theme} onChange={event => update({ theme: event.target.value as ReviewSelection['theme'] })}>{themes.map(theme => <option key={theme.name} value={theme.name}>{theme.label}</option>)}</Select>
+            <Select label="画布宽度" value={state.width} onChange={event => update({ width: event.target.value === 'fit' ? 'fit' : Number(event.target.value) })}><option value="fit">适应容器</option>{(catalog?.widths ?? defaultWidths).map(width => <option key={width} value={width}>{width} px</option>)}</Select>
+            {scene?.dimensions?.map(dimension => <Select key={dimension.id} label={dimension.label} value={state.dimensions[dimension.id]} onChange={event => update({ dimensions: { ...state.dimensions, [dimension.id]: event.target.value } })}>{dimension.options.map(option => <option key={option.id} value={option.id}>{option.label}</option>)}</Select>)}
+            <Button variant="secondary" onClick={() => select(state, true)}>重置场景</Button>
+          </div>
+          <details className="rhine-review-options"><summary>更多设置 · {state.zoom * 100}% CSS zoom · {{ system: '跟随系统', full: '完整动态', reduced: '减少动态', paused: '暂停' }[state.motion]}</summary>
+            <div className="rhine-review-controls">
+              <Select label="CSS 缩放" value={state.zoom} onChange={event => update({ zoom: Number(event.target.value) as 1 | 2 })}><option value="1">100%</option><option value="2">200%（CSS zoom）</option></Select>
+              <Select label="动态偏好" value={state.motion} onChange={event => update({ motion: event.target.value as ReviewSelection['motion'] })}><option value="system">跟随系统</option>{scene?.motionControls?.includes('full') && <option value="full">完整动态</option>}<option value="reduced">减少动态</option>{scene?.motionControls?.includes('paused') && <option value="paused">暂停</option>}</Select>
+              {!trouble && <Button variant="secondary" onClick={reload}>重新载入画布</Button>}
+            </div><p>重新载入会清空未保存草稿，并保留当前评审条件。</p>
+          </details>
+        </>}
+        <div className="rhine-review-feedback">
+          <p role="status">{phaseLabel}</p>
+          {trouble && <div className="rhine-review-recovery"><Button variant="secondary" onClick={reload}>重新载入画布</Button><span>清空未保存草稿，保留当前评审条件。</span></div>}
+          {log.errors > 0 && <p role="alert">{log.errors} 条错误待确认{lastError ? ` · ${lastError.message}` : ''}</p>}
+          {log.entries.length > 0 && <details className="rhine-review-log"><summary>评审反馈 · {log.entries.length} 条记录{log.errors ? ` · ${log.errors} 条错误待确认` : ''}</summary>
+            <ol>{log.entries.map(entry => <li key={entry.id} data-kind={entry.kind}><strong>{catalog?.scenes.find(item => item.id === entry.scene)?.title ?? entry.scene}</strong><span>{entry.message}</span></li>)}</ol>
+            {log.omittedErrors > 0 && <p>另有 {log.omittedErrors} 条较早错误未展示，仍计入待确认数量。</p>}
+            <Button variant="secondary" onClick={() => setLog(emptyFeedback())}>确认并清除反馈</Button>
+          </details>}
+        </div>
+        <p className="rhine-review-size" aria-label="画布尺寸">画布 {size.width} × {size.height} px · {(state?.zoom ?? 1) * 100}% CSS zoom · 等效内容宽度约 {Math.round(size.width / (state?.zoom ?? 1))} CSS px</p>
+        <div className="rhine-review-viewport">
+          <iframe key={frameEpoch} ref={frame} title="产品场景画布" src={new URL('canvas.html', location.href).href} sandbox="allow-scripts allow-same-origin allow-forms" referrerPolicy="no-referrer" onLoad={() => {
+            if (frame.current?.contentWindow) sendReview(frame.current.contentWindow, { type: 'hello' });
+          }} style={{ width: state?.width === 'fit' || !state ? '100%' : state.width }} />
+        </div>
+        {scene && <details className="rhine-review-notes"><summary>场景说明与验证状态</summary><p>{scene.description ?? '此场景使用产品提供的合成数据。'}</p>{scene.source && <p>源码：<code>{scene.source}</code></p>}{scene.issue && /^https:\/\//.test(scene.issue) && <a href={scene.issue} target="_blank" rel="noreferrer">关联 issue</a>}<p>{scene.validation ?? '验证状态由产品维护；可交互预览不等于生产或原生验收。'}</p></details>}
+      </main>
+    </div>
+  </ThemeProvider>;
+}
+export function mountReviewShell() { createRoot(document.getElementById('root')!).render(<ReviewShell />); }