@ultimat3/cli 20.1.6 → 20.2.1

package/src/mcp-ui.ts

@@ -1,6 +1,9 @@
-// The dev MCP server's two eyes: `ui.shot` (a route) and `ui.island` (a component's states), as
-// the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a browser is the CLI's
-// to launch. Both are `x shot` under another name: the same server lookup (a running `x dev` is
+// The dev MCP server's eyes and hand: `ui.shot` (a route), `ui.island` (a component's states),
+// `ui.inspect` (DOM facts for a set of selectors, in `mcp-ui-inspect.ts`), `ui.interact` (steps
+// first, then the picture, in `mcp-ui-interact.ts`) and `ui.diff` (two captures compared, in
+// `mcp-ui-diff.ts`), as the `DevCapabilities` half `packages/mcp` declares and cannot satisfy — a
+// browser is the CLI's to launch, and the files are the CLI's to read. The four that look
+// are `x shot` under another name: the same server lookup (a running `x dev` is
 // reused through its lock, otherwise a scratch one boots), the same driver, the same verdict.
 // Nothing here is a new capability; it is the existing one made reachable from inside the loop
 // an agent already works in, so "does it look right" stops needing a hand-written script.
@@ -8,7 +11,18 @@
 // why: Bun exposes no path-join primitive, and the picture's directory is a path an agent opens.
 import { join } from 'node:path';
 import { UltimateError } from '@ultimat3/core';
-import type { UiIslandInput, UiIslandResult, UiShotInput, UiShotResult } from '@ultimat3/mcp';
+import type {
+  UiDiffInput,
+  UiDiffResult,
+  UiInspectInput,
+  UiInspectResult,
+  UiInteractInput,
+  UiInteractResult,
+  UiIslandInput,
+  UiIslandResult,
+  UiShotInput,
+  UiShotResult,
+} from '@ultimat3/mcp';
 import { describeRoutes } from '@ultimat3/render';
 import type { ScrapeDriver } from '@ultimat3/scraping';
 import { DEFAULT_PAGE_TIMEOUT_MS } from '@ultimat3/scraping';
@@ -17,6 +31,9 @@ import { DEFAULT_SETTLE_MS, runShot, SHOT_DIR, shotSlug } from './cmd-shot';
 import { islandShot } from './cmd-shot-island';
 import type { Env } from './dev-services';
 import { islandVerdictJson } from './island-verdict';
+import { diffShots } from './mcp-ui-diff';
+import { inspectRoute } from './mcp-ui-inspect';
+import { interactRoute } from './mcp-ui-interact';
 import { retryMemo } from './retry-memo';
 import { shotBrowserChoice } from './shot-browser';
 import { devServerFor, type ShotServer } from './shot-server';
@@ -44,7 +61,7 @@ export function assertBudgetedRoute(route: string, declared: readonly DeclaredRo
     throw new UltimateError({
       code: 'X_UI_SHOT_ROUTE_UNKNOWN',
       cause: `no route in this app answers ${route}`,
-      fix: 'x routes --json   # then ui.shot with one of its `path` values',
+      fix: 'x routes --json   # then call the ui.* tool with one of its `path` values',
     });
   }
   if (hit.budgetJs === null) {
@@ -78,6 +95,10 @@ export interface UiHostInput {
 export interface UiCapabilities {
   shotRoute(shot: UiShotInput): Promise<UiShotResult>;
   shotIsland(island: UiIslandInput): Promise<UiIslandResult>;
+  inspectRoute(inspect: UiInspectInput): Promise<UiInspectResult>;
+  interactRoute(interact: UiInteractInput): Promise<UiInteractResult>;
+  /** Two captures under `.x/shot/` compared without a browser; never boots the scratch server. */
+  diffShots(diff: UiDiffInput): Promise<UiDiffResult>;
   /** Stops the scratch server, if one was booted. Never boots one in order to stop it. */
   close(): Promise<void>;
 }
@@ -100,6 +121,17 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
   // provider's CDP URL, or the launcher's own discovery.
   const browser = () => shotBrowserChoice({ cdpFlag: undefined, browserFlag: undefined, env });
   const routes = input.routes ?? describeRoutes;
+  // One browser per call, sized to the call: the injected driver in a test, `appBrowser` otherwise.
+  const driverFor = async (viewport: UiShotInput['viewport']): Promise<ScrapeDriver> => {
+    if (input.driver !== undefined) return input.driver(viewport);
+    const { cdpUrl, executablePath } = browser();
+    return appBrowser({
+      root,
+      viewport,
+      ...(executablePath === undefined ? {} : { executablePath }),
+      ...(cdpUrl === undefined ? {} : { cdpUrl }),
+    });
+  };
   let closed = false;
 
   return {
@@ -113,16 +145,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
 
     async shotRoute(shot) {
       assertBudgetedRoute(shot.route, routes());
-      const { cdpUrl, executablePath } = browser();
-      const driver =
-        input.driver === undefined
-          ? await appBrowser({
-              root,
-              viewport: shot.viewport,
-              ...(executablePath === undefined ? {} : { executablePath }),
-              ...(cdpUrl === undefined ? {} : { cdpUrl }),
-            })
-          : await input.driver(shot.viewport);
+      const driver = await driverFor(shot.viewport);
       // One directory per (route, viewport, scheme), so two pictures of one route at two widths
       // never overwrite each other and an agent can hold both.
       const outDir = join(
@@ -149,6 +172,21 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
       };
     },
 
+    async inspectRoute(inspect) {
+      // The same gate as `ui.shot`, for the same reason: facts about a draft are facts about the
+      // wrong thing.
+      assertBudgetedRoute(inspect.route, routes());
+      return inspectRoute({ root, boot, driver: driverFor }, inspect);
+    },
+
+    async interactRoute(interact) {
+      assertBudgetedRoute(interact.route, routes());
+      return interactRoute({ root, boot, driver: driverFor }, interact);
+    },
+    // No route gate and no boot: the captures were gated when they were taken, and a diff of two
+    // files needs neither a server nor a browser.
+    diffShots: (diff) => diffShots({ root }, diff),
+
     async shotIsland(island) {
       const { cdpUrl, executablePath } = browser();
       const artifacts = await islandShot({

package/src/output.ts

@@ -64,7 +64,7 @@ export interface CommandResult {
    * Which fd this result is written to. `stdout` for every command, absent included — and
    * `stderr` for the one case where fd 1 is not the command's to write on: `x mcp serve
    * --transport stdio`, whose stdout carries JSON-RPC frames, and where the `✓ mcp stdio serving
-   * 15 tools` line printed after the loop exits is a malformed frame to whatever is reading.
+   * 18 tools` line printed after the loop exits is a malformed frame to whatever is reading.
    *
    * Behaviour, not a fact, exactly like `hold` above — so NEITHER renderer carries it. It says
    * where a rendered line goes, and a payload that also claimed it would be a second answer to a

package/src/prerender.ts

@@ -30,6 +30,7 @@ import {
   serviceWorkerHead,
   serviceWorkerRegistration,
 } from './sw-artifacts';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -186,6 +187,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
   // The registration TAG now, the worker itself after the render loop — the two halves are wanted
   // at different moments and used to be taken at the same one. Every document below has to name
   // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
@@ -238,6 +240,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
+        themeHead: theme.head,
         ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
       }),
     );

package/src/scaffold-typecheck.ts

@@ -146,6 +146,11 @@ const overlay = (root: string, app: string): string =>
       compilerOptions: {
         noEmit: true,
         paths: {
+          // The two subpath exports a generated app reaches for, spelled the way the packages'
+          // own `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a
+          // package name. Longest prefix wins, so these are consulted first.
+          '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
+          '@ultimat3/render/server': [`${root}/packages/render/src/server`],
           '@ultimat3/*': [`${root}/packages/*/src`],
           [`@${app}/web/*`]: ['./apps/web/*'],
           [`@${app}/admin/*`]: ['./apps/admin/*'],

package/src/script-csp.ts

@@ -11,7 +11,10 @@ import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
  * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
  * reach it. Read from `@ultimat3/render`'s own enumeration rather than restated here — the body
  * the document carries and the body the policy hashes have to be one string.
+ *
+ * `extra` is for sources the caller already hashed from a body it emits — the theme boot's,
+ * which `theme-boot.ts` derives from the same string it inlines.
  */
-export function inlineScriptSources(): readonly string[] {
-  return [...new Set(HYDRATE_RUNTIME_BODIES.map(cspHashSource))].sort();
+export function inlineScriptSources(extra: readonly string[] = []): readonly string[] {
+  return [...new Set([...HYDRATE_RUNTIME_BODIES.map(cspHashSource), ...extra])].sort();
 }

package/src/serve.ts

@@ -40,6 +40,7 @@ import { startServices } from './dev-runtime';
 import type { Env } from './dev-services';
 import { resolveServices } from './dev-services';
 import { storageRoutes } from './dev-storage';
+import { errorPageStyleSources } from './error-page-csp';
 import { PortInvalidError, RoleUnknownError } from './errors';
 import { holdUntilShutdown } from './hold';
 import { buildIslands } from './island-bundle';
@@ -53,6 +54,7 @@ import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
 
 export const DEFAULT_PORT = 3000;
 
@@ -360,6 +362,7 @@ async function bootRoles(boot: {
   // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
   // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
@@ -393,6 +396,7 @@ async function bootRoles(boot: {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
@@ -419,6 +423,10 @@ async function bootRoles(boot: {
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: await errorPageStyleSources(options.root),
+    inlineScripts: [theme.cspSource],
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,

package/src/shot-theme.ts

@@ -0,0 +1,52 @@
+// The script a capture runs ahead of the document when a theme was ASKED for. Since 20.2.0 the
+// boot inlines a theme script (`@ultimat3/render`'s `themeScriptBody`) whose fallback is the app's
+// `theme.defaultMode`, and only a stored choice under `THEME_STORAGE_KEY` beats it — so emulating
+// `prefers-color-scheme` alone photographs a `defaultMode: 'dark'` app dark whatever was requested
+// (issue #489). A requested theme is therefore stored as the visitor's CHOICE, on the page's origin,
+// before the boot reads it: the picture is then what a visitor who chose that theme sees.
+
+import { THEME_STORAGE_KEY } from '@ultimat3/render';
+import type { ColorScheme } from '@ultimat3/scraping';
+import { BadFlagError } from './errors';
+
+/** What `x shot --theme` accepts: the two the boot honours from storage, and nothing else. */
+const SHOT_THEMES = ['light', 'dark'] as const;
+export type ShotTheme = (typeof SHOT_THEMES)[number];
+
+const isShotTheme = (value: string): value is ShotTheme =>
+  (SHOT_THEMES as readonly string[]).includes(value);
+
+/**
+ * `--theme light|dark` on a ROUTE shot, or nothing — the box's own preference and the app's own
+ * default, which is what `x shot` has always photographed. Refused by name for any other value:
+ * `no-preference` is the scraping vocabulary's clear, not a theme a reader can ask for.
+ */
+export function readThemeFlag(value: string | undefined): ShotTheme | undefined {
+  if (value === undefined) return undefined;
+  if (isShotTheme(value)) return value;
+  throw new BadFlagError({
+    flag: 'theme',
+    command: 'shot',
+    reason: `"${value}" is not a theme; it is light or dark`,
+    fix: 'x shot / --theme light --json',
+  });
+}
+
+/**
+ * The seeding expression, DETERMINISTIC per scheme: the offline drivers key recordings on the exact
+ * string, and a test asserts on it by value. `'no-preference'` answers `undefined` — the boot
+ * honours only `"light"` and `"dark"` from storage, so there is no choice to store, and storing
+ * anything else would be a value the tokens have no block for.
+ *
+ * `JSON.stringify` on both halves, never a value pasted between quotes: the key and the scheme land
+ * inside a JS string, where one `"` ends it. The `try` is for the origin the page starts on:
+ * `about:blank` is opaque and its `localStorage` throws, and a throw from a new-document script
+ * would surface as a page error on a capture that has not navigated yet.
+ */
+export function themeChoiceExpression(scheme: ColorScheme): string | undefined {
+  if (scheme === 'no-preference') return undefined;
+  return (
+    `try{localStorage.setItem(${JSON.stringify(THEME_STORAGE_KEY)},${JSON.stringify(scheme)})}` +
+    'catch(e){}'
+  );
+}

package/src/templates/index.ts

@@ -39,11 +39,15 @@ export { claudeFiles } from './scaffold-claude';
 export { claudeAgentFiles } from './scaffold-claude-agents';
 export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
+export { dashboardFiles } from './scaffold-dashboard';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { entryFiles } from './scaffold-entries';
-// The four guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
+export { errorPageFiles, PWA_COLORS } from './scaffold-errors';
+// The nine guards `x new` ships, distinct from `guardFiles` above, which is `x g guard <name>`.
 export { scaffoldGuardFiles } from './scaffold-guards';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
+export { shellFiles } from './scaffold-shell';
+export { siteFiles } from './scaffold-site';
 export type { SliceModule } from './slice-foundation';
 export { sliceFoundation } from './slice-foundation';

package/src/templates/scaffold-app.ts

@@ -6,10 +6,14 @@ import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
 import { authFiles } from './scaffold-auth';
+import { dashboardFiles } from './scaffold-dashboard';
 import { entryFiles } from './scaffold-entries';
+import { errorPageFiles } from './scaffold-errors';
 import { httpFiles } from './scaffold-http';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
+import { shellFiles } from './scaffold-shell';
+import { siteFiles } from './scaffold-site';
 
 // The one dependency this manifest names, and it is not decoration: every page below reads its
 // strings through `@<app>/i18n`'s `useT()`, so the surface that renders a string DEPENDS on the
@@ -42,154 +46,6 @@ const tsconfig = (): string => `{
 }
 `;
 
-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).
-${sortedImports([
-  `import { useT } from '@${app.kebab}/i18n';`,
-  `import { defineRoute } from '@ultimat3/render';`,
-])}
-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.hero}>
-      <h1>{t('site.home.title')}</h1>
-      <p>{t('site.home.description')}</p>
-      <a class={styles.cta} href="/dashboard">
-        {t('site.home.cta')}
-      </a>
-    </main>
-  );
-}
-
-export const appName = '${app.kebab}';
-`;
-
-const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
-
-.hero {
-  display: grid;
-  gap: tokens.space(4);
-  padding: tokens.space(8);
-  background: tokens.role('bg');
-  color: tokens.role('fg');
-}
-
-.cta {
-  justify-self: start;
-  padding: tokens.space(2) tokens.space(4);
-  border-radius: tokens.radius('md');
-  background: tokens.role('accent');
-  color: tokens.role('accent-fg');
-}
-`;
-
-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('');
-});
-`;
-
-const dashboardPage = (
-  app: NameSet,
-): string => `// The authed dashboard. app/ streams: a static shell is flushed instantly and the holes arrive
-// as their data resolves.
-
-// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-${sortedImports([
-  `import { useT } from '@${app.kebab}/i18n';`,
-  `import { defineRoute } from '@ultimat3/render';`,
-])}
-import styles from './page.module.scss';
-
-export const config = defineRoute({
-  // 'ssr', not 'stream', and this is not a downgrade: 'stream' needs a boundary to stream into,
-  // and the framework has no hole marker yet. Solid's <Suspense> is not it — it throws outside a
-  // Solid renderer, and the server JSX factory is inert on purpose. A scaffolded 'stream' route
-  // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
-  // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
-  render: 'ssr',
-  // Stated with no island on the page, deliberately and for free — \`apps/admin/app/admin/page.tsx\`
-  // carries the reason.
-  hydrate: 'visible',
-  offline: 'runtime',
-  // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
-  policy: { permission: 'dashboard:read' },
-  budget: { js: '60kb' },
-  meta: ({ t }) => ({
-    title: t('app.dashboard.title'),
-    description: t('app.dashboard.description'),
-  }),
-});
-
-export function DashboardPage() {
-  const t = useT();
-
-  return (
-    <section class={styles.panel}>
-      <h1>{t('app.dashboard.title')}</h1>
-    </section>
-  );
-}
-`;
-
-const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
-
-.panel {
-  padding: tokens.space(6);
-  background: tokens.role('surface-raised');
-  color: tokens.role('fg');
-}
-`;
-
-const dashboardTest =
-  (): string => `// The dashboard renders per request, is gated by a policy, and has an offline strategy. Losing
-// the policy is the interesting regression: the page still renders, to anyone.
-import { expect, unitTest } from '@ultimat3/testing';
-import { config } from './page';
-
-unitTest('the dashboard renders on the server, is gated, and has an offline strategy', () => {
-  expect(config.render).toBe('ssr');
-  expect(config.policy?.permission).toBe('dashboard:read');
-  expect(config.offline).toBe('runtime');
-});
-`;
-
 const offlineTest =
   (): string => `// The offline fallback has to render with nothing: no network, no session, no database, and no
 // JavaScript. Every one of those is a config field here, and every one of them rots the moment
@@ -419,7 +275,8 @@ restructure.
 | Start | \`x new ${app.kebab}-${surface}\` inside this directory, or wire it by hand |
 `;
 
-/** `example` reaches only `apps/web/api/index.ts`: the slice it registers is written elsewhere. */
+/** `example` decides the API registration, the shell's nav and which dashboard is written; the
+ * slice itself is written elsewhere. */
 export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile[] {
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
@@ -427,12 +284,14 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
     ...entryFiles(),
     { path: 'apps/web/site/icon.png', contents: icon() },
-    { 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() },
-    { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage(app) },
-    { path: 'apps/web/app/dashboard/page.module.scss', contents: dashboardStyle() },
-    { path: 'apps/web/app/dashboard/page.test.ts', contents: dashboardTest() },
+    // The landing page: hero, two calls to action, three feature cards — `scaffold-site.ts`.
+    ...siteFiles(app),
+    // The signed-in product: its frame and the one island it ships (`scaffold-shell.ts`), then the
+    // dashboard in the shape the invocation earns (`scaffold-dashboard.ts`).
+    ...shellFiles(app, example),
+    ...dashboardFiles(app, example),
+    // Served verbatim for those statuses and carried into the static export — `scaffold-errors.ts`.
+    ...errorPageFiles(app),
     // The third piece of the authz story the scaffold already tells twice: the routes declare a
     // policy and `shared/roles.ts` declares the grants, and until this file existed nothing
     // answered "who is this?" — so every one of those routes refused every request.