@ultimat3/cli 11.1.0 → 11.2.0

package/src/island-harness-route.ts

@@ -0,0 +1,91 @@
+// Serving the harness. It is a `x dev` route and not a second server, for the reason `x shot`
+// reuses a running dev server at all: the chunks, the app's stylesheet registry and the island
+// bundle all live in the process that built them, and embedded Postgres is single-writer so there
+// can only be one of those per checkout.
+
+import type { Route, UltimateRequest } from '@ultimat3/http';
+import { html, json } from '@ultimat3/http';
+import type { IslandStatesManifest } from '@ultimat3/testing';
+import {
+  islandShotFile,
+  islandShotTargets,
+  islandStatesMatching,
+  islandStatesNames,
+  parseIslandAddress,
+} from '@ultimat3/testing';
+import { harnessPage, ISLAND_HARNESS_PATH } from './island-harness';
+import type { IslandSource } from './island-routes';
+
+/**
+ * A getter, never the manifests: `x dev` rebuilds on the watcher tick, and a set captured when the
+ * route was mounted would serve a state the author has since edited for the rest of the session.
+ * It is async because reading a states file is an `import()`, and one that throws is answered as a
+ * refusal rather than taking the dev server down.
+ */
+export type IslandStatesSource = () => Promise<readonly IslandStatesManifest[]>;
+
+const refused = (cause: string, fix: string): Response =>
+  json(
+    { ok: false, error: { code: 'X_SHOT_ISLAND_UNPHOTOGRAPHABLE', cause, fix } },
+    { status: 404 },
+  );
+
+export interface HarnessRouteInput {
+  readonly islands: IslandSource;
+  readonly states: IslandStatesSource;
+}
+
+/**
+ * `GET /_x/island?island=…&state=…&theme=…`. The address is parsed by the vocabulary's own
+ * `parseIslandAddress`, which is `islandAddress`'s inverse and is TOTAL — a mistyped theme falls
+ * back rather than throwing, because a page that renders an error over a typo turns a typo into a
+ * screenshot of the framework.
+ *
+ * An island or a state this process does not know is the one case that IS refused, and it can only
+ * mean the two processes disagree: `x shot` computed its picture list from the states files on disk
+ * and this server was booted against an older set.
+ */
+export function islandHarnessRoutes(input: HarnessRouteInput): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: ISLAND_HARNESS_PATH,
+      meta: { name: 'dev._x.island', auth: 'public', tags: ['dev'] },
+      handler: async (request: UltimateRequest): Promise<Response> => {
+        const address = parseIslandAddress(request.url.search);
+        const all = await input.states();
+        const manifest = islandStatesMatching(all, address.island)[0];
+        if (manifest === undefined) {
+          return refused(
+            `this dev server declares no island states for ${address.island === '' ? '(no island named)' : address.island} — it knows ${islandStatesNames(all).join(', ') || 'none'}`,
+            'restart x dev, then: x shot --island <name> --json',
+          );
+        }
+        // `wanted`, never a local called `state`: `bun run secret-compare` reads the NAME of a
+        // comparison's operands and `state` is on its list — an OAuth handshake state is compared
+        // under exactly that name, and this one is a screenshot filename stem.
+        const wanted = address.state;
+        const declared = manifest.states.find((one) => one.id === wanted);
+        const file = islandShotFile(manifest.name, wanted, address.theme);
+        const target = islandShotTargets(manifest).find((one) => one.file === file);
+        if (declared === undefined || target === undefined) {
+          return refused(
+            `${manifest.island} declares no state ${wanted === '' ? '(none named)' : wanted} in theme ${address.theme}`,
+            `x shot --island ${manifest.name} --state ${manifest.states[0]?.id ?? '<id>'} --json`,
+          );
+        }
+        // The chunk is looked up rather than built here: `x dev` already built every island at
+        // boot and rebuilds on the watcher tick, so a second build would be a second answer to
+        // "what code does this island run".
+        const chunk = input.islands().chunks.find((one) => one.file === manifest.island);
+        if (chunk === undefined) {
+          return refused(
+            `${manifest.island} is declared as an island's states file but this build has no chunk for it`,
+            `x g island ${manifest.name} --at ${manifest.island.split('/').slice(0, -1).join('/')}`,
+          );
+        }
+        return html(harnessPage({ target, state: declared, entry: chunk.url }));
+      },
+    },
+  ];
+}

package/src/island-harness-script.ts

@@ -0,0 +1,147 @@
+// The inline script the harness page runs BEFORE the island's chunk: the sealed network, the
+// pinned clock and the readiness signal. A classic `<script>` in `<head>` evaluates before any
+// module script, which is the only ordering in which a component's first `fetch` can be caught.
+//
+// A string and not a module, deliberately: this runs in the browser and the CLI has no bundler in
+// the path that serves a page. `@ultimat3/testing`'s `sealNetwork()` patches THIS process's
+// `globalThis.fetch` and cannot reach the page's realm.
+
+import type { IslandRouteStub } from '@ultimat3/testing';
+
+/**
+ * Consecutive animation frames with an unchanged activity counter before a page is called ready.
+ * QUIET, never zero in flight: a state whose fixture is deliberately `pending` has a request that
+ * never settles, so waiting for zero hangs forever — and a fixed sleep photographs whatever a slow
+ * machine had painted by then.
+ */
+export const QUIET_FRAMES = 3;
+
+/** The one global the CLI reads back. Namespaced so an app's own page state can never collide. */
+export const HARNESS_GLOBAL = '__xShot';
+
+/**
+ * Embedded as a JS string literal, so `<` is escaped: a `</script` anywhere inside a stub body
+ * would otherwise end the tag and the rest of the page would be parsed as markup. Escaping the
+ * character rather than the sequence is the total form — there is no second spelling of it.
+ */
+const embed = (value: unknown): string => JSON.stringify(value ?? null).replaceAll('<', '\\u003c');
+
+export interface HarnessScriptOptions {
+  readonly stubs: readonly IslandRouteStub[];
+  /** The frozen instant, with an explicit offset — the manifest's `now`. */
+  readonly now: string;
+  /** The IANA zone every unzoned `Intl.DateTimeFormat` in the page is given. */
+  readonly timeZone: string;
+}
+
+/**
+ * The seal. Four egress surfaces, and an unmatched request on any of them REJECTS while recording
+ * itself: a component whose fetch quietly hangs paints its own loading branch, and the picture then
+ * shows a fixture gap dressed up as a real component state.
+ *
+ * `activity` counts a request STARTING and a request SETTLING, which is what lets readiness be
+ * "nothing changed for N frames" rather than "nothing is in flight" — the second is unreachable for
+ * a `pending` fixture, which is a state an author declares on purpose.
+ */
+const sealScript = (stubs: readonly IslandRouteStub[]): string => `
+var W=window.${HARNESS_GLOBAL};var STUBS=${embed(stubs)};
+function bump(){W.activity+=1}
+function stubFor(method,path){var k=method.toUpperCase()+' '+path;
+for(var i=0;i<STUBS.length;i+=1){if(k.indexOf(STUBS[i].match)===0)return STUBS[i].respond}
+W.unstubbed.push(k);return null}
+// Pathname AND query: the vocabulary says a stub's \`match\` is a PREFIX, so \`'GET /api/quota'\`
+// catching \`/api/quota?window=day\` is a property of the key carrying the query, not of the match.
+function pathOf(url){try{var u=new URL(url,location.href);return u.pathname+u.search}catch(e){return String(url)}}
+function refuse(k){return new Error('x shot: no stub answers '+k+' — declare it in the state\\'s routes')}
+function answer(respond,k){
+if(respond===null)return Promise.reject(refuse(k));
+if(respond.kind==='pending')return new Promise(function(){});
+if(respond.kind==='offline')return Promise.reject(new TypeError('x shot: offline fixture for '+k));
+return Promise.resolve(new Response(JSON.stringify(respond.body===undefined?null:respond.body),
+{status:respond.status||200,headers:{'content-type':'application/json'}}))}
+window.fetch=function(input,init){
+var url=typeof input==='string'?input:(input&&input.url)||String(input);
+var method=(init&&init.method)||(typeof input==='object'&&input&&input.method)||'GET';
+var path=pathOf(url);var k=method.toUpperCase()+' '+path;
+var respond=stubFor(method,path);bump();
+return answer(respond,k).then(function(r){bump();return r},function(e){bump();throw e})};
+// A socket and an event stream have no stub vocabulary at all, so both are refused outright and
+// recorded: a live component that opened one would otherwise sit in its loading branch forever.
+window.WebSocket=function(url){W.unstubbed.push('WS '+url);throw refuse('WS '+url)};
+window.EventSource=function(url){W.unstubbed.push('SSE '+url);throw refuse('SSE '+url)};
+var RealXHR=window.XMLHttpRequest;
+window.XMLHttpRequest=function(){var xhr=new RealXHR();var open=xhr.open;
+xhr.open=function(method,url){W.unstubbed.push(String(method).toUpperCase()+' '+pathOf(url));
+return open.apply(xhr,arguments)};return xhr};
+// Nothing here serves a service worker, and one an earlier page registered would answer requests
+// this seal never sees. A no-op registration keeps a component that asks from throwing.
+if(navigator.serviceWorker)navigator.serviceWorker.register=function(){return Promise.resolve(undefined)};
+`;
+
+/**
+ * The clock, pinned in both halves. A harness that freezes the INSTANT and leaves the zone ambient
+ * renders `12:00` on one machine and `14:00` on the next, and the review diff then reports a
+ * component change that never happened — so the zone is filled in for every `Intl.DateTimeFormat`
+ * built without one, and the instant replaces the argumentless `new Date()`.
+ *
+ * `toLocaleString` on a Date is NOT covered: it reaches the engine's own Intl and not this global.
+ * The framework's rule is that no date is formatted without an explicit `timeZone`, so a component
+ * obeying it is pinned; one that does not is a blind spot the verdict names rather than hides.
+ */
+const clockScript = (now: string, timeZone: string): string => `
+var FIXED=${embed(Date.parse(now))};var ZONE=${embed(timeZone)};
+class ShotDate extends Date{constructor(){if(arguments.length===0)super(FIXED);else super(...arguments)}
+static now(){return FIXED}}
+window.Date=ShotDate;
+var RealDTF=Intl.DateTimeFormat;
+function zoned(options){return options&&options.timeZone?options:Object.assign({},options,{timeZone:ZONE})}
+function ShotDTF(locales,options){return new RealDTF(locales,zoned(options))}
+ShotDTF.prototype=RealDTF.prototype;
+ShotDTF.supportedLocalesOf=RealDTF.supportedLocalesOf.bind(RealDTF);
+Intl.DateTimeFormat=ShotDTF;
+`;
+
+/**
+ * Ready is quiet, not idle. Fonts first — a picture taken mid-swap photographs the fallback face —
+ * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled.
+ */
+const readyScript = (): string => `
+var last=-1;var still=0;
+function tick(){var seen=W.activity;
+if(seen===last)still+=1;else{still=0;last=seen}
+if(still>=${QUIET_FRAMES}){W.ready=true;return}
+requestAnimationFrame(tick)}
+(document.fonts?document.fonts.ready:Promise.resolve()).then(function(){requestAnimationFrame(tick)});
+`;
+
+/** The whole prelude, in the one order that works: state, seal, clock, then the readiness watch. */
+export function harnessScript(options: HarnessScriptOptions): string {
+  return [
+    `window.${HARNESS_GLOBAL}={harness:true,activity:0,ready:false,unstubbed:[]};`,
+    sealScript(options.stubs),
+    clockScript(options.now, options.timeZone),
+    readyScript(),
+  ].join('\n');
+}
+
+/**
+ * What the CLI evaluates before every capture, as one expression — `CdpPageLike.evaluate` takes
+ * the string form only. Every clause is a fact a picture cannot carry: a host that never attached,
+ * a mount that rejected, a box of zero pixels, a box holding nothing, a request nobody stubbed.
+ *
+ * `selector` is the crop target the manifest declared; the island's own host element when absent.
+ */
+export const readinessProbe = (selector: string): string =>
+  `(function(){var W=window.${HARNESS_GLOBAL}||{};` +
+  'var host=document.querySelector("[data-x-island]");' +
+  `var box=document.querySelector(${JSON.stringify(selector)})||host;` +
+  'var r=box?box.getBoundingClientRect():{width:0,height:0,x:0,y:0};' +
+  'return{harness:W.harness===true,ready:W.ready===true,' +
+  'unstubbed:(W.unstubbed||[]).slice(),' +
+  'attached:host!==null&&document.body.contains(host),' +
+  'mounted:host!==null&&host.hasAttribute("data-x-mounted"),' +
+  'failed:host&&host.hasAttribute("data-x-failed")?host.getAttribute("data-x-failed"):null,' +
+  // Children OR text: a component that renders one text node has painted, and one that mounted
+  // and rendered nothing is the silence a non-zero box would otherwise read as success.
+  'filled:box?(box.children.length>0||(box.textContent||"").trim().length>0):false,' +
+  'box:{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)}};})()';

package/src/island-harness.ts

@@ -0,0 +1,98 @@
+// The harness document: one island, one state, one theme, mounted over the SEAM the framework
+// already has — `data-x-entry` for the chunk, `data-x-props` for the props, and
+// `@ultimat3/render`'s own hydration runtime to boot it. A second mounting mechanism here would be
+// a picture of something no page ever renders.
+
+// why: no Bun native takes a path apart; the surface is a segment of an app-root-relative path.
+import { basename } from 'node:path';
+import type { IslandDirective, Surface } from '@ultimat3/render';
+import {
+  emitIslandAttributes,
+  emitIslandProps,
+  hydrateRuntime,
+  islandModuleId,
+  SURFACES,
+} from '@ultimat3/render';
+import { stylesFor } from '@ultimat3/render/server';
+import type { IslandShotTarget, IslandState } from '@ultimat3/testing';
+import { harnessScript } from './island-harness-script';
+
+/** Where the harness lives in `x dev`'s own namespace, so no app route can shadow it. */
+export const ISLAND_HARNESS_PATH = '/_x/island';
+
+/**
+ * `idle`, and not because the picture should wait: it is the only strategy whose runtime boots an
+ * island nothing has scrolled to or clicked, and reusing a shipped strategy is what keeps the
+ * `data-x-mounted` / `data-x-failed` markers — the two facts a picture cannot carry — landing here
+ * exactly as they land on a real page.
+ */
+const HARNESS_STRATEGY = 'idle';
+
+/**
+ * `apps/web/app/settings/settings.island.tsx` → `app`. The CSS a document carries is per surface
+ * (axiom 6 applied to bytes the browser parses), so a `site/` island photographed against `app/`'s
+ * stylesheet would be a picture of styling that page never receives.
+ */
+export function surfaceOf(island: string): Surface | null {
+  const segment = island.split('/')[2];
+  return SURFACES.find((surface) => surface === segment) ?? null;
+}
+
+/**
+ * The frame, and every rule in it is about what a REVIEWER sees. Animations and transitions are
+ * off because a picture taken mid-transition is a picture of a moment no user experiences; the
+ * caret is invisible because a focused input blinks and two otherwise identical runs then differ.
+ * Colours are semantic tokens, never literals — the app's own global layer defines them.
+ */
+const FRAME_STYLE = `
+*,*::before,*::after{animation:none !important;transition:none !important;
+scroll-behavior:auto !important;caret-color:transparent !important}
+html{background:rgb(var(--color-bg) / 1)}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+background:rgb(var(--color-bg) / 1)}
+#x-shot-frame{padding:var(--space-4, 16px);max-width:100%;box-sizing:border-box}
+`.trim();
+
+export interface HarnessPageInput {
+  readonly target: IslandShotTarget;
+  readonly state: IslandState;
+  /** The built chunk's immutable URL — what `data-x-entry` carries and what the runtime imports. */
+  readonly entry: string;
+}
+
+/**
+ * One address, one document, and every address is a FULL PAGE LOAD. Switching islands or states
+ * client-side would carry the previous state's fixtures, its resolved resources and its mounted
+ * DOM into the next picture, which is the one way a screenshot tool can lie about its own subject.
+ */
+export function harnessPage(input: HarnessPageInput): string {
+  const moduleId = islandModuleId(basename(input.target.island));
+  const directive: IslandDirective = {
+    islandId: moduleId,
+    moduleId,
+    strategy: HARNESS_STRATEGY,
+    entry: input.entry,
+    props: input.state.props,
+  };
+  const css = stylesFor(surfaceOf(input.target.island));
+  return [
+    '<!doctype html>',
+    `<html lang="en" data-theme="${input.target.theme}">`,
+    '<head><meta charset="utf-8">',
+    `<title>${input.target.name} · ${input.target.state} · ${input.target.theme}</title>`,
+    css.length === 0 ? '' : `<style>${css}</style>`,
+    `<style>${FRAME_STYLE}</style>`,
+    // Before the body and before every module script, which is the only ordering in which the
+    // seal can catch a component's first request.
+    `<script>${harnessScript({
+      stubs: input.state.routes,
+      now: input.target.now,
+      timeZone: input.target.timeZone,
+    })}</script>`,
+    '</head><body>',
+    `<div id="x-shot-frame"><div ${emitIslandAttributes(directive)}></div></div>`,
+    emitIslandProps(directive),
+    hydrateRuntime([directive]),
+    '</body></html>',
+  ].join('');
+}

package/src/island-shot-errors.ts

@@ -0,0 +1,94 @@
+// The four ways `x shot --island` refuses, beside their one thrower rather than in `errors.ts` —
+// which is at the 500-line ceiling. The codes, their titles and the single `registerErrorCodes`
+// call stay in `error-codes.ts`: one owner, one registration, one place a duplicate can surface.
+
+import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+
+// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`.
+
+/** Neither path is the framework's: both arrive from an app's own declaration. */
+const STATES_PLACEHOLDER = '<the states file the cause names>';
+
+/**
+ * A `*.island.states.ts` that exports no manifest — the author wrote `defineIslandStates(…)` and
+ * did not `export` the result, or exported it from a file nothing else names. It expands to no
+ * picture, so a run over it photographs nothing and reports success, which is the one outcome this
+ * whole command exists to make impossible.
+ */
+export class IslandStatesFileEmptyError extends UltimateError {
+  constructor(input: { readonly file: string }) {
+    super({
+      code: 'X_SHOT_ISLAND_STATES_EMPTY',
+      cause: `${renderCauseValue(input.file)} exports no defineIslandStates() result, so it declares no picture`,
+      fix: `in ${renderFixLiteral(input.file, STATES_PLACEHOLDER)} write: export const states = defineIslandStates({ island: '…', states: [...] })`,
+    });
+  }
+}
+
+/**
+ * The page could not be photographed, and the reason is named. Every clause is something a picture
+ * would have hidden rather than shown: a host element that never attached photographs the harness
+ * chrome, a zero-sized box photographs whatever is behind it, and a box with no children is a
+ * component that mounted and rendered nothing — each of which comes out as a plausible-looking
+ * image of the wrong thing.
+ */
+export class IslandUnphotographableError extends UltimateError {
+  constructor(input: {
+    readonly island: string;
+    readonly state: string;
+    readonly theme: string;
+    readonly reason: string;
+    readonly fix: string;
+  }) {
+    super({
+      code: 'X_SHOT_ISLAND_UNPHOTOGRAPHABLE',
+      cause: `${input.island} in state ${renderCauseValue(input.state)} (${input.theme}) ${input.reason}`,
+      fix: input.fix,
+      meta: { island: input.island, state: input.state, theme: input.theme },
+    });
+  }
+}
+
+/**
+ * The component asked the network for something no stub answers. Refused rather than allowed
+ * through, because the alternative is the failure this command was built to prevent: a `fetch`
+ * that quietly hangs leaves the component painting its own loading branch, and the picture then
+ * shows a fixture gap dressed up as a real component state.
+ */
+export class IslandRequestUnstubbedError extends UltimateError {
+  constructor(input: {
+    readonly island: string;
+    readonly state: string;
+    readonly requests: readonly string[];
+    readonly statesFile: string;
+  }) {
+    super({
+      code: 'X_SHOT_ISLAND_UNSTUBBED_REQUEST',
+      cause: `${input.island} in state ${renderCauseValue(input.state)} made ${input.requests.length} request(s) no stub answers: ${input.requests.join(', ')}`,
+      fix: `in ${renderFixLiteral(input.statesFile, STATES_PLACEHOLDER)} add to that state: routes: [{ match: '${input.requests[0] ?? 'GET /api/x'}', respond: { kind: 'json', body: {} } }]`,
+      meta: { island: input.island, state: input.state, requests: [...input.requests] },
+    });
+  }
+}
+
+/**
+ * The gate that does not depend on the browser's own verdict: every declared state expands to a
+ * file, and a file that is not on disk when the run ends is a picture nobody took. A capture loop
+ * that swallowed one failure and exited 0 is exactly what this refuses, and it is checked against
+ * the expansion computed before a browser existed rather than against what the loop believes it did.
+ */
+export class IslandShotsMissingError extends UltimateError {
+  constructor(input: {
+    readonly island: string;
+    readonly missing: readonly string[];
+    readonly expected: number;
+    readonly dir: string;
+  }) {
+    super({
+      code: 'X_SHOT_ISLAND_MISSING',
+      cause: `${input.missing.length} of ${input.expected} declared picture(s) are not on disk under ${renderCauseValue(input.dir)}: ${input.missing.join(', ')}`,
+      fix: `x shot --island ${input.island} --json   # the run above names why each one was refused`,
+      meta: { island: input.island, missing: [...input.missing] },
+    });
+  }
+}