@ultimat3/cli 7.0.0 → 9.0.0

package/src/shot-settle.ts

@@ -0,0 +1,57 @@
+// When a shot may be TAKEN: the two rules that decide whether the page has finished hydrating,
+// separated from both the command that drives a browser and the verdict that judges what came
+// back. Plain values and an injected sleep, so the whole loop is proved with neither.
+
+import type { IslandCount } from './shot-verdict';
+
+/**
+ * When there is nothing left to wait for. `booted` counts the islands whose chunk the runtime
+ * ASKED for; `mounted` and `failed` are the two ways that request can end — so the outcome of
+ * every boot exists exactly when they add up to it. An island that never booted is not something
+ * to wait for (`visible` with nothing scrolled to it, `never` by declaration), and `null` is "the
+ * page answered no probe", which no amount of waiting turns into an answer.
+ */
+export const islandsSettled = (islands: IslandCount | null): boolean =>
+  islands === null || islands.mounted + islands.failed >= islands.booted;
+
+/**
+ * How often the island probe is re-read while the page settles. Short enough that a page whose
+ * mounts have already resolved pays one extra read and nothing else.
+ */
+export const SETTLE_POLL_MS = 100;
+
+export interface SettleOptions {
+  /** The extra budget a mount gets AFTER the boot deadline. Bounded: a picture is still owed. */
+  readonly windowMs: number;
+  readonly pollMs: number;
+  /** Injected by the test, so the poll is proved without spending its own window in real time. */
+  readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+
+/**
+ * Read the probe until every booted island has settled, or the window runs out.
+ *
+ * `DEFAULT_SETTLE_MS` is the deadline at which the hydration runtime CALLS `import()` — `mounted`
+ * and `failed` land after it — so a single read at that instant reports `mounted: 0` for a page
+ * that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
+ * is the only shape that ends EARLY on a fast page and still bounds a slow one.
+ *
+ * A `null` answer never overwrites a real count: `null` means "not counted", and a probe that
+ * fails once would otherwise turn a page with islands into a page reported to have none.
+ */
+export async function settleIslands(
+  probe: () => Promise<IslandCount | null>,
+  options: SettleOptions,
+): Promise<IslandCount | null> {
+  const sleep = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
+  let answer = await probe();
+  let waited = 0;
+  while (!islandsSettled(answer) && waited < options.windowMs) {
+    // At least 1ms, or a `pollMs` of zero is a loop with no exit while the window stands.
+    const step = Math.max(1, Math.min(options.pollMs, options.windowMs - waited));
+    await sleep(step);
+    waited += step;
+    answer = (await probe()) ?? answer;
+  }
+  return answer;
+}

package/src/shot-verdict.ts

@@ -33,6 +33,7 @@ export const SHOT_MESSAGE_KEYS = [
   'cli.shot.canvasUnreadable',
   'cli.shot.islands',
   'cli.shot.islandsUnknown',
+  'cli.shot.islandFailed',
   'cli.shot.network',
   'cli.shot.console',
   'cli.shot.threw',
@@ -176,19 +177,28 @@ const levelCount = (lines: readonly ConsoleLine[], level: ConsoleLine['level']):
   lines.filter((line) => line.level === level).length;
 
 /**
- * `ok` is three conditions, and every one is something a picture cannot show: nothing on the page
- * logged an error, nothing THREW, and the document photographed is the route that was asked for.
+ * `ok` is four conditions, and every one is something a picture cannot show: nothing on the page
+ * logged an error, nothing THREW, no island's `mount()` REJECTED, and the document photographed is
+ * the route that was asked for.
  *
  * The throw is its own clause rather than folded into `errors` because an uncaught exception calls
  * no console method — a page whose island died can log nothing at all, and `errors === 0` would
- * then pass it. A redirect is a failure of the CAPTURE rather than of the app: an agent that
+ * then pass it. A rejected mount is a third silent one and was read by NOTHING until 2026-08-22:
+ * the prelude pays 129 B an island to write `data-x-failed`, the probe counted it into the
+ * artifact, and every island on a page could reject while the run reported "clean". `?? 0` keeps
+ * an uncounted probe (`null`) out of the verdict — "not counted" is not "none failed".
+ * A redirect is a failure of the CAPTURE rather than of the app: an agent that
  * photographs the sign-in page and files "the island did not mount" is the outcome this prevents.
  */
 export function buildVerdict(input: ShotInput): ShotVerdict {
   const errors = levelCount(input.console, 'error');
   return {
     ...input,
-    ok: errors === 0 && input.pageErrors.length === 0 && input.requestedUrl === input.finalUrl,
+    ok:
+      errors === 0 &&
+      input.pageErrors.length === 0 &&
+      (input.islands?.failed ?? 0) === 0 &&
+      input.requestedUrl === input.finalUrl,
     redirected: input.requestedUrl !== input.finalUrl,
     errors,
     warnings: levelCount(input.console, 'warn'),
@@ -328,6 +338,19 @@ export const shotSummary = (verdict: ShotVerdict): string => {
       first: verdict.pageErrors[0]?.message ?? '',
     });
   }
+  // Ahead of the console count for the same reason, and it is the same silence: a rejected mount
+  // promise calls no console method either, so a page whose every island died can read `errors: 0`.
+  // The first failure is NAMED — "1 island failed" sends a reader back to the artifact for the one
+  // fact they need to start.
+  const failure = verdict.islands?.failures[0];
+  if (failure !== undefined) {
+    return msg('cli.shot.islandFailed', {
+      route: verdict.route,
+      failed: verdict.islands?.failed ?? 0,
+      island: failure.island,
+      message: failure.message,
+    });
+  }
   if (verdict.errors > 0) {
     return msg('cli.shot.errors', { route: verdict.route, errors: verdict.errors });
   }

package/src/solid-loader.ts

@@ -7,7 +7,7 @@
 // `tsc` compiles this file inside ITS program, where a `.d.ts` sitting in this directory is
 // not included and its `declare module` never applies. `tsc -b` proves it in this repo.
 import { transformAsync } from '@babel/core';
-import { contentHash } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 import solidPreset from 'babel-preset-solid';
 import type { BunPlugin } from 'bun';
 import { IslandBuildFailedError } from './errors';

package/src/style-csp.ts

@@ -4,7 +4,8 @@
 // stylesheet the document no longer carries — and the CSP would block the framework's own CSS.
 
 import { cspHashSource } from '@ultimat3/http';
-import { SURFACES, stylesFor } from '@ultimat3/render';
+import { SURFACES } from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
 
 /**
  * Call AFTER `loadApp`. One hash per distinct body: `stylesFor` is what `dev-render.ts` puts in

package/src/sync-authenticator.ts

@@ -4,7 +4,8 @@
 // per-tenant subscription cap all decided against an anonymous actor. Realtime was single-tenant
 // by wiring, not by design.
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, Clock } from '@ultimat3/core';
+import { systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
@@ -12,7 +13,37 @@ import {
   defineHttpConfig,
   UltimateRequest,
 } from '@ultimat3/http';
-import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime';
+import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime/server';
+
+/**
+ * How long one grant stands before the node re-decides it.
+ *
+ * A grant with no expiry never appears in `GrantBook.expired()`, so `sweepGrants` — the only path
+ * to `hub.onActorChange` and `registry.reauthorize` — never fired for a socket this adapter opened.
+ * `logout`, `revokeSession`, `disableUser` and `updatePrivileges` closed the HTTP session and never
+ * the websocket, and the client's 15s heartbeat beats the 120s idle sweep, so the socket stayed up
+ * with the revoked actor's authority for as long as the tab was open.
+ *
+ * Five minutes, against `DEFAULT_REAUTH_INTERVAL_MS` (30s): the window a revoked actor keeps its
+ * socket is this plus one sweep, and the cost is one resolver call per socket per window — 167/s
+ * on the 50,000-socket node this repo has measured, against 1,667/s at a 30s TTL. A deployment
+ * whose credential has a shorter real lifetime passes `runtime.syncAuthenticate` and states it.
+ */
+export const SYNC_GRANT_TTL_MS = 5 * 60_000;
+
+/**
+ * The credential this adapter retains per socket, and nothing else.
+ *
+ * `sync-auth.ts` says the seam is a closure precisely so a node does not hold one `Request` per
+ * connection for the life of that connection: `SyncSocket`'s budget is ~1KB and the grant sits
+ * beside it. Two header values is what an app that closes over a token string would hold.
+ *
+ * Dropping the rest can only make a refresh MORE restrictive, never more permissive: an app that
+ * resolves identity from some other header sees its refresh answer `null`, which closes the socket
+ * with `1008` and the client re-dials carrying that header again. One reconnect per window, not an
+ * escalation — and `runtime.syncAuthenticate` is the declared seam for stating something else.
+ */
+const CREDENTIAL_HEADERS = ['cookie', 'authorization'] as const;
 
 /**
  * The upgrade request, dressed as the request an `Authenticator` reads.
@@ -27,33 +58,74 @@ function upgradeConfig(buildId: string): HttpConfig {
   return defineHttpConfig({ buildId, rateLimit: { enabled: false, scope: 'process' } });
 }
 
+/** What the closure keeps: enough to ask the app's resolver the same question a second time. */
+interface Credential {
+  readonly url: string;
+  readonly method: string;
+  readonly headers: Headers;
+}
+
+function credentialOf(request: Request): Credential {
+  const headers = new Headers();
+  for (const name of CREDENTIAL_HEADERS) {
+    const value = request.headers.get(name);
+    if (value !== null) headers.set(name, value);
+  }
+  return { url: request.url, method: request.method, headers };
+}
+
+export interface SyncAuthenticatorOptions {
+  /** The clock a grant's window is measured on. Injected so a re-auth is provable without sleeping. */
+  readonly clock?: Clock;
+  /** Overrides `SYNC_GRANT_TTL_MS`. A test names its own window; nothing in the boot passes one. */
+  readonly ttlMs?: number;
+}
+
 /**
  * What the sync node is given when the app configured an authenticator, and `undefined` when it
  * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
  * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
  *
- * The grant carries **no `expiresAt` and no `refresh`**, and that is the honest limit of this
- * adapter rather than an omission: `configureAuthenticator()` resolves an `Actor` and says nothing
- * about how long it stays true, so inventing a window here would either close live sockets that
- * are still authorized or claim a lifetime the app never promised. A deployment whose credential
- * has a real expiry passes `runtime.syncAuthenticate` and gets re-authorization; the timer for it
- * already lives in `createSyncNode.start()`.
+ * The grant carries an `expiresAt` and a `refresh`, and both are the app's own resolver asked
+ * again: `configureAuthenticator` says who is dialling, and the only honest way to learn that it
+ * has stopped being true is to ask. A `null` second answer is a revocation the node turns into a
+ * `1008`; a THROW is a backend failure, and `sweepGrants` keeps the grant and retries — the
+ * adapter must not collapse those two, here or on the refresh path.
  */
-export function syncAuthenticator(buildId: string): SyncAuthenticator | undefined {
+export function syncAuthenticator(
+  buildId: string,
+  options: SyncAuthenticatorOptions = {},
+): SyncAuthenticator | undefined {
   const authenticate = configuredAuthenticator();
   if (authenticate === undefined) return undefined;
   // Once per node, not once per upgrade: resolving a config is pure and a 50k-socket node pays
   // this per connection otherwise.
   const config = upgradeConfig(buildId);
-  return async (request: Request): Promise<SyncGrant | null> => {
+  const clock = options.clock ?? systemClock;
+  const ttlMs = options.ttlMs ?? SYNC_GRANT_TTL_MS;
+
+  const resolve = async (credential: Credential): Promise<SyncGrant | null> => {
+    const request = new Request(credential.url, {
+      method: credential.method,
+      headers: credential.headers,
+    });
     const ctx = createRequestContext({
-      url: new URL(request.url),
-      method: request.method,
+      url: new URL(credential.url),
+      method: credential.method,
       role: 'sync',
       config,
-      requestHeaders: request.headers,
+      requestHeaders: credential.headers,
     });
     const actor: Actor | null = await authenticate(new UltimateRequest(request, ctx), ctx);
-    return actor === null ? null : { actor };
+    if (actor === null) return null;
+    return {
+      // The window is measured from the answer, not from the upgrade: a refreshed grant that
+      // returned its original instant would be expired again on the very next pass.
+      actor,
+      expiresAt: clock.now().getTime() + ttlMs,
+      refresh: () => resolve(credential),
+    };
   };
+
+  return async (request: Request): Promise<SyncGrant | null> => resolve(credentialOf(request));
 }

package/src/templates/guard-bare-error.ts

@@ -0,0 +1,122 @@
+// The `bare-error` guard `x new` ships: no shipped module throws a bare `Error`.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `throw new Error(...)` in a
+// scaffolded `repo.ts` was green on `x verify`, and it reaches an agent as a stack trace with no
+// code, no cause and nothing to run.
+
+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 = 'bare-error';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// bare-error: a failure this app raises carries a code, a cause and an executable fix.
+// \`x verify\` discovers every file in \`guards/\` and runs its \`guard\` inside the \`boundaries\`
+// step — nothing registers this file, so nothing can forget to.
+
+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}';
+
+/**
+ * A THROW, never a construction. \`new Error(…)\` handed to something as INPUT is legitimate — a
+ * test fixture, an \`AbortSignal\` reason, a rejection this module is passing along — and only the
+ * throw is this module stating its own verdict.
+ */
+const BARE_THROW = /\\bthrow\\s+new\\s+(Error|TypeError|RangeError|SyntaxError)\\s*\\(/g;
+
+export interface SourceFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly source: string;
+}
+
+/** 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;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function bareThrows(files: readonly SourceFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const text = blank(file.source);
+    for (const match of text.matchAll(BARE_THROW)) {
+      const line = lineOf(text, match.index);
+      const thrown = match[1] ?? 'Error';
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${line} throws a bare \${thrown} — it reaches its reader as a stack trace with no code, no cause and nothing to run\`,
+        fix: \`subclass UltimateError in \${file.path} with an X_SCREAMING_SNAKE code, a cause and a fix naming a command, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a failure carries a code, a cause and an executable fix — never a bare Error',
+  async check(root) {
+    const files: SourceFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.{ts,tsx}').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      // A test states its verdict with \`expect.unreachable()\`, which the suite reports on its own
+      // terms; \`node_modules\` is not this app's source.
+      if (path.includes('node_modules/') || /\\.(?:test|d)\\.tsx?$/.test(path)) continue;
+      files.push({ path, source: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return bareThrows(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 { bareThrows } from './bare-error';
+
+const file = (source: string) => [{ path: 'apps/web/app/post/repo.ts', source }];
+
+unitTest('a bare throw is refused, and the finding names the line', () => {
+  const findings = bareThrows(file("const x = 1;\\nthrow new Error('no post');"));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('TypeError and RangeError are the same rule', () => {
+  expect(bareThrows(file("throw new TypeError('x');"))).toHaveLength(1);
+  expect(bareThrows(file("throw new RangeError('x');"))).toHaveLength(1);
+});
+
+unitTest('an UltimateError subclass is what the rule asks for', () => {
+  expect(bareThrows(file('throw new PostError(missingPost(id));'))).toEqual([]);
+});
+
+unitTest('a bare Error that is INPUT is not a verdict', () => {
+  expect(bareThrows(file("controller.abort(new Error('cancelled'));"))).toEqual([]);
+  expect(bareThrows(file("// throw new Error('x');"))).toEqual([]);
+});
+`;
+
+/** `guards/bare-error.ts` and its test. No index, no registry — the directory registers it. */
+export const bareErrorGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/bare-error.ts', contents: source() },
+  { path: 'guards/bare-error.test.ts', contents: test() },
+];

package/src/templates/guard-raw-colour.ts

@@ -0,0 +1,138 @@
+// The `raw-colour` guard `x new` ships: no stylesheet in this app names a colour.
+// `AGENTS.md` has always stated the rule and NOTHING enforced it — `verify-checks.ts` said it rode
+// on `packages/ui/src/tokens/tokens.test.ts`, which covers the framework's stylesheets and never
+// the app's, so `color: #ff0000` in a scaffolded `page.module.scss` was green on `x verify`.
+
+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 = 'raw-colour';
+const CODE = guardCode(NAME);
+
+const source =
+  (): string => `// raw-colour: every colour in this app is a semantic token, so dark theme is not a later project.
+// \`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}';
+
+/** A hex literal. \`#{$x}\` is Sass interpolation, not a colour, and \`{\` is not a hex digit. */
+const HEX = /#[0-9a-fA-F]{3,8}\\b/;
+const CHANNEL_FUNCTION = /\\b(?:rgba?|hsla?|lab|lch|oklab|oklch|color)\\(/i;
+/** The named colours a human actually types. The full CSS list would report \`.item\` selectors. */
+const NAMED =
+  /\\b(?:white|black|red|green|blue|yellow|orange|purple|pink|brown|gray|grey|silver|navy|teal|olive|lime|aqua|maroon|fuchsia|gold|beige|coral|crimson|indigo|violet|khaki|salmon|tan|turquoise|wheat)\\b/i;
+
+/**
+ * A DECLARATION, never a whole line: a selector carries no colon, so \`#hero { … }\` is not a value
+ * and is never reported. The value stops at the first \`;\`, \`{\` or \`}\`.
+ */
+const DECLARATION = /([\\w-]+)\\s*:\\s*([^;{}]+)/g;
+
+export interface StyleFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly scss: string;
+}
+
+/**
+ * Comments blanked rather than removed, so the reported line number still points at the source
+ * line. \`//\` is skipped when a \`:\` precedes it — \`url(https://…)\` is a value, not a comment.
+ */
+const blankComments = (scss: string): string =>
+  scss
+    .replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, (match) => match.replaceAll(/[^\\n]/g, ' '))
+    .replaceAll(/(?<![:\\w])\\/\\/[^\\n]*/g, (match) => ' '.repeat(match.length));
+
+/** Quoted text is a filename or a token name, never a colour: \`url('red.png')\`, \`role('bg')\`. */
+const unquote = (value: string): string => value.replaceAll(/'[^']*'|"[^"]*"/g, ' ');
+
+const lineOf = (text: string, index: number): number => text.slice(0, index).split('\\n').length;
+
+/** Pure — the caller does the I/O — so the rule is testable without a filesystem. */
+export function rawColours(files: readonly StyleFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    const scss = blankComments(file.scss);
+    for (const match of scss.matchAll(DECLARATION)) {
+      const property = match[1] ?? '';
+      const value = unquote(match[2] ?? '');
+      const literal = HEX.exec(value) ?? CHANNEL_FUNCTION.exec(value) ?? NAMED.exec(value);
+      if (literal === null) continue;
+      findings.push({
+        code: CODE,
+        cause: \`\${file.path}:\${lineOf(scss, match.index)} sets \${property} to the raw colour \${literal[0]} — a value no theme can restate, so dark theme renders it unchanged\`,
+        fix: \`replace \${literal[0]} in \${file.path} with tokens.role('fg'), tokens.role('bg') or the role this element means, then: x verify\`,
+        at: file.path,
+      });
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a stylesheet names a semantic token, never a colour',
+  async check(root) {
+    const files: StyleFile[] = [];
+    for await (const entry of new Bun.Glob('{apps,packages}/**/*.scss').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      const path = entry.split('\\\\').join('/');
+      if (path.includes('node_modules/')) continue;
+      files.push({ path, scss: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return rawColours(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 { rawColours } from './raw-colour';
+
+const sheet = (scss: string) => [{ path: 'apps/web/site/page.module.scss', scss }];
+
+unitTest('a hex literal in a declaration is refused', () => {
+  const findings = rawColours(sheet('.hero {\\n  color: #ff0000;\\n}\\n'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.code).toBe('${CODE}');
+  expect(findings[0]?.cause).toContain('#ff0000');
+  expect(findings[0]?.cause).toContain(':2');
+});
+
+unitTest('rgb(), hsl() and a named colour are the same rule', () => {
+  expect(rawColours(sheet('.a { background: rgb(1 2 3); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { background: hsl(1 2% 3%); }'))).toHaveLength(1);
+  expect(rawColours(sheet('.a { border-color: white; }'))).toHaveLength(1);
+});
+
+unitTest('a token, a selector and a quoted filename are not colours', () => {
+  expect(rawColours(sheet(".a { background: tokens.role('bg'); }"))).toEqual([]);
+  expect(rawColours(sheet('#hero { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet(".a { background: url('red-hero.png'); }"))).toEqual([]);
+});
+
+unitTest('a commented-out colour is a note, not a declaration', () => {
+  expect(rawColours(sheet('// color: #ff0000;\\n.a { padding: 0; }'))).toEqual([]);
+  expect(rawColours(sheet('/* color: #ff0000; */\\n.a { padding: 0; }'))).toEqual([]);
+});
+`;
+
+/** `guards/raw-colour.ts` and its test. No index, no registry — the directory is the registration. */
+export const rawColourGuardFiles = (): readonly GeneratedFile[] => [
+  { path: 'guards/raw-colour.ts', contents: source() },
+  { path: 'guards/raw-colour.test.ts', contents: test() },
+];