waygraph 0.15.42 → 0.15.43

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/package.json

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