waygraph 0.15.41 → 0.15.43

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.js

@@ -130,17 +130,19 @@ export function collectPracticeWarnings(projectDir, walkDir, opts) {
             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",
+                detail: `uses ${via} — reach for a plain CSS selector (id/class/data-attribute, via a _sel.ts/` +
+                    "*.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"));
+            // Two real, coexisting conventions: the Map layout's own `_sel.ts` (one per page folder, next
+            // to `_nav`/`_page`/`_methods`) and the freeform layout's per-concern `<name>.sel.ts`.
+            const siblingSelFile = readdirSync(dirname(file)).some((f) => f === "_sel.ts" || 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 — " +
+                    detail: "a selector string is inlined here, but this directory already has a _sel.ts / *.sel.ts file — " +
                         "add/reuse the selector there instead of a new one-off literal",
                 });
             }
@@ -171,7 +173,7 @@ export function practiceKindLabel(kind) {
         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";
+            return "inline selector — a _sel.ts/*.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.41",
+  "version": "0.15.43",
   "type": "module",
   "description": "A typed graph of reusable Blocks for driving a browser through E2E flows.",
   "license": "MIT",
@@ -42,11 +42,13 @@
     "test": "npm run check:structure && npm run test:unit && playwright test",
     "test:ui": "playwright test --ui",
     "test:unit": "node --import tsx/esm --test tests/unit/*.spec.ts",
-    "docs:preview": "python3 -m http.server 4173 --directory docs",
     "example:saucedemo:install": "npm --prefix examples/saucedemo install",
     "example:saucedemo:test": "npm --prefix examples/saucedemo test",
     "example:saucedemo:auto": "npm --prefix examples/saucedemo run auto",
-    "check:structure": "node scripts/check-structure.mjs"
+    "check:structure": "node scripts/check-structure.mjs",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "peerDependencies": {
     "@playwright/test": "^1.40.0"
@@ -58,6 +60,7 @@
   "devDependencies": {
     "@playwright/test": "^1.63.0",
     "@types/node": "^26.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitepress": "^1.6.4"
   }
 }

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

@@ -17,10 +17,12 @@ against a live site, use `--skill-pilot-blind`.
 2. **Navigation only inside Nav.** `page.goto` / NavBlock `click` live in
    `defineNavBlock` / `defineNavClickBlock` only. Method/Effect `act` uses ActionPage
    (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`, and separately on any inline
-   selector literal (`.locator("#x")`, `click: "#x"`) in a directory that already has a `*Sel`.
+3. **Selectors in `*Sel`, never inline.** DOM strings live in a `*Sel` next to the page - `_sel.ts`
+   in the Map layout (one per page folder, next to `_nav`/`_page`/`_methods`), `<name>.sel.ts` in a
+   freeform layout (one per concern) - never a fresh file-naming convention per project (`_sel.ts`,
+   not `_selectors.ts` or a `_selectors/` folder). Mem keys store values, not selectors. `waygraph
+   check` warns on 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.ts`/`*.sel.ts`.
    **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