waygraph 0.15.2 → 0.15.4

package/templates/quickstart/src/flows/login.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { Engine, withTitle } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
 import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
@@ -8,7 +8,16 @@ const engine = new Engine();
 
 // The step-mode overlay prepends "Episode N: " itself - the title here is
 // just the label, not the full heading.
+// map() + ctx stubs on the Method blocks (see fill-username / fill-password /
+// submit-login) - no HighlightFixtureMap.
 export const loginFlow = withTitle(
-  engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginForFlow, end]),
+  engine
+    .map()
+    .start()
+    .gotoPage(NavLoginBlock)
+    .method(FillUsernameBlock)
+    .method(FillPasswordBlock)
+    .method(SubmitLoginForFlow)
+    .end(),
   "Sign In",
 );

package/templates/quickstart/src/flows/shop.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle } from "waygraph";
+import { Engine, withTitle } from "waygraph";
 import { AddToCartBlock } from "../blocks/saucedemo-web/inventory/methods/add-to-cart.effect.block.js";
 import { NavCartBlock } from "../blocks/saucedemo-web/cart/nav-cart.block.js";
 import { NavCheckoutInfoBlock } from "../blocks/saucedemo-web/cart/nav-checkout-info.block.js";
@@ -13,17 +13,17 @@ const engine = new Engine();
 // Episode-2 half of chainFlow(loginFlow, shopFlow) - assumes already LoggedIn
 // (AddToCartBlock's In is the Checkpoint<string> wildcard).
 export const shopFlow = withTitle(
-  engine.defineFlow([
-    start,
-    AddToCartBlock,
-    NavCartBlock,
-    NavCheckoutInfoBlock,
-    FillFirstNameBlock,
-    FillLastNameBlock,
-    FillPostalCodeBlock,
-    SubmitCheckoutInfoBlock,
-    FinishOrderBlock,
-    end,
-  ]),
+  engine
+    .map()
+    .start()
+    .method(AddToCartBlock)
+    .gotoPage(NavCartBlock)
+    .gotoPage(NavCheckoutInfoBlock)
+    .method(FillFirstNameBlock)
+    .method(FillLastNameBlock)
+    .method(FillPostalCodeBlock)
+    .method(SubmitCheckoutInfoBlock)
+    .method(FinishOrderBlock)
+    .end(),
   "Shop & Checkout",
 );

package/templates/quickstart/src/flows/viewer-blocked.flow.ts

@@ -1,4 +1,4 @@
-import { Engine, start, end, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
+import { Engine, withTitle, withSessionReset, withExpectedFailure } from "waygraph";
 import { NavLoginBlock } from "../blocks/saucedemo-web/nav-login.block.js";
 import { FillUsernameBlock } from "../blocks/saucedemo-web/methods/fill-username.method.block.js";
 import { FillPasswordBlock } from "../blocks/saucedemo-web/methods/fill-password.method.block.js";
@@ -25,7 +25,14 @@ const engine = new Engine();
 export const viewerBlockedFlow = withExpectedFailure(
   withTitle(
     withSessionReset(
-      engine.defineFlow([start, NavLoginBlock, FillUsernameBlock, FillPasswordBlock, SubmitLoginBlock, end]),
+      engine
+        .map()
+        .start()
+        .gotoPage(NavLoginBlock)
+        .method(FillUsernameBlock)
+        .method(FillPasswordBlock)
+        .method(SubmitLoginBlock)
+        .end(),
     ),
     "Viewer: Blocked Login Attempt",
   ),

package/templates/skills/waygraph-blind-pilot.skill.md

@@ -25,7 +25,8 @@ permanent, reusable, typed coverage instead of leaving nothing behind.
    (`(group)/<page-slug>/page.block.ts` + `nav.block.ts` + `methods/*.block.ts` + one `*.sel.ts`)
    so the result becomes part of the Waygraph Map, not a scattered one-off file.
 4. `auto reload <sessionId>` to pick up the newly-written Block(s) without restarting.
-5. Run the new Block for real via `auto send` - prove it works before moving to the next
+5. Optionally narrate for a headful watcher: `auto highlight <sessionId> '{"rings":[...],"todos":[...]}'`
+6. Run the new Block for real via `auto send` - prove it works before moving to the next
    pattern, exactly like any other real Block.
 6. Ask the user a clarifying question only when something genuinely can't be resolved from
    the DOM alone (is this instance local or published? does a downstream integration exist?)

package/templates/skills/waygraph-pilot.skill.md

@@ -16,12 +16,29 @@ waygraph pilot start                      # bootstraps: {sessionId, socketPath,
 waygraph auto status <sessionId>          # re-read the live menu, no side effects
 waygraph auto send <sessionId> "<pick>"   # run exactly one Block (by menu index or name)
 waygraph auto reach <sessionId> <Checkpoint>  # path-find + run a whole route in one call
+waygraph auto highlight <sessionId> '<json>'  # paint rings/todos on the live page (agent fixtures)
 ```
 
 `graph` in `pilot start`'s response is the **whole project's** Block/Checkpoint graph, not
 just what's reachable from here - use it to plan several steps ahead before you start
 sending picks.
 
+## Highlight fixtures (agent-sent narration)
+
+Block `stubBefore` / `withHighlightFixtures` only paint in `waygraph demo`. In Pilot they
+land in `auto trace` as metadata but do **not** draw on the page. When a human is watching
+a headful session (or you want to narrate intent before a send), paint yourself:
+
+```
+waygraph auto highlight <sessionId> '{"rings":[{"selector":"#user-name","label":"Username","tone":"planned"},{"selector":"#password","label":"Password","tone":"info"}],"todos":["Fill username","Fill password","Submit"],"todoIndex":0,"holdMs":0}'
+waygraph auto highlight <sessionId> '{"clear":true}'
+```
+
+- `tone`: `planned` (purple, default) | `auto` | `info` | `warning` | `danger` | `success` (pilot `orange` is for `auto dom` vision only)
+- `holdMs`: ms to keep fixtures; `0` = until the next highlight / clear (default 12000)
+- Missing selectors are listed in the JSON response (`missing`) - not a hard failure
+- Does not replace `auto send` - paint, then run the real Block
+
 ## Rule 1: run real Blocks, not raw primitives
 
 Default action is always `auto send`/`auto reach` (a real Block). `auto dom/click/type/

package/examples/saucedemo/.waygraph-auto/0b1f5b26.json

@@ -1,8 +0,0 @@
-{
-  "sessionId": "0b1f5b26",
-  "socketPath": "/tmp/waygraph-auto/0b1f5b26.sock",
-  "pid": 1136773,
-  "projectDir": "/home/dan/Desktop/Work/zsign/services/waygraph/examples/saucedemo",
-  "startedAt": "2026-09-20T18:04:00.000Z",
-  "headless": false
-}