@linhey/rhine-design 0.10.0 → 0.11.1

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 />); }

package/review/state.ts

@@ -0,0 +1,41 @@
+import { themes } from '../components/themeMetadata';
+import type { ReviewCatalog, ReviewCatalogInfo, ReviewSelection } from './types';
+
+export const defaultWidths = [400, 520, 880, 1280] as const;
+const validId = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function defineReview(catalog: ReviewCatalog): ReviewCatalog {
+  if (!catalog.scenes.length) throw new Error('Review needs at least one scene.');
+  const unique = (ids: string[]) => ids.every(id => validId.test(id)) && new Set(ids).size === ids.length;
+  if (!unique(catalog.scenes.map(scene => scene.id))) throw new Error('Scene IDs must be unique stable identifiers.');
+  for (const scene of catalog.scenes) {
+    if (!unique((scene.dimensions ?? []).map(d => d.id))) throw new Error(`Invalid dimensions: ${scene.id}`);
+    for (const dimension of scene.dimensions ?? []) {
+      if (!dimension.options.length || !unique(dimension.options.map(o => o.id))) throw new Error(`Invalid options: ${dimension.id}`);
+    }
+  }
+  if (catalog.widths && (!catalog.widths.length || catalog.widths.some(w => !Number.isInteger(w) || w < 240 || w > 3840))) throw new Error('Widths must be integers between 240 and 3840.');
+  return catalog;
+}
+export function catalogInfo(catalog: ReviewCatalog): ReviewCatalogInfo {
+  return { title: catalog.title, widths: catalog.widths, scenes: catalog.scenes.map(({ setup: _setup, ...info }) => info) };
+}
+export function parseReviewState(hash: string, catalog: ReviewCatalogInfo): ReviewSelection {
+  const params = new URLSearchParams(hash.replace(/^#/, ''));
+  const scene = catalog.scenes.find(s => s.id === params.get('scene')) ?? catalog.scenes[0];
+  if (!scene) throw new Error('Empty review catalog.');
+  const width = Number(params.get('width'));
+  const motion = params.get('motion');
+  return {
+    scene: scene.id,
+    dimensions: Object.fromEntries((scene.dimensions ?? []).map(d => [d.id, d.options.find(o => o.id === params.get(`d.${d.id}`))?.id ?? d.options[0].id])),
+    theme: themes.find(t => t.name === params.get('theme'))?.name ?? 'rhine',
+    width: (catalog.widths ?? defaultWidths).includes(width) ? width : 'fit',
+    zoom: params.get('zoom') === '2' ? 2 : 1,
+    motion: motion === 'reduced' ? motion : (motion === 'full' || motion === 'paused') && scene.motionControls?.includes(motion) ? motion : 'system',
+  };
+}
+export function serializeReviewState(state: ReviewSelection): string {
+  const params = new URLSearchParams({ scene: state.scene, theme: state.theme, width: String(state.width), zoom: String(state.zoom), motion: state.motion });
+  for (const key of Object.keys(state.dimensions).sort()) params.set(`d.${key}`, state.dimensions[key]);
+  return `#${params}`;
+}

package/review/types.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+import type { ThemeName } from '../components/themeMetadata';
+
+export type ReviewMotion = 'system' | 'full' | 'reduced' | 'paused';
+export interface ReviewEnvironment {
+  theme: ThemeName;
+  motion: ReviewMotion;
+  reducedMotion: boolean;
+  paused: boolean;
+}
+export interface ReviewSelection {
+  scene: string;
+  dimensions: Record<string, string>;
+  theme: ThemeName;
+  width: number | 'fit';
+  zoom: 1 | 2;
+  motion: ReviewMotion;
+}
+export interface ReviewOption { id: string; label: string }
+export interface ReviewDimension { id: string; label: string; options: readonly ReviewOption[] }
+export interface ReviewSceneInfo {
+  id: string;
+  title: string;
+  group?: string;
+  description?: string;
+  source?: string;
+  issue?: string;
+  validation?: string;
+  /** Host apps with an existing ThemeProvider own their single theme root. */
+  themeRoot?: 'runtime' | 'host';
+  /** Opt in only if every scene animation handles the corresponding environment flag. */
+  motionControls?: readonly ('full' | 'paused')[];
+  dimensions?: readonly ReviewDimension[];
+}
+export interface ReviewContext {
+  dimensions: Readonly<Record<string, string>>;
+  signal: AbortSignal;
+  reason: 'select' | 'reset';
+  /** Register immediately, including resources acquired before async setup finishes. */
+  onDispose(cleanup: () => void | Promise<void>): void;
+  /** Only synthetic requests are dispatched here. Returning undefined explicitly fails. */
+  mockHttp(handler: (request: Request) => Response | undefined | Promise<Response | undefined>): void;
+  report(message: string, kind?: 'info' | 'error'): void;
+}
+export interface ReviewSession {
+  render(environment: ReviewEnvironment): ReactNode;
+  /** Explicit reset notification; a fresh setup always follows disposal. */
+  reset?(): void | Promise<void>;
+  dispose(): void | Promise<void>;
+}
+export interface ReviewScene extends ReviewSceneInfo {
+  setup(context: ReviewContext): ReviewSession | Promise<ReviewSession>;
+}
+export interface ReviewCatalog {
+  title: string;
+  widths?: readonly number[];
+  scenes: readonly ReviewScene[];
+}
+export type ReviewCatalogInfo = Omit<ReviewCatalog, 'scenes'> & { scenes: readonly ReviewSceneInfo[] };

package/review/vite.d.mts

@@ -0,0 +1,10 @@
+import type { Plugin } from 'vite';
+export interface ReviewViteOptions {
+  /** Catalog module relative to the dedicated Vite root. */
+  catalog: string;
+  /** Product router base, separate from static asset base. */
+  routerBase?: string;
+}
+export function reviewPlugin(options: ReviewViteOptions): Plugin;
+/** Forbidden paths are exact files/directories relative to the production Vite root. */
+export function reviewProductionGuard(options?: { forbidden?: readonly string[] }): Plugin;

package/review/vite.mjs

@@ -0,0 +1,107 @@
+// @ts-check
+import { resolve, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+const directory = dirname(fileURLToPath(import.meta.url));
+const ids = { shell: '\0rhine-review:shell', canvas: '\0rhine-review:canvas' };
+const csp = "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; media-src 'self' blob:; connect-src 'none'; frame-src 'self'; worker-src 'none'; object-src 'none'; form-action 'none'; base-uri 'self'";
+/** @param {string} script @param {string[]} styles */
+function html(script, styles = []) {
+    return `<!doctype html><html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="${csp}"><link rel="icon" href="data:,"><title>Rhine Review</title>${styles.map(style => `<link rel="stylesheet" href="${style}">`).join('')}</head><body><div id="root"></div><script type="module" src="${script}"></script></body></html>`;
+}
+/** Use in a dedicated config, never merge a production config containing secrets/proxies. */
+/** @param {import('./vite.mjs').ReviewViteOptions} options @returns {import('vite').Plugin} */
+export function reviewPlugin(options) {
+    /** @type {import('vite').ResolvedConfig} */
+    let config;
+    return {
+        name: 'rhine-review',
+        enforce: 'pre',
+        config(userConfig) {
+            const root = userConfig.root ?? process.cwd();
+            return {
+                appType: 'mpa', envDir: false, publicDir: false, envPrefix: 'RHINE_REVIEW_PUBLIC_',
+                server: { hmr: false },
+                cacheDir: resolve(root, 'node_modules/.vite-review'),
+                optimizeDeps: { entries: [resolve(directory, 'shell.tsx'), resolve(directory, 'canvas.tsx'), resolve(root, options.catalog)] },
+                resolve: { dedupe: ['react', 'react-dom'] },
+                define: options.routerBase ? { 'import.meta.env.BASE_URL': JSON.stringify(options.routerBase) } : {},
+                build: { cssCodeSplit: false, rollupOptions: { input: { review: ids.shell, canvas: ids.canvas } } },
+            };
+        },
+        configResolved(resolved) {
+            config = resolved;
+            if (resolved.envDir !== false || resolved.publicDir !== '' || Object.keys(resolved.server.proxy ?? {}).length || Object.keys(resolved.preview.proxy ?? {}).length) {
+                throw new Error('Review requires envDir:false, publicDir:false and no server/preview proxies.');
+            }
+            if (resolved.build.outDir === '.' || resolve(resolved.root, resolved.build.outDir) === resolved.root)
+                throw new Error('Review output must use a separate directory.');
+        },
+        resolveId(id) { if (Object.values(ids).includes(id))
+            return id; },
+        load(id) {
+            if (id === ids.shell)
+                return `import {mountReviewShell} from ${JSON.stringify(resolve(directory, 'shell.tsx'))}; mountReviewShell();`;
+            if (id === ids.canvas)
+                return `import {mountReviewCanvas} from ${JSON.stringify(resolve(directory, 'canvas.tsx'))}; mountReviewCanvas(() => import(${JSON.stringify(resolve(config.root, options.catalog))}));`;
+        },
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                const requested = (request.url ?? '/').split('?')[0];
+                const pathname = config.base !== './' && requested.startsWith(config.base) ? `/${requested.slice(config.base.length)}` : requested;
+                if (pathname === '/@vite/client') {
+                    response.setHeader('Content-Type', 'text/javascript');
+                    response.end(readFileSync(resolve(directory, 'dev-client.mjs'), 'utf8'));
+                    return;
+                }
+                if (!['/', '/index.html', '/canvas.html'].includes(pathname)) {
+                    next();
+                    return;
+                }
+                const entry = pathname === '/canvas.html' ? ids.canvas : ids.shell;
+                try {
+                    let document = await server.transformIndexHtml(pathname, html(`/@id/${entry.replace('\0', '__x00__')}`));
+                    document = document.replace(/<script type="module" src="[^\"]*\/@vite\/client"><\/script>/g, '');
+                    response.statusCode = 200;
+                    response.setHeader('Content-Type', 'text/html');
+                    response.end(document);
+                }
+                catch (error) {
+                    next(error);
+                }
+            });
+        },
+        generateBundle: { order: 'post', handler(_options, bundle) {
+                const assetBase = config.base === './' || config.base === '' ? './' : config.base;
+                const styles = Object.values(bundle).filter(asset => asset.type === 'asset' && asset.fileName.endsWith('.css')).map(asset => `${assetBase}${asset.fileName}`);
+                for (const [name, entryId] of Object.entries(ids)) {
+                    const entry = Object.values(bundle).find(asset => asset.type === 'chunk' && asset.isEntry && asset.facadeModuleId === entryId);
+                    if (!entry)
+                        this.error(`Missing review entry: ${name}`);
+                    this.emitFile({ type: 'asset', fileName: name === 'shell' ? 'index.html' : 'canvas.html', source: html(`${assetBase}${entry.fileName}`, styles) });
+                }
+            } },
+    };
+}
+/** Add to the actual production build. A build fails if fixtures or review code are imported. */
+/** @param {{forbidden?: readonly string[]}} options @returns {import('vite').Plugin} */
+export function reviewProductionGuard(options = {}) {
+    /** @type {string} */
+    let root;
+    return {
+        name: 'rhine-review-production-guard', apply: 'build',
+        configResolved(config) { root = config.root; },
+        generateBundle(_options, bundle) {
+            const forbidden = [directory, ...(options.forbidden ?? []).map(path => resolve(root, path))].map(path => path.replaceAll('\\', '/'));
+            for (const chunk of Object.values(bundle)) {
+                if (chunk.type !== 'chunk')
+                    continue;
+                for (const module of Object.keys(chunk.modules)) {
+                    const normalized = module.replaceAll('\\', '/').split('?')[0];
+                    if (normalized.includes('rhine-review:') || forbidden.some(path => normalized === path || normalized.startsWith(`${path}/`)))
+                        this.error(`Production bundle imports review runtime or forbidden fixtures: ${relative(root, normalized)}`);
+                }
+            }
+        },
+    };
+}

package/scripts/check-combobox-modal-focus.js

@@ -0,0 +1,22 @@
+// Regression for the interval between a nested popup closing and its modal scope resuming.
+async page => {
+  const origin = new URL(page.url()).origin, cases = [], errors = [];
+  page.on('pageerror', error => errors.push(String(error)));
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) for (const width of [400, 880]) for (const zoom of [1, 2]) {
+    await page.setViewportSize({ width, height: 960 });
+    await page.goto(`${origin}/?theme=${theme}#compact-filters`); await page.reload();
+    await page.evaluate(value => { document.documentElement.style.zoom = String(value); }, zoom);
+    await page.getByRole('button', { name: '在弹窗内选择', exact: true }).click();
+    const input = page.getByRole('combobox', { name: '弹窗部门', exact: true });
+    await input.click(); await input.press('Shift+Tab');
+    await page.keyboard.press('Shift+Tab');
+    const immediateInside = await page.getByRole('dialog').evaluate(element => element.contains(document.activeElement));
+    // Assert the fast path before waiting; then separately verify normal navigation resumes.
+    await page.waitForTimeout(50);
+    const close = page.getByRole('button', { name: '关闭对话框', exact: true });
+    await close.focus(); await page.keyboard.press('Shift+Tab');
+    const resumed = await page.getByRole('dialog').evaluate(element => element.contains(document.activeElement) && document.activeElement?.getAttribute('aria-label') !== '关闭对话框');
+    cases.push({ theme, width, zoom, immediateInside, resumed });
+  }
+  return { pass: cases.every(item => item.immediateInside && item.resumed) && !errors.length, cases, errors };
+}

package/scripts/check-combobox-zoom.js

@@ -0,0 +1,109 @@
+// Open the built gallery, then run with Playwright CLI run-code --filename.
+async page => {
+  const origin = new URL(page.url()).origin;
+  page.setDefaultTimeout(10000);
+  const failures = [], errors = [], cases = [];
+  page.on('pageerror', error => errors.push(String(error)));
+  const bounds = locator => locator.evaluate(element => {
+    const r = element.getBoundingClientRect();
+    return { left: r.left, right: r.right, top: r.top, bottom: r.bottom, width: innerWidth, height: innerHeight };
+  });
+  const contained = r => r.left >= -1 && r.top >= -1 && r.right <= r.width + 1 && r.bottom <= r.height + 1;
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) {
+    for (const width of [400, 520, 880]) for (const zoom of [1, 2]) for (const modal of [false, true]) {
+      const spec = { theme, width, zoom, modal };
+      await page.setViewportSize({ width, height: 960 });
+      await page.goto(`${origin}/?theme=${theme}#compact-filters`);
+      await page.reload();
+      await page.getByRole('heading', { name: '密集筛选控件', exact: true }).waitFor();
+      await page.evaluate(zoom => { document.documentElement.style.zoom = String(zoom); }, zoom);
+      if (modal) await page.getByRole('button', { name: '在弹窗内选择', exact: true }).click();
+      const label = modal ? '弹窗部门' : '部门';
+      const input = page.getByRole('combobox', { name: label, exact: true });
+      await input.fill('合成部门 99');
+      const list = page.getByRole('listbox', { name: label, exact: true });
+      await list.getByRole('option', { name: '合成部门 99', exact: true }).waitFor();
+      await page.waitForTimeout(200);
+      // Native Tab targets differ with browser/platform keyboard preferences.
+      // Compare the exit with the same input's ordinary closed-popup Tab path.
+      await input.press('Escape'); await input.press('Tab');
+      const naturalNext = await page.evaluateHandle(() => document.activeElement);
+      await input.click(); await list.waitFor();
+      const popup = list.locator('..');
+      const completion = popup.getByRole('button', { name: '完成选择', exact: true });
+      await input.press('Tab');
+      const tabIn = await completion.evaluate(element => element === document.activeElement);
+      await completion.press('Shift+Tab');
+      const tabBack = await input.evaluate(element => element === document.activeElement);
+      await input.press('Tab'); await completion.press('Tab');
+      await list.waitFor({ state: 'detached' });
+      const tabOut = await page.waitForFunction(element => element === document.activeElement, naturalNext, { timeout: 2000 }).then(() => true, () => false);
+      await naturalNext.dispose();
+      await input.click(); await list.waitFor();
+
+      const rect = await bounds(popup);
+      await list.getByRole('option', { name: '合成部门 99', exact: true }).click();
+      const selected = await list.getByRole('option', { name: '合成部门 99', exact: true }).getAttribute('aria-selected');
+      await input.press('Escape');
+      await list.waitFor({ state: 'detached' });
+      const focusRetained = await input.evaluate(element => element === document.activeElement);
+      await input.fill('没有匹配的合成部门');
+      await list.getByText('暂无匹配结果', { exact: true }).waitFor();
+      await input.fill('合成部门 98');
+      await input.press('ArrowDown');
+      await input.press('Enter');
+      const keyboardSelected = await list.getByRole('option', { name: '合成部门 98', exact: true }).getAttribute('aria-selected');
+      const node = await input.elementHandle();
+      await page.evaluate(zoom => { document.documentElement.style.zoom = String(zoom === 1 ? 2 : 1); }, zoom);
+      await page.waitForTimeout(200);
+      const stable = await node.evaluate(element => element.isConnected && element.value === '合成部门 98');
+      const dynamic = await bounds(popup);
+      const option = list.getByRole('option', { name: '合成部门 98', exact: true });
+      await option.click();
+      const toggledOff = await option.getAttribute('aria-selected') === 'false';
+      await input.press('ArrowDown');
+      await input.press('Enter');
+      const toggledOn = await option.getAttribute('aria-selected') === 'true';
+      await input.fill('');
+      await list.getByRole('option').last().waitFor();
+      const done = popup.getByRole('button', { name: '完成选择', exact: true });
+      await done.scrollIntoViewIfNeeded();
+      const doneBounds = await bounds(done);
+      const longListBounds = await bounds(popup);
+      const boundedList = longListBounds.bottom - longListBounds.top <= Math.min(240 * (zoom === 1 ? 2 : 1), 936) + 1;
+      await done.click();
+      await list.waitFor({ state: 'detached' });
+      const completed = await input.evaluate(element => element === document.activeElement && element.value === '' && element.getAttribute('aria-expanded') === 'false');
+      const field = page.locator('.rhine-multi-select').filter({ has: input });
+      let cleared = true;
+      for (const initiallyOpen of [false, true]) {
+        await input.fill('合成部门 99');
+        await input.press('ArrowDown'); await input.press('Enter');
+        if (!initiallyOpen) await popup.getByRole('button', { name: '完成选择', exact: true }).click();
+        await field.getByRole('button', { name: '清空选择', exact: true }).click();
+        await list.waitFor({ state: 'detached' });
+        cleared = cleared && await input.evaluate(element => element === document.activeElement && element.value === '合成部门 99' && element.getAttribute('aria-expanded') === 'false') && await field.getByRole('button', { name: '清空选择', exact: true }).count() === 0;
+      }
+      for (const name of ['合成部门 99', '合成部门 98']) {
+        await input.fill(name); await input.press('ArrowDown');
+        await list.getByRole('option', { name, exact: true }).waitFor();
+        await input.press('Enter');
+        await page.waitForFunction(({ id, name }) => [...document.getElementById(id).querySelectorAll('[role=option]')].some(element => element.textContent.trim().replace(/^✓/, '').trim() === name && element.getAttribute('aria-selected') === 'true'), { id: await list.getAttribute('id'), name });
+      }
+      await popup.getByRole('button', { name: '完成选择', exact: true }).click();
+      await field.getByRole('button', { name: '移除合成部门 99', exact: true }).click();
+      const tagRemoved = await input.evaluate(element => element === document.activeElement && element.value === '合成部门 98' && element.getAttribute('aria-expanded') === 'false');
+      await input.fill(''); await input.press('Backspace');
+      const backspaceRetained = await input.getAttribute('aria-expanded') === 'true' && await field.getByRole('button', { name: '清空选择', exact: true }).count() === 0;
+      await input.press('Escape');
+      const pass = boundedList && tabIn && tabBack && tabOut && cleared && tagRemoved && backspaceRetained && contained(rect) && contained(dynamic) && selected === 'true' && keyboardSelected === 'true' && focusRetained && stable && toggledOff && toggledOn && contained(doneBounds) && completed;
+      cases.push({ ...spec, pass });
+      if (!pass) failures.push({ ...spec, rect, dynamic, selected, keyboardSelected, focusRetained, stable, toggledOff, toggledOn, doneBounds, completed, cleared, tagRemoved, backspaceRetained, tabIn, tabBack, tabOut, boundedList, longListBounds });
+      if (modal) {
+        await input.press('Escape');
+        await page.getByRole('dialog', { name: '搜索多选', exact: true }).waitFor({ state: 'detached' });
+      }
+    }
+  }
+  return { pass: !failures.length && !errors.length, cases: cases.length, failures, errors };
+}