@fusion.dev/helix-cli 0.215.3 → 0.216.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-cli",
   "description": "The Helix command line, for a workspace that reaches it through npm, and the visual tests it runs.",
-  "version": "0.215.3",
+  "version": "0.216.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -30,7 +30,7 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-templates": "0.215.3"
+    "@fusion.dev/helix-templates": "0.216.0"
   },
   "homepage": "https://fusion.dev",
   "keywords": [
@@ -44,11 +44,11 @@
     "visual-regression"
   ],
   "optionalDependencies": {
-    "@fusion.dev/helix-cli-darwin-arm64": "0.215.3",
-    "@fusion.dev/helix-cli-darwin-x64": "0.215.3",
-    "@fusion.dev/helix-cli-linux-arm64": "0.215.3",
-    "@fusion.dev/helix-cli-linux-x64": "0.215.3",
-    "@fusion.dev/helix-cli-win32-x64": "0.215.3"
+    "@fusion.dev/helix-cli-darwin-arm64": "0.216.0",
+    "@fusion.dev/helix-cli-darwin-x64": "0.216.0",
+    "@fusion.dev/helix-cli-linux-arm64": "0.216.0",
+    "@fusion.dev/helix-cli-linux-x64": "0.216.0",
+    "@fusion.dev/helix-cli-win32-x64": "0.216.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.132",

package/visual/README.md

@@ -286,6 +286,35 @@ picture is committed.
   that differs stops and names what differs, because every picture would
   differ for that reason alone.
 
+## Picture a screen in a state
+
+A page pictured as it loads shows every menu closed and every field empty. To
+picture it with a menu open, a field filled, or a list scrolled, save the screen
+and keep the file beside the entry's baselines as `<stem>.state.json`, where
+`<stem>` is what the entry's baseline files start with. The run puts it back
+once the page has upgraded and before it waits for the page to hold still.
+
+Save a screen from the page itself, in the browser's console or from a test.
+Helix puts its capture on the page only when asked, so a page in production
+hands no script the text in its fields. Ask with `exposeState` from
+`@fusion.dev/helix-core`, or, from a tool that drives a page it did not write,
+set the slot to `true` before the page loads, as the run does:
+
+```js
+import { exposeState } from '@fusion.dev/helix-core'
+
+exposeState()
+const { captureState } = globalThis[Symbol.for('fusion.dev/helix/state')]
+copy(JSON.stringify(captureState(), null, 2))
+```
+
+The state is put back through each element's own requests, so a page that
+controls a component hears the same events it hears from a reader. An entry
+whose state names an element the page no longer draws, or one the page refuses,
+fails rather than picturing a different screen. A password field, a field whose
+`autocomplete` names a password, a one-time code or a payment card, and anything
+under `snapshot="off"` are never saved.
+
 ## The report
 
 Every `helix visual test` and `helix visual update` writes a report into the config's

package/visual/driver.mjs

@@ -56,14 +56,15 @@ const STYLE_ID = 'helix-visual-harness'
 const DIAGNOSTICS = '__helix-diagnostics'
 
 /* **Read and written synchronously, on the descriptors themselves.** Bun
-   1.1.43, the runtime Fusion's CI pins, hands a script nothing from a piped
-   standard input until the pipe closes, so a stream reader would wait for a
-   request the binary is waiting to have answered. `readSync` on descriptor 0
-   returns each line as it arrives, in Bun and in Node. A request is read only
-   when the last one is answered, which is the one time this has nothing else
-   to do. Answers are written with `writeSync` for the same reason: the next
-   thing after an answer is that blocking read, and an answer still queued
-   behind it would never reach the binary. */
+   1.1.43, the runtime Fusion's CI pinned when this was written, hands a
+   script nothing from a piped standard input until the pipe closes, so a
+   stream reader would wait for a request the binary is waiting to have
+   answered. `readSync` on descriptor 0 returns each line as it arrives, in
+   Bun and in Node. A request is read only when the last one is answered,
+   which is the one time this has nothing else to do. Answers are written
+   with `writeSync` for the same reason: the next thing after an answer is
+   that blocking read, and an answer still queued behind it would never
+   reach the binary. */
 for (const name of ['debug', 'info', 'log']) {
   console[name] = console.error
 }
@@ -405,6 +406,43 @@ const codeBlocks = (page, { minimum, selector }) =>
     { minimum, selector },
   )
 
+/**
+ * Asks every page in `context` for its state tools before the page loads,
+ * since Helix puts them on `globalThis` only where something asked for them.
+ */
+const askForState = (context) =>
+  context.addInitScript(() => {
+    globalThis[Symbol.for('fusion.dev/helix/state')] ??= true
+  })
+
+/**
+ * Puts back the screen an entry's `<stem>.state.json` saved, through the
+ * page's own Helix: `restoreState` from `@fusion.dev/helix-core`, which the
+ * first copy of Helix to load puts on `globalThis`, since `askForState`
+ * asked for it. An entry whose state names
+ * an element the page no longer draws, or one the page refused, fails, since
+ * its picture would not be of the screen the state describes.
+ */
+const restore = async (page, state) => {
+  const report = await page.evaluate(async (saved) => {
+    const tools = globalThis[Symbol.for('fusion.dev/helix/state')]
+    if (!tools) {
+      return { error: 'the page has no Helix to restore its state with' }
+    }
+    return tools.restoreState(saved)
+  }, state)
+  if (report.error) {
+    throw new Error(report.error)
+  }
+  const wrong = [
+    ...report.missed.map((path) => `${path} is not on the page`),
+    ...report.refused.map((path) => `${path} refused its state`),
+  ]
+  if (wrong.length > 0) {
+    throw new Error(`the saved state did not take: ${wrong.join('; ')}`)
+  }
+}
+
 /** One entry, every shot of it from one navigation. */
 const take = async (lane, item, { elements, readyProperty }, progress) => {
   const { page } = lane
@@ -442,6 +480,9 @@ const take = async (lane, item, { elements, readyProperty }, progress) => {
             `nothing defines ${missing.map((tag) => `<${tag}>`).join(', ')}, after ${UPGRADES} seconds of waiting`,
           )
         }
+        if (item.state) {
+          await restore(page, item.state)
+        }
       } else if (shot.harness !== null) {
         await page.evaluate(
           ([id, rules]) => {
@@ -622,6 +663,7 @@ const lanes = async (count) => {
       reducedMotion: 'reduce',
       viewport: { height: 800, width: 1280 },
     })
+    await askForState(context)
     if (state.network === 'origin') {
       await context.route('**/*', (route) => {
         let origin