@cosmicdrift/kumiko-testing 0.308.0 → 0.310.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-testing",
-  "version": "0.308.0",
+  "version": "0.310.0",
   "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -63,9 +63,9 @@
     "kumiko-testing": "./bin/kumiko-testing.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.308.0",
-    "@cosmicdrift/kumiko-dev-server": "0.308.0",
-    "@cosmicdrift/kumiko-framework": "0.308.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.310.0",
+    "@cosmicdrift/kumiko-dev-server": "0.310.0",
+    "@cosmicdrift/kumiko-framework": "0.310.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/src/bunfig.ts

@@ -1,9 +1,12 @@
+import { E2E_TIMEOUT_MS } from "./e2e/timeouts";
+
 export const TEST_TIMEOUT_MS = {
   unit: 5000,
   integration: 15000,
   dom: 15000,
-  // Real providers add network round-trips and provider-side latency the local stack never has.
-  real: 120000,
+  // Same class budget as Playwright real runs (E2E_TIMEOUT_MS.real) — one
+  // constant covers both the bun test:real path and defineAppE2eConfig.
+  real: E2E_TIMEOUT_MS.real,
 } as const;
 
 export const BUNFIG_FILES = {

package/src/changes.json

@@ -1,4 +1,66 @@
 [
+  {
+    "version": "0.310.0",
+    "type": "improvement",
+    "title": "captureScreenshot accepts fit viewport, fullPage or content",
+    "detail": "`fit: \"viewport\"` (default) keeps the previous behaviour. `fit: \"fullPage\"`\ncaptures the whole document, so offlot's inline mid-flow shots\n(channel-request, channel-prompts, vehicle-channel-texts) can move to\ncaptureScreenshot. `fit: \"content\"` grows the viewport until neither the\ndocument nor a visible overflow-auto/scroll container (WorkspaceShell's\ninner scroll area) overflows, captures, and restores the viewport; it\nthrows instead of writing a cropped image when growth does not converge\nwithin 4 rounds. A 1px container overflow counts as sub-pixel rounding\n(overflow-x-auto table wrappers), not content. This replaces solon's own `e2e/_helpers/shot.ts`; its\nimages pick up the `reducedMotion: \"reduce\"` default on the switch, so a\none-time pixel drift in the handbook PNGs is expected."
+  },
+  {
+    "version": "0.310.0",
+    "type": "breaking",
+    "title": "defineAppE2eConfig's chromium project runs at 1920×1080 instead of Desktop Chrome's 1280×720",
+    "detail": "The template took Playwright's \"Desktop Chrome\" device unchanged, so every\ne2e run and every inline captureScreenshot rendered at 1280×720 while\nrunMatrix's desktop screenshots used 1920×1080. Both now share\nDESKTOP_VIEWPORT (1920×1080). A root `use.viewport` override in an app's\nplaywright config never reached the chromium project anyway (project `use`\nwins), so solon's 1920 override was silently ineffective.",
+    "migration": "Drop app-level desktop viewport overrides. Specs asserting a layout that\nonly exists below 1920px (collapsed sidebar, stacked panes) set their own\nviewport via test.use({ viewport }). Committed inline screenshots taken\nin the chromium project regenerate at 1920 width."
+  },
+  {
+    "version": "0.310.0",
+    "type": "fix",
+    "title": "defineAppE2eConfig's webServer env no longer defaults MEILI_URL and MEILI_MASTER_KEY",
+    "detail": "Since the infra env defaults landed, every e2e webServer got\nMEILI_URL=http://localhost:17700. Apps that choose Meilisearch over\ntheir in-memory search adapter when MEILI_URL is set then pointed at an\nunreachable host in CI without a Meili service. Meili is opt-in again:\nthe two vars reach the webServer only when the environment sets them or\nthe app passes them via `env`. All other infra defaults are unchanged.\nMigration: an app whose e2e needs Meilisearch sets MEILI_URL (and\nMEILI_MASTER_KEY) in `defineAppE2eConfig({ env })` or in the CI env; an\napp that worked around it with `MEILI_URL: \"\"` can drop that override."
+  },
+  {
+    "version": "0.310.0",
+    "type": "fix",
+    "title": "Screenshot scenario waitFor uses the template timeout budget instead of a fixed 10s",
+    "detail": "runScreenshots/runMatrix wait for a scenario's `waitFor` selector with\n`E2E_TIMEOUT_MS.navigation`, or `E2E_TIMEOUT_MS.real` under\nKUMIKO_REAL_PROVIDERS=1, so real-provider screenshot scenarios no longer\ntime out on LLM/OCR latency and apps don't need their own wait timeouts."
+  },
+  {
+    "version": "0.309.0",
+    "type": "breaking",
+    "title": "reducedMotion defaults to \"reduce\" in runScreenshots/runMatrix/captureScreenshot; captureScreenshot(page, name) added",
+    "detail": "rAF-driven chart/tween animations were invisible to the settle-detection\nwait, so screenshots sometimes captured a mid-animation frame. Both matrix\nhelpers now call page.emulateMedia({ reducedMotion: \"reduce\" }) at test\nstart, before the first navigation. The new captureScreenshot(page, name,\nopts?) applies the same media emulation at capture time, so it only affects\nanimations started after that point; set reducedMotion via test.use() for\nmid-flow shots of charts that animate on mount. captureScreenshot reuses the\nmatrix runner's settle logic, writes $SCREENSHOT_DIR/<name>.png, and is a\nno-op when SCREENSHOT_DIR is unset, for solon's mid-flow shot(page, id) and\nofflot's inline page.screenshot writes into docs/screenshots/e2e/.",
+    "migration": "Pass `reducedMotion: \"no-preference\"` in runScreenshots/runMatrix's\noptions, or as captureScreenshot's third argument, for a scenario that\nmust keep real motion."
+  },
+  {
+    "version": "0.309.0",
+    "type": "fix",
+    "title": "test:real now filters to *.real.test.ts, and real-provider runs share one 240s timeout budget",
+    "detail": "bunfig.real.toml's pathIgnorePatterns is blacklist-only (no gitignore-style\nnegation), so an unfiltered `bun test --config=bunfig.real.toml` still ran\nthe whole unit suite under the real-provider env. The generated `test:real`\nscript now passes a positional `real.test.ts` filter. TEST_TIMEOUT_MS.real\n(bun --timeout) and E2E_TIMEOUT_MS.real (the Playwright real-run path via\ndefineAppE2eConfig) now both come from the same 240_000 template constant\ninstead of a separately hardcoded 120s, covering solon's real-provider\ndocument-onboarding flow. `isRealProviderRun(env?)` is exported next to\n`REAL_PROVIDERS_ENV`/`requireRealProviders` so apps stop duplicating the\n`KUMIKO_REAL_PROVIDERS === \"1\"` literal."
+  },
+  {
+    "version": "0.309.0",
+    "type": "improvement",
+    "title": "runMatrix locales are app-injectable via localeTags, and gains a namedDevice mode for phone-style device projects",
+    "detail": "runMatrix's locale list was fixed to en/de with hardcoded BCP47 tags.\nopts.localeTags lets an app supply its own locale -> tag map (e.g. \"es\" ->\n\"es-ES\"); locales with neither an app override nor the en/de default fall\nback to Intl.Locale(locale).maximize().region derivation, throwing only\nwhen no tag is derivable. A Playwright project whose name isn't a\nViewportId but is a mobile/device project (offlot's \"phone\" project) now\ngets its own namedDevice output subtree\n(<dir>/<outputPrefix>/<name>/<locale>/<theme>/<viewport>.png) fixed to the mobile\nviewport, instead of incorrectly falling through to the desktop pass."
+  },
+  {
+    "version": "0.309.0",
+    "type": "improvement",
+    "title": "Scenario flow receives runMatrix's locale; Scenario.captureStyle for screenshot-only CSS",
+    "detail": "runMatrix passes the current locale to `flow(page, { seedTenant, locale })`,\nso apps whose routes carry the locale in the path (offlot's public vehicle\npage) can build the URL per locale. `captureStyle` is handed to Playwright's\nscreenshot `style` option in runScreenshots and runMatrix: the CSS applies\nto the capture only and does not leak into the next theme × viewport shot."
+  },
+  {
+    "version": "0.309.0",
+    "type": "improvement",
+    "title": "seedTenant accepts an admin identity (displayName/email) for demo and screenshot tenants",
+    "detail": "SeedTenantOptions gained an optional `admin: { displayName?, email? }`.\nemail supports a `{tenantId}` placeholder, substituted per call, so a\nfixed template (e.g. `admin+{tenantId}@example.test`) stays unique across\nthe global `read_users_email_unique` index instead of colliding across\nper-scenario tenants. Threaded through both the plain seed-tenant.ts path\nand the HTTP seed route/fixture."
+  },
+  {
+    "version": "0.309.0",
+    "type": "fix",
+    "title": "defineAppE2eConfig's webServer env now defaults the infra service vars, environment wins",
+    "detail": "webServer.env is now built as `{ ...infraEnvDefaults(), ...PLAYWRIGHT_DEMO_ENV, ...env }`,\nwhere infraEnvDefaults() reads the same SERVICE_ENV_DEFAULTS the app's own\npreload uses (DATABASE_URL, REDIS_URL, MEILI_URL, MINIO_*, ...), falling\nback to each default only when process.env doesn't already carry a value.\nA CI/shell-set env var still wins over the template default. No\n`--env-file` is loaded here."
+  },
   {
     "version": "0.308.0",
     "type": "fix",

package/src/e2e/constants.ts

@@ -15,9 +15,18 @@ export const SEED_TOKEN_ENV = "KUMIKO_TEST_SEED_TOKEN";
 export const SEED_TOKEN_HEADER = "x-kumiko-test-seed";
 export const E2E_WORKERS_ENV = "KUMIKO_E2E_WORKERS";
 
-// Same literal as the framework's requireRealProviders(), which does not export it.
+// Same literal as the framework's requireRealProviders()/isRealProviderRun(),
+// duplicated because the Playwright config runs under Node and importing the
+// framework's "./testing" barrel there would pull in its full Bun-toolchain
+// dependency graph for a single string constant.
 export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
 
+export function isRealProviderRun(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  return env[REAL_PROVIDERS_ENV] === "1";
+}
+
 // Same literal as kumiko-dev-server's createKumikoServer (STYLESHEET_WATCH_ENV),
 // duplicated because the Playwright config runs under Node and can't import
 // that Bun-toolchain-adjacent module.
@@ -34,3 +43,8 @@ export const SEED_ROUTES = {
   seedUser: `${SEED_ROUTE_PREFIX}/seed-user`,
   inbox: `${SEED_ROUTE_PREFIX}/inbox`,
 } as const;
+
+// Desktop default for e2e runs and screenshots alike. Playwright's "Desktop
+// Chrome" device ships 1280×720: handbook and doc shots at 1280 visibly soften
+// on a HiDPI display, and a list next to a reading pane looks cramped.
+export const DESKTOP_VIEWPORT = { width: 1920, height: 1080 } as const;

package/src/e2e/define-app-e2e-config.ts

@@ -8,11 +8,13 @@ import {
   type PlaywrightWorkerOptions,
   type Project,
 } from "@playwright/test";
+import { SERVICE_ENV_DEFAULTS } from "../preload/service-env-defaults-values";
 import {
+  DESKTOP_VIEWPORT,
   E2E_WORKERS_ENV,
+  isRealProviderRun,
   PLAYWRIGHT_DEMO_ENV,
   PROD_BUNDLES_ENV,
-  REAL_PROVIDERS_ENV,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
   STYLESHEET_WATCH_ENV,
@@ -20,6 +22,29 @@ import {
 import { screenshotSpecsIgnore } from "./screenshot-dir";
 import { E2E_TIMEOUT_MS } from "./timeouts";
 
+// Apps pick Meilisearch over their in-memory search adapter just because
+// MEILI_URL is set, so a default here would point every consumer without a
+// Meili service at an unreachable host. Meili stays opt-in: environment or `env`.
+const OPT_IN_SERVICE_ENV_KEYS: readonly string[] = [
+  "MEILI_URL",
+  "MEILI_MASTER_KEY",
+] satisfies readonly (keyof typeof SERVICE_ENV_DEFAULTS)[];
+
+// A `??` merge per key, not a raw process.env spread — CI or the shell
+// environment wins over the local-dev default without leaking unrelated
+// host env vars into the webServer process.
+function infraEnvDefaults(): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(SERVICE_ENV_DEFAULTS).flatMap(([key, value]) => {
+      const fromEnvironment = process.env[key];
+      if (OPT_IN_SERVICE_ENV_KEYS.includes(key)) {
+        return fromEnvironment === undefined ? [] : [[key, fromEnvironment]];
+      }
+      return [[key, fromEnvironment ?? value]];
+    }),
+  );
+}
+
 const TEMPLATE_OWNED_PROJECT_KEYS = [
   "fullyParallel",
   "retries",
@@ -121,7 +146,7 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
   assertNoReservedEnv(env);
   for (const project of projects) assertTemplateOwnedKeysUnset(project);
   const baseURL = `http://localhost:${port}`;
-  const realRun = process.env[REAL_PROVIDERS_ENV] === "1";
+  const realRun = isRealProviderRun();
 
   return defineConfig({
     testDir,
@@ -134,7 +159,7 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
     retries: 0,
     workers: resolveE2eWorkers(),
     reporter: [["list"]],
-    timeout: E2E_TIMEOUT_MS.test,
+    timeout: realRun ? E2E_TIMEOUT_MS.real : E2E_TIMEOUT_MS.test,
     expect: { timeout: E2E_TIMEOUT_MS.expect },
     use: {
       baseURL,
@@ -144,11 +169,15 @@ export function defineAppE2eConfig(input: AppE2eConfigInput): PlaywrightTestConf
       actionTimeout: E2E_TIMEOUT_MS.action,
       navigationTimeout: E2E_TIMEOUT_MS.navigation,
     },
-    projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }, ...projects],
+    projects: [
+      { name: "chromium", use: { ...devices["Desktop Chrome"], viewport: DESKTOP_VIEWPORT } },
+      ...projects,
+    ],
     webServer: {
       command: `bun run ${serverEntry}`,
       url: baseURL,
       env: {
+        ...infraEnvDefaults(),
         ...PLAYWRIGHT_DEMO_ENV,
         ...env,
         PORT: String(port),

package/src/e2e/index.ts

@@ -16,8 +16,10 @@ export {
   CSRF_COOKIE_NAME,
   CSRF_HEADER_NAME,
   E2E_WORKERS_ENV,
+  isRealProviderRun,
   KUMIKO_SECRETS_MASTER_KEY_V1,
   PLAYWRIGHT_DEMO_ENV,
+  REAL_PROVIDERS_ENV,
   SEED_ENABLE_ENV,
   SEED_TOKEN_ENV,
 } from "./constants";
@@ -37,6 +39,9 @@ export {
 } from "./screenshot-dir";
 export {
   applyDefaultTheme,
+  type CaptureFit,
+  type CaptureScreenshotOptions,
+  captureScreenshot,
   DEFAULT_THEMES,
   type DefaultThemeId,
   type FlatOptions,
@@ -45,6 +50,7 @@ export {
   runMatrix,
   runScreenshots,
   type Scenario,
+  type ScenarioFixtures,
   type ThemeScreenshotDigest,
   validateScenarios,
 } from "./screenshots";

package/src/e2e/screenshots.ts

@@ -1,9 +1,14 @@
 import { createHash } from "node:crypto";
 import { mkdirSync, statSync } from "node:fs";
+import { dirname } from "node:path";
 import { expect, type Page, type Request } from "@playwright/test";
+import { DESKTOP_VIEWPORT, isRealProviderRun } from "./constants";
 import { pinEnglishLocale } from "./pin-english-locale";
-import { requireScreenshotDir } from "./screenshot-dir";
+import { requireScreenshotDir, SCREENSHOT_DIR_ENV } from "./screenshot-dir";
 import { type SeedTenantFixture, test } from "./seeded-tenant-fixture";
+import { E2E_TIMEOUT_MS } from "./timeouts";
+
+export const DEFAULT_REDUCED_MOTION = "reduce" as const;
 
 // runScreenshots: one image per scenario → $SCREENSHOT_DIR/<name>.png.
 // runMatrix: every scenario × locale × theme × viewport in ONE run →
@@ -27,13 +32,24 @@ export async function applyDefaultTheme(page: Page, theme: DefaultThemeId): Prom
   }, theme);
 }
 
+export interface ScenarioFixtures {
+  readonly seedTenant: SeedTenantFixture;
+  // runMatrix's current locale, for apps whose routes carry the locale in the
+  // path (kumiko:locale alone can't change the URL). Undefined in runScreenshots.
+  readonly locale?: string;
+}
+
 export interface Scenario {
   readonly name: string;
   readonly description?: string;
   readonly url?: string;
-  readonly flow?: (page: Page, fixtures: { seedTenant: SeedTenantFixture }) => Promise<void>;
+  readonly flow?: (page: Page, fixtures: ScenarioFixtures) => Promise<void>;
   readonly waitFor?: string;
   readonly fullPage?: boolean;
+  // Playwright's screenshot-only `style`: applied for the capture and removed
+  // afterwards, unlike an addStyleTag in beforeCapture that would persist into
+  // the next theme × viewport capture.
+  readonly captureStyle?: string;
   readonly viewport?: { readonly width: number; readonly height: number };
   // Runs after the viewport is set and the page has settled, right before the
   // screenshot. runMatrix calls this once per theme × viewport combination for
@@ -100,20 +116,27 @@ async function openScenario(
   page: Page,
   s: Scenario,
   inFlightDataRequests: () => number,
-  fixtures: { seedTenant: SeedTenantFixture },
+  fixtures: ScenarioFixtures,
 ): Promise<void> {
   if (s.flow) await s.flow(page, fixtures);
   else if (s.url) await page.goto(s.url);
   else throw new Error(`Scenario "${s.name}" needs either url or flow`);
 
   if (s.waitFor) {
-    await expect(page.locator(s.waitFor).first()).toBeVisible({ timeout: 10_000 });
+    // Real-provider scenarios wait on LLM/OCR latency before the page is ready.
+    const timeout = isRealProviderRun() ? E2E_TIMEOUT_MS.real : E2E_TIMEOUT_MS.navigation;
+    await expect(page.locator(s.waitFor).first()).toBeVisible({ timeout });
   }
   await waitForSettledPage(page, inFlightDataRequests);
 }
 
+export type ReducedMotionOption = "reduce" | "no-preference";
+
 export interface FlatOptions {
   readonly pinLocale?: boolean;
+  // rAF-driven chart tweens etc. are invisible to waitForSettledPage's DOM/scroll
+  // fingerprint, so "reduce" is the default — pass "no-preference" to capture motion.
+  readonly reducedMotion?: ReducedMotionOption;
 }
 
 // Fail at registration time, not mid-run: a url-only scenario with no
@@ -151,13 +174,20 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
       test(
         s.description ? `${s.name} — ${s.description}` : s.name,
         async ({ page, seedTenant }) => {
+          // reducedMotion isn't a PlaywrightTestOptions fixture (test.use can't
+          // set it), so it's applied per-page like the rest of emulateMedia.
+          await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
           if (opts.pinLocale) await pinEnglishLocale(page);
           const inFlightDataRequests = countInFlightDataRequests(page);
           if (s.viewport) await page.setViewportSize(s.viewport);
           await openScenario(page, s, inFlightDataRequests, { seedTenant });
           if (s.beforeCapture) await s.beforeCapture(page);
           const path = `${outDir}/${s.name}.png`;
-          await page.screenshot({ path, fullPage: s.fullPage ?? false });
+          await page.screenshot({
+            path,
+            fullPage: s.fullPage ?? false,
+            ...(s.captureStyle !== undefined && { style: s.captureStyle }),
+          });
           expect.soft(statSync(path).size).toBeGreaterThan(MIN_BYTES);
         },
       );
@@ -168,11 +198,7 @@ export function runScreenshots(scenarios: readonly Scenario[], opts: FlatOptions
 const VIEWPORT_IDS = ["desktop", "tablet", "mobile"] as const;
 export type ViewportId = (typeof VIEWPORT_IDS)[number];
 const VIEWPORTS: Record<ViewportId, { readonly width: number; readonly height: number }> = {
-  // 1920×1080 instead of the earlier 1280×900: these shots land in the
-  // handbook and doc pages, where a 1280 image visibly softens on a HiDPI
-  // display. Wider also shows what a two-column layout actually does — at
-  // 1280 any list next to a reading pane looks cramped.
-  desktop: { width: 1920, height: 1080 },
+  desktop: DESKTOP_VIEWPORT,
   // Landscape: portrait tablet shots collapsed two-column layouts into the mobile stack.
   tablet: { width: 1112, height: 834 },
   mobile: { width: 390, height: 844 },
@@ -204,13 +230,41 @@ export interface MatrixOptions<T extends string> {
   readonly themes: readonly T[];
   readonly applyTheme: (page: Page, theme: T) => Promise<void>;
   readonly locales?: readonly string[];
+  readonly localeTags?: Readonly<Record<string, string>>;
+  readonly reducedMotion?: ReducedMotionOption;
 }
 
 // App locale codes ("en"/"de") -> BCP47 tags for Playwright's browser-context
 // `locale` option, pinning JS-side Intl/navigator.language regardless of the
 // host's own locale — without it, a screenshot regen on a non-en-US host bakes
 // in the host's Intl-driven formatting regardless of SCREENSHOT_LOCALES.
-const LOCALE_TAGS: Readonly<Record<string, string>> = { en: "en-US", de: "de-DE" };
+const DEFAULT_LOCALE_TAGS: Readonly<Record<string, string>> = { en: "en-US", de: "de-DE" };
+
+// Intl.Locale.maximize() derives a region for a bare language code (es -> es-ES)
+// the same way DEFAULT_LOCALE_TAGS was hand-picked for en/de — apps with a
+// locale that needs a different region (e.g. a Swiss "de" build) pass their
+// own `localeTags` instead of relying on the derived default.
+function deriveLocaleTag(locale: string): string | undefined {
+  try {
+    const region = new Intl.Locale(locale).maximize().region;
+    return region === undefined ? undefined : `${locale}-${region}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveLocaleTag(
+  locale: string,
+  localeTags: Readonly<Record<string, string>> | undefined,
+): string {
+  const tag = localeTags?.[locale] ?? DEFAULT_LOCALE_TAGS[locale] ?? deriveLocaleTag(locale);
+  if (tag === undefined) {
+    throw new Error(
+      `runMatrix(): no BCP47 tag for locale "${locale}" — pass it in opts.localeTags`,
+    );
+  }
+  return tag;
+}
 
 export interface ThemeScreenshotDigest<T extends string> {
   readonly viewport: string;
@@ -252,6 +306,15 @@ export interface MatrixProjectInfo {
 
 export type MatrixViewportPlan =
   | { readonly mode: "device"; readonly viewports: readonly [ViewportId] }
+  // A device project whose name is NOT a ViewportId (e.g. offlot's "phone",
+  // devices["iPhone 13"]) writes under its own <baseDir>/<projectName>/ subtree
+  // instead of the shared matrix directory, so it never collides with the
+  // desktop pass's own "mobile" viewport file for the same scenario.
+  | {
+      readonly mode: "namedDevice";
+      readonly viewports: readonly [ViewportId];
+      readonly outputPrefix: string;
+    }
   | { readonly mode: "desktop"; readonly viewports: readonly ViewportId[] }
   | { readonly mode: "skip"; readonly reason: string };
 
@@ -279,6 +342,9 @@ export function resolveMatrixViewports(
     }
     return { mode: "device", viewports: [projectName] };
   }
+  if (isMobileProject) {
+    return { mode: "namedDevice", viewports: ["mobile"], outputPrefix: projectName };
+  }
   const deviceProjectIds = new Set(
     projects.filter((p) => p.isMobile && isViewportId(p.name)).map((p) => p.name),
   );
@@ -305,17 +371,15 @@ export function runMatrix<T extends string>(
       // Browser-context locale for JS-side Intl/navigator.language — the
       // kumiko:locale seed below only drives the app's own i18n strings.
       // ponytail: see the runScreenshots() locale comment above / #1851
-      const tag = LOCALE_TAGS[locale];
-      if (tag === undefined) {
-        throw new Error(
-          `runMatrix(): no BCP47 tag mapped for locale "${locale}" — extend LOCALE_TAGS`,
-        );
-      }
+      const tag = resolveLocaleTag(locale, opts.localeTags);
       test.use({ locale: tag });
 
       for (const s of scenarios) {
         if (only !== undefined && only !== s.name) continue;
         test(s.name, async ({ page, seedTenant }) => {
+          // reducedMotion isn't a PlaywrightTestOptions fixture (test.use can't set
+          // it), so it's applied per-page like the rest of emulateMedia.
+          await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
           const info = test.info();
           const plan = resolveMatrixViewports(
             info.project.name,
@@ -336,9 +400,11 @@ export function runMatrix<T extends string>(
             localStorage.removeItem("kumiko:theme");
           }, locale);
           const inFlightDataRequests = countInFlightDataRequests(page);
-          await openScenario(page, s, inFlightDataRequests, { seedTenant });
+          await openScenario(page, s, inFlightDataRequests, { seedTenant, locale });
 
           const digests: ThemeScreenshotDigest<T>[] = [];
+          const projectBaseDir =
+            plan.mode === "namedDevice" ? `${baseDir}/${plan.outputPrefix}` : baseDir;
 
           for (const theme of themes) {
             await opts.applyTheme(page, theme);
@@ -346,7 +412,7 @@ export function runMatrix<T extends string>(
               if (plan.mode === "desktop") await page.setViewportSize(VIEWPORTS[vp]);
               await waitForSettledPage(page, inFlightDataRequests);
               if (s.beforeCapture) await s.beforeCapture(page);
-              const dir = `${baseDir}/${s.name}/${locale}/${theme}`;
+              const dir = `${projectBaseDir}/${s.name}/${locale}/${theme}`;
               mkdirSync(dir, { recursive: true });
               const path = `${dir}/${vp}.png`;
               // animations: "disabled" jumps to end-state at the engine level — immune to CSS specificity, unlike an addStyleTag injection.
@@ -356,6 +422,7 @@ export function runMatrix<T extends string>(
                 path,
                 fullPage: s.fullPage ?? false,
                 animations: "disabled",
+                ...(s.captureStyle !== undefined && { style: s.captureStyle }),
               });
               expect.soft(buffer.length).toBeGreaterThan(MIN_BYTES);
               digests.push({
@@ -379,3 +446,108 @@ export function runMatrix<T extends string>(
     });
   }
 }
+
+// Per-page in-flight counter for captureScreenshot() — a call mid-flow attaches
+// its own page.on("request") listener the first time it sees a given page, so a
+// second captureScreenshot() on that page reuses the same tracker instead of
+// missing requests that were already in flight when the listener attached.
+const inFlightTrackersByPage = new WeakMap<Page, () => number>();
+
+function inFlightTrackerFor(page: Page): () => number {
+  const existing = inFlightTrackersByPage.get(page);
+  if (existing !== undefined) return existing;
+  const tracker = countInFlightDataRequests(page);
+  inFlightTrackersByPage.set(page, tracker);
+  return tracker;
+}
+
+// "viewport": what the window shows. "fullPage": Playwright's document-height
+// capture, which renders a sticky sidebar floating mid-page. "content": grows the
+// viewport until nothing overflows, including WorkspaceShell's internally
+// scrolling `overflow-auto` containers that document.scrollHeight never sees.
+export type CaptureFit = "viewport" | "fullPage" | "content";
+
+export interface CaptureScreenshotOptions {
+  readonly reducedMotion?: ReducedMotionOption;
+  readonly fit?: CaptureFit;
+}
+
+const CONTENT_FIT_MAX_ROUNDS = 4;
+
+// Runs in the browser: the largest vertical overflow of the document or of any
+// visible scrolling container. Serialized into the page, so it may not reference
+// module scope. A 1px container deficit is sub-pixel rounding, not content: an
+// `overflow-x-auto` table wrapper computes overflow-y to `auto` as well and
+// reported scrollHeight one pixel above clientHeight in solon at 1280px, so
+// growth never converged.
+function scrollDeficit(): number {
+  const containerDeficits = [...document.querySelectorAll("*")]
+    .filter((el) => {
+      const style = getComputedStyle(el);
+      return (
+        (style.overflowY === "auto" || style.overflowY === "scroll") &&
+        el.scrollHeight - el.clientHeight > 1 &&
+        el.getClientRects().length > 0 &&
+        style.visibility !== "hidden"
+      );
+    })
+    .map((el) => el.scrollHeight - el.clientHeight);
+  return Math.max(
+    0,
+    document.documentElement.scrollHeight - window.innerHeight,
+    ...containerDeficits,
+  );
+}
+
+// Growing the viewport re-flows flex-1 regions under an h-svh shell, which can
+// reveal more content, hence rounds. A deficit left after the last round throws
+// instead of writing a silently cropped screenshot.
+async function growViewportToContent(page: Page, name: string, width: number): Promise<void> {
+  for (let round = 0; round < CONTENT_FIT_MAX_ROUNDS; round++) {
+    const deficit = await page.evaluate(scrollDeficit);
+    if (deficit === 0) break;
+    const height = page.viewportSize()?.height ?? 0;
+    await page.setViewportSize({ width, height: height + deficit });
+  }
+  const remaining = await page.evaluate(scrollDeficit);
+  if (remaining > 0) {
+    throw new Error(
+      `captureScreenshot(${name}): viewport growth did not converge after ${CONTENT_FIT_MAX_ROUNDS} rounds, ${remaining}px still overflow`,
+    );
+  }
+}
+
+// Inline mid-flow screenshot for a single point in an existing e2e/real-provider
+// spec (solon's `shot(page, id)`, offlot's inline docs/screenshots/e2e/* writes) —
+// reuses the runner's settle logic and reduced-motion default, and is a no-op
+// when SCREENSHOT_DIR is unset so a plain e2e run never writes into the repo.
+export async function captureScreenshot(
+  page: Page,
+  name: string,
+  opts: CaptureScreenshotOptions = {},
+): Promise<void> {
+  const dir = process.env[SCREENSHOT_DIR_ENV];
+  // skip: a plain e2e run without SCREENSHOT_DIR must not write screenshots.
+  if (dir === undefined || dir === "") return;
+  const fit = opts.fit ?? "viewport";
+  await page.emulateMedia({ reducedMotion: opts.reducedMotion ?? DEFAULT_REDUCED_MOTION });
+  await waitForSettledPage(page, inFlightTrackerFor(page));
+  const path = `${dir}/${name}.png`;
+  mkdirSync(dirname(path), { recursive: true });
+  if (fit === "content") await captureGrownToContent(page, name, path);
+  else await page.screenshot({ path, animations: "disabled", fullPage: fit === "fullPage" });
+}
+
+async function captureGrownToContent(page: Page, name: string, path: string): Promise<void> {
+  const viewport = page.viewportSize();
+  if (viewport === null) {
+    throw new Error(`captureScreenshot(${name}): fit "content" needs a page with a viewport`);
+  }
+  try {
+    await growViewportToContent(page, name, viewport.width);
+    await page.screenshot({ path, animations: "disabled" });
+  } finally {
+    // Later assertions in the same test must run against the original window.
+    await page.setViewportSize(viewport);
+  }
+}

package/src/e2e/seed-contract.ts

@@ -5,10 +5,19 @@ export const SEEDABLE_ROLES = [ROLES.TenantAdmin, ROLES.Member] as const;
 export const MAX_SEED_MEMBERS = 10;
 export const MAX_TENANT_NAME_LENGTH = 100;
 const MAX_EMAIL_LENGTH = 320;
+const MAX_DISPLAY_NAME_LENGTH = 100;
+
+export const seedAdminIdentitySchema = z.strictObject({
+  displayName: z.string().min(1).max(MAX_DISPLAY_NAME_LENGTH).optional(),
+  // May contain the literal "{tenantId}" placeholder — substituted server-side
+  // in persistTenantRows, since user:create's email uniqueness is global.
+  email: z.string().min(1).max(MAX_EMAIL_LENGTH).optional(),
+});
 
 export const seedTenantRequestSchema = z.strictObject({
   name: z.string().min(1).max(MAX_TENANT_NAME_LENGTH).optional(),
   members: z.number().int().min(0).max(MAX_SEED_MEMBERS).optional(),
+  admin: seedAdminIdentitySchema.optional(),
 });
 
 export const seededCredentialsSchema = z.object({

package/src/e2e/seed-route.ts

@@ -134,7 +134,11 @@ export function createE2eSeedRoutes(
         unwrapSavedRow(handlerQn, await deps.dispatchSystemWrite({ handlerQn, payload, tenantId }));
       try {
         return c.json(
-          await persistTenantRows(write, { name: verified.name, users: verified.members }),
+          await persistTenantRows(write, {
+            name: verified.name,
+            users: verified.members,
+            admin: verified.admin,
+          }),
         );
       } catch (error) {
         return c.json({ error: error instanceof Error ? error.message : "seed failed" }, 500);

package/src/e2e/seeded-tenant-fixture.ts

@@ -104,7 +104,7 @@ export async function provideSeedTenant(
     const seeded = await postSeedRoute(
       request,
       SEED_ROUTES.seedTenant,
-      { name: opts.name, members: opts.users },
+      { name: opts.name, members: opts.users, admin: opts.admin },
       seedTenantResponseSchema,
     );
     const tenantId = seeded.id;

package/src/e2e/timeouts.ts

@@ -1,5 +1,7 @@
 // Class budget for every app: solon's 30s/5s flows run 4-parallel today; webServer is the
 // slowest sample boot (Bun.build + Tailwind), poll is phronexsis's 15s projection wait.
+// `real` covers solon's document-onboarding real-provider flow (240s), the slowest
+// consumer today — apps no longer set test.setTimeout/describe.configure for real runs.
 export const E2E_TIMEOUT_MS = {
   test: 30_000,
   expect: 5_000,
@@ -7,4 +9,5 @@ export const E2E_TIMEOUT_MS = {
   navigation: 10_000,
   poll: 15_000,
   webServer: 90_000,
+  real: 240_000,
 } as const;

package/src/preload/service-env-defaults-values.ts

@@ -0,0 +1,14 @@
+export const SERVICE_ENV_DEFAULTS = {
+  DATABASE_URL: "postgresql://kumiko:kumiko@localhost:15432/kumiko_dev",
+  TEST_DATABASE_URL: "postgresql://kumiko:kumiko@localhost:15432/kumiko_test",
+  REDIS_URL: "redis://localhost:16379",
+  MEILI_URL: "http://localhost:17700",
+  MEILI_MASTER_KEY: "kumiko-dev-key",
+  JWT_SECRET: "test-jwt-secret-at-least-32-characters-long",
+  MINIO_ENDPOINT: "http://localhost:19000",
+  MINIO_ACCESS_KEY: "kumiko",
+  MINIO_SECRET_KEY: "kumiko-dev-secret",
+  MINIO_BUCKET: "kumiko-dev",
+  MINIO_REGION: "us-east-1",
+  LEGACY_DATABASE_URL: "",
+} as const satisfies Record<string, string>;

package/src/preload/service-env-defaults.ts

@@ -1,14 +1,5 @@
-process.env["DATABASE_URL"] ??= "postgresql://kumiko:kumiko@localhost:15432/kumiko_dev";
-process.env["TEST_DATABASE_URL"] ??= "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
-process.env["REDIS_URL"] ??= "redis://localhost:16379";
-process.env["MEILI_URL"] ??= "http://localhost:17700";
-process.env["MEILI_MASTER_KEY"] ??= "kumiko-dev-key";
-process.env["JWT_SECRET"] ??= "test-jwt-secret-at-least-32-characters-long";
+import { SERVICE_ENV_DEFAULTS } from "./service-env-defaults-values";
 
-process.env["MINIO_ENDPOINT"] ??= "http://localhost:19000";
-process.env["MINIO_ACCESS_KEY"] ??= "kumiko";
-process.env["MINIO_SECRET_KEY"] ??= "kumiko-dev-secret";
-process.env["MINIO_BUCKET"] ??= "kumiko-dev";
-process.env["MINIO_REGION"] ??= "us-east-1";
-
-process.env["LEGACY_DATABASE_URL"] ??= "";
+for (const [key, value] of Object.entries(SERVICE_ENV_DEFAULTS)) {
+  process.env[key] ??= value;
+}

package/src/scaffold.ts

@@ -189,7 +189,13 @@ export function renderTestSetup(input: RenderTestSetupInput): ScaffoldTestSetup
     scripts: {
       test: `bun --config=${BUNFIG_FILES.unit} test --timeout=${TEST_TIMEOUT_MS.unit} --dots`,
       "test:integration": `bun kumiko-testing integration --parallel ${SCAFFOLD_INTEGRATION_PARALLEL}`,
-      "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real}`,
+      // bunfig.real.toml's pathIgnorePatterns can only blacklist (no "!" negation,
+      // verified against bun 1.4), so it can't express "match only *.real.test.ts"
+      // on its own — every *.test.ts file matches bun's default test glob too,
+      // real.test.ts included. The positional filter narrows the run to files
+      // whose path contains "real.test.ts", so an unfiltered test:real never
+      // picks up the unit suite.
+      "test:real": `${REAL_PROVIDERS_ENV}=1 bun --config=${BUNFIG_FILES.real} test --timeout=${TEST_TIMEOUT_MS.real} real.test.ts`,
       "test:bunfig": "bun kumiko-testing bunfig --hoisted",
       e2e: "bunx --bun playwright test",
       "e2e:real": `${REAL_PROVIDERS_ENV}=1 bunx --bun playwright test`,

package/src/seed-tenant.ts

@@ -13,6 +13,7 @@ import type { TestStack } from "@cosmicdrift/kumiko-framework/stack";
 import { isPlainObject } from "@cosmicdrift/kumiko-framework/utils";
 import {
   type BoundApi,
+  type SeedAdminIdentity,
   type SeededCredentials,
   type SeededTenant,
   type SeedTenantOptions,
@@ -21,6 +22,7 @@ import {
 
 export type {
   BoundApi,
+  SeedAdminIdentity,
   SeededCredentials,
   SeededTenant,
   SeededUser,
@@ -54,9 +56,14 @@ function bindApi(stack: TestStack, user: SessionUser): BoundApi {
   };
 }
 
-function lightCredentials(): SeededCredentials {
+function lightCredentials(email?: string): SeededCredentials {
   const id = randomUUID();
-  return { id, email: `user-${id}@example.test`, password: `pw-${randomUUID()}` };
+  const resolvedEmail = email ?? `user-${id}@example.test`;
+  return { id, email: resolvedEmail, password: `pw-${randomUUID()}` };
+}
+
+function substituteTenantId(email: string, tenantId: string): string {
+  return email.replaceAll("{tenantId}", tenantId);
 }
 
 function newTenantIdentity(name: string | undefined): {
@@ -100,14 +107,17 @@ export async function persistUserRows(
   write: SeedWriter,
   tenantId: TenantId,
   roles: readonly string[],
+  identity: SeedAdminIdentity = {},
 ): Promise<SeededCredentials> {
-  const light = lightCredentials();
+  const light = lightCredentials(
+    identity.email !== undefined ? substituteTenantId(identity.email, tenantId) : undefined,
+  );
   const created = await write(
     UserHandlers.create,
     {
       email: light.email,
       passwordHash: await hashPassword(light.password),
-      displayName: `Seed ${light.id.slice(0, 8)}`,
+      displayName: identity.displayName ?? `Seed ${light.id.slice(0, 8)}`,
     },
     tenantId,
   );
@@ -122,11 +132,15 @@ export async function persistUserRows(
 
 export async function persistTenantRows(
   write: SeedWriter,
-  opts: { readonly name?: string; readonly users?: number } = {},
+  opts: {
+    readonly name?: string;
+    readonly users?: number;
+    readonly admin?: SeedAdminIdentity;
+  } = {},
 ): Promise<PersistedTenant> {
   const { id, key, name } = newTenantIdentity(opts.name);
   await write(TenantHandlers.create, { id, key, name }, id);
-  const admin = await persistUserRows(write, id, [ROLES.TenantAdmin]);
+  const admin = await persistUserRows(write, id, [ROLES.TenantAdmin], opts.admin);
   const members: SeededCredentials[] = [];
   for (let i = 0; i < (opts.users ?? 0); i++) {
     members.push(await persistUserRows(write, id, [ROLES.Member]));
@@ -136,8 +150,10 @@ export async function persistTenantRows(
 
 function lightTenantRows(opts: SeedTenantOptions): PersistedTenant {
   const identity = newTenantIdentity(opts.name);
-  const members = Array.from({ length: opts.users ?? 0 }, lightCredentials);
-  return { ...identity, admin: lightCredentials(), members };
+  const members = Array.from({ length: opts.users ?? 0 }, () => lightCredentials());
+  const adminEmail =
+    opts.admin?.email !== undefined ? substituteTenantId(opts.admin.email, identity.id) : undefined;
+  return { ...identity, admin: lightCredentials(adminEmail), members };
 }
 
 export async function seedTenant(

package/src/seed-types.ts

@@ -22,11 +22,20 @@ export type SeededUser = SeededCredentials & { readonly session: SessionUser };
 
 export type SeedPart = (ctx: { readonly tenant: SeededTenant }) => Promise<void>;
 
+// email may contain the literal "{tenantId}" placeholder, substituted with the
+// seeded tenant's id — user:create's email uniqueness is global (fw#2134/#2593),
+// so a fixed literal email collides across per-scenario tenants.
+export type SeedAdminIdentity = {
+  readonly displayName?: string;
+  readonly email?: string;
+};
+
 export type SeedTenantOptions = {
   readonly name?: string;
   readonly users?: number;
   readonly with?: readonly SeedPart[];
   readonly persist?: boolean;
+  readonly admin?: SeedAdminIdentity;
 };
 
 export type SeededTenant = {

package/src/setup-app-test-stack.ts

@@ -14,7 +14,11 @@ export async function setupAppTestStack(
   options: SetupAppTestStackOptions = {},
 ): Promise<TestStack> {
   const { registryTables = true, includeBundled = true, ...stackOptions } = options;
-  const stack = await setupTestStackFromFeatures(features, { ...stackOptions, includeBundled });
+  const stack = await setupTestStackFromFeatures(features, {
+    ...stackOptions,
+    includeBundled,
+    entityTables: registryTables,
+  });
   if (!registryTables) return stack;
   try {
     await pushEntityProjectionTables(stack, stack.registry);