@linhey/rhine-design 0.10.0 → 0.11.0

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-review-package.mjs

@@ -0,0 +1,11 @@
+import { execFileSync } from 'node:child_process';
+import assert from 'node:assert/strict';
+const [pack] = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], { encoding: 'utf8' }));
+const files = pack.files.map(file => file.path);
+for (const path of files) {
+  assert(!path.split('/').some(part => part === 'node_modules' || part.startsWith('.vite') || part.startsWith('.playwright')), `Package includes development cache: ${path}`);
+}
+for (const path of ['review/index.ts', 'review/vite.mjs', 'review/vite.d.mts', 'review/dev-client.mjs', 'examples/review/http/catalog.tsx', 'examples/review/platform/catalog.tsx', 'examples/review/product.css']) {
+  assert(files.includes(path), `Package omits review entry/example: ${path}`);
+}
+console.log('Review package verified: public entries/examples included, development caches excluded.');

package/scripts/check-review-recovery.js

@@ -0,0 +1,47 @@
+// Run against the final static examples served on 18342. Chromium/Firefox/WebKit use the same checks.
+async page => {
+  const failures = [], errors = [];
+  const check = (value, name) => { if (!value) failures.push(name); };
+  page.on('pageerror', error => errors.push(String(error)));
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await page.goto('http://127.0.0.1:18342/review-platform/');
+  const frame = page.frameLocator('iframe');
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  check(await page.getByRole('combobox', { name: '动态偏好' }).count() === 0, 'advanced settings collapsed');
+  check((await page.getByLabel('画布尺寸').textContent()).includes('等效内容宽度'), 'canvas dimensions visible');
+  await page.getByRole('link', { name: '清理错误留存', exact: true }).click();
+  await frame.getByText('离开此场景后，合成清理错误应保留到显式确认。').waitFor();
+  await page.getByRole('link', { name: '桌面工作区', exact: true }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  await page.getByRole('alert').filter({ hasText: '合成清理失败' }).waitFor();
+  await page.getByRole('combobox', { name: '界面主题' }).selectOption('arknights');
+  await frame.locator('.rhine-theme[data-rhine-theme=arknights]').waitFor();
+  check(await page.getByRole('alert').filter({ hasText: '合成清理失败' }).count() === 1, 'ready does not overwrite error');
+  await page.locator('.rhine-review-log summary').click();
+  check(await page.locator('.rhine-review-log li[data-kind=error] strong').textContent() === '清理错误留存', 'error retains origin scene');
+  await page.getByRole('button', { name: '确认并清除反馈' }).click();
+  check(await page.getByRole('alert').count() === 0, 'explicit acknowledgement clears errors');
+  await page.getByRole('link', { name: '清理挂起恢复', exact: true }).click();
+  await frame.getByText('此场景模拟清理挂起，请切换到桌面工作区验证恢复。').waitFor();
+  await page.getByRole('link', { name: '桌面工作区', exact: true }).click();
+  await page.getByRole('alert').filter({ hasText: '初始化或清理超过 10 秒' }).waitFor({ timeout: 15000 });
+  check(await frame.getByRole('heading', { name: '桌面工作区' }).count() === 0, 'never initializes in uncleared context');
+  const oldFrame = await page.locator('iframe').elementHandle();
+  await page.getByRole('button', { name: '重新载入画布' }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  check(await oldFrame.evaluate(element => !element.isConnected), 'recovery replaces browsing context');
+  check(await page.getByRole('combobox', { name: '界面主题' }).inputValue() === 'arknights', 'recovery keeps URL preferences');
+  check(await page.getByRole('alert').count() === 1, 'recovery retains prior timeout record');
+  await page.locator('.rhine-review-options summary').click();
+  await page.getByRole('combobox', { name: 'CSS 缩放' }).selectOption('2');
+  await page.getByRole('combobox', { name: '画布宽度' }).selectOption('520');
+  await page.waitForFunction(() => document.querySelector('[aria-label="画布尺寸"]')?.textContent.includes('等效内容宽度约 259 CSS px'));
+  await page.route('**/review-platform/canvas.html', route => route.abort());
+  await page.goto('http://127.0.0.1:18342/review-platform/');
+  await page.getByRole('alert').filter({ hasText: '连接画布超时' }).waitFor({ timeout: 15000 });
+  await page.unroute('**/review-platform/canvas.html');
+  await page.getByRole('button', { name: '重新载入画布' }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  check(await page.getByRole('status').filter({ hasText: '已就绪' }).count() === 1, 'initial load failure recovers');
+  return { failures, errors, browser: await page.evaluate(() => navigator.userAgent) };
+}

package/scripts/check-review.js

@@ -0,0 +1,153 @@
+// Build both examples and serve dist at loopback port 18342; HTTP dev uses 18340.
+// playwright-cli run-code --filename scripts/check-review.js
+async page => {
+  const failures = [], errors = [], requests = [], consoleErrors = [], consoleChecks = [];
+  page.on('console', message => {
+    if (message.type() !== 'error') return;
+    // Firefox renders an Error argument as only "Error"; inspect the actual exception too.
+    consoleChecks.push(Promise.all(message.args().map(argument => argument.evaluate(value => value instanceof Error ? value.message : '').catch(() => ''))).then(messages => {
+      if (!message.text().includes('合成渲染失败') && !messages.includes('合成渲染失败')) consoleErrors.push(message.text());
+    }));
+  });
+  const check = (condition, message) => { if (!condition) failures.push(message); };
+  page.on('pageerror', error => errors.push(String(error)));
+  page.on('request', request => requests.push(request.url()));
+  const http = 'http://127.0.0.1:18342/review-http/';
+  const advanced = async () => { const details = page.locator('.rhine-review-options'); if (!await details.evaluate(element => element.open)) await details.locator('summary').click(); };
+  const motion = async value => { await advanced(); await page.getByRole('combobox', { name: '动态偏好' }).selectOption(value); };
+  let cases = 0;
+  for (const base of [http, 'http://127.0.0.1:18340/review-http/']) {
+    await page.goto(base);
+    const frame = page.frameLocator('iframe');
+    await frame.getByRole('heading', { name: '项目工作台' }).waitFor();
+    check(await page.locator('.rhine-review-header').evaluate(element => getComputedStyle(element).display === 'flex'), `${base} stylesheet loaded`);
+    await frame.getByRole('button', { name: '加载延迟模块' }).click();
+    await frame.getByText('延迟模块已加载 · 资源 base 与产品路由互相独立').waitFor();
+    await frame.getByRole('textbox', { name: '未保存草稿' }).fill('浏览器保留草稿');
+    await frame.getByRole('button', { name: '新建项目', exact: true }).click();
+    const input = frame.getByRole('textbox', { name: '项目名称' });
+    const handle = await input.elementHandle();
+    await input.focus();
+    for (const theme of ['rhine', 'arknights', 'neo-brutalism']) {
+      await page.getByRole('combobox', { name: '界面主题' }).selectOption(theme);
+      await page.getByRole('combobox', { name: '画布宽度' }).selectOption('520');
+      check(await input.inputValue() === '浏览器保留草稿', `${base} ${theme} draft`);
+      check(await handle.evaluate(element => element.isConnected && element === element.ownerDocument.activeElement), `${base} ${theme} node/focus`);
+      check(await frame.locator('.rhine-theme').count() === 1, `${base} single theme root`);
+      await frame.locator(`.rhine-theme[data-rhine-theme="${theme}"]`).waitFor();
+    }
+    await frame.getByRole('button', { name: '保存项目', exact: true }).click();
+    await frame.getByRole('dialog').waitFor({ state: 'detached' });
+    check(await frame.getByText('浏览器保留草稿', { exact: true }).count() === 1, `${base} form submit`);
+    await frame.getByRole('button', { name: '触发未实现操作' }).click();
+    await page.getByRole('alert').filter({ hasText: '未实现模拟请求' }).waitFor();
+    // Verify real navigation defaults never escape the runtime, while same-document anchors work.
+    const child = page.frames().find(frame => frame !== page.mainFrame());
+    const before = child.url();
+    for (const href of ['/product/detail', '/api/export', 'https://synthetic.invalid/export']) {
+      await child.evaluate(href => { const link = document.createElement('a'); link.href = href; link.textContent = '测试导航'; document.body.append(link); link.click(); link.remove(); }, href);
+      check(child.url() === before, `${base} blocked ${href}`);
+    }
+    await child.evaluate(() => { const link = document.createElement('a'); link.href = '#local-section'; document.body.append(link); link.click(); link.remove(); });
+    await child.waitForFunction(() => location.hash === '#local-section');
+    check(child.url().endsWith('#local-section'), `${base} local anchor`);
+    const beforeReset = await frame.getByRole('textbox', { name: '未保存草稿' }).elementHandle();
+    await page.getByRole('button', { name: '重置场景' }).click();
+    await beforeReset.evaluate(element => new Promise((resolve, reject) => { const start = performance.now(); const poll = () => { if (!element.isConnected) resolve(true); else if (performance.now() - start > 1500) reject(new Error('reset did not unmount previous session')); else requestAnimationFrame(poll); }; poll(); }));
+    await frame.getByRole('textbox', { name: '未保存草稿' }).waitFor();
+    check(await frame.getByRole('textbox', { name: '未保存草稿' }).inputValue() === '', `${base} reset`);
+    for (const state of ['loading', 'empty', 'error', 'dense', 'normal']) {
+      await page.getByRole('combobox', { name: '列表状态' }).selectOption(state);
+      const expected = { loading: '正在加载合成项目…', empty: '暂无项目', error: '合成服务暂不可用', dense: '合成项目 1 · 跨团队设计评审与持续验证的长标题示例', normal: '合成项目 1' }[state];
+      await frame.getByText(expected, { exact: true }).waitFor();
+    }
+    await page.getByRole('combobox', { name: '角色', exact: true }).selectOption('reader');
+    await frame.getByText('合成数据 · 只读 · 独立产品路由', { exact: true }).waitFor();
+    check(await frame.getByRole('button', { name: '新建项目', exact: true }).isDisabled(), `${base} read-only`);
+    const deepLink = page.url(); await page.reload();
+    await frame.getByRole('heading', { name: '项目工作台' }).waitFor();
+    check(page.url() === deepLink, `${base} refresh URL`);
+    await page.getByRole('combobox', { name: '角色', exact: true }).selectOption('editor');
+    await page.goBack();
+    check(await page.getByRole('combobox', { name: '角色', exact: true }).inputValue() === 'reader', `${base} history back`);
+    await page.goForward();
+    check(await page.getByRole('combobox', { name: '角色', exact: true }).inputValue() === 'editor', `${base} history forward`);
+    cases++;
+  }
+  // Final artifact visual / keyboard matrix (CSS zoom, not browser zoom).
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) for (const width of [400, 520, 880, 1280]) for (const zoom of [1, 2]) {
+    await page.setViewportSize({ width, height: 1000 });
+    await page.goto(`${http}#scene=projects&theme=${theme}&width=fit&zoom=${zoom}&d.status=dense`);
+    const frame = page.frameLocator('iframe');
+    await frame.getByRole('button', { name: '新建项目', exact: true }).click();
+    const dialog = frame.getByRole('dialog');
+    await dialog.waitFor();
+    await frame.getByRole('textbox', { name: '项目名称' }).fill('窄屏键盘');
+    await page.keyboard.press('Tab');
+    check(await dialog.evaluate(element => element.contains(element.ownerDocument.activeElement)), `${theme}/${width}/${zoom} focus trap`);
+    await page.keyboard.press('Escape');
+    await dialog.waitFor({ state: 'detached' });
+    try { await frame.getByRole('button', { name: '新建项目', exact: true }).evaluate(element => new Promise((resolve, reject) => { const start = performance.now(); const poll = () => { if (element === document.activeElement) resolve(true); else if (performance.now() - start > 1500) reject(new Error('focus timeout')); else requestAnimationFrame(poll); }; poll(); })); } catch { check(false, `${theme}/${width}/${zoom} focus return`); }
+    const overflow = await page.evaluate(() => document.documentElement.scrollWidth > innerWidth + 1);
+    check(!overflow, `${theme}/${width}/${zoom} shell overflow`);
+    if (width === 400 && zoom === 2) await page.screenshot({ path: `output/playwright/review-${theme}-400-css200.png`, fullPage: true });
+    cases++;
+  }
+  await page.setViewportSize({ width: 400, height: 1000 });
+  await page.goto('http://127.0.0.1:18342/review-platform/');
+  await page.getByRole('button', { name: '场景目录' }).click();
+  await page.getByRole('textbox', { name: '搜索场景' }).fill('没有此场景');
+  await page.getByText('没有匹配场景').waitFor();
+  await page.getByRole('textbox', { name: '搜索场景' }).fill('');
+  await page.getByRole('textbox', { name: '搜索场景' }).focus();
+  await page.keyboard.press('Escape');
+  check(await page.getByRole('button', { name: '场景目录' }).evaluate(element => element === document.activeElement), 'mobile directory escape focus');
+  await page.getByRole('button', { name: '场景目录' }).click();
+  await page.getByRole('link', { name: '慢速初始化', exact: true }).click();
+  check(await page.getByRole('button', { name: '场景目录' }).getAttribute('aria-expanded') === 'false', 'mobile directory closes after navigation');
+  await page.setViewportSize({ width: 1280, height: 1000 });
+  await page.goto('http://127.0.0.1:18342/review-platform/');
+  const frame = page.frameLocator('iframe');
+  const actualCanvas = frame.locator('canvas');
+  await actualCanvas.waitFor();
+  const frames = async () => Number(await actualCanvas.getAttribute('data-frames'));
+  let count = await frames(); await page.waitForTimeout(120); check(await frames() > count, 'canvas plays');
+  await motion('paused');
+  await frame.getByText('已暂停', { exact: true }).waitFor();
+  count = await frames(); await page.waitForTimeout(120); check(await frames() === count, 'canvas pauses');
+  await motion('full');
+  count = await frames(); await page.waitForTimeout(120); check(await frames() > count, 'canvas resumes');
+  await motion('reduced');
+  await frame.getByText('减少动态', { exact: true }).waitFor();
+  count = await frames(); await page.waitForTimeout(120); check(await frames() === count, 'manual reduced');
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+  await motion('system');
+  count = await frames(); await page.waitForTimeout(120); check(await frames() === count, 'system reduced');
+  await page.emulateMedia({ reducedMotion: 'no-preference' });
+  count = await frames(); await page.waitForTimeout(120); check(await frames() > count, 'system resumes');
+  const oldCanvas = await actualCanvas.elementHandle();
+  await frame.getByRole('textbox', { name: '工作区名称' }).fill('内存工作区');
+  await frame.getByRole('button', { name: '保存工作区' }).click();
+  await frame.getByText('内存工作区已保存').waitFor();
+  await page.getByRole('link', { name: '慢速初始化', exact: true }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor({ state: 'detached' });
+  const oldCount = await oldCanvas.evaluate(element => element.dataset.frames);
+  await page.getByRole('link', { name: '桌面工作区', exact: true }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  await page.waitForTimeout(4200);
+  check(await oldCanvas.evaluate(element => element.dataset.frames) === oldCount, 'unmounted canvas stops');
+  check(await frame.getByText('慢速初始化完成').count() === 0, 'late setup discarded');
+  await page.getByRole('link', { name: '渲染错误边界', exact: true }).click();
+  await frame.getByRole('alert').waitFor();
+  await page.getByRole('alert').filter({ hasText: '场景渲染失败' }).waitFor();
+  await page.getByRole('link', { name: '桌面工作区', exact: true }).click();
+  await frame.getByRole('heading', { name: '桌面工作区' }).waitFor();
+  await page.screenshot({ path: 'output/playwright/review-platform.png', fullPage: true });
+  const outbounds = requests.filter(url => !url.startsWith('http://127.0.0.1:1834') && !url.startsWith('data:'));
+  const businessRequests = requests.filter(url => /\/api\//.test(url));
+  check(!outbounds.length && !businessRequests.length, 'no real business/network egress');
+  check(!errors.length, `page errors: ${errors}`);
+  await Promise.all(consoleChecks);
+  check(!consoleErrors.length, `console errors: ${consoleErrors}`);
+  return { cases, failures, errors, consoleErrors, outbounds, businessRequests, requests: requests.length };
+}

package/skills/rhine-design/references/API_MAP.md

@@ -34,6 +34,8 @@ All paths are relative to the matching package root. `package.json` exports, `co
 | Toast | `components/Toast.tsx` |
 | Button, Badge, Surface, SelectionCard, TextField, Tabs, SegmentedControl, Notice, Progress, Skeleton, Disclosure, EmptyState | `components/components.tsx`；Surface 的 `padding="none"` 仅取消表格容器外围内距，默认不变；此选项自 0.9.1 提供，见 `CHANGELOG.md` |
 
+Additions in 0.11.0: `Tabs` / `TabItem` `description` and `status`, `Toast placement="floating"`, and `SegmentedControl size="compact"`. They are absent from npm 0.10.0. Pin 0.11.0 and read `CHANGELOG.md` before upgrading.
+
 Primary contracts: `components/README.md` and `components/COMMON_COMPONENTS.md`. Find behavioral evidence in `tests/` and composition examples in `preview/`.
 
 ```sh
@@ -55,3 +57,5 @@ API decisions that commonly matter:
 - Components in `preview/` are demonstrations. Public API must resolve through a `package.json` export; theme APIs use the separate `/theme` entry.
 
 Available since 0.8.0 (check installed exports): `ThemePicker` / `ThemePreview` in `components/ThemePicker.tsx`, contract `docs/THEME_PICKER.md`; `Dialog.navigation` in `components/Overlays.tsx`, contract `docs/SETTINGS_DIALOG.md`; shared floating CSS zoom behavior in `docs/FLOATING_OVERLAYS.md`.
+
+Product review tooling (since 0.11.0): `/review` exports `defineReview`, URL helpers and scene/session types from `review/index.ts`; `/review/vite` exports Node-only `reviewPlugin` and `reviewProductionGuard` from `review/vite.mjs`, types in `review/vite.d.mts`. Never import the Vite entry into production UI. Read `docs/REVIEW_TOOL.md`; npm 0.10.0 does not contain these entries.