waygraph 0.16.2 → 0.16.4

package/templates/quickstart/src/stubs/finish-order.ts

@@ -3,12 +3,12 @@ import { CheckoutOverviewSel } from "../blocks/saucedemo-web/checkout-step-two/m
 
 /** Rings Finish while the order is placed. */
 export function placingOrder(ctx: StubCtx): void {
-  ctx.ring("finish", { selector: CheckoutOverviewSel.finishBtn, label: "Placing the order" });
+  ctx.ui.ring("finish", { selector: CheckoutOverviewSel.finishBtn, label: "Placing the order" });
 }
 
 /** Yap slides after the order is placed. They play on the completion page, so they ring its header, not #finish. */
 export function orderPlacedYap(ctx: StubCtx): void {
-  ctx.slides([
+  ctx.ui.slides([
     {
       caption: "Checkout is a short pipeline",
       detail: "Cart -> info -> overview -> done. You just placed the order.",

package/templates/quickstart/src/stubs/login.ts

@@ -3,8 +3,8 @@ import { LoginSel } from "../blocks/saucedemo-web/methods/login.sel.js";
 
 /** What a refused login looks like on screen: the title, a finished checklist and the error banner. */
 export function loginRefused(ctx: StubCtx): void {
-  ctx.title("Login blocked");
-  ctx.todos(
+  ctx.ui.title("Login blocked");
+  ctx.ui.todos(
     "saucedemo",
     [
       { id: "login-user", text: "Enter username", done: true },
@@ -13,7 +13,7 @@ export function loginRefused(ctx: StubCtx): void {
     ],
     { title: "Sign in", style: "checklist" },
   );
-  ctx.ring("error", {
+  ctx.ui.ring("error", {
     selector: LoginSel.errorBanner,
     label: "Login error banner",
     detail: "tone: danger (red)",
@@ -25,8 +25,8 @@ export function loginRefused(ctx: StubCtx): void {
 
 /** Rings the error banner when the login step itself throws. */
 export function loginFailed(ctx: StubCtx): void {
-  ctx.title("Login failed");
-  ctx.ring("error", {
+  ctx.ui.title("Login failed");
+  ctx.ui.ring("error", {
     selector: LoginSel.errorBanner,
     label: "Login error banner",
     detail: "tone: danger (red)",

package/templates/scaffold/src/flows/(external)/hoppscotch/auth.flow.ts

@@ -19,7 +19,7 @@ export const hoppscotchAuthFlow = engine
   .start()
   .gotoExternal(
     NavHoppscotchSettingsBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Hoppscotch GET with query params and bearer token");
+      ctx.ui.title("Scaffold: Hoppscotch GET with query params and bearer token");
     }),
   )
   .method(PickExtensionInterceptorBlock)

package/templates/scaffold/src/flows/(external)/hoppscotch/get.flow.ts

@@ -13,7 +13,7 @@ export const hoppscotchGetFlow = engine
   .start()
   .gotoExternal(
     NavHoppscotchSettingsBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Hoppscotch GET");
+      ctx.ui.title("Scaffold: Hoppscotch GET");
     }),
   )
   .method(PickExtensionInterceptorBlock)

package/templates/scaffold/src/flows/(external)/hoppscotch/post.flow.ts

@@ -18,7 +18,7 @@ export const hoppscotchPostFlow = engine
   .start()
   .gotoExternal(
     NavHoppscotchSettingsBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Hoppscotch POST with header and JSON body");
+      ctx.ui.title("Scaffold: Hoppscotch POST with header and JSON body");
     }),
   )
   .method(PickExtensionInterceptorBlock)

package/templates/scaffold/src/flows/(user-stories)/email-verification.flow.ts

@@ -14,12 +14,12 @@ export const emailVerificationFlow = engine
   .start()
   .gotoExternal(
     NavMailpitInboxBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Cross-origin mail verification (QA-rich)");
+      ctx.ui.title("Scaffold: Cross-origin mail verification (QA-rich)");
     }),
   )
   .assert(
     AssertEmailReceivedBlock.stubAfter((ctx) => {
-      ctx.ring("note", {
+      ctx.ui.ring("note", {
         selector: MailpitSel.messageRow,
         label: "AC · email arrived",
         detail: "Confirmed before opening anything.",
@@ -30,12 +30,12 @@ export const emailVerificationFlow = engine
   .method(OpenMessageBlock)
   .assert(
     AssertEmailContentBlock.stubAfter((ctx) => {
-      ctx.ring("note", { selector: MailpitSel.previewIframe, label: "AC · email body matches expected copy", tag: "AC" });
+      ctx.ui.ring("note", { selector: MailpitSel.previewIframe, label: "AC · email body matches expected copy", tag: "AC" });
     }),
   )
   .method(
     ExtractEmailLinkBlock.stubAfter((ctx) => {
-      ctx.ring("note", {
+      ctx.ui.ring("note", {
         selector: MailpitSel.previewIframe,
         label: "AC · link found",
         detail: "Read from the message preview iframe.",

package/templates/scaffold/src/flows/README.md

@@ -34,6 +34,6 @@ src/flows/
 
 - Build it with `engine.map({ memStub })…end()`; nest another with `.flow(sub, { reset: true })`;
   `.end()` takes nothing.
-- The flow's name and narration are ctx stubs chained on the Block where they apply: `ctx.title("…")`, `ctx.ring(…)`.
+- The flow's name and narration are ctx stubs chained on the Block where they apply: `ctx.ui.title("…")`, `ctx.ui.ring(…)`.
 - A flow expected to fail (a locked-out user) says so in `map({ expectedFailure: "…" })`.
 - A step's speed in the demo is `{ pace }`: `.method(FillBlock, { pace: "blitz" })`.

package/templates/scaffold/src/flows/home/cart.flow.ts

@@ -10,10 +10,10 @@ import "../../map/(app_base)/home/_page.block.js";
 
 // `map({ memStub: true })` fills SelectedItem (alpha) from src/states/demo.mem-stubs.ts; --data overrides it.
 const AddShown = AddItemBlock.stubBefore((ctx) => {
-  ctx.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
+  ctx.ui.ring("add", { selector: DemoSel.catalog, label: "Catalog" });
 })
   .stubAfter((ctx) => {
-    ctx.ring("cart", {
+    ctx.ui.ring("cart", {
       selector: DemoSel.cartCount,
       label: "AC · item in cart",
       detail: "Cart count bumped after Add.",
@@ -22,17 +22,17 @@ const AddShown = AddItemBlock.stubBefore((ctx) => {
     });
   })
   .stubOnError((ctx) => {
-    ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
+    ctx.ui.ring("cart", { selector: DemoSel.cartCount, label: "Cart at failure", tag: "FAIL" });
   });
 
 const RemoveShown = RemoveItemBlock.stubAfter((ctx) => {
-  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
+  ctx.ui.ring("cart", { selector: DemoSel.cartCount, label: "Cart count", duration: true });
 });
 
 const ClearShown = ClearCartBlock.stubBefore((ctx) => {
-  ctx.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
+  ctx.ui.ring("clear", { selector: DemoSel.clear, label: "Clear cart" });
 }).stubAfter((ctx) => {
-  ctx.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
+  ctx.ui.ring("cart", { selector: DemoSel.cartCount, label: "Empty cart", duration: true });
 });
 
 export const homeCartFlow = engine
@@ -40,7 +40,7 @@ export const homeCartFlow = engine
   .start()
   .gotoPage(
     NavHomeBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Shop (Effect + clear)");
+      ctx.ui.title("Scaffold: Shop (Effect + clear)");
     }),
   )
   .method(AddShown)

package/templates/scaffold/src/flows/home/hello.flow.ts

@@ -13,32 +13,32 @@ export const homeHelloFlow = engine
   .start()
   .gotoPage(
     NavHomeBlock.stubBefore((ctx) => {
-      ctx.title("Scaffold: Hello Waygraph");
+      ctx.ui.title("Scaffold: Hello Waygraph");
     }).stubAfter((ctx) => {
-      ctx.ring("title", { selector: DemoSel.title, label: "Home heading", duration: true });
+      ctx.ui.ring("title", { selector: DemoSel.title, label: "Home heading", duration: true });
     }).stubOnError((ctx) => {
-      ctx.ring("title", { selector: DemoSel.title, label: "Home heading at failure" });
+      ctx.ui.ring("title", { selector: DemoSel.title, label: "Home heading at failure" });
     }),
   )
   .assert(
     AssertHelloBlock.stubBefore((ctx) => {
-      ctx.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
+      ctx.ui.ring("title", { selector: DemoSel.title, label: "Heading about to check" });
     })
       .stubAfter((ctx) => {
-        ctx.ring("title", {
+        ctx.ui.ring("title", {
           selector: DemoSel.title,
           label: "AC · Hello visible",
           detail: "Replace this copy with your ticket lines.",
           tag: "AC",
           duration: true,
         });
-        ctx.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
-        ctx.slides([
+        ctx.ui.ring("sub", { selector: DemoSel.sub, label: "Subcopy", duration: 1500 });
+        ctx.ui.slides([
           { caption: "Scaffold covers auto + narration", detail: "Page hub, Effect instanceOptions, stubs, YAP.", tag: "YAP", duration: true },
         ]);
       })
       .stubOnError((ctx) => {
-        ctx.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
+        ctx.ui.ring("title", { selector: DemoSel.title, label: "Heading at failure", tag: "FAIL" });
       }),
   )
   .gotoPage(NavDocsBlock)

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

@@ -68,18 +68,26 @@ against a live site, use `--skill-pilot-blind`.
    when a *different* Block right after it in the `.flow.ts` is what actually confirms the
    transition (e.g. an `AssertXBlock`) - `// waygraph-ignore: empty-verify`.
 
+9. **Never hand-write UI.** All demo UI goes through `ctx.ui` (`ring`, `caption`, `title`, `todos`, `slides`,
+   `device`, `zoom`, `showNetworkTab`), chained where the flow uses the Block. Never build your own caption, highlight
+   or banner in the page (`page.evaluate` + `document.createElement` / `innerHTML` / `.style`, `page.addStyleTag`),
+   and never restyle or call waygraph's overlay (`#wg-*`, `.wg-*`, `window.__wg*`). It changes the page under test (an
+   injected banner can cover a button, an injected style can hide a bug) and breaks silently when the overlay changes.
+   If `ctx.ui` lacks something, say so and ask for it in waygraph - don't override. `waygraph check` flags it
+   (`hand-written-ui`).
+
 ## Flows, stubs and config (the scaffold's shape)
 
 - **Build flows with `map()`** (`engine.map({ memStub }).start().gotoPage(Nav).method(B, { pace }).assert(A).end()`;
   `.gotoExternal` for another origin); it is the only way to build one. Flow settings (`memStub`, `expectedFailure`, `demoPace`, `sessionReset`) go in `map({ … })` before the chain
-  and `.end()` takes nothing. The flow's title is `ctx.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**.
+  and `.end()` takes nothing. The flow's title is `ctx.ui.title(...)` in a stub. **Nest flows with `.flow(sub, { reset: true })`**.
   `defineFlow`, `chainFlow` and the `with*` flow wrappers were removed in 0.16.0; `waygraph upgrade --codemod flows` converts them.
 - **`src/flows/` holds use cases and mirrors the front end's endpoints**: a folder per page (`flows/auth/login/`) with one
   file per scenario named for its outcome (`success.flow.ts`, `wrong-password.flow.ts`, `empty-fields.flow.ts`), and
   `(user-stories)/` (any `(group)`) for flows that cross pages. Export names are `<page><Outcome>Flow`. Not one file per
   Block chain, not a flat folder of unrelated flows.
 - **Blocks carry no stubs; the flow does.** Demo highlights are ctx stubs chained on the Block where the flow uses it:
-  `AddItemBlock.stubAfter((ctx) => { ctx.ring("cart", { selector: DemoSel.cartCount, label: "AC · item in cart" }); })`.
+  `AddItemBlock.stubAfter((ctx) => { ctx.ui.ring("cart", { selector: DemoSel.cartCount, label: "AC · item in cart" }); })`.
   That chained function is the only form: a Block's definition (its options or `instruction`) takes no stub, and a stub
   is never a slot map. A Block used twice gets one `const AddShown = AddItemBlock.stubAfter(...)`. A stub that throws
   fails its step in the demo, named.

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

@@ -157,6 +157,13 @@ the entire reason this package exists. If a needed action truly has no Block, wr
 properly (mirroring a sibling Block's shape) and `auto reload` it in rather than raw-clicking
 past the gap.
 
+To know what the page shows, read the `read` field every `status`/`send`/`reach` reply
+carries (or `pilot read <id> [path]` for one part, uncut): it comes from the project's Read
+Blocks (`*.read.block.ts`, beta) as typed JSON. Reach for `auto dom` only when `read` is empty
+(no Read Block covers the page) or misses what you need - and then consider writing the Read
+Block. `pilot watch <id>` streams every step, read and snapshot as JSON lines if you need to
+follow changes you did not cause (another user, a server push).
+
 The one legitimate exception: `auto dom` to resolve a real ambiguity the menu's own labels
 can't (e.g. two products tied at the same displayed price) - and say so explicitly when you
 do it.