waygraph 0.15.40 → 0.15.42

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export type { Checkpoint, Instruction, Block, DefinedBlock, Start, WaygraphInsta
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
+export { css, byText, byRole } from "./selector.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
 export type { BranchEntry, BranchRunResult, RunBranchRegressionOptions } from "./engine/branch-regression.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { connect, checkpoint } from "./types.js";
 export { MemKey, MemPage, key, keyGroup } from "./mem-page.js";
 export { registerMemStub, seedMemStub, getMemStub } from "./mem-stub.js";
+export { css, byText, byRole } from "./selector.js";
 export { Trait, urlMatches, textEquals, visible, disabled, enabled, frameVisible, frameTextEquals, frameContainsText, } from "./trait.js";
 export { runGraph, spawnTab, narrate, Engine, start, end, branch, withVerify, modVerify, modVerifyAll, defineBlock, defineNavBlock, defineNavClickBlock, defineMethodBlock, defineActionBlock, defineAssertBlock, definePageBlock, defineEffectBlock, defineMemEffectBlock, defineMemNavBlock, locate, composeBlock, fastForwardComposeBlock, isFastForwardBlock, preflight, withSessionReset, withTitle, withMemStub, withDemoPace, withBlockPace, withHighlightStyle, withExpectedFailure, withHighlightFixtures, withStubBefore, withStubAfter, withStubOnError, chainFlow, defineLayout, map, MapBuilder, branchRoutes, collectBranchFlows, runBranchRegression, } from "./engine.js";
 export { resolveHighlightSlots, resolveSlides, runStubPhase, resolveFixtureDwellMs, resolveSlideDwellMs, formatHighlightCaption, hasAuthoredStubAfter, hasAuthoredStubOnError, normalizeHighlightTone, normalizeDemoPace, normalizeHighlightSize, normalizeHighlightWeight, applyHighlightStyleDefaults, toneIconPrefix, resolveStepDemoPace, demoPaceScale, demoPaceIsBlitz, demoPaceIsFast, demoPaceIsSlow, demoPaceGateMs, formatDemoPaceBadge, formatDemoPaceLabel, normalizeTodos, normalizeTodoPos, normalizeTodoStyle, buildTodoDock, applyTodoPhase, advanceTodoDock, completeSequentialTodoDock, applyDevicePhase, resolveDeviceState, normalizeDevicePreset, normalizeDeviceOrientation, applyOrientation, orientationFromViewport, DEVICE_PRESETS, resolveTodoDockUi, FIXTURE_DURATION_MS_DEFAULT, FIXTURE_DURATION_FAST_MS_DEFAULT, FIXTURE_DURATION_SLOW_MS_DEFAULT, SLIDE_DURATION_MS_DEFAULT, SLIDE_DURATION_FAST_MS_DEFAULT, WAYGRAPH_RING_CSS, } from "./highlights.js";

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/selector.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Thin selector helpers - the obvious, discoverable shape for the plain-CSS-first rule
+ * (`waygraph-convention.skill.md` #3, `practices-check.ts`'s `overcomplex-selector` warning).
+ * Every `selector: string` in the engine (Trait factories, Block `click`/`url`, `.sel.ts` exports)
+ * already accepts a plain string - these don't add a new selector TYPE, they add three obvious
+ * *functions* to reach for instead of hand-writing a regex/XPath/text-match locator from scratch.
+ *
+ * `css()` also validates: it throws immediately (not just a lint warning later) if you hand it a
+ * regex-looking or XPath string, so the mistake this file exists to steer away from fails loud at
+ * the call site instead of quietly working via a needlessly complex selector.
+ *
+ * A full generated registry of a project's own `*Sel` selectors (Adonis/Prisma-style - typed
+ * autocomplete over selectors that already exist, not just these three shapes) is real, larger,
+ * future work - backlogged until waygraph's own bigger step (a Dagster/Airflow-style run UI), not
+ * part of this pass.
+ */
+/**
+ * A plain CSS selector - id, class, tag, attribute, or any combination Playwright's own CSS engine
+ * accepts. Throws if `raw` looks like a regex text-match pseudo-class or an XPath instead of CSS -
+ * use {@link byText} for a genuine text match, or a raw string (still perfectly valid) when the DOM
+ * truly has no stable selector and a regex/XPath is the only option.
+ * @example css("#login-button")
+ * @example css(".inventory_item .btn_primary")
+ */
+export declare function css(raw: string): string;
+/**
+ * A text-match selector, scoped to `within` (a plain CSS selector) when given. Exact match by
+ * default - pass `{ contains: true }` for a substring match (Playwright's own `:has-text()`).
+ * Prefer this over hand-writing `:has-text(/regex/)` when a plain string is all you need.
+ * @example byText("Login")                         // any element with exactly this text
+ * @example byText("Submit", { within: "form" })     // scoped to a plain CSS selector
+ * @example byText("out of stock", { contains: true }) // substring match
+ */
+export declare function byText(text: string, opts?: {
+    within?: string;
+    contains?: boolean;
+}): string;
+/**
+ * An ARIA role selector (Playwright's own `role=` engine) - the accessible-name-first way to
+ * target a control, ahead of a brittle DOM-structure guess. `name` matches the element's
+ * accessible name exactly (whitespace-normalized), same as Playwright's own role engine default.
+ * @example byRole("button", { name: "Login" })
+ * @example byRole("checkbox", { name: "Remember me", checked: true })
+ */
+export declare function byRole(role: string, opts?: {
+    name?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    pressed?: boolean;
+}): string;

package/dist/selector.js

@@ -0,0 +1,69 @@
+/**
+ * Thin selector helpers - the obvious, discoverable shape for the plain-CSS-first rule
+ * (`waygraph-convention.skill.md` #3, `practices-check.ts`'s `overcomplex-selector` warning).
+ * Every `selector: string` in the engine (Trait factories, Block `click`/`url`, `.sel.ts` exports)
+ * already accepts a plain string - these don't add a new selector TYPE, they add three obvious
+ * *functions* to reach for instead of hand-writing a regex/XPath/text-match locator from scratch.
+ *
+ * `css()` also validates: it throws immediately (not just a lint warning later) if you hand it a
+ * regex-looking or XPath string, so the mistake this file exists to steer away from fails loud at
+ * the call site instead of quietly working via a needlessly complex selector.
+ *
+ * A full generated registry of a project's own `*Sel` selectors (Adonis/Prisma-style - typed
+ * autocomplete over selectors that already exist, not just these three shapes) is real, larger,
+ * future work - backlogged until waygraph's own bigger step (a Dagster/Airflow-style run UI), not
+ * part of this pass.
+ */
+const LOOKS_LIKE_REGEX_TEXT_MATCH = /:text-matches\(|:has-text\(\s*\//;
+const LOOKS_LIKE_XPATH = /^\s*(?:xpath=)?\/\//;
+/**
+ * A plain CSS selector - id, class, tag, attribute, or any combination Playwright's own CSS engine
+ * accepts. Throws if `raw` looks like a regex text-match pseudo-class or an XPath instead of CSS -
+ * use {@link byText} for a genuine text match, or a raw string (still perfectly valid) when the DOM
+ * truly has no stable selector and a regex/XPath is the only option.
+ * @example css("#login-button")
+ * @example css(".inventory_item .btn_primary")
+ */
+export function css(raw) {
+    if (LOOKS_LIKE_XPATH.test(raw)) {
+        throw new Error(`css("${raw}"): looks like an XPath, not a plain CSS selector - use the raw string directly ` +
+            "if the DOM genuinely has no stable id/class/attribute (css() is for the common case only).");
+    }
+    if (LOOKS_LIKE_REGEX_TEXT_MATCH.test(raw)) {
+        throw new Error(`css("${raw}"): looks like a regex text-match pseudo-class - use byText() for a plain text ` +
+            "match, or the raw string directly if you genuinely need a regex.");
+    }
+    return raw;
+}
+/**
+ * A text-match selector, scoped to `within` (a plain CSS selector) when given. Exact match by
+ * default - pass `{ contains: true }` for a substring match (Playwright's own `:has-text()`).
+ * Prefer this over hand-writing `:has-text(/regex/)` when a plain string is all you need.
+ * @example byText("Login")                         // any element with exactly this text
+ * @example byText("Submit", { within: "form" })     // scoped to a plain CSS selector
+ * @example byText("out of stock", { contains: true }) // substring match
+ */
+export function byText(text, opts) {
+    const escaped = text.replace(/"/g, '\\"');
+    const clause = opts?.contains ? `:has-text("${escaped}")` : `:text-is("${escaped}")`;
+    return opts?.within ? `${css(opts.within)} ${clause}` : `*${clause}`;
+}
+/**
+ * An ARIA role selector (Playwright's own `role=` engine) - the accessible-name-first way to
+ * target a control, ahead of a brittle DOM-structure guess. `name` matches the element's
+ * accessible name exactly (whitespace-normalized), same as Playwright's own role engine default.
+ * @example byRole("button", { name: "Login" })
+ * @example byRole("checkbox", { name: "Remember me", checked: true })
+ */
+export function byRole(role, opts) {
+    const attrs = [];
+    if (opts?.name !== undefined)
+        attrs.push(`name="${opts.name.replace(/"/g, '\\"')}"`);
+    if (opts?.checked !== undefined)
+        attrs.push(`checked=${opts.checked}`);
+    if (opts?.disabled !== undefined)
+        attrs.push(`disabled=${opts.disabled}`);
+    if (opts?.pressed !== undefined)
+        attrs.push(`pressed=${opts.pressed}`);
+    return attrs.length ? `role=${role}[${attrs.join("][")}]` : `role=${role}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waygraph",
-  "version": "0.15.40",
+  "version": "0.15.42",
   "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