waygraph 0.15.39 → 0.15.41

package/dist/pilot-overlay/fixtures.d.ts

@@ -1,4 +1,4 @@
-import type { BannerPos, BannerUiOpts, DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts } from "../highlights.js";
+import type { BannerPos, BannerUiOpts, DevicePreset, DeviceState, HighlightTone, TodoDockUiOpts, TodoListStyle, WaygraphTodoGroupInput } from "../highlights.js";
 import type { Page } from "@playwright/test";
 /** One ring the Pilot agent wants painted (same fields as demo stub rings). */
 export type PilotFixtureRing = {
@@ -40,6 +40,10 @@ export type PilotHighlightFixtures = {
     todoTitle?: string;
     /** Todo dock side. Default `right`. */
     todoPos?: "left" | "right";
+    /** Presentation: `sequential` (default, arrow walkthrough) | `checklist` | `bullets`. Same as ctx.todoStyle. */
+    todoStyle?: TodoListStyle;
+    /** Multiple titled lists (FR/Scenarios/ACs, same as ctx.todoGroups) - replaces {@link todos} when set. */
+    todoGroups?: readonly WaygraphTodoGroupInput[];
     /**
      * Todo-dock UX (compact / collision / behind-ring). Defaults smart-on;
      * pass false fields to opt out. See {@link TodoDockUiOpts}.

package/dist/pilot-overlay/fixtures.js

@@ -1,5 +1,5 @@
 // Split out of the former 950-line pilot-overlay.ts (see src/ARCHITECTURE.md). Behavior unchanged.
-import { formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
+import { buildTodoDock, formatHighlightCaption, normalizeHighlightSize, normalizeHighlightTone, normalizeHighlightWeight, resolveDeviceState, resolveTodoDockUi } from "../highlights.js";
 import { ensureInstalled } from "./shell.js";
 /**
  * Paint (or clear) agent-authored highlight fixtures on the live page.
@@ -38,11 +38,24 @@ export async function showPilotFixtures(page, fixtures) {
             focus: r.focus === true,
         };
     });
-    const todos = fixtures.clear ? [] : (fixtures.todos ?? []);
     const todoIndex = fixtures.todoIndex ?? 0;
     const todoTitle = fixtures.todoTitle ?? "Plan";
     const todoPos = fixtures.todoPos === "left" ? "left" : "right";
     const todoUi = resolveTodoDockUi(fixtures.todoUi ?? null);
+    // Real TodoDockState (groups/style), same builder the demo runner uses - not a flat string[]
+    // re-implementation, so a Block/agent that authors ctx.todoGroups()/ctx.todoStyle() looks the
+    // same on Pilot as it does in `waygraph demo`.
+    const todoDock = fixtures.clear
+        ? undefined
+        : buildTodoDock({
+            todos: fixtures.todos,
+            todoIndex,
+            todoTitle,
+            todoStyle: fixtures.todoStyle,
+            todoGroups: fixtures.todoGroups,
+            todoPos,
+        });
+    const todoGroups = todoDock?.groups ?? [];
     // Effective zoom: phase zoom, else last ring that authored zoom.
     let zoom = fixtures.clear === true
         ? 1
@@ -70,34 +83,29 @@ export async function showPilotFixtures(page, fixtures) {
         if (hit?.zoomOut !== undefined)
             zoomOut = hit.zoomOut !== false;
     }
-    // Device viewport (Node-side) before paint so rings land on the new size.
+    // Device viewport - same runner/device-stage.js + inpage/device.js every other surface uses
+    // (toast + persistent chip + touch mode), not a separate, simpler Pilot-only chip.
     if (fixtures.clear === true) {
-        // Leave viewport alone on clear - only drop overlays.
+        const { applyDeviceToPage } = await import("../runner/device-stage.js");
+        await applyDeviceToPage(page, undefined, "clear").catch(() => { });
     }
     else if (fixtures.device !== undefined) {
         const d = resolveDeviceState(fixtures.device);
         if (d) {
-            await page
-                .setViewportSize({
-                width: Math.max(200, Math.floor(d.viewport.width)),
-                height: Math.max(200, Math.floor(d.viewport.height)),
-            })
-                .catch(() => { });
+            const [{ applyDeviceToPage }, { installDevice }] = await Promise.all([
+                import("../runner/device-stage.js"),
+                import("../runner/inpage/device.js"),
+            ]);
+            await page.evaluate(installDevice, {}).catch(() => { });
+            await applyDeviceToPage(page, d, "set").catch(() => { });
         }
     }
-    const deviceLabel = fixtures.clear === true
-        ? ""
-        : fixtures.device === undefined
-            ? ""
-            : typeof fixtures.device === "string"
-                ? fixtures.device
-                : fixtures.device.preset || "device";
     const bannerTitle = fixtures.clear ? undefined : fixtures.title;
     const bannerPos = fixtures.clear ? undefined : fixtures.titlePos;
     const bannerHidden = !!fixtures.clear || !!fixtures.bannerUi?.hidden;
     const bannerCollision = fixtures.bannerUi?.collision !== false;
     return page
-        .evaluate(({ rings, todos, todoIndex, todoTitle, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, deviceLabel, todoUi, bannerTitle, bannerPos, bannerHidden, bannerCollision, }) => {
+        .evaluate(({ rings, todoGroups, todoPos, holdMs, zoom, zoomSelector, zoomOut, clearAll, todoUi, bannerTitle, bannerPos, bannerHidden, bannerCollision, }) => {
         // Same #wg-banner element/CSS the demo runner paints (ui/css/banner.css, already in the
         // shared bundle) - so ctx.title / ctx.titlePos / ctx.bannerUi behave identically on a Pilot
         // session, not a separate re-implementation.
@@ -178,16 +186,6 @@ export async function showPilotFixtures(page, fixtures) {
             root.style.removeProperty("transition");
             __wgById("wg-pilot-fx-zoom")?.remove();
         };
-        const setDeviceChip = (label) => {
-            __wgById("wg-pilot-fx-device")?.remove();
-            if (!label)
-                return;
-            const chip = document.createElement("div");
-            chip.id = "wg-pilot-fx-device";
-            chip.dataset.preset = label;
-            chip.textContent = `device \u00b7 ${label}`;
-            __wgAdd(chip);
-        };
         w.__wgPilotFxZoomOutOnHide = zoomOut;
         const clearFx = () => {
             __wgQA(".wg-pilot-fx-ring, .wg-pilot-fx-label").forEach((el) => el.remove());
@@ -196,7 +194,6 @@ export async function showPilotFixtures(page, fixtures) {
             if (w.__wgPilotFxZoomOutOnHide !== false || clearAll)
                 clearZoom();
             if (clearAll) {
-                __wgById("wg-pilot-fx-device")?.remove();
                 clearZoom();
             }
         };
@@ -261,42 +258,59 @@ export async function showPilotFixtures(page, fixtures) {
                 focusBox = { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
             }
         }
-        if (todos.length > 0) {
+        // Real TodoDockState groups (same shape/builder the demo runner uses) - a group's own
+        // style (sequential/checklist/bullets) and its own done/current flags drive rendering here,
+        // not a re-derived index over a flattened string list.
+        const flat = todoGroups.flatMap((g) => g.items);
+        if (flat.length > 0) {
             const dock = document.createElement("div");
             dock.id = "wg-pilot-fx-todos";
             dock.dataset.pos = todoPos;
-            const title = document.createElement("div");
-            title.className = "wg-pilot-fx-todo-title";
-            title.textContent = todoTitle;
-            dock.appendChild(title);
             const WINDOW = todoUi.cap > 0 ? todoUi.cap : 5;
-            const compact = todoUi.compact !== false && todos.length > WINDOW;
+            const compact = todoUi.compact !== false && flat.length > WINDOW;
             if (compact)
                 dock.dataset.compact = "1";
+            const currentFlat = Math.max(0, flat.findIndex((it) => it.current));
             let start = 0;
-            let end = todos.length;
+            let end = flat.length;
             if (compact) {
-                start = Math.max(0, todoIndex - Math.floor((WINDOW - 1) / 2));
-                end = Math.min(todos.length, start + WINDOW);
+                start = Math.max(0, currentFlat - Math.floor((WINDOW - 1) / 2));
+                end = Math.min(flat.length, start + WINDOW);
                 start = Math.max(0, end - WINDOW);
             }
-            const ol = document.createElement("ol");
-            todos.forEach((text, i) => {
-                const li = document.createElement("li");
-                li.textContent = text;
-                if (i < todoIndex)
-                    li.className = "wg-pilot-fx-todo-done";
-                else if (i === todoIndex)
-                    li.className = "wg-pilot-fx-todo-now";
-                if (compact && (i < start || i >= end))
-                    li.classList.add("wg-todo-fold");
-                ol.appendChild(li);
-            });
-            dock.appendChild(ol);
-            if (compact && todos.length - (end - start) > 0) {
+            let flatIdx = 0;
+            let shown = 0;
+            for (const group of todoGroups) {
+                if (group.items.length === 0)
+                    continue;
+                if (group.title) {
+                    const title = document.createElement("div");
+                    title.className = "wg-pilot-fx-todo-title";
+                    title.textContent = group.title;
+                    dock.appendChild(title);
+                }
+                const ol = document.createElement("ol");
+                const marker = group.style === "checklist" ? (done) => (done ? "\u2611 " : "\u2610 ") : group.style === "bullets" ? () => "\u2022 " : () => "";
+                for (const item of group.items) {
+                    const i = flatIdx++;
+                    const li = document.createElement("li");
+                    li.textContent = marker(!!item.done) + item.text;
+                    if (item.done)
+                        li.className = "wg-pilot-fx-todo-done";
+                    else if (item.current)
+                        li.className = "wg-pilot-fx-todo-now";
+                    if (compact && (i < start || i >= end))
+                        li.classList.add("wg-todo-fold");
+                    else
+                        shown++;
+                    ol.appendChild(li);
+                }
+                dock.appendChild(ol);
+            }
+            if (compact && flat.length - shown > 0) {
                 const more = document.createElement("div");
                 more.className = "wg-todo-more";
-                more.textContent = "+" + (todos.length - (end - start)) + " more";
+                more.textContent = "+" + (flat.length - shown) + " more";
                 dock.appendChild(more);
             }
             __wgAdd(dock);
@@ -342,25 +356,20 @@ export async function showPilotFixtures(page, fixtures) {
         else if (zoom > 1.001) {
             setZoomBadge(zoom);
         }
-        if (deviceLabel)
-            setDeviceChip(deviceLabel);
         if (holdMs > 0 &&
-            (painted > 0 || todos.length > 0 || zoom > 1.001 || !!deviceLabel)) {
+            (painted > 0 || todoGroups.some((g) => g.items.length > 0) || zoom > 1.001)) {
             w.__wgPilotFxHideTimer = setTimeout(() => clearFx(), holdMs);
         }
         return { painted, missing };
     }, {
         rings,
-        todos,
-        todoIndex,
-        todoTitle,
+        todoGroups,
         todoPos,
         holdMs,
         zoom,
         zoomSelector: zoomSelector ?? "",
         zoomOut,
         clearAll: fixtures.clear === true,
-        deviceLabel,
         todoUi,
         bannerTitle,
         bannerPos,

package/dist/pilot-overlay/shell.js

@@ -149,6 +149,10 @@ export async function installPersistentPilotOverlay(context) {
 export async function ensureInstalled(page) {
     await ensureShadowRoot(page);
     await page.evaluate(installPilotOverlayShell, OVERLAY_CSS).catch(() => { });
+    // Device toast/chip CSS (runner/overlay-css.js's RUNNER_EXTRA_CSS) - same rules the demo runner
+    // uses, reused here (not re-authored) so a device fixture looks identical on Pilot.
+    const { RUNNER_EXTRA_CSS } = await import("../runner/overlay-css.js");
+    await page.evaluate(([css, key]) => __wgCss(css, key), [RUNNER_EXTRA_CSS, "wg-runner-css"]).catch(() => { });
 }
 /**
  * Bottom-left transient toast, separate from the persistent bottom-right

package/dist/practices-check.d.ts

@@ -1,4 +1,4 @@
-export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify";
+export type PracticeKind = "wildcard-checkpoint" | "assert-no-type-arg" | "multi-input" | "combined-action" | "empty-verify" | "overcomplex-selector" | "inline-selector-should-use-sel-file";
 export interface PracticeWarning {
     kind: PracticeKind;
     file: string;

package/dist/practices-check.js

@@ -3,8 +3,8 @@
  * that compile but erode the typed graph. Warnings only (never fail exit code)
  * unless paired with `tsc` errors in `waygraph typecheck`.
  */
-import { readFileSync } from "node:fs";
-import { relative } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, relative } from "node:path";
 /** define*Block<…Checkpoint<string>…> — prefer project Checkpoint types. */
 const WILDCARD_CHECKPOINT = /\bdefine(?:Method|Effect|Page|Nav|MemNav|NavClick|Action)Block\s*<[^>]*\bCheckpoint\s*<\s*string\s*>/;
 /** defineAssertBlock({ … }) with no explicit Out type — defaults to wildcard. */
@@ -23,6 +23,19 @@ const EMPTY_VERIFY_ARRAY = /\bverify\s*:\s*\[\s*\]/;
 /** Any `verify:` key at all, empty or not. */
 const HAS_VERIFY_KEY = /\bverify\s*:/;
 const SCAN_GLOB = /\.(block|flow)\.ts$/;
+/**
+ * A selector string reaching for a regex-based Playwright text pseudo-class (`:has-text(/…/)`,
+ * `:text-matches(…)`) or a plain XPath - real, recurring pattern: an LLM asked to target a simple
+ * element (one class, one id, one data-attribute) instead writes a regex/XPath from scratch. Not a
+ * type error (Playwright's own selector syntax accepts all of this), so nothing else catches it.
+ */
+const TEXT_MATCHES_PSEUDO = /:text-matches\(/;
+const HAS_TEXT_REGEX_PSEUDO = /:has-text\(\s*\//;
+const XPATH_LOCATOR = /\.locator\(\s*["'`](?:xpath=)?\/\//;
+/** A selector string literal inline in a Block file (`.locator("…")`, `click: "…"`, `url: "…"`) -
+ *  scoped to simple, single-token selectors (id/class/attr/tag) so this doesn't fire on the
+ *  legitimate multi-part selectors `.sel.ts` files themselves are made of. */
+const INLINE_SIMPLE_SELECTOR = /(?:\.locator|\bclick|\burl)\s*[:(]\s*["'`](#|\.)[\w-]+["'`]/;
 const METHOD_OR_EFFECT_FILE = /\.(method|effect)\.block\.ts$/;
 const METHOD_OR_EFFECT_DEFINE = /\bdefine(?:Method|Effect)Block\b/;
 /** Whole-file opt-out: `// waygraph-ignore-practices` */
@@ -107,6 +120,31 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
                 });
             }
         }
+        if (!isIgnored("overcomplex-selector", ignore) &&
+            (TEXT_MATCHES_PSEUDO.test(src) || HAS_TEXT_REGEX_PSEUDO.test(src) || XPATH_LOCATOR.test(src))) {
+            const via = TEXT_MATCHES_PSEUDO.test(src)
+                ? ":text-matches(...)"
+                : HAS_TEXT_REGEX_PSEUDO.test(src)
+                    ? ":has-text(/regex/)"
+                    : "an XPath locator";
+            warnings.push({
+                kind: "overcomplex-selector",
+                file: rel,
+                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a .sel.ts ` +
+                    "export) instead of a regex/XPath match unless the DOM genuinely has no stable selector",
+            });
+        }
+        if (!isIgnored("inline-selector-should-use-sel-file", ignore) && INLINE_SIMPLE_SELECTOR.test(src)) {
+            const siblingSelFile = readdirSync(dirname(file)).some((f) => f.endsWith(".sel.ts"));
+            if (siblingSelFile) {
+                warnings.push({
+                    kind: "inline-selector-should-use-sel-file",
+                    file: rel,
+                    detail: "a selector string is inlined here, but this directory already has a *.sel.ts file — " +
+                        "add/reuse the selector there instead of a new one-off literal",
+                });
+            }
+        }
         if (!isIgnored("empty-verify", ignore) && IS_ASSERT_BLOCK.test(src) && EMPTY_VERIFY_ARRAY.test(src)) {
             warnings.push({
                 kind: "empty-verify",
@@ -130,6 +168,10 @@ export function practiceKindLabel(kind) {
             return "fill and click in one Block";
         case "empty-verify":
             return "empty verify — transition unconfirmed";
+        case "overcomplex-selector":
+            return "regex/XPath selector where a plain one would do";
+        case "inline-selector-should-use-sel-file":
+            return "inline selector — a .sel.ts file already exists here";
         default: {
             const _exhaustive = kind;
             return _exhaustive;

package/dist/runner/device-stage.d.ts

@@ -0,0 +1,9 @@
+import type { Page } from "@playwright/test";
+import type { DeviceState } from "../highlights.js";
+
+export function applyDeviceToPage(
+  page: Page,
+  device: DeviceState | undefined,
+  sync: "set" | "clear" | "keep",
+): Promise<void>;
+export function applyVideoDeviceStage(page: Page, shell: unknown, viewport: unknown, opts?: unknown): Promise<void>;

package/dist/runner/inpage/device.d.ts

@@ -0,0 +1,3 @@
+/** In-page installer (page.evaluate target) - see device.js's own header. Args are accepted for
+ * signature-consistency with the other inpage/* installers; only defines window.__wgSyncDevice. */
+export function installDevice(args: Record<string, unknown>): void;

package/dist/runner/overlay-css.d.ts

@@ -0,0 +1,3 @@
+export const RUNNER_EXTRA_CSS: string;
+export const HOST_CSS: string;
+export const WAYGRAPH_FAVICON: string;

package/examples/saucedemo/.waygraph-auto/3a8674d5.log

@@ -0,0 +1,6 @@
+[11:37:39.688] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[11:37:39.688] waygraph pilot: stub.before ctx.todos n=6 index=0
+[11:37:39.688] waygraph pilot: stub.before ctx.device(mobile)
+[11:37:39.688] waygraph pilot: stub.before ctx.zoom(1.35)
+[11:37:39.688] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[11:37:41.397] waygraph pilot: stub.after ctx.todos n=6 index=1

package/examples/saucedemo/.waygraph-auto/b75168f7.log

@@ -0,0 +1 @@
+[11:36:30.657] waygraph pilot: highlight ctx.todos n=3 index=1

package/examples/saucedemo/.waygraph-auto/cf34b895.log

@@ -0,0 +1,2 @@
+[11:33:28.909] waygraph pilot: highlight ctx.device(mobile)
+[11:33:28.910] waygraph pilot: highlight ring #user-name tone=planned label="U"

package/examples/saucedemo/.waygraph-auto/d4afe93f.log

@@ -0,0 +1,5 @@
+[11:36:57.309] waygraph pilot: highlight ctx.todos n=3 index=0
+[11:36:57.309] waygraph pilot: highlight ring #user-name tone=planned label="Username"
+[11:36:57.310] waygraph pilot: highlight ring #password tone=info label="Password"
+[11:37:00.472] waygraph pilot: highlight ring #no-such-element-waygraph tone=danger label="Gone"
+[11:37:04.621] waygraph pilot: highlight ring #login-button tone=success label="Login"

package/examples/saucedemo/.waygraph-auto/dddd057c.log

@@ -0,0 +1,20 @@
+[11:37:16.027] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[11:37:16.027] waygraph pilot: stub.before ctx.todos n=6 index=0
+[11:37:16.027] waygraph pilot: stub.before ctx.device(mobile)
+[11:37:16.027] waygraph pilot: stub.before ctx.zoom(1.35)
+[11:37:16.027] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[11:37:17.582] waygraph pilot: stub.after ctx.todos n=6 index=1
+[11:37:19.508] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[11:37:19.699] waygraph pilot: stub.after ctx.todos n=6 index=2
+[11:37:21.435] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[11:37:21.669] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[11:37:21.669] waygraph pilot: stub.after ctx.todos n=6 index=3
+[11:37:21.669] waygraph pilot: stub.after ctx.device(mobile)
+[11:37:21.669] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[11:37:25.741] waygraph pilot: stub.before ctx.title("Open cart · landscape")
+[11:37:25.741] waygraph pilot: stub.before ctx.todos n=6 index=5
+[11:37:25.741] waygraph pilot: stub.before ctx.device(mobile)
+[11:37:25.741] waygraph pilot: stub.before ctx.zoom(1.4)
+[11:37:25.741] waygraph pilot: stub.before ring .shopping_cart_link tone=planned label="Cart"
+[11:37:26.102] waygraph pilot: stub.after ctx.title("Your cart · desktop")
+[11:37:26.102] waygraph pilot: stub.after ring .cart_item tone=success label="Cart items"

package/examples/saucedemo/.waygraph-auto/f1f38eeb.log

@@ -0,0 +1,22 @@
+[11:37:25.914] waygraph pilot: stub.before ctx.title("Signing in · mobile")
+[11:37:25.915] waygraph pilot: stub.before ctx.todos n=6 index=0
+[11:37:25.915] waygraph pilot: stub.before ctx.device(mobile)
+[11:37:25.915] waygraph pilot: stub.before ctx.zoom(1.35)
+[11:37:25.915] waygraph pilot: stub.before ring #user-name tone=info label="Username"
+[11:37:27.864] waygraph pilot: stub.after ctx.todos n=6 index=1
+[11:37:31.358] waygraph pilot: stub.before ring #password tone=planned label="Password"
+[11:37:31.685] waygraph pilot: stub.after ctx.todos n=6 index=2
+[11:37:35.206] waygraph pilot: stub.before ring #login-button tone=warning label="Login"
+[11:37:35.729] waygraph pilot: stub.after ctx.title("Inventory · landscape")
+[11:37:35.729] waygraph pilot: stub.after ctx.todos n=6 index=3
+[11:37:35.729] waygraph pilot: stub.after ctx.device(mobile)
+[11:37:35.729] waygraph pilot: stub.after ring .inventory_list tone=success label="Product shelf"
+[11:37:43.407] waygraph pilot: stub.before ctx.title("Pick a product · tablet")
+[11:37:43.407] waygraph pilot: stub.before ctx.todos n=6 index=3
+[11:37:43.407] waygraph pilot: stub.before ctx.device(tablet)
+[11:37:43.407] waygraph pilot: stub.before ctx.zoom(1.35)
+[11:37:43.407] waygraph pilot: stub.before ring div.inventory_item:has(button[data-test="add-to-cart-sauce-labs-backpack"], button[data-test="remove-sauce-labs-backpack"]) .inventory_item_name tone=info label="Sauce Labs Backpack"
+[11:37:43.407] waygraph pilot: stub.before ring [data-test="add-to-cart-sauce-labs-backpack"] tone=success label="Add to cart"
+[11:37:44.906] waygraph pilot: stub.after ctx.title("In the cart")
+[11:37:44.906] waygraph pilot: stub.after ctx.todos n=6 index=4
+[11:37:44.906] waygraph pilot: stub.after ring .shopping_cart_badge tone=success label="Cart badge"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.39",
+  "version": "0.15.41",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",

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

@@ -19,7 +19,14 @@ against a live site, use `--skill-pilot-blind`.
    (no goto) even when the app changes URL as a side effect of a button click.
 3. **Selectors in `*Sel`, never inline.** DOM strings live in a `*Sel` next to the page
    (static + `(id) => …`). Mem keys store values, not selectors. `waygraph check` warns on
-   inline selector literals in `Trait.visible` / `Trait.text`.
+   inline selector literals in `Trait.visible` / `Trait.text`, and separately on any inline
+   selector literal (`.locator("#x")`, `click: "#x"`) in a directory that already has a `*Sel`.
+   **Plain CSS first, always.** An id, a class, or `[data-testid=…]` is the selector for
+   almost everything real apps have - reach for that before anything else. Don't invent a
+   regex/XPath match (`:has-text(/…/)`, `:text-matches(…)`, an XPath locator) for something a
+   one-line class or id selector already targets uniquely; `waygraph check` flags this too.
+   A regex/text match is for a genuinely unstable DOM with no stable attribute at all, not
+   the default first move.
 4. **Assert-only = `defineAssertBlock`.** Self-loop, no hand-written `act`/`resolve`. Pass
    an explicit type argument when it sits between two specifically-typed Blocks in a Flow.
    Not just static content or an action's result - it also names a *feature state* worth a