@ultimat3/cli 20.1.5 → 20.2.0

package/src/templates/scaffold-site.ts

@@ -0,0 +1,287 @@
+// The generated landing page — `apps/web/site/page.tsx` and its stylesheet and test. Split out of
+// `scaffold-app.ts` when it grew from an `<h1>` and a link into a hero: a dot-grid ground, an
+// eyebrow, a balanced headline, a lede, two calls to action and three feature cards, every string
+// a catalog key and every colour a token. Still 0kb: `render: 'static'`, `hydrate: 'never'`, no
+// island, and it does not wear the app shell — see the page's own header comment.
+
+import { sortedImports } from './imports';
+import type { GeneratedFile, NameSet } from './naming';
+
+// Plain strings for the framework lines, never template literals: the workspace-dependency scanner
+// blanks a string's contents but not a nested template's, so a template here would bill the CLI
+// for the imports of the app it writes.
+const sitePage = (
+  app: NameSet,
+): string => `// The landing page. site/ is 0kb JS: static render, hydrate never, no framework script tag.
+//
+// Strings come from \`useT()\` — this app's own catalog module — and never from
+// \`t\` in @ultimat3/i18n. That import is what puts the module holding \`defineCatalogs()\` in
+// this page's graph, so rendering a string is what registers the catalogs. A page that reached
+// past it shipped every string as \`\u27e6key\u27e7\` with \`x verify\` green (issue #249).
+//
+// Not inside \`shared/shell.tsx\`: the shell is the signed-in product's chrome, and a landing page
+// that wore it would ship a sidebar to visitors who cannot open anything in it.
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  "import { defineRoute } from '@ultimat3/render';",
+  "import { Icon } from '@ultimat3/ui';",
+  "import { iconArrowRight } from '@ultimat3/ui/icons/arrow-right';",
+  "import { iconGauge } from '@ultimat3/ui/icons/gauge';",
+  "import { iconShieldCheck } from '@ultimat3/ui/icons/shield-check';",
+  "import { iconZap } from '@ultimat3/ui/icons/zap';",
+])}
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  hydrate: 'never',
+  offline: 'precache',
+  budget: { js: '0kb' },
+  // \`t\` is handed to \`meta\` by the router — one translator per render, resolved against the
+  // request's locale before the head is built.
+  meta: ({ t }) => ({
+    title: t('site.home.title'),
+    description: t('site.home.description'),
+  }),
+});
+
+export function HomePage() {
+  const t = useT();
+
+  return (
+    <main class={styles.page}>
+      <header class={styles.hero}>
+        <p class={styles.eyebrow}>{t('site.home.eyebrow')}</p>
+        <h1 class={styles.title}>{t('site.home.headline')}</h1>
+        <p class={styles.lede}>{t('site.home.lede')}</p>
+        <div class={styles.actions}>
+          <a class={styles.cta} href="/dashboard">
+            {t('site.home.cta')}
+            <Icon glyph={iconArrowRight} size="sm" />
+          </a>
+          <a class={styles.ghost} href="/admin">
+            {t('site.home.secondary')}
+          </a>
+        </div>
+      </header>
+      {/* What this app already IS, in three facts — not three adjectives. Static markup: this
+          route ships no island and its JS budget is zero. */}
+      <ul class={styles.features}>
+        <li class={styles.feature}>
+          <span class={styles.featureIcon} aria-hidden="true">
+            <Icon glyph={iconZap} size="sm" />
+          </span>
+          <h2>{t('site.home.f1Title')}</h2>
+          <p>{t('site.home.f1Body')}</p>
+        </li>
+        <li class={styles.feature}>
+          <span class={styles.featureIcon} aria-hidden="true">
+            <Icon glyph={iconShieldCheck} size="sm" />
+          </span>
+          <h2>{t('site.home.f2Title')}</h2>
+          <p>{t('site.home.f2Body')}</p>
+        </li>
+        <li class={styles.feature}>
+          <span class={styles.featureIcon} aria-hidden="true">
+            <Icon glyph={iconGauge} size="sm" />
+          </span>
+          <h2>{t('site.home.f3Title')}</h2>
+          <p>{t('site.home.f3Body')}</p>
+        </li>
+      </ul>
+    </main>
+  );
+}
+
+export const appName = '${app.kebab}';
+`;
+
+const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.page {
+  display: flex;
+  flex-direction: column;
+  gap: tokens.space(12);
+  max-inline-size: 72rem;
+  min-block-size: 100dvh;
+  margin-inline: auto;
+  padding: tokens.space(8) tokens.space(4) tokens.space(16);
+  background: tokens.role('bg');
+  color: tokens.role('fg');
+
+  @include tokens.respond-to(md) {
+    padding: tokens.space(16) tokens.space(8);
+  }
+}
+
+.hero {
+  @include tokens.dot-grid;
+
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: tokens.space(5);
+  padding: tokens.space(8) tokens.space(6);
+  overflow: hidden;
+  border: 1px solid tokens.role('line', 0.6);
+  border-radius: tokens.radius('xl');
+
+  @include tokens.respond-to(md) {
+    padding: tokens.space(16) tokens.space(12);
+  }
+}
+
+.eyebrow {
+  @include tokens.label-caps;
+
+  margin: 0;
+  padding: tokens.space(1) tokens.space(3);
+  border: 1px solid tokens.role('accent', 0.35);
+  border-radius: tokens.radius('pill');
+  background: tokens.role('accent', 0.1);
+  color: tokens.role('accent');
+}
+
+.title {
+  max-inline-size: 18ch;
+  margin: 0;
+  color: tokens.role('fg-strong');
+  font-size: tokens.text('3xl');
+  font-weight: tokens.weight('semibold');
+  letter-spacing: tokens.tracking('tight');
+  line-height: 1.05;
+  text-wrap: balance;
+}
+
+.lede {
+  max-inline-size: 36rem;
+  margin: 0;
+  color: tokens.role('fg-muted');
+  font-size: tokens.text('lg');
+  line-height: tokens.leading('normal');
+  text-wrap: pretty;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: tokens.space(3);
+  margin-block-start: tokens.space(2);
+}
+
+// Both calls to action share one shape; only the paint differs.
+@mixin action {
+  @include tokens.focus-ring;
+
+  display: inline-flex;
+  align-items: center;
+  gap: tokens.space(2);
+  block-size: 2.75rem;
+  padding-inline: tokens.space(5);
+  border-radius: tokens.radius('md');
+  font-weight: tokens.weight('medium');
+  text-decoration: none;
+  transition:
+    background-color tokens.duration('fast') tokens.easing('out'),
+    border-color tokens.duration('fast') tokens.easing('out'),
+    color tokens.duration('fast') tokens.easing('out');
+}
+
+.cta {
+  @include action;
+
+  background: tokens.role('accent');
+  color: tokens.role('accent-fg');
+
+  &:hover {
+    background: tokens.role('accent-strong');
+  }
+}
+
+.ghost {
+  @include action;
+
+  border: 1px solid tokens.role('line');
+  color: tokens.role('fg');
+
+  &:hover {
+    border-color: tokens.role('fg-muted');
+    color: tokens.role('fg-strong');
+  }
+}
+
+.features {
+  display: grid;
+  gap: tokens.space(4);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+
+  @include tokens.respond-to(md) {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+.feature {
+  display: flex;
+  flex-direction: column;
+  gap: tokens.space(3);
+  padding: tokens.space(6);
+  border: 1px solid tokens.role('line', 0.6);
+  border-radius: tokens.radius('lg');
+  background: tokens.role('surface');
+
+  h2 {
+    margin: 0;
+    color: tokens.role('fg-strong');
+    font-size: tokens.text('md');
+    font-weight: tokens.weight('medium');
+  }
+
+  p {
+    margin: 0;
+    color: tokens.role('fg-muted');
+    font-size: tokens.text('sm');
+    line-height: tokens.leading('normal');
+  }
+}
+
+.featureIcon {
+  display: inline-grid;
+  place-items: center;
+  inline-size: tokens.space(8);
+  block-size: tokens.space(8);
+  border: 1px solid tokens.role('line');
+  border-radius: tokens.radius('md');
+  background: tokens.role('surface-raised');
+  color: tokens.role('accent');
+}
+`;
+
+const sitePageTest =
+  (): string => `// The landing page ships zero JS and declares its metadata. Both are promises the file makes in
+// its config, and both are the kind that rot silently when someone adds one import.
+import { metaContextFor, routeDataFor } from '@ultimat3/render';
+import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+// The same two objects a render builds: \`routeDataFor\` resolves the route's data once, and
+// \`metaContextFor\` wraps it the way every render mode wraps it before calling \`meta\`.
+const ctx = { params: {}, url: 'https://example.test/' };
+
+unitTest('the landing page ships zero JS and declares metadata', async () => {
+  expect(config.render).toBe('static');
+  expect(config.hydrate).toBe('never');
+  expect(config.budget.js).toBe('0kb');
+  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
+  expect(meta.title ?? '').not.toBe('');
+});
+`;
+
+/** The landing page, its stylesheet and its test. */
+export const siteFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
+  { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
+  { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
+];

package/src/theme-boot.ts

@@ -0,0 +1,59 @@
+// The no-flash theme script, inlined into every document a served or exported process writes,
+// with `theme.defaultMode` from `app.config.ts` as its fallback. Before this the key had no reader
+// at all (pinned as a dead key in `scripts/lib/config-reader-pins.ts`) and neither of the two
+// scripts the framework exported was wired into a document: an app that wanted to open dark had to
+// write its own boot script AND admit it to the CSP by hand — which every app forgot in one of the
+// two places. Sibling of `app-auth.ts`'s `loadSignInPath` and imports the config for the same
+// reason: a regex over the app's source is the pattern `app-load.ts` refuses.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative — the same
+// necessity `app-auth.ts` records.
+import { join } from 'node:path';
+import type { ThemeMode } from '@ultimat3/core';
+import { cspHashSource } from '@ultimat3/http';
+import { renderHead, themeScript, themeScriptBody } from '@ultimat3/render';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const isThemeMode = (value: unknown): value is ThemeMode =>
+  value === 'light' || value === 'dark' || value === 'system';
+
+/**
+ * `theme.defaultMode`, or `'system'` — the value `defineConfig` fills in — when the app declares
+ * none or the file is absent. Structural, never `instanceof`, for `loadSignInPath`'s reason.
+ */
+export async function loadThemeMode(root: string): Promise<ThemeMode> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return 'system';
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return 'system';
+  const theme = config['theme'];
+  if (!isRecord(theme)) return 'system';
+  const mode = theme['defaultMode'];
+  return isThemeMode(mode) ? mode : 'system';
+}
+
+export interface ThemeBoot {
+  /** The rendered `<script>` tag, for `DocumentOptions.themeHead`. */
+  readonly head: string;
+  /** The `script-src` source that admits exactly that tag's body. */
+  readonly cspSource: string;
+}
+
+/**
+ * Tag and hash from ONE body: `themeScriptBody` is what `themeScript` inlines, so a policy hashed
+ * here admits the script the document carries and not a restatement of it. The storage key is
+ * render's `THEME_STORAGE_KEY`, which `theme-boot.test.ts` pins equal to `@ultimat3/ui`'s — the
+ * toggle writes the key the boot reads.
+ */
+export function themeBoot(mode: ThemeMode): ThemeBoot {
+  const options = { fallback: mode };
+  return {
+    head: renderHead([themeScript(options)]),
+    cspSource: cspHashSource(themeScriptBody(options)),
+  };
+}

package/src/ui-diff.ts

@@ -0,0 +1,90 @@
+// The pixel half of `ui.diff`: two RGBA buffers of one size in, a count, a bounding box and a
+// diff picture out. Pure — no file, no PNG container, no browser — so the rule a picture is judged
+// by can be read in one screen and tested with four-byte images.
+//
+// The rule is per channel: a pixel is CHANGED when any of its four channels moved by more than
+// `threshold * 255` between the two captures. There is deliberately NO anti-alias detection: a
+// pixelmatch-style "this differs but a neighbour matches, so it is a font hinting artefact" pass
+// is a heuristic a model then has to reason about, and the threshold already absorbs a one-level
+// wobble. A capture that rendered a glyph one subpixel over is a change — an agent that judges it
+// noise raises the threshold, which is a number in the call rather than a rule in this file.
+//
+// The diff picture is the `after` capture faded to a quarter over a light grey, with every changed
+// pixel solid red. Faded rather than removed, so a red pixel is read against what it sits on.
+
+import type { UiInspectBox } from '@ultimat3/mcp';
+
+export interface PixelDiff {
+  readonly changedPixels: number;
+  /** The tightest box around every changed pixel, or `null` when nothing changed. */
+  readonly changedBox: UiInspectBox | null;
+  /** RGBA, the same size as the inputs: the faded `after` with changed pixels in `DIFF_RED`. */
+  readonly diffRgba: Uint8ClampedArray;
+}
+
+const CHANNELS = 4;
+/** Where an unchanged pixel lands: a quarter of its own colour over `FADE_GROUND`. */
+export const FADE_ALPHA = 0.25;
+export const FADE_GROUND = 230;
+export const DIFF_RED = [255, 0, 0, 255] as const;
+
+/** `threshold` in `[0, 1]` as a fraction of a channel's range; a delta strictly above it counts. */
+export function channelLimit(threshold: number): number {
+  return Math.min(1, Math.max(0, threshold)) * 255;
+}
+
+/** The faded value of one channel: `FADE_ALPHA` of it over the ground, rounded like a compositor. */
+export const faded = (channel: number): number =>
+  Math.round(channel * FADE_ALPHA + FADE_GROUND * (1 - FADE_ALPHA));
+
+export function diffPixels(
+  before: Uint8ClampedArray,
+  after: Uint8ClampedArray,
+  width: number,
+  height: number,
+  threshold: number,
+): PixelDiff {
+  const limit = channelLimit(threshold);
+  const diffRgba = new Uint8ClampedArray(width * height * CHANNELS);
+  let changedPixels = 0;
+  let minX = width;
+  let minY = height;
+  let maxX = -1;
+  let maxY = -1;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const at = (y * width + x) * CHANNELS;
+      const changed =
+        Math.abs((before[at] ?? 0) - (after[at] ?? 0)) > limit ||
+        Math.abs((before[at + 1] ?? 0) - (after[at + 1] ?? 0)) > limit ||
+        Math.abs((before[at + 2] ?? 0) - (after[at + 2] ?? 0)) > limit ||
+        Math.abs((before[at + 3] ?? 0) - (after[at + 3] ?? 0)) > limit;
+      if (changed) {
+        changedPixels += 1;
+        if (x < minX) minX = x;
+        if (x > maxX) maxX = x;
+        if (y < minY) minY = y;
+        if (y > maxY) maxY = y;
+        diffRgba.set(DIFF_RED, at);
+      } else {
+        diffRgba[at] = faded(after[at] ?? 0);
+        diffRgba[at + 1] = faded(after[at + 1] ?? 0);
+        diffRgba[at + 2] = faded(after[at + 2] ?? 0);
+        // Opaque: the fade is baked into the colour, so the picture reads the same on any viewer.
+        diffRgba[at + 3] = 255;
+      }
+    }
+  }
+  const changedBox =
+    changedPixels === 0
+      ? null
+      : { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+  return { changedPixels, changedBox, diffRgba };
+}
+
+/** `changedPixels / (width * height)` as a percentage with two decimals; `0` for an empty image. */
+export function changedPercent(changedPixels: number, width: number, height: number): number {
+  const total = width * height;
+  if (total === 0) return 0;
+  return Math.round((changedPixels / total) * 10_000) / 100;
+}

package/src/ui-inspect-probe.ts

@@ -0,0 +1,131 @@
+// The one expression `ui.inspect` runs in the page, and the parser that refuses to trust what
+// came back. Built from plain values and DETERMINISTIC for one spec: the offline drivers answer
+// `evaluate` from a recording keyed by the exact expression string, so `mcp-ui-inspect.test.ts`
+// records against `inspectExpression(spec)` and proves the whole tool on a box with no Chrome.
+//
+// Every cap is applied IN the page — matches, text length, attribute count — so the wire payload
+// is bounded before the browser serialises it. A `*` selector on a long page is thousands of
+// nodes, and `textContent` of `<body>` is the whole document; a probe that fetched all of it and
+// trimmed afterwards would still have paid for all of it.
+
+import { UI_INSPECT_LIMITS } from '@ultimat3/mcp';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { t, validate } from '@ultimat3/schema';
+
+export interface InspectSpec {
+  readonly selectors: readonly string[];
+  /** Computed property names, kebab-case, already filtered by the tool handler. */
+  readonly styles: readonly string[];
+  readonly activeElement: boolean;
+}
+
+export interface InspectProbeMatch {
+  readonly tag: string;
+  readonly text: string;
+  readonly box: {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+  };
+  readonly visible: boolean;
+  readonly attrs: Readonly<Record<string, string>>;
+  readonly styles: Readonly<Record<string, string>>;
+}
+
+export interface InspectProbeSelector {
+  readonly selector: string;
+  readonly valid: boolean;
+  readonly count: number;
+  readonly truncated: boolean;
+  readonly matches: readonly InspectProbeMatch[];
+}
+
+export interface InspectProbe {
+  readonly title: string;
+  readonly theme: string | null;
+  readonly activeElement: {
+    readonly tag: string;
+    readonly id: string;
+    readonly role: string;
+    readonly name: string;
+  } | null;
+  readonly selectors: readonly InspectProbeSelector[];
+}
+
+/**
+ * ES5 and an expression, never a closure: `CdpPageLike.evaluate` takes the string form only, and
+ * the page may be older than the CLI. `querySelectorAll` runs inside a `try` so a selector the
+ * engine cannot parse is reported as `valid: false` beside the ones it could — one bad selector
+ * must not cost the whole navigation. Rounded boxes: a sub-pixel `x` is noise an agent diffs on.
+ */
+export function inspectExpression(spec: InspectSpec): string {
+  const selectors = JSON.stringify([...spec.selectors]);
+  const styles = JSON.stringify([...spec.styles]);
+  const active = spec.activeElement ? 'true' : 'false';
+  const { matches, textChars, attrs } = UI_INSPECT_LIMITS;
+  return (
+    `(function(){var S=${selectors};var P=${styles};var A=${active};` +
+    'function nm(el){return el.getAttribute("aria-label")||el.getAttribute("name")||"";}' +
+    `function at(el){var o={};var a=el.attributes;for(var i=0;i<a.length&&i<${attrs};i+=1){` +
+    `o[a[i].name]=String(a[i].value).slice(0,${textChars});}return o;}` +
+    'function st(el){var o={};if(P.length===0)return o;var cs=getComputedStyle(el);' +
+    'for(var i=0;i<P.length;i+=1){o[P[i]]=cs.getPropertyValue(P[i]);}return o;}' +
+    'function m(el){var r=el.getBoundingClientRect();var cs=getComputedStyle(el);' +
+    'return{tag:el.tagName.toLowerCase(),' +
+    `text:(el.textContent||"").replace(/\\s+/g," ").trim().slice(0,${textChars}),` +
+    'box:{x:Math.round(r.left),y:Math.round(r.top),width:Math.round(r.width),height:Math.round(r.height)},' +
+    'visible:r.width>0&&r.height>0&&cs.visibility!=="hidden"&&cs.display!=="none",' +
+    'attrs:at(el),styles:st(el)};}' +
+    'var out=[];for(var i=0;i<S.length;i+=1){var sel=S[i];var els;' +
+    'try{els=document.querySelectorAll(sel);}catch(e){' +
+    'out.push({selector:sel,valid:false,count:0,truncated:false,matches:[]});continue;}' +
+    `var ms=[];for(var j=0;j<els.length&&j<${matches};j+=1)ms.push(m(els[j]));` +
+    `out.push({selector:sel,valid:true,count:els.length,truncated:els.length>${matches},matches:ms});}` +
+    'var ae=document.activeElement;var active=A&&ae?{tag:ae.tagName.toLowerCase(),id:ae.id||"",' +
+    'role:ae.getAttribute("role")||"",name:nm(ae)}:null;' +
+    'return{title:document.title||"",theme:document.documentElement.getAttribute("data-theme"),' +
+    'activeElement:active,selectors:out};})()'
+  );
+}
+
+const matchSchema = t.object({
+  tag: t.string,
+  text: t.string.min(0),
+  box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
+  visible: t.boolean,
+  attrs: t.record(t.string.min(0)),
+  styles: t.record(t.string.min(0)),
+});
+
+const inspectProbeSchema: StandardSchemaV1<unknown, InspectProbe> = t.object({
+  title: t.string.min(0),
+  theme: t.nullable(t.string.min(0)),
+  activeElement: t.nullable(
+    t.object({
+      tag: t.string,
+      id: t.string.min(0),
+      role: t.string.min(0),
+      name: t.string.min(0),
+    }),
+  ),
+  selectors: t.array(
+    t.object({
+      selector: t.string.min(0),
+      valid: t.boolean,
+      count: t.number,
+      truncated: t.boolean,
+      matches: t.array(matchSchema),
+    }),
+  ),
+}) as unknown as StandardSchemaV1<unknown, InspectProbe>;
+
+/**
+ * `evaluate()` answers `unknown` on every driver, so the probe's result is PARSED and never cast —
+ * the rule `parseIslandProbe` follows. `null` for anything that does not fit: the picture and the
+ * verdict were already taken, and a malformed probe must not take them down with it.
+ */
+export function parseInspectProbe(value: unknown): InspectProbe | null {
+  const result = validate(inspectProbeSchema, value);
+  return result.issues === undefined ? result.value : null;
+}