@linhey/rhine-design 0.9.1 → 0.11.0

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-checkbox-rows.js

@@ -0,0 +1,65 @@
+// Use a production preview and run with playwright-cli run-code --filename.
+async page => {
+  page.setDefaultTimeout(10000);
+  const origin = new URL(page.url()).origin;
+  const failures = [], errors = [];
+  let scenarios = 0;
+  page.on('pageerror', error => errors.push(String(error)));
+  const check = (pass, context) => { if (!pass) failures.push(context); };
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) {
+    for (const width of [400, 520, 880]) for (const zoom of [1, 2]) {
+      await page.setViewportSize({ width, height: 1000 });
+      await page.goto(`${origin}/?theme=${theme}&proof=${Date.now()}#checkbox-rows`);
+      await page.getByRole('heading', { name: '侧栏双行多选', exact: true }).waitFor();
+      await page.evaluate(value => { document.documentElement.style.zoom = String(value); }, zoom);
+      const container = page.locator('[data-checkbox-rows]');
+      for (const requestedWidth of [160, 240, 320]) {
+        const context = { theme, width, zoom, requestedWidth };
+        await page.getByRole('combobox', { name: '侧栏宽度', exact: true }).selectOption(String(requestedWidth));
+        const geometry = await container.evaluate((root, zoom) => {
+          const rows = [...root.querySelectorAll('.rhine-check--row > label')];
+          return rows.map(row => {
+            const name = row.querySelector('.rhine-check__name'), hint = row.querySelector('.rhine-check__hint');
+            const text = row.querySelector('.rhine-check__text');
+            const r = row.getBoundingClientRect(), n = name.getBoundingClientRect(), h = hint?.getBoundingClientRect(), t = text.getBoundingClientRect();
+            const style = getComputedStyle(row), ns = getComputedStyle(name), hs = hint && getComputedStyle(hint);
+            const border = parseFloat(style.borderTopWidth);
+            return { height:r.height / zoom, fits:row.scrollWidth <= row.clientWidth + 1, nameSize:ns.fontSize, nameLine:ns.lineHeight, nameWeight:ns.fontWeight, hintSize:hs?.fontSize, hintLine:hs?.lineHeight,
+              aligned:!h || Math.abs(n.left-h.left)<1, gap:h ? (h.top-n.bottom)/zoom : null, top:(t.top-r.top)/zoom-border, bottom:(r.bottom-t.bottom)/zoom-border };
+          });
+        }, zoom);
+        check(geometry.every(row => row.fits && row.height >= 44 && row.nameSize === '14px' && row.nameLine === '22px' && row.nameWeight === (theme === 'neo-brutalism' ? '600' : '500') && row.aligned && (row.gap === null || Math.abs(row.gap-4)<.1) && (!row.hintSize || row.hintSize === '12px' && row.hintLine === '18px') && Math.abs(row.top-row.bottom)<.1), { ...context, kind:'geometry', geometry });
+        check(await container.evaluate(e => e.scrollWidth <= e.clientWidth + 1), { ...context, kind:'container-fit' });
+        scenarios++;
+      }
+      const all = container.getByRole('checkbox', { name:'全部项目', exact:true });
+      const input = container.getByRole('checkbox', { name:'示例项目 A', exact:true });
+      check(await all.evaluate(e => e.indeterminate), { theme,width,zoom,kind:'mixed' });
+      const row = input.locator('..');
+      const selectedStyle = await row.evaluate(e => ({ background:getComputedStyle(e).backgroundColor,border:getComputedStyle(e).borderColor }));
+      await row.getByText('内存卡 · 14 项', { exact:true }).click();
+      check(!await input.isChecked(), { theme,width,zoom,kind:'hint-click' });
+      await page.mouse.move(0, 0);
+      const defaultStyle = await row.evaluate(e => ({ background:getComputedStyle(e).backgroundColor,border:getComputedStyle(e).borderColor }));
+      check(defaultStyle.background !== selectedStyle.background && defaultStyle.border !== selectedStyle.border, { theme,width,zoom,kind:'selection-style' });
+      const rowBox = await row.boundingBox();
+      await row.click({ position:{x:rowBox.width / 2,y:4} });
+      check(await input.isChecked(), { theme,width,zoom,kind:'padding-click' });
+      await all.focus(); await page.keyboard.press('Tab');
+      check(await input.evaluate(e => e === document.activeElement) && await row.evaluate(e => getComputedStyle(e).boxShadow.includes('inset')), { theme,width,zoom,kind:'keyboard-focus' });
+      await page.keyboard.press('Space');
+      check(!await input.isChecked(), { theme,width,zoom,kind:'space-toggle' });
+      const disabled = container.getByRole('checkbox', { name:'不可用项目',exact:true });
+      await disabled.locator('..').scrollIntoViewIfNeeded();
+      const disabledBox = await disabled.locator('..').boundingBox();
+      await page.mouse.click(disabledBox.x + disabledBox.width / 2, disabledBox.y + disabledBox.height / 2);
+      check(!await disabled.isChecked(), { theme,width,zoom,kind:'disabled' });
+      if (width === 400 && zoom === 2) {
+        await page.getByRole('combobox', { name:'侧栏宽度',exact:true }).selectOption('160');
+        await all.focus(); await page.keyboard.press('Tab');
+        await container.screenshot({ path:`output/playwright/issue-29/${theme}.png` });
+      }
+    }
+  }
+  return { pass:!failures.length && !errors.length, scenarios, failures, errors, scope:'Chromium, three themes, 400/520/880px, 160/240/320px sidebar capped by available space, CSS zoom 100/200%; native browser menu zoom not covered.' };
+}

package/scripts/check-component-typography.js

@@ -0,0 +1,76 @@
+// Run against the production preview with playwright-cli run-code --filename.
+async page => {
+  page.setDefaultTimeout(10000);
+  const origin = new URL(page.url()).origin;
+  const failures = [], errors = [];
+  let scenarios = 0;
+  page.on('pageerror', error => errors.push(String(error)));
+  const check = (pass, context) => { if (!pass) failures.push(context); };
+  const typography = async (selector, size, leading, weight, context) => {
+    const actual = await page.locator(selector).first().evaluate(e => {
+      const s = getComputedStyle(e);
+      return { size:s.fontSize, leading:s.lineHeight, weight:s.fontWeight };
+    });
+    check(actual.size === `${size}px` && actual.leading === `${leading}px` && actual.weight === String(weight), { ...context, selector, actual, expected:{size,leading,weight} });
+  };
+  const wrappedText = async (selector, context) => {
+    const actual = await page.locator(selector).evaluate(e => {
+      const range = document.createRange();
+      range.selectNodeContents(e);
+      const lines = Array.from(range.getClientRects());
+      const box = e.getBoundingClientRect();
+      return {
+        lineCount:new Set(lines.map(r => Math.round(r.top))).size,
+        unclipped:e.scrollWidth <= e.clientWidth+1 && e.scrollHeight <= e.clientHeight+1 &&
+          lines.every(r => r.left >= box.left-1 && r.right <= box.right+1 && r.top >= box.top-1 && r.bottom <= box.bottom+1)
+      };
+    });
+    check(actual.lineCount > 1 && actual.unclipped, {...context,selector,kind:'text-wrap',actual});
+  };
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) {
+    for (const width of [400,520,880]) for (const zoom of [1,2]) {
+      const context = {theme,width,zoom}, heading = theme === 'neo-brutalism' ? 750 : 600;
+      await page.setViewportSize({width,height:1000});
+      await page.goto(`${origin}/?theme=${theme}&proof=${Date.now()}#component-typography`);
+      await page.getByRole('heading',{name:'公共组件文字配对',exact:true}).waitFor();
+      await page.evaluate(value => { document.documentElement.style.zoom=String(value); },zoom);
+      await page.getByRole('button',{name:'模拟复制',exact:true}).click();
+      await page.locator('.rhine-copy>[role]').filter({hasText:'已复制'}).waitFor();
+      await page.locator('.rhine-theme-preview[data-state=error]').waitFor();
+      for (const inherited of [false,true]) {
+        if (inherited) await page.locator('.rhine-theme').evaluate(e => { e.style.lineHeight='38px'; e.style.fontWeight='700'; });
+        const state = {...context,inherited};
+        await typography('.rhine-empty strong',16,24,heading,state);
+        await typography('.rhine-error-summary h3',16,24,heading,state);
+        for (const selector of ['.rhine-copy>[role]','.rhine-steps small','.rhine-fieldset>p','.rhine-theme-option__status','.rhine-theme-preview']) await typography(selector,12,18,400,state);
+        await typography('.rhine-media-card__status',14,22,400,state);
+      }
+      await page.locator('.rhine-theme').evaluate(e => { e.style.lineHeight=''; e.style.fontWeight=''; });
+      check(await page.locator('.rhine-empty').evaluate(e => e.scrollWidth <= e.clientWidth+1), {...context,kind:'empty-wrap'});
+      if (width === 400 && zoom === 2) await wrappedText('.rhine-empty strong',context);
+      if (width === 400 && zoom === 2) await page.locator('.rhine-empty').screenshot({path:`output/playwright/issue-31/empty-${theme}.png`});
+      const opener=page.getByRole('button',{name:'打开媒体示例',exact:true});
+      await opener.click();
+      const dialog=page.getByRole('dialog');
+      await dialog.waitFor();
+      await typography('.rhine-media-viewer__header p',12,18,400,context);
+      await typography('.rhine-media-viewer__header h2',18,26,heading,context);
+      await typography('.rhine-media-viewer__actions label',12,18,400,context);
+      if (width === 400 && zoom === 2) await wrappedText('.rhine-media-viewer__header p',context);
+      check(await dialog.evaluate(e => e.scrollWidth <= e.clientWidth+1), {...context,kind:'viewer-wrap'});
+      check(await dialog.locator('button,select').evaluateAll((elements, zoom) => elements.every(e => e.getBoundingClientRect().height/zoom >= 44),zoom), {...context,kind:'hit-targets'});
+      await dialog.getByRole('button',{name:'下一项',exact:true}).click();
+      check(await dialog.getByRole('heading',{name:'下一项合成媒体',exact:true}).isVisible(), {...context,kind:'next'});
+      if (width === 400 && zoom === 2) await page.locator('.rhine-media-viewer__header').screenshot({path:`output/playwright/issue-31/media-${theme}.png`});
+      const close=dialog.getByRole('button',{name:'关闭媒体查看器',exact:true});
+      await close.scrollIntoViewIfNeeded();
+      check(await close.evaluate(e => { const r=e.getBoundingClientRect(); return r.top >= 0 && r.bottom <= innerHeight && r.left >= 0 && r.right <= innerWidth; }), {...context,kind:'close-visible'});
+      await close.click(); await dialog.waitFor({state:'detached'});
+      await page.waitForFunction(() => document.activeElement?.textContent === '打开媒体示例');
+      await opener.click(); await page.keyboard.press('Escape'); await dialog.waitFor({state:'detached'});
+      await page.waitForFunction(() => document.activeElement?.textContent === '打开媒体示例');
+      scenarios++;
+    }
+  }
+  return {pass:!failures.length&&!errors.length,scenarios,failures,errors,scope:'Chromium, three themes, 400/520/880px, CSS zoom 100/200%; synthetic content and inherited-style stress. Native menu zoom is not covered.'};
+}

package/scripts/check-dense-filters.js

@@ -0,0 +1,60 @@
+// Run against a production preview: playwright-cli run-code --filename=scripts/check-dense-filters.js
+async page => {
+  page.setDefaultTimeout(10000);
+  const origin = new URL(page.url()).origin;
+  const failures = [], errors = [];
+  let scenarios = 0;
+  page.on('pageerror', error => errors.push(String(error)));
+  const check = (pass, context) => { if (!pass) failures.push(context); };
+  for (const theme of ['rhine', 'arknights', 'neo-brutalism']) {
+    for (const width of [400, 520, 880]) for (const zoom of [1, 2]) {
+      const context = { theme, width, zoom };
+      await page.setViewportSize({ width, height: 1000 });
+      await page.goto(`${origin}/?theme=${theme}&proof=${Date.now()}-${scenarios}#compact-filters`);
+      await page.getByRole('heading', { name: '密集筛选控件', exact: true }).waitFor();
+      await page.evaluate(value => { document.documentElement.style.zoom = String(value); }, zoom);
+      const tags = page.getByRole('list', { name: '部门已选项' });
+      check(await tags.getByRole('listitem').count() === 2, { ...context, kind: 'bounded-tags' });
+      check(await tags.evaluate(e => e.scrollWidth <= e.clientWidth + 1 && [...e.children].every(li => li.scrollWidth <= li.clientWidth + 1)), { ...context, kind: 'tags-fit' });
+      await page.getByRole('button', { name: '展开已选项' }).click();
+      check(await tags.getByRole('listitem').count() === 90 && await tags.evaluate(e => e.clientHeight <= 224 && e.scrollHeight > e.clientHeight), { ...context, kind: 'bounded-expansion' });
+      await page.getByRole('button', { name: '移除合成部门 90', exact: true }).click();
+      check(await page.getByRole('combobox', { name: '部门', exact: true }).evaluate(e => document.activeElement === e), { ...context, kind: 'remove-focus' });
+      await page.getByRole('button', { name: '清空部门', exact: true }).click();
+      await page.getByRole('button', { name: '全选部门', exact: true }).click();
+      check(await tags.getByRole('listitem').count() === 2, { ...context, kind: 'reset-expansion' });
+      const range = page.getByRole('group', { name: '日期区间', exact: true });
+      const start = range.getByLabel('开始日期', { exact: true });
+      await start.fill('2026-10-01'); await start.focus();
+      await page.keyboard.press('ArrowRight'); await page.keyboard.press('ArrowRight'); await page.keyboard.press('ArrowUp');
+      check(await start.inputValue() === '2026-10-02', { ...context, kind: 'native-last-segment' });
+      check(await range.evaluate(e => e.scrollWidth <= e.clientWidth + 1), { ...context, kind: 'date-fit' });
+      if (width === 400 && zoom === 2) await range.screenshot({ path: `output/playwright/issue-27/date-${theme}.png` });
+      const trigger = page.getByRole('button', { name: '更多筛选', exact: true });
+      await trigger.click();
+      const dialog = page.getByRole('dialog', { name: '紧凑筛选示例', exact: true });
+      await dialog.evaluate(e => Promise.all(e.getAnimations().map(a => a.finished)));
+      check(!await dialog.getAttribute('aria-describedby') && await dialog.locator('.rhine-list-filter-bar__feedback').count() === 0, { ...context, kind: 'omitted-feedback' });
+      const segments = dialog.locator('fieldset.rhine-segmented');
+      check(await segments.evaluate(e => {
+        const items = [...e.querySelectorAll('label')].map(label => ({ label: label.getBoundingClientRect(), span: label.querySelector('span').getBoundingClientRect() }));
+        return items.every(item => Math.abs(item.label.width - items[0].label.width) < 1 && Math.abs(item.label.width - item.span.width) < 1 && Math.abs(item.label.height - item.span.height) < 1);
+      }), { ...context, kind: 'equal-segment-backgrounds' });
+      await segments.getByRole('radio', { name: '今天', exact: true }).focus();
+      await page.keyboard.press('ArrowRight');
+      check(await segments.getByRole('radio', { name: '昨天', exact: true }).isChecked(), { ...context, kind: 'native-radio-keyboard' });
+      check(await dialog.evaluate(e => e.scrollWidth <= e.clientWidth + 1), { ...context, kind: 'drawer-fit' });
+      await page.keyboard.press('Escape'); await dialog.waitFor({ state: 'detached' });
+      await trigger.waitFor();
+      await page.waitForFunction(() => document.activeElement?.textContent?.includes('更多筛选'));
+      for (const [state, text] of [['加载', '正在更新结果…'], ['失败', '暂时无法更新合成结果，请重试。']]) {
+        await page.getByRole('button', { name: state, exact: true }).click();
+        await trigger.click();
+        check(await dialog.getByText(text, { exact: true }).isVisible(), { ...context, kind: `feedback-${state}` });
+        await page.keyboard.press('Escape'); await dialog.waitFor({ state: 'detached' });
+      }
+      scenarios++;
+    }
+  }
+  return { pass: failures.length === 0 && errors.length === 0, scenarios, failures, errors, scope: 'Chromium, three themes, 400/520/880px, 100/200% CSS zoom; synthetic data only. Native menu zoom is not covered.' };
+}

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