@ultimat3/cli 19.4.0 → 20.0.0

package/src/templates/guard-semantic-interactive.ts

@@ -0,0 +1,244 @@
+// The `semantic-interactive` guard `x new` ships: an element that answers a click IS a control.
+// The cheapest a11y win there is, and the one an agent undoes by reflex — WebAIM's annual survey of
+// a million home pages finds pages using ARIA average ~41% MORE detected errors than pages using
+// none, because `role="button"` is a PROMISE (Space, Enter, focus, disabled) and only the native
+// element keeps it. Nothing in the gate could see a `<div onClick>` before this file existed.
+
+import { guardCode } from './guard';
+import type { GeneratedFile } from './naming';
+
+/**
+ * Derived from the guard's name, never written as a literal — the same rule `x g guard` follows.
+ * An `X_*` literal in framework source is a FRAMEWORK code: `error-catalog.test.ts` refuses one the
+ * registry does not hold, and `wiki/Error-Codes.md` would owe it a row. The APP owns the codes its
+ * own conventions raise, so this one is spelled by the file it lands in and nowhere else.
+ */
+const NAME = 'semantic-interactive';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// semantic-interactive: a click is answered by a control, and a role is a promise.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to. Delete it to drop the rule.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/** The app owns the codes its own conventions raise — this one is named for the guard. */
+const CODE = '${CODE}';
+
+/**
+ * Elements with no behaviour of their own: no tab stop, no Enter, no Space, no disabled state.
+ * A handler on one of these reaches a mouse and nothing else.
+ */
+const INERT = new Set([
+  'div',
+  'span',
+  'li',
+  'p',
+  'section',
+  'article',
+  'aside',
+  'header',
+  'footer',
+  'main',
+  'nav',
+  'ul',
+  'ol',
+  'td',
+  'tr',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+]);
+
+/** A role whose native element already exists, and the element to write instead of the role. */
+const NATIVE = new Map([
+  ['button', { tag: 'button', write: '<button type="button">' }],
+  ['link', { tag: 'a', write: '<a href="…">' }],
+  ['checkbox', { tag: 'input', write: '<input type="checkbox">' }],
+]);
+
+/** \`(?<![\\w-])\` on every one: \`data-role\` is not \`role\`, and \`maxWidth\` is not \`width\`. */
+const HANDLER = /(?<![\\w-])(on(?:Click|MouseDown|KeyDown))\\s*=/;
+const ROLE = /(?<![\\w-])role\\s*=\\s*["']([a-z]+)["']/;
+const TABINDEX = /(?<![\\w-])tab[Ii]ndex\\s*=/;
+const KEYS = /(?<![\\w-])onKey(?:Down|Up|Press)\\s*=/;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+interface Tag {
+  readonly name: string;
+  readonly attrs: string;
+  readonly index: number;
+}
+
+/** Comments blanked IN PLACE — not deleted — so a reported line number still points at the source. */
+const blank = (text: string): string =>
+  text
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+const NAME_AT = /^([A-Za-z][\\w.-]*)/;
+
+/**
+ * Every opening tag, with its attribute text. The tag ends at the first \`>\` OUTSIDE braces and
+ * quotes, which is the whole reason this is a scanner and not a regex: \`onClick={() => save()}\`
+ * holds a \`>\` that closes nothing, so a pattern reading to the next \`>\` cuts the element in half
+ * and misses every handler written as an arrow — the way all of them are written.
+ */
+function openingTags(text: string): readonly Tag[] {
+  const tags: Tag[] = [];
+  for (let i = 0; i < text.length; i += 1) {
+    if (text[i] !== '<') continue;
+    const name = NAME_AT.exec(text.slice(i + 1, i + 64))?.[1];
+    if (name === undefined) continue;
+    const from = i + 1 + name.length;
+    let depth = 0;
+    let quote = '';
+    let end = from;
+    for (; end < text.length; end += 1) {
+      const ch = text[end];
+      if (quote !== '') {
+        if (ch === quote) quote = '';
+        continue;
+      }
+      if (ch === '"' || ch === "'" || ch === '\`') quote = ch;
+      else if (ch === '{') depth += 1;
+      else if (ch === '}') depth -= 1;
+      else if (depth === 0 && (ch === '>' || ch === '<')) break;
+    }
+    tags.push({ name, attrs: text.slice(from, end), index: i });
+    // Continue from just after the NAME, never after the tag: a nested element inside a brace
+    // expression — \`{items.map((i) => <li onClick={…}>…)}\` — is a tag this rule has to see.
+    i = from - 1;
+  }
+  return tags;
+}
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function semanticInteractive(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const tag of openingTags(text)) {
+      // A role, a tab stop and a key handler together are the COMPLETE set the ARIA practices
+      // guide asks for — a deliberate widget, written by someone who read the obligation. This
+      // rule is about the incomplete ones, so all three present is the one shape it passes over.
+      if (ROLE.test(tag.attrs) && TABINDEX.test(tag.attrs) && KEYS.test(tag.attrs)) continue;
+      const at = \`\${file.path}:\${lineOf(text, tag.index)}\`;
+      const role = ROLE.exec(tag.attrs)?.[1] ?? '';
+      const native = NATIVE.get(role);
+      // One finding per tag, role first: \`<div role="button" onClick>\` is one mistake with two
+      // symptoms, and two findings would make the reader fix it twice.
+      if (native !== undefined && tag.name !== native.tag) {
+        findings.push({
+          code: CODE,
+          cause: \`\${at} puts role="\${role}" on <\${tag.name}> — a role is a promise, and this one obliges the element to answer Space, Enter, focus and disabled, which the native element already does\`,
+          fix: \`replace <\${tag.name} role="\${role}"> in \${file.path} with \${native.write}, then: x verify\`,
+          at: file.path,
+        });
+        continue;
+      }
+      const handler = INERT.has(tag.name) ? HANDLER.exec(tag.attrs)?.[1] : undefined;
+      if (handler === undefined) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${at} hangs \${handler} on <\${tag.name}>, which takes no focus and answers no key — a keyboard, a screen reader and a switch reach a mouse handler on an inert element in exactly one way, which is not at all\`,
+        fix: \`write <button type="button"> — or the native control this element means — in place of <\${tag.name}> at \${at}, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a click is answered by a control, never by a div with a handler',
+  async check(root) {
+    const files: SourceFile[] = [];
+    // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
+    // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
+    // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
+    // matches 17 — so folding these into one line silently turns the guard off, which is worse than
+    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // \`{apps,packages}/**/*.scss\` matches all 15.
+    for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
+      for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
+        const path = entry.split('\\\\').join('/');
+        if (path.includes('node_modules/') || /\\.test\\.tsx?$/.test(path)) continue;
+        files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+      }
+    }
+    return semanticInteractive(files);
+  },
+};
+`;
+
+const test =
+  (): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { semanticInteractive } from './semantic-interactive';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/page.tsx', source }];
+
+unitTest('a div with a click handler is refused, and the finding names the line', () => {
+  const findings = semanticInteractive(
+    file('<main>\\n  <div onClick={() => save()}>Save</div>\\n</main>'),
+  );
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+  expect(findings[0]?.fix).toContain('<button type="button">');
+});
+
+unitTest('role="button" on a div names the native element to write instead', () => {
+  const findings = semanticInteractive(file('<div role="button" onClick={go}>Go</div>'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('a role is a promise');
+  expect(findings[0]?.fix).toContain('<button type="button">');
+});
+
+unitTest('the native control it names is not itself a finding', () => {
+  expect(semanticInteractive(file('<button type="button" onClick={go}>Go</button>'))).toEqual([]);
+  expect(semanticInteractive(file('<a href="/x" onClick={go}>Go</a>'))).toEqual([]);
+});
+
+// The boundary, stated: a role, a tab stop and a key handler together are the complete set the
+// ARIA practices guide asks for. This rule reports the INCOMPLETE widget, never the deliberate one.
+unitTest('a role with a tab stop and a key handler is a deliberate widget', () => {
+  const widget = '<div role="button" tabindex="0" onClick={go} onKeyDown={go}>Go</div>';
+  expect(semanticInteractive(file(widget))).toEqual([]);
+});
+
+unitTest('data-role is not role, and a live region is not a control', () => {
+  expect(semanticInteractive(file('<p data-role="status" role="status">Saved</p>'))).toEqual([]);
+});
+
+// The reason the tag end is scanned rather than matched: an arrow function's \`>\` closes nothing,
+// and a pattern that stopped at it would read the element as ending before its own handler.
+unitTest('an arrow function in an earlier attribute does not end the tag', () => {
+  const source = '<div class={cx(() => a > b)} onClick={go}>Go</div>';
+  expect(semanticInteractive(file(source))).toHaveLength(1);
+});
+
+unitTest('a commented-out handler is a note, not an element', () => {
+  expect(semanticInteractive(file('// <div onClick={go}>Go</div>\\nconst a = 1;'))).toEqual([]);
+});
+`;
+
+/** `guards/semantic-interactive.ts` and its test. The directory is the registration. */
+export const semanticInteractiveGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/semantic-interactive.ts', contents: source() },
+  { path: 'guards/semantic-interactive.test.ts', contents: test() },
+];

package/src/templates/guard-untranslated-string.ts

@@ -36,8 +36,6 @@ const CODE = '${CODE}';
  * rule wants: a parent whose children are elements has no text of its own.
  */
 const ELEMENT = /<([A-Za-z][\\w.:-]*)(?:\\s[^<>]*)?>([^<>]*?)<\\/\\1>/g;
-/** A \`{…}\` child is an expression — \`{t('key')}\`, \`{props.row.title}\` — never typed prose. */
-const EXPRESSION = /\\{[^{}]*\\}/g;
 /** Two word characters in a row. One is \`&\`, \`×\`, an initial — never a sentence. */
 const PROSE = /[\\p{L}\\p{N}]{2,}/u;
 
@@ -55,13 +53,43 @@ const blank = (text: string): string =>
 
 const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
 
+/**
+ * Every \`{…}\` child removed — \`{t('key')}\`, \`{props.row.title}\` — leaving only what was TYPED
+ * between the tags.
+ *
+ * A depth scan and never a regex, because a JSX expression NESTS and a regex does not:
+ * \`/\\{[^{}]*\\}/g\` strips the INNER group of
+ * \`{t('app.feed.heading', { org: actor.org.name })}\` first, leaves the unbalanced remnant
+ * \`{t('app.feed.heading',  )}\`, and then reads that remnant as prose — so every \`t()\` call with an
+ * interpolation object or a template-literal key was reported as an untranslated string, which is
+ * the exact opposite of the rule. Measured at 12 findings, all false, before this scan replaced it.
+ *
+ * A closing brace with nothing open is kept: it is a stray character, and prose it is not.
+ */
+const withoutExpressions = (children: string): string => {
+  let out = '';
+  let depth = 0;
+  for (const character of children) {
+    if (character === '{') {
+      depth += 1;
+      continue;
+    }
+    if (character === '}' && depth > 0) {
+      depth -= 1;
+      continue;
+    }
+    if (depth === 0) out += character;
+  }
+  return out;
+};
+
 /** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
 export function untranslatedStrings(files: readonly SourceFile[]): readonly Finding[] {
   const findings: Finding[] = [];
   for (const file of files) {
     const text = blank(file.source);
     for (const match of text.matchAll(ELEMENT)) {
-      const typed = (match[2] ?? '').replaceAll(EXPRESSION, ' ').trim();
+      const typed = withoutExpressions(match[2] ?? '').trim();
       if (!PROSE.test(typed)) continue;
       findings.push({
         code: CODE,
@@ -83,9 +111,12 @@ export const guard: Guard = {
     // a hardcoded string there used to be green. \`api/\` renders nothing and \`shared/\` is a leaf of
     // helpers; \`packages/*/dist\` is a build output, not source.
     //
-    // TWO globs, never one with a leading \`{a,b}\` group: \`Bun.Glob.scan()\` matches nothing at all
-    // for a pattern that starts with a brace group — measured — so folding these into one line
-    // silently turns the guard off, which is worse than the hole it closes.
+    // TWO globs, and the rule is that a brace ALTERNATIVE may not contain a \`/\`. Measured on Bun
+    // 1.4.0 against \`examples/dummy\`: \`{apps/*/{site,app},packages/*/src}/**/*.tsx\` and
+    // \`{apps/web,packages/ui}/**/*.tsx\` each match ZERO files, where \`apps/*/{site,app}/**/*.tsx\`
+    // matches 17 — so folding these into one line silently turns the guard off, which is worse than
+    // the hole it closes. A LEADING group is fine and four guards here rely on it:
+    // \`{apps,packages}/**/*.scss\` matches all 15.
     for (const pattern of ['apps/*/{site,app}/**/*.tsx', 'packages/*/src/**/*.tsx']) {
       for await (const entry of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
         const path = entry.split('\\\\').join('/');
@@ -119,6 +150,23 @@ unitTest('a t() child satisfies it, and so does any other expression', () => {
   expect(untranslatedStrings(file('<li class={styles.item}>{row.title}</li>'))).toEqual([]);
 });
 
+// The legitimate lookalike, and the one this rule got wrong: a JSX expression NESTS. A mask that
+// does not strips the inner \`{ org: … }\` first and reads the unbalanced remnant as prose, so the
+// guard reported the very calls it exists to require.
+unitTest('a t() call carrying an interpolation object is not typed prose', () => {
+  const interpolated = "<h1>{t('app.feed.heading', { org: actor.org.name })}</h1>";
+  expect(untranslatedStrings(file(interpolated))).toEqual([]);
+  expect(untranslatedStrings(file(\`<span>{t(\\\`plans.\\\${plan}.name\\\`)}</span>\`))).toEqual([]);
+});
+
+// The other direction: masking a nested child may not swallow the prose beside it.
+unitTest('prose beside an interpolating t() call is still refused', () => {
+  const mixed = "<h1>{t('app.feed.heading', { org: actor.org.name })} Welcome back</h1>";
+  const findings = untranslatedStrings(file(mixed));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.cause).toContain('Welcome back');
+});
+
 // The reason the rule reads a CLOSING tag: a generic type argument is a > followed by source that
 // looks exactly like prose, and a pattern reading to the next < reports every one of them.
 unitTest('a generic type argument is not a JSX text node', () => {

package/src/templates/island.ts

@@ -5,7 +5,7 @@
 // compiles. All three are pinned by the emitted test, which builds the chunk and mounts it.
 
 import type { GeneratedFile } from './naming';
-import { kebab, pascal } from './naming';
+import { camel, kebab, pascal } from './naming';
 
 export interface IslandOptions {
   /** Directory the entry lands in, app-root-relative and POSIX — normally a route's own folder. */
@@ -170,12 +170,55 @@ describe('the ${name} island', () => {
 });
 `;
 
+/**
+ * The states file beside the entry, and it ships WITH the island rather than after it: `x verify`'s
+ * `boundaries` step refuses an island that declares none (`guards/island-without-states.ts`), so a
+ * generator that wrote only the component would scaffold a file that fails the app's own gate on
+ * the next command. The second state is the point of the whole mechanism — a label a translation
+ * is three times as long in is a state nobody can reach by clicking in the locale they develop in.
+ */
+const islandStates = (name: string, dir: string): string => {
+  const Name = pascal(name);
+  return `// The states \`${name}\` can be photographed in. \`x shot --island ${name} --json\` takes one
+// picture per state per theme into \`.x/shot/island/${name}/\`, and the states worth declaring are
+// the ones a running app will not produce on request.
+//
+// PURE DATA. No JSX, no \`solid-js\`, and the one import below is \`import type\`, which
+// \`verbatimModuleSyntax\` erases entirely — the command that takes the pictures has to know the
+// complete expected list before a browser exists. \`X_TEST_ISLAND_STATES_NOT_PURE\` is the refusal.
+//
+// The labels are literals here and that is not a \`t()\` violation: an island's props cross the seam
+// as JSON inside the document, so the SERVER translates and the browser is handed text.
+
+import { defineIslandStates } from '@ultimat3/testing';
+import type { ${Name}Props } from './${name}.island';
+
+export const ${camel(name)}States = defineIslandStates({
+  island: '${dir}/${name}.island.tsx',
+  states: [
+    {
+      id: 'idle',
+      title: 'the first paint, before anything has been clicked',
+      props: { label: 'Open' } satisfies ${Name}Props,
+    },
+    {
+      id: 'long-label',
+      title: 'the label a translation is three times as long in',
+      note: 'you cannot reach this by clicking: it needs a locale whose word for this is long, and the one this was written in is not it',
+      props: { label: 'Abrechnungseinstellungen anzeigen' } satisfies ${Name}Props,
+    },
+  ],
+});
+`;
+};
+
 export function islandFiles(rawName: string, options: IslandOptions): readonly GeneratedFile[] {
   const name = kebab(rawName);
   const dir = options.dir.replace(/\/+$/, '');
   return [
     { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
     { path: `${dir}/${name}.module.scss`, contents: islandStyle() },
+    { path: `${dir}/${name}.island.states.ts`, contents: islandStates(name, dir) },
     { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name, dir) },
   ];
 }

package/src/templates/resource-form-island.ts

@@ -265,6 +265,69 @@ describe('the ${feature.kebab} form island', () => {
 });
 `;
 
+/**
+ * The states file beside the entry, and it ships WITH the island rather than after it: `x verify`'s
+ * `boundaries` step refuses an island that declares none (`guards/island-without-states.ts`), so a
+ * generator that wrote only the component would scaffold a file that fails the app's own gate on
+ * the next command.
+ */
+const formIslandStates = (
+  feature: NameSet,
+  dir: string,
+): string => `// The states the ${feature.kebab} form can be photographed in. \`x shot --island ${feature.kebab}-form --json\`
+// takes one picture per state per theme into \`.x/shot/island/${feature.kebab}-form/\`, and the states
+// worth declaring are the ones a running app will not produce on request.
+//
+// PURE DATA. No JSX, no \`solid-js\`, and the one import below is \`import type\`, which
+// \`verbatimModuleSyntax\` erases entirely — the command that takes the pictures has to know the
+// complete expected list before a browser exists. \`X_TEST_ISLAND_STATES_NOT_PURE\` is the refusal.
+//
+// The labels are literals here and that is not a \`t()\` violation: an island's props cross the seam
+// as JSON inside the document, so the SERVER translates and the browser is handed text. These are
+// the text the server would have handed it.
+
+import { defineIslandStates } from '@ultimat3/testing';
+import type { ${feature.pascal}FormProps } from './${feature.kebab}-form.island';
+
+/** What a working render hands the form — the baseline the state below departs from. */
+const BASE = {
+  endpoint: '/api/create-${feature.kebab}',
+  locale: 'en',
+  labels: {
+    title: 'Title',
+    submit: 'Save',
+    saved: 'Saved',
+    retry: 'That did not save. Try again.',
+  },
+} satisfies ${feature.pascal}FormProps;
+
+export const ${feature.camel}FormStates = defineIslandStates({
+  island: '${dir}/${feature.kebab}-form.island.tsx',
+  states: [
+    {
+      id: 'idle',
+      title: 'the first paint, before anything has been typed',
+      props: BASE satisfies ${feature.pascal}FormProps,
+    },
+    {
+      id: 'long-labels',
+      title: 'the same form in a locale whose words are three times as long',
+      note: 'you cannot reach this by clicking: it needs a translation, and the locale this was written in is the one that fits',
+      props: {
+        ...BASE,
+        locale: 'de',
+        labels: {
+          title: 'Bezeichnung des Beitrags',
+          submit: 'Änderungen speichern',
+          saved: 'Änderungen gespeichert',
+          retry: 'Das konnte nicht gespeichert werden. Bitte erneut versuchen.',
+        },
+      } satisfies ${feature.pascal}FormProps,
+    },
+  ],
+});
+`;
+
 /**
  * The slice's form, as the one client shape: `<dir>/<feature>-form.island.tsx` plus its test.
  *
@@ -281,6 +344,10 @@ export function formIslandFiles(
       path: `${dir}/${feature.kebab}-form.island.tsx`,
       contents: formIslandSource(feature, formIslandSpecifier(feature, dir, pageDir)),
     },
+    {
+      path: `${dir}/${feature.kebab}-form.island.states.ts`,
+      contents: formIslandStates(feature, dir),
+    },
     {
       path: `${dir}/${feature.kebab}-form.island.test.ts`,
       contents: formIslandTest(feature, dir),

package/src/templates/scaffold-claude-agents.ts

@@ -131,8 +131,17 @@ calls. A change outside that set is a collision — report it, do not make it.
 | Semantic tokens only | never a raw hex, in a component or a stylesheet |
 | Dates name a zone | explicit IANA time zone at every call site, no ambient default |
 | A page calls primitives | queries and actions, never a repo and never the database |
+| A click needs a control | \`<button>\`, \`<a href>\`, \`<input>\` — never a \`<div onClick>\`, and never \`role="button"\` where the tag exists. A role is a promise: it obliges you to answer Space, Enter, focus and disabled |
+| The focus ring is replaced | \`outline: none\` on its own leaves a keyboard user with nothing. \`@include tokens.focus-ring\`, or a \`:focus-visible\` box-shadow beside it |
+| Every image has a box | width + height, or an aspect-ratio. An unsized image moves everything under it when its bytes land, and the priority one is never \`loading="lazy"\` |
+| Animate transform and opacity | nothing else composites: a \`top\`, a \`width\` or a \`box-shadow\` costs a layout pass every frame, and \`transition: all\` animates properties nobody chose. \`tokens.duration()\` / \`tokens.easing()\` are the values |
+| An island declares its states | a sibling \`<name>.island.states.ts\`, so \`x shot --island <name> --json\` can photograph the failures nobody can click to |
 
-Inspect before you change: \`x routes --json\`, and \`x i18n check\` for catalog gaps.
+Every one of the last five is a build error, not a preference — \`guards/\` holds them and \`x verify\`'s
+\`boundaries\` step runs them. Read the guard rather than guessing at the rule.
+
+Inspect before you change: \`x routes --json\`, \`x i18n check\` for catalog gaps, and
+\`x shot <route> --json\` when you need to see what you built.
 
 Checks: \`bun test <path>/page.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
 once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.

package/src/templates/scaffold-docs.ts

@@ -28,11 +28,22 @@ not exist — five of these had an empty column and were each measured green on
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+| Interaction | a click is answered by a control — never a \`<div onClick>\`, and never a \`role=\` where the native tag exists | \`guards/semantic-interactive.ts\` |
+| Focus | \`outline: none\` replaces the ring in the same rule or the one beside it, or it does not remove it | \`guards/focus-visible.ts\` |
+| Images | every image carries width + height or an aspect-ratio, and the priority one is never \`loading="lazy"\` | \`guards/image-dimensions.ts\` |
+| Motion | animate \`transform\` and \`opacity\` — never a layout property, never \`transition: all\` | \`guards/animated-layout-property.ts\` |
+| Islands | every \`*.island.tsx\` has a sibling \`*.island.states.ts\`, so \`x shot --island\` can photograph its failures | \`guards/island-without-states.ts\` |
 | Size | one file, one job — ${LINE_CEILING} lines of reviewable logic, and split past it | \`X_FILE_TOO_LONG\` |
 
 \`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
 \`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
 
+The last five rows are about what this app is like to USE, and each is decidable from the file
+alone — which is why they are those five and not the many that are not. A role is a promise:
+\`role="button"\` obliges you to answer Space, Enter, focus and disabled, and the native element
+already does. Only \`transform\` and \`opacity\` animate without a layout pass. An image with no box
+moves everything under it when its bytes land.
+
 Size is a hard line and not a style note: past ${LINE_CEILING} lines a file has stopped being the
 unit of review, and \`x verify\` refuses it. The one exemption is a file that is nothing but re-exports —
 it has one job by construction, and its length tracks the API's size rather than its complexity;

package/src/templates/scaffold-guards.ts

@@ -6,9 +6,19 @@
 // (`packages/cli/src/guards.ts`). What was missing is any guard to discover. Four of the five are
 // here; the fifth, money-as-float, has no static signature and is answered by the `Money` type
 // instead — `scaffold-docs.ts` says so where an author reads it.
+//
+// The other five are about what the app is like to USE, which no row of `AGENTS.md` had ever been
+// about: a control a keyboard cannot reach, a focus ring taken away and not replaced, an image with
+// no box, an animation the compositor cannot run, and an island nobody has seen fail. Each is
+// statically decidable from the file alone — the reason those five and not the many that are not.
 
+import { animatedLayoutPropertyGuardFiles } from './guard-animated-layout-property';
 import { bareErrorGuardFiles } from './guard-bare-error';
+import { focusVisibleGuardFiles } from './guard-focus-visible';
+import { imageDimensionsGuardFiles } from './guard-image-dimensions';
+import { islandWithoutStatesGuardFiles } from './guard-island-without-states';
 import { rawColourGuardFiles } from './guard-raw-colour';
+import { semanticInteractiveGuardFiles } from './guard-semantic-interactive';
 import { untranslatedStringGuardFiles } from './guard-untranslated-string';
 import { unzonedDateGuardFiles } from './guard-unzoned-date';
 import type { GeneratedFile } from './naming';
@@ -19,8 +29,13 @@ import type { GeneratedFile } from './naming';
  * `x g guard <name>`, the same shape.
  */
 export const scaffoldGuardFiles = (): readonly GeneratedFile[] => [
+  ...animatedLayoutPropertyGuardFiles(),
   ...bareErrorGuardFiles(),
+  ...focusVisibleGuardFiles(),
+  ...imageDimensionsGuardFiles(),
+  ...islandWithoutStatesGuardFiles(),
   ...rawColourGuardFiles(),
+  ...semanticInteractiveGuardFiles(),
   ...untranslatedStringGuardFiles(),
   ...unzonedDateGuardFiles(),
 ];

package/src/templates/scaffold-repo.ts

@@ -26,6 +26,17 @@ import { uiPackageFiles } from './scaffold-ui-package';
  */
 const BIOME_VERSION = '2.5.8';
 
+/**
+ * The checker a scaffolded app typechecks with, and it must not lag the one the FRAMEWORK is built
+ * and gated on: `@ultimat3/*` ships `.d.ts` emitted by this compiler, so an app pinned a major
+ * behind reads the types its own dependencies were written against through an older checker.
+ * It drifted for exactly the reason `BIOME_VERSION` did not — Biome's was spelled once as a
+ * constant and TypeScript's was a literal buried in a dependency block, so the framework moved to
+ * 7.x and every `x new` kept scaffolding `^6.0.3`. `scaffold-repo.test.ts` now pins this against
+ * the repo's own root `package.json`, so the next bump cannot leave the scaffold behind in silence.
+ */
+const TYPESCRIPT_VERSION = '^7.0.2';
+
 // `version` is not decoration: the manifest's app version IS the contract's compatibility gate,
 // and the manifest never fabricates one — so an app scaffolded without it failed `x manifest`,
 // the `manifest` verify step and every production boot with X_APP_PACKAGE_INVALID.
@@ -54,7 +65,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "@electric-sql/pglite": "^0.5.4",
     "@types/bun": "^1.4.0",
     "@ultimat3/testing": "^${version}",
-    "typescript": "^6.0.3"
+    "typescript": "${TYPESCRIPT_VERSION}"
   },
   "dependencies": {
     "@ultimat3/action": "^${version}",