@marktiderman/genesis-cli 1.28.0 → 1.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -831,6 +831,8 @@ Exit codes: `0` pass, `1` findings, `2` the doctor couldn't run (bad config, Gen
831
831
  | `custom-view-states` | warn | A custom view that draws its own loading, empty or error state: a `status === "loading"`, `"empty"` or `"error"` check in a file that renders `<CustomView>` or calls `useCustomView`. `<CustomView>` draws the three states in the app's style; its `loading`, `empty` and `error` props replace one (ADR 0019). |
832
832
  | `client/layer` | warn | Once the app has a client layer (a `resource-view.tsx` in `src/client/`, or genesis.config.json's `client.dir`): a screen outside it that renders Genesis's `<ResourceView>` or `<RecordView>` directly (`<RecordView>` once the layer has `record-view.tsx`). Screens render the layer's, so the app's defaults reach them (ADR 0020). |
833
833
  | `client/one-view-per-resource` | warn | Once the app has a client layer: a second `defineView` over the same contract, told apart by where it is imported from (module and name, plus a `["…"]` key), not its spelling. Stories and tests are skipped, and so is a contract bound only locally (a name any function, method, arrow or `catch` binds as a parameter anywhere in the file, defaults and types aside: the skip is file-wide, a missed warning rather than a false one) or by destructuring (`const { tasks } = contracts`): the text can't tell those apart, so they're never counted (a missed warning, not a false one). Keep one view per resource and narrow it on the screen (`preset`, `filter`, `columns`), so its rules can't drift (ADR 0020). |
834
+ | `data/declared-access` | warn | A `createSupabaseProvider(…)` call without `access: "declared"` (its resources may read and write their tables with nothing saying so), and a table write in app code (`.from("t").insert/update/upsert/delete(…)`) outside tests and `supabase/`. Declared, each resource names its read (`source`: a view or a function) and its writes (`writes`: named database functions), and opts a table in only with `table: { …, why }`; a direct write that must stay is an `allow` entry with its reason ([DATA-ACCESS.md](../../docs/DATA-ACCESS.md)). |
835
+ | `data/access-rule-tests` | warn | An app that configures the Supabase provider (`createSupabaseProvider`) with no test calling `expectAccessRulesCover` (`@marktiderman/genesis-core/testing`). That test reads the provider's options and fails for each declared function (`writes`, `actions`, `source: { rpc }`) whose name no spec it is given carries. It compares names only, so give it the same specs the `accessRules` cases are registered from; the function holds who may call it, and its cases prove who is allowed and who is refused ([DATA-ACCESS.md](../../docs/DATA-ACCESS.md)). |
834
836
  | `deprecated-import` | warn | A named import of a Genesis export tagged `@deprecated` (or `@stability Deprecated`) in its published declarations. It goes at the next major; the message carries the tag's advice. Ratcheted by default: under `--base`, files that didn't change report it as `info`, so an upgrade never fails strict CI on untouched files. |
835
837
  | `beta-import` | info | A named import of an export tagged `@stability Beta` or `Experimental`, which may still change in a minor. Info by default since most of Genesis is beta; set it to `warn` in `rules` to see it in CI. |
836
838
  | `figma-routes` | info | Runs only when genesis.config.json has a `figma` block: [genesis figma:routes](#genesis-figmaroutes) as findings. A configured page the file doesn't have, a route with no frame, navigation with no hotspot and a `// figma:` id that isn't the route's frame are `info`, `warn` under `--strict`; frames with no route, hotspots to them and navigation that isn't a string literal are always `info`, by design. Never `error`. Invalid JSON or a bad `figma` block in genesis.config.json is one `warn` naming the file. Without `FIGMA_ACCESS_TOKEN`, or when the API can't be read or doesn't answer within 30 seconds, one `info` notice. The Vite plugin and `genesis upgrade` skip it (it reads the network). |
@@ -1329,6 +1331,51 @@ if (!result.ok) throw new Error(formatReport(result));
1329
1331
  4. Run `genesis doctor`, fix or `allow` what it reports (it checks `raw-color` in code as well
1330
1332
  as CSS, and `raw-tag` only in JSX files), then delete the old script.
1331
1333
 
1334
+ ## Runtime conformance checks (`/verify`)
1335
+
1336
+ `genesis doctor` reads code; it can't see layout. `@marktiderman/genesis-cli/verify` checks a page
1337
+ in a real browser, the rules of `docs/RESPONSIVE.md` that a browser can measure. Genesis runs it
1338
+ over its sample app and every story in Chromium, WebKit and Firefox (the Conformance workflow),
1339
+ and an app can call it from its own Playwright tests.
1340
+
1341
+ ```ts
1342
+ import { test, expect } from "@playwright/test";
1343
+ import { checkPage, widthViewport, contextOptions, formatFinding } from "@marktiderman/genesis-cli/verify";
1344
+
1345
+ const viewport = widthViewport(375);
1346
+ test.use(contextOptions(viewport, "webkit"));
1347
+
1348
+ test("items reflows on a phone", async ({ page }) => {
1349
+ await page.goto("/items");
1350
+ const findings = await checkPage(page, { viewport });
1351
+ expect(findings.map(formatFinding)).toEqual([]);
1352
+ });
1353
+ ```
1354
+
1355
+ | Check | Fails when | Source |
1356
+ | --- | --- | --- |
1357
+ | `reflow` | the page or the app shell's scroller scrolls sideways, or an element runs past the viewport, unless it is wide content (a table, grid, code, a map, a tab strip, or a frame marked `data-scroll-frame`) in a frame that scrolls; content cut off by an ancestor that hides overflow counts, except a table cell clipping at its column's edge inside a table that scrolls | WCAG 1.4.10, rule 2 |
1358
+ | `text-clipped` | at 200% text (the `text-200` viewport), text is cut off by a box that hides its overflow (an ellipsis or line clamp is fine) | WCAG 1.4.4 |
1359
+ | `axe` | any axe WCAG 2.2 A/AA rule, `target-size` included (a `touchTarget` control passes on touch) | WCAG 2.5.8 and the rest |
1360
+ | `hit-area` | on a coarse pointer, a control (with its `<label>` and its `::before`/`::after`) is under 44×44px, or a hit test of its 44px box lands on something else (clipped or overlapped); a link in running text is exempt | rule 3 |
1361
+ | `focus-obscured` | a focused element is entirely hidden under a fixed or sticky element | WCAG 2.4.11 |
1362
+ | `floating-controls` | more than one floating control on a phone | rule 9 |
1363
+ | `viewport-meta` | the meta lacks `width=device-width`, `viewport-fit=cover` or `interactive-widget=resizes-content` | rules 6, 7 |
1364
+ | `touch-media` | touch is on but `(pointer: coarse)` and `(hover: none)` don't both match in that engine: an `info` note, and the coarse checks are skipped | the run itself |
1365
+
1366
+ `allViewports()` is the matrix: 320, 375, 768, 1024, 1280 and 1440px with touch at 768px and below;
1367
+ 200% and 400% zoom of a 1280×1024 window (640×512 and 320×256 CSS px, with a mouse); and `text-200`,
1368
+ the browser's text size doubled (Chromium only, `zoomText(page)` before `goto`). Playwright's WebKit
1369
+ is a desktop build: safe areas, the browser toolbar and the on-screen keyboard still need a check
1370
+ on a device or the iOS Simulator.
1371
+
1372
+ Known findings go in an allow list shaped like the doctor's (`AllowEntry`: check, page, viewports,
1373
+ engines, target, reason; pages as paths or route patterns, targets with their quoted accessible
1374
+ name); `applyAllow` splits them, and `info` notes, from the rest. Axe runs first; the focus check
1375
+ runs last and restores focus and every frame's scroll. The page gets no input but `focus()` and an
1376
+ Escape after each (to close a tooltip it opened): the checks click and type nothing. Focus and blur
1377
+ handlers do run, so a page that saves on blur or marks things read on focus is changed by them.
1378
+
1332
1379
  ## genesis agents
1333
1380
 
1334
1381
  Writes the agent guide from the installed Genesis packages, so every coding agent and reviewer in