reflection-check 0.0.3 → 0.0.5

package/docs/target-ir-and-adapters.md

@@ -30,7 +30,7 @@ The IR currently supports four families:
 | --- | --- | --- | --- |
 | `browser-route` | browser routes | `smoke`, `full` | Render a route and evaluate DOM/layout/console expectations. |
 | `route-visual` | browser visual smoke cases | `smoke`, `full` | Compare route screenshots against read-only baselines. |
-| `component-visual` | Storybook component cases | `visual`, `full` | Compare component story screenshots against read-only baselines. |
+| `component-visual` | Storybook or portal component cases | `visual`, `full` | Compare component screenshots against read-only baselines. |
 | `design-command` | design command checks | `design`, `full` | Run project-owned design contract commands. |
 
 All targets include:
@@ -59,20 +59,20 @@ console.log(ir.targets.map((target) => `${target.family}:${target.id}`));
 // ]
 ```
 
-The compiler preserves visual metadata that matters to later review, including zero-valued thresholds. Do not use truthiness checks when copying optional numeric metadata; use explicit `!== undefined` checks so values like `0` survive.
+The compiler preserves visual metadata that matters to later review, including component source (`storybook` or `portal`), portal paths, story ids, zero-valued thresholds, explicit component `viewportSize` values, and component `framing`. Do not use truthiness checks when copying optional numeric metadata; use explicit `!== undefined` checks so values like `0` survive.
 
 ## Adapter contract
 
 Adapters should compile their input into the same target shape and mark targets with `source: 'adapter'`.
 
-Adapters must not make core runners aware of the source format. The runner should receive normalized route/story/visual/command information and should not branch on adapter names.
+Adapters must not make core runners aware of the source format. The runner should receive normalized route/component/visual/command information and should not branch on adapter names.
 
 A good adapter is:
 
 - **optional** — normal Reflection config works without it;
 - **validated** — malformed adapter input fails before runner execution;
 - **neutral** — no external product names leak into core commands or reports unless the user explicitly names their own target ids;
-- **lossless enough for review** — route paths, viewports, expectations, baselines, thresholds, and blocking semantics are preserved in IR.
+- **lossless enough for review** — route paths, component portal paths or Storybook ids, viewports, component viewport sizes, component framing, expectations, baselines, thresholds, and blocking semantics are preserved in IR.
 
 ## Route manifest adapter proof
 

package/docs/visual-contract.md

@@ -82,7 +82,7 @@ If the matching browser route result is missing, the visual check becomes a revi
 
 ## Component visual baselines
 
-Component visual cases use Storybook. Reflection resolves the configured `storyId` through Storybook `/index.json`, opens the iframe URL, captures a screenshot, and compares it with the configured baseline.
+Component visual cases can use Storybook or a Reflection-generated portal. Storybook cases resolve `storyId` through Storybook `/index.json`; portal cases open a configured `path` in a generated Vite runtime.
 
 ```ts
 component: {
@@ -96,7 +96,13 @@ component: {
     {
       id: 'button-primary',
       storyId: 'atoms-button--primary',
-      viewport: 'component',
+      viewport: 'button-default',
+      viewportSize: { width: 390, height: 220 },
+      framing: {
+        background: '#ffffff',
+        align: 'center',
+        padding: 0
+      },
       baselineRoot: 'tests/fixtures/baselines',
       baseline: 'components/button/primary.chromium-linux.light.png',
       threshold: { maxDiffPixelRatio: 0.005 }
@@ -105,6 +111,44 @@ component: {
 }
 ```
 
+Portal cases use the same case fields, but replace `storyId` with `path` and configure `component.portal`:
+
+```ts
+component: {
+  portal: {
+    entry: './tests/reflection/react-portal.tsx',
+    readyUrl: 'http://127.0.0.1:6106'
+  },
+  cases: [
+    {
+      id: 'button-primary',
+      path: '/reflection/button/primary/light',
+      viewport: 'button-default',
+      viewportSize: { width: 390, height: 220 },
+      framing: {
+        rootSelector: '#reflection-root',
+        background: '#ffffff',
+        align: 'center',
+        padding: 0
+      },
+      baselineRoot: 'tests/fixtures/baselines',
+      baseline: 'components/button/primary.chromium-linux.light.png',
+      threshold: { maxDiffPixels: 0, maxDiffPixelRatio: 0 },
+      strict: true
+    }
+  ]
+}
+```
+
+For component baselines exported from a design tool, treat `viewportSize` and `framing` as part of the visual contract. The exported PNG width/height and the runtime screenshot width/height must be identical. `viewport` may be a built-in preset such as `component` or a semantic custom label such as `button-default`; when `viewportSize` is present, the explicit dimensions win. Portal cases require `viewportSize`, and the generated frame uses those dimensions directly.
+
+`framing` is optional and only affects the screenshot when configured. It applies fixed canvas styles before capture so the runtime component can match a Figma frame:
+
+- `rootSelector`: root to frame; defaults to `#storybook-root` for Storybook and `#reflection-root` for portal cases.
+- `background`: CSS background matching the Figma frame fill.
+- `align`: `center` or `start`; `center` places the component in the middle of the frame.
+- `padding`: integer pixel padding inside the frame.
+
 ### Pseudo states
 
 Prefer story-controlled states. A story named `Button/Hover` or `Button/Focused` is usually more deterministic than moving the mouse in the browser.
@@ -130,6 +174,7 @@ When the browser must force a state, Reflection requires effective animation sta
 Reports include `statePolicy` metadata:
 
 - `story-controlled` when no `browserState` is configured;
+- `portal-controlled` when the generated portal renders the state;
 - `browser-forced-with-stabilization` when Reflection applies hover/focus in the browser.
 
 ## Thresholds

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflection-check",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "CLI for evidence-backed rendered UI validation.",
   "license": "MIT",
   "type": "module",
@@ -45,8 +45,9 @@
     "commander": "^14.0.3",
     "jiti": "^2.7.0",
     "pixelmatch": "^7.2.0",
-    "pngjs": "^7.0.0",
     "playwright": "^1.60.0",
+    "pngjs": "^7.0.0",
+    "vite": "^8.0.16",
     "zod": "^4.4.3"
   },
   "devDependencies": {