@orkestrel/scaffold 0.0.93 → 0.0.94

package/dist/src/core/index.d.cts

@@ -1494,7 +1494,7 @@ export declare class Compiler implements CompilerInterface {
                   journey: "import type { JourneyVariant } from '@orkestrel/test'\nimport { defineConfig } from 'vitest/config'\nimport { appJourney } from '../../vite.config.ts'\n\n// Rename and extend these viewports for the application. Apply themes through its interface.\nconst VARIANTS: readonly JourneyVariant[] = Object.freeze([\n\t{ name: 'desktop', width: 1280, height: 800 },\n\t{ name: 'compact', width: 390, height: 844 },\n])\n\nexport default defineConfig(({ mode }) => ({\n\ttest: {\n\t\tprojects: VARIANTS.map((variant) => () => appJourney(variant, VARIANTS, mode)),\n\t},\n}))\n";
               }>;
           }>;
-          browsers: "// A generated browser workspace resolves its own Chromium here rather than in\n// `configs/helpers.ts`, because that leaf is vendored byte-identical to every\n// workspace and most of them declare no `playwright` to import.\n\nimport type { PlaywrightProviderOptions } from '@vitest/browser-playwright'\nimport { chromium } from 'playwright'\nimport { accessSync, constants as FS_CONSTANTS, globSync, readdirSync, statSync } from 'node:fs'\nimport { basename, dirname, join, resolve as resolvePath } from 'node:path'\n\n/**\n * Lists the Chromium executable layouts inside a `chromium-<revision>` browsers-directory\n * entry, per platform.\n *\n * @remarks\n * The current Playwright build ships Chrome for Testing on macOS. The trailing `Chromium.app`\n * layouts are what earlier builds shipped, so the list spans Playwright versions instead of\n * pinning to the installed one.\n */\nexport const CHROMIUM_LAYOUTS = Object.freeze([\n\t'chrome-linux/chrome',\n\t'chrome-linux64/chrome',\n\t'chrome-win/chrome.exe',\n\t'chrome-win64/chrome.exe',\n\t'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac/Chromium.app/Contents/MacOS/Chromium',\n\t'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',\n])\n\n/** Matches the `chromium-<revision>` entry name Playwright installs one managed build into. */\nexport const CHROMIUM_ENTRY_PATTERN = /^chromium-\\d+$/\n\n/** Matches the revision number carried by any path containing a `chromium-<revision>` segment. */\nexport const CHROMIUM_REVISION_PATTERN = /chromium-(\\d+)/\n\n/** Names the directory a managed Linux container installs its bundled Playwright browsers into. */\nexport const BUNDLED_BROWSERS_ROOT = '/opt/pw-browsers'\n\n/**\n * Lists the bundled Chromium layouts under the managed-container browsers root, as glob patterns.\n *\n * @remarks\n * The revision directory and its inner layout both drift across Playwright builds, and the\n * container also carries a top-level `chromium` alias, so every known shape is globbed.\n */\nexport const BUNDLED_CHROMIUM_LAYOUTS = Object.freeze([\n\t'chromium',\n\t'chromium-*/chrome-linux64/chrome',\n\t'chromium-*/chrome-linux/chrome',\n])\n\n/** Lists the stable Playwright Chromium channels and their standard executable layouts. */\nexport const SYSTEM_BROWSER_CHANNELS = Object.freeze([\n\tObject.freeze({\n\t\tchannel: 'chrome',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/google/chrome/chrome',\n\t\t\tdarwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',\n\t\t\twin32: Object.freeze(['Google', 'Chrome', 'Application', 'chrome.exe']),\n\t\t}),\n\t}),\n\tObject.freeze({\n\t\tchannel: 'msedge',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/microsoft/msedge/msedge',\n\t\t\tdarwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',\n\t\t\twin32: Object.freeze(['Microsoft', 'Edge', 'Application', 'msedge.exe']),\n\t\t}),\n\t}),\n])\n\n/**\n * Determines whether a path identifies an executable regular file.\n *\n * @param path - The filesystem path to inspect.\n * @returns True if the path is a regular file with execute access; false otherwise.\n *\n * @example\n * ```ts\n * isBrowserExecutable('/opt/google/chrome/chrome')\n * ```\n */\nexport function isBrowserExecutable(path: string): boolean {\n\ttry {\n\t\tif (!statSync(path).isFile()) return false\n\t\taccessSync(path, FS_CONSTANTS.X_OK)\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/**\n * Orders two Chromium paths so the highest revision sorts first.\n *\n * @param left - The first path or directory entry to compare.\n * @param right - The second path or directory entry to compare.\n * @returns A negative number when `left` sorts first, positive when `right` does.\n *\n * @remarks\n * Revisions are numbers, so `chromium-1200` outranks `chromium-999` despite sorting below it\n * lexically. A path carrying no revision falls back to descending name order.\n *\n * @example\n * ```ts\n * ['chromium-999', 'chromium-1200'].sort(compareRevisions)\n * ```\n */\nexport function compareRevisions(left: string, right: string): number {\n\tconst leftRevision = CHROMIUM_REVISION_PATTERN.exec(left)?.[1]\n\tconst rightRevision = CHROMIUM_REVISION_PATTERN.exec(right)?.[1]\n\tif (leftRevision === undefined || rightRevision === undefined) return right.localeCompare(left)\n\treturn Number(rightRevision) - Number(leftRevision)\n}\n\n/**\n * Reads the executable path of Playwright's pinned Chromium revision.\n *\n * @returns The pinned executable path, or `undefined` when this platform has none.\n *\n * @remarks\n * Playwright throws rather than returning a path when the current platform carries no initialized\n * executable, and an unguarded call would fail configuration evaluation for every project.\n *\n * @example\n * ```ts\n * resolvePinnedBrowser()\n * ```\n */\nexport function resolvePinnedBrowser(): string | undefined {\n\ttry {\n\t\tconst pinned = chromium.executablePath()\n\t\treturn pinned.length === 0 ? undefined : pinned\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Resolves a launchable Playwright-managed Chromium executable: the pinned revision when installed,\n * otherwise a `chromium` / `chromium.exe` alias or any other `chromium-*` revision under the same\n * Playwright browsers directory. A pinned-revision miss is not Chromium absence — managed\n * containers ship one usable build, often behind a revision-agnostic alias, for many Playwright\n * versions.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision.\n * @returns The managed executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveManagedBrowser('/root/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome')\n * ```\n */\nexport function resolveManagedBrowser(pinned: string): string | undefined {\n\tif (isBrowserExecutable(pinned)) return pinned\n\tlet revisionRoot = dirname(pinned)\n\tfor (;;) {\n\t\tif (CHROMIUM_ENTRY_PATTERN.test(basename(revisionRoot))) break\n\t\tconst parent = dirname(revisionRoot)\n\t\tif (parent === revisionRoot) return undefined\n\t\trevisionRoot = parent\n\t}\n\tconst browsersRoot = dirname(revisionRoot)\n\tfor (const alias of ['chromium', 'chromium.exe']) {\n\t\tconst candidate = resolvePath(browsersRoot, alias)\n\t\tif (isBrowserExecutable(candidate)) return candidate\n\t}\n\tlet entries: readonly string[]\n\ttry {\n\t\tentries = readdirSync(browsersRoot)\n\t} catch {\n\t\treturn undefined\n\t}\n\tconst revisions = entries\n\t\t.filter((entry) => CHROMIUM_ENTRY_PATTERN.test(entry))\n\t\t.sort(compareRevisions)\n\tfor (const revision of revisions) {\n\t\tfor (const layout of CHROMIUM_LAYOUTS) {\n\t\t\tconst candidate = resolvePath(browsersRoot, revision, layout)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the Chromium a managed Linux container bundles outside the Playwright cache.\n *\n * @param platform - The Node platform the container runs on.\n * @param root - The bundled browsers directory to search.\n * @returns The highest matching executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveBundledBrowser('linux', BUNDLED_BROWSERS_ROOT)\n * ```\n */\nexport function resolveBundledBrowser(platform: NodeJS.Platform, root: string): string | undefined {\n\tif (platform !== 'linux') return undefined\n\tfor (const layout of BUNDLED_CHROMIUM_LAYOUTS) {\n\t\tlet matches: readonly string[]\n\t\ttry {\n\t\t\tmatches = globSync(layout, { cwd: root })\n\t\t} catch {\n\t\t\treturn undefined\n\t\t}\n\t\tfor (const match of [...matches].sort(compareRevisions)) {\n\t\t\tconst candidate = resolvePath(root, match)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the first installed stable system Chromium channel.\n *\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying Windows installation roots.\n * @returns `chrome`, then `msedge`, or `undefined` when neither is executable.\n *\n * @example\n * ```ts\n * resolveSystemBrowser(process.platform, process.env)\n * ```\n */\nexport function resolveSystemBrowser(\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n): string | undefined {\n\tif (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') return undefined\n\tconst roots = new Set<string>()\n\tif (platform === 'win32') {\n\t\tfor (const root of [\n\t\t\tenvironment.LOCALAPPDATA,\n\t\t\tenvironment.PROGRAMFILES,\n\t\t\tenvironment['PROGRAMFILES(X86)'],\n\t\t]) {\n\t\t\tif (root !== undefined && root.length > 0) roots.add(root)\n\t\t}\n\t\tconst homeDrive = environment.HOMEDRIVE\n\t\tif (homeDrive !== undefined && homeDrive.length > 0) {\n\t\t\troots.add(join(homeDrive, 'Program Files'))\n\t\t\troots.add(join(homeDrive, 'Program Files (x86)'))\n\t\t}\n\t}\n\tfor (const browser of SYSTEM_BROWSER_CHANNELS) {\n\t\tif (platform === 'win32') {\n\t\t\tfor (const root of roots) {\n\t\t\t\tif (isBrowserExecutable(join(root, ...browser.layouts.win32))) return browser.channel\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (isBrowserExecutable(browser.layouts[platform])) return browser.channel\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves Playwright provider options for Chromium on this host.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision, when it has one.\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying operator overrides and Windows roots.\n * @param root - The managed-container bundled browsers directory to search.\n * @returns Provider options naming an executable, a WebSocket endpoint, or a channel.\n *\n * @remarks\n * Precedence, most important first: `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`,\n * `PLAYWRIGHT_CHANNEL`, the managed Playwright Chromium, the container's bundled Chromium, a\n * verified system channel, then the platform default channel. An operator override outranks\n * discovery and is returned exactly as given: none of those environment values is checked\n * against the filesystem, because verifying an override would defeat the override. The pinned\n * managed revision outranks anything found on the host because it is deterministic. The installed\n * pinned revision returns empty options so Playwright keeps its own default launch semantics. Only\n * a discovered system channel is verified before it is named. The platform default is unverified\n * as well and exists only as a last resort: Windows takes `msedge`, which ships with the OS and\n * never collides with a foreground Chrome.\n *\n * The resolver and the gate cover Chromium alone. Reopen engine selection when another\n * Playwright engine is installed and launches on the host with a `captureFrame` reading\n * back at its declared size, or when a journey or style divergence is recorded.\n *\n * @example\n * ```ts\n * resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)\n * ```\n */\nexport function resolveBrowser(\n\tpinned: string | undefined,\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n\troot: string = BUNDLED_BROWSERS_ROOT,\n): PlaywrightProviderOptions {\n\tconst executable = environment.PLAYWRIGHT_EXECUTABLE_PATH\n\tif (executable !== undefined && executable.length > 0) {\n\t\treturn { launchOptions: { executablePath: executable } }\n\t}\n\tconst endpoint = environment.PLAYWRIGHT_WS_ENDPOINT\n\tif (endpoint !== undefined && endpoint.length > 0) {\n\t\treturn { connectOptions: { wsEndpoint: endpoint } }\n\t}\n\tconst requested = environment.PLAYWRIGHT_CHANNEL\n\tif (requested !== undefined && requested.length > 0) {\n\t\treturn { launchOptions: { channel: requested } }\n\t}\n\tconst managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)\n\tif (managed !== undefined) {\n\t\treturn managed === pinned ? {} : { launchOptions: { executablePath: managed } }\n\t}\n\tconst bundled = resolveBundledBrowser(platform, root)\n\tif (bundled !== undefined) return { launchOptions: { executablePath: bundled } }\n\tconst fallback = platform === 'win32' ? 'msedge' : 'chrome'\n\treturn { launchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback } }\n}\n";
+          browsers: "// A generated browser workspace resolves its own Chromium here rather than in\n// `configs/helpers.ts`, because that leaf is vendored byte-identical to every\n// workspace and most of them declare no `playwright` to import.\n\nimport type { PlaywrightProviderOptions } from '@vitest/browser-playwright'\nimport { chromium } from 'playwright'\nimport { accessSync, constants as FS_CONSTANTS, globSync, readdirSync, statSync } from 'node:fs'\nimport { basename, dirname, join, resolve as resolvePath } from 'node:path'\n\n/**\n * Lists the Chromium executable layouts inside a `chromium-<revision>` browsers-directory\n * entry, per platform.\n *\n * @remarks\n * The current Playwright build ships Chrome for Testing on macOS. The trailing `Chromium.app`\n * layouts are what earlier builds shipped, so the list spans Playwright versions instead of\n * pinning to the installed one.\n */\nexport const CHROMIUM_LAYOUTS = Object.freeze([\n\t'chrome-linux/chrome',\n\t'chrome-linux64/chrome',\n\t'chrome-win/chrome.exe',\n\t'chrome-win64/chrome.exe',\n\t'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac/Chromium.app/Contents/MacOS/Chromium',\n\t'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',\n])\n\n/** Matches the `chromium-<revision>` entry name Playwright installs one managed build into. */\nexport const CHROMIUM_ENTRY_PATTERN = /^chromium-\\d+$/\n\n/** Matches the revision number carried by any path containing a `chromium-<revision>` segment. */\nexport const CHROMIUM_REVISION_PATTERN = /chromium-(\\d+)/\n\n/** Names the directory a managed Linux container installs its bundled Playwright browsers into. */\nexport const BUNDLED_BROWSERS_ROOT = '/opt/pw-browsers'\n\n/**\n * Lists the bundled Chromium layouts under the managed-container browsers root, as glob patterns.\n *\n * @remarks\n * The revision directory and its inner layout both drift across Playwright builds, and the\n * container also carries a top-level `chromium` alias, so every known shape is globbed.\n */\nexport const BUNDLED_CHROMIUM_LAYOUTS = Object.freeze([\n\t'chromium',\n\t'chromium-*/chrome-linux64/chrome',\n\t'chromium-*/chrome-linux/chrome',\n])\n\n/** Lists the stable Playwright Chromium channels and their standard executable layouts. */\nexport const SYSTEM_BROWSER_CHANNELS = Object.freeze([\n\tObject.freeze({\n\t\tchannel: 'chrome',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/google/chrome/chrome',\n\t\t\tdarwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',\n\t\t\twin32: Object.freeze(['Google', 'Chrome', 'Application', 'chrome.exe']),\n\t\t}),\n\t}),\n\tObject.freeze({\n\t\tchannel: 'msedge',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/microsoft/msedge/msedge',\n\t\t\tdarwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',\n\t\t\twin32: Object.freeze(['Microsoft', 'Edge', 'Application', 'msedge.exe']),\n\t\t}),\n\t}),\n])\n\n/**\n * Determines whether a path identifies an executable regular file.\n *\n * @param path - The filesystem path to inspect.\n * @returns True if the path is a regular file with execute access; false otherwise.\n *\n * @example\n * ```ts\n * isBrowserExecutable('/opt/google/chrome/chrome')\n * ```\n */\nexport function isBrowserExecutable(path: string): boolean {\n\ttry {\n\t\tif (!statSync(path).isFile()) return false\n\t\taccessSync(path, FS_CONSTANTS.X_OK)\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/**\n * Orders two Chromium paths so the highest revision sorts first.\n *\n * @param left - The first path or directory entry to compare.\n * @param right - The second path or directory entry to compare.\n * @returns A negative number when `left` sorts first, positive when `right` does.\n *\n * @remarks\n * Revisions are numbers, so `chromium-1200` outranks `chromium-999` despite sorting below it\n * lexically. A path carrying no revision falls back to descending name order.\n *\n * @example\n * ```ts\n * ['chromium-999', 'chromium-1200'].sort(compareRevisions)\n * ```\n */\nexport function compareRevisions(left: string, right: string): number {\n\tconst leftRevision = CHROMIUM_REVISION_PATTERN.exec(left)?.[1]\n\tconst rightRevision = CHROMIUM_REVISION_PATTERN.exec(right)?.[1]\n\tif (leftRevision === undefined || rightRevision === undefined) return right.localeCompare(left)\n\treturn Number(rightRevision) - Number(leftRevision)\n}\n\n/**\n * Reads the executable path of Playwright's pinned Chromium revision.\n *\n * @returns The pinned executable path, or `undefined` when this platform has none.\n *\n * @remarks\n * Playwright throws rather than returning a path when the current platform carries no initialized\n * executable, and an unguarded call would fail configuration evaluation for every project.\n *\n * @example\n * ```ts\n * resolvePinnedBrowser()\n * ```\n */\nexport function resolvePinnedBrowser(): string | undefined {\n\ttry {\n\t\tconst pinned = chromium.executablePath()\n\t\treturn pinned.length === 0 ? undefined : pinned\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Resolves a launchable Playwright-managed Chromium executable: the pinned revision when installed,\n * otherwise a `chromium` / `chromium.exe` alias or any other `chromium-*` revision under the same\n * Playwright browsers directory. A pinned-revision miss is not Chromium absence — managed\n * containers ship one usable build, often behind a revision-agnostic alias, for many Playwright\n * versions.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision.\n * @returns The managed executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveManagedBrowser('/root/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome')\n * ```\n */\nexport function resolveManagedBrowser(pinned: string): string | undefined {\n\tif (isBrowserExecutable(pinned)) return pinned\n\tlet revisionRoot = dirname(pinned)\n\tfor (;;) {\n\t\tif (CHROMIUM_ENTRY_PATTERN.test(basename(revisionRoot))) break\n\t\tconst parent = dirname(revisionRoot)\n\t\tif (parent === revisionRoot) return undefined\n\t\trevisionRoot = parent\n\t}\n\tconst browsersRoot = dirname(revisionRoot)\n\tfor (const alias of ['chromium', 'chromium.exe']) {\n\t\tconst candidate = resolvePath(browsersRoot, alias)\n\t\tif (isBrowserExecutable(candidate)) return candidate\n\t}\n\tlet entries: readonly string[]\n\ttry {\n\t\tentries = readdirSync(browsersRoot)\n\t} catch {\n\t\treturn undefined\n\t}\n\tconst revisions = entries\n\t\t.filter((entry) => CHROMIUM_ENTRY_PATTERN.test(entry))\n\t\t.sort(compareRevisions)\n\tfor (const revision of revisions) {\n\t\tfor (const layout of CHROMIUM_LAYOUTS) {\n\t\t\tconst candidate = resolvePath(browsersRoot, revision, layout)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the Chromium a managed Linux container bundles outside the Playwright cache.\n *\n * @param platform - The Node platform the container runs on.\n * @param root - The bundled browsers directory to search.\n * @returns The highest matching executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveBundledBrowser('linux', BUNDLED_BROWSERS_ROOT)\n * ```\n */\nexport function resolveBundledBrowser(platform: NodeJS.Platform, root: string): string | undefined {\n\tif (platform !== 'linux') return undefined\n\tfor (const layout of BUNDLED_CHROMIUM_LAYOUTS) {\n\t\tlet matches: readonly string[]\n\t\ttry {\n\t\t\tmatches = globSync(layout, { cwd: root })\n\t\t} catch {\n\t\t\treturn undefined\n\t\t}\n\t\tfor (const match of [...matches].sort(compareRevisions)) {\n\t\t\tconst candidate = resolvePath(root, match)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the first installed stable system Chromium channel.\n *\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying Windows installation roots.\n * @returns `chrome`, then `msedge`, or `undefined` when neither is executable.\n *\n * @example\n * ```ts\n * resolveSystemBrowser(process.platform, process.env)\n * ```\n */\nexport function resolveSystemBrowser(\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n): string | undefined {\n\tif (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') return undefined\n\tconst roots = new Set<string>()\n\tif (platform === 'win32') {\n\t\tfor (const root of [\n\t\t\tenvironment.LOCALAPPDATA,\n\t\t\tenvironment.PROGRAMFILES,\n\t\t\tenvironment['PROGRAMFILES(X86)'],\n\t\t]) {\n\t\t\tif (root !== undefined && root.length > 0) roots.add(root)\n\t\t}\n\t\tconst homeDrive = environment.HOMEDRIVE\n\t\tif (homeDrive !== undefined && homeDrive.length > 0) {\n\t\t\troots.add(join(homeDrive, 'Program Files'))\n\t\t\troots.add(join(homeDrive, 'Program Files (x86)'))\n\t\t}\n\t}\n\tfor (const browser of SYSTEM_BROWSER_CHANNELS) {\n\t\tif (platform === 'win32') {\n\t\t\tfor (const root of roots) {\n\t\t\t\tif (isBrowserExecutable(join(root, ...browser.layouts.win32))) return browser.channel\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (isBrowserExecutable(browser.layouts[platform])) return browser.channel\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves Playwright provider options for Chromium on this host.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision, when it has one.\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying operator overrides and Windows roots.\n * @param root - The managed-container bundled browsers directory to search.\n * @returns Provider options naming an executable, a WebSocket endpoint, or a channel.\n *\n * @remarks\n * Precedence, most important first: `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`,\n * `PLAYWRIGHT_CHANNEL`, the managed Playwright Chromium, the container's bundled Chromium, a\n * verified system channel, then the platform default channel. An operator override outranks\n * discovery and is returned exactly as given: none of those environment values is checked\n * against the filesystem, because verifying an override would defeat the override. The pinned\n * managed revision outranks anything found on the host because it is deterministic. The installed\n * pinned revision returns empty options unless `PLAYWRIGHT_SCROLLBARS=classic` is set. Only a\n * discovered system channel is verified before it is named. The platform default is unverified\n * as well and exists only as a last resort: Windows takes `msedge`, which ships with the OS and\n * never collides with a foreground Chrome.\n *\n * Set `PLAYWRIGHT_SCROLLBARS=classic` only for runs that measure scrollbar compensation, never\n * for a standing gate. Every Chromium launch in that run omits Playwright's `--hide-scrollbars`\n * default argument so classic scrollbars can take layout space in every case. An empty or unset\n * value preserves the launch defaults; any other value throws an `Error`. Pairing `classic`\n * with `PLAYWRIGHT_WS_ENDPOINT` throws an `Error`, even with an executable override, because the\n * server owns the launch.\n *\n * The resolver and the gate cover Chromium alone. Reopen engine selection when another\n * Playwright engine is installed and launches on the host with a `captureFrame` reading\n * back at its declared size, or when a journey or style divergence is recorded.\n *\n * @example\n * ```ts\n * resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)\n * ```\n */\nexport function resolveBrowser(\n\tpinned: string | undefined,\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n\troot: string = BUNDLED_BROWSERS_ROOT,\n): PlaywrightProviderOptions {\n\tconst scrollbars = environment.PLAYWRIGHT_SCROLLBARS\n\tif (scrollbars !== undefined && scrollbars.length > 0 && scrollbars !== 'classic') {\n\t\tthrow new Error('PLAYWRIGHT_SCROLLBARS must be classic or empty')\n\t}\n\tconst endpoint = environment.PLAYWRIGHT_WS_ENDPOINT\n\tif (scrollbars === 'classic' && endpoint !== undefined && endpoint.length > 0) {\n\t\tthrow new Error('PLAYWRIGHT_SCROLLBARS=classic cannot be used with PLAYWRIGHT_WS_ENDPOINT')\n\t}\n\tconst launch: PlaywrightProviderOptions['launchOptions'] =\n\t\tscrollbars === 'classic' ? { ignoreDefaultArgs: ['--hide-scrollbars'] } : {}\n\tconst executable = environment.PLAYWRIGHT_EXECUTABLE_PATH\n\tif (executable !== undefined && executable.length > 0) {\n\t\treturn { launchOptions: { executablePath: executable, ...launch } }\n\t}\n\tif (endpoint !== undefined && endpoint.length > 0) {\n\t\treturn { connectOptions: { wsEndpoint: endpoint } }\n\t}\n\tconst requested = environment.PLAYWRIGHT_CHANNEL\n\tif (requested !== undefined && requested.length > 0) {\n\t\treturn { launchOptions: { channel: requested, ...launch } }\n\t}\n\tconst managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)\n\tif (managed !== undefined) {\n\t\tif (managed === pinned) return scrollbars === 'classic' ? { launchOptions: launch } : {}\n\t\treturn { launchOptions: { executablePath: managed, ...launch } }\n\t}\n\tconst bundled = resolveBundledBrowser(platform, root)\n\tif (bundled !== undefined) return { launchOptions: { executablePath: bundled, ...launch } }\n\tconst fallback = platform === 'win32' ? 'msedge' : 'chrome'\n\treturn {\n\t\tlaunchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback, ...launch },\n\t}\n}\n";
       }>;
 
       /** Names the official-tooling drift proof whose presence makes a workspace `conformance`. */

package/dist/src/core/index.d.ts

@@ -1494,7 +1494,7 @@ export declare class Compiler implements CompilerInterface {
                   journey: "import type { JourneyVariant } from '@orkestrel/test'\nimport { defineConfig } from 'vitest/config'\nimport { appJourney } from '../../vite.config.ts'\n\n// Rename and extend these viewports for the application. Apply themes through its interface.\nconst VARIANTS: readonly JourneyVariant[] = Object.freeze([\n\t{ name: 'desktop', width: 1280, height: 800 },\n\t{ name: 'compact', width: 390, height: 844 },\n])\n\nexport default defineConfig(({ mode }) => ({\n\ttest: {\n\t\tprojects: VARIANTS.map((variant) => () => appJourney(variant, VARIANTS, mode)),\n\t},\n}))\n";
               }>;
           }>;
-          browsers: "// A generated browser workspace resolves its own Chromium here rather than in\n// `configs/helpers.ts`, because that leaf is vendored byte-identical to every\n// workspace and most of them declare no `playwright` to import.\n\nimport type { PlaywrightProviderOptions } from '@vitest/browser-playwright'\nimport { chromium } from 'playwright'\nimport { accessSync, constants as FS_CONSTANTS, globSync, readdirSync, statSync } from 'node:fs'\nimport { basename, dirname, join, resolve as resolvePath } from 'node:path'\n\n/**\n * Lists the Chromium executable layouts inside a `chromium-<revision>` browsers-directory\n * entry, per platform.\n *\n * @remarks\n * The current Playwright build ships Chrome for Testing on macOS. The trailing `Chromium.app`\n * layouts are what earlier builds shipped, so the list spans Playwright versions instead of\n * pinning to the installed one.\n */\nexport const CHROMIUM_LAYOUTS = Object.freeze([\n\t'chrome-linux/chrome',\n\t'chrome-linux64/chrome',\n\t'chrome-win/chrome.exe',\n\t'chrome-win64/chrome.exe',\n\t'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac/Chromium.app/Contents/MacOS/Chromium',\n\t'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',\n])\n\n/** Matches the `chromium-<revision>` entry name Playwright installs one managed build into. */\nexport const CHROMIUM_ENTRY_PATTERN = /^chromium-\\d+$/\n\n/** Matches the revision number carried by any path containing a `chromium-<revision>` segment. */\nexport const CHROMIUM_REVISION_PATTERN = /chromium-(\\d+)/\n\n/** Names the directory a managed Linux container installs its bundled Playwright browsers into. */\nexport const BUNDLED_BROWSERS_ROOT = '/opt/pw-browsers'\n\n/**\n * Lists the bundled Chromium layouts under the managed-container browsers root, as glob patterns.\n *\n * @remarks\n * The revision directory and its inner layout both drift across Playwright builds, and the\n * container also carries a top-level `chromium` alias, so every known shape is globbed.\n */\nexport const BUNDLED_CHROMIUM_LAYOUTS = Object.freeze([\n\t'chromium',\n\t'chromium-*/chrome-linux64/chrome',\n\t'chromium-*/chrome-linux/chrome',\n])\n\n/** Lists the stable Playwright Chromium channels and their standard executable layouts. */\nexport const SYSTEM_BROWSER_CHANNELS = Object.freeze([\n\tObject.freeze({\n\t\tchannel: 'chrome',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/google/chrome/chrome',\n\t\t\tdarwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',\n\t\t\twin32: Object.freeze(['Google', 'Chrome', 'Application', 'chrome.exe']),\n\t\t}),\n\t}),\n\tObject.freeze({\n\t\tchannel: 'msedge',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/microsoft/msedge/msedge',\n\t\t\tdarwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',\n\t\t\twin32: Object.freeze(['Microsoft', 'Edge', 'Application', 'msedge.exe']),\n\t\t}),\n\t}),\n])\n\n/**\n * Determines whether a path identifies an executable regular file.\n *\n * @param path - The filesystem path to inspect.\n * @returns True if the path is a regular file with execute access; false otherwise.\n *\n * @example\n * ```ts\n * isBrowserExecutable('/opt/google/chrome/chrome')\n * ```\n */\nexport function isBrowserExecutable(path: string): boolean {\n\ttry {\n\t\tif (!statSync(path).isFile()) return false\n\t\taccessSync(path, FS_CONSTANTS.X_OK)\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/**\n * Orders two Chromium paths so the highest revision sorts first.\n *\n * @param left - The first path or directory entry to compare.\n * @param right - The second path or directory entry to compare.\n * @returns A negative number when `left` sorts first, positive when `right` does.\n *\n * @remarks\n * Revisions are numbers, so `chromium-1200` outranks `chromium-999` despite sorting below it\n * lexically. A path carrying no revision falls back to descending name order.\n *\n * @example\n * ```ts\n * ['chromium-999', 'chromium-1200'].sort(compareRevisions)\n * ```\n */\nexport function compareRevisions(left: string, right: string): number {\n\tconst leftRevision = CHROMIUM_REVISION_PATTERN.exec(left)?.[1]\n\tconst rightRevision = CHROMIUM_REVISION_PATTERN.exec(right)?.[1]\n\tif (leftRevision === undefined || rightRevision === undefined) return right.localeCompare(left)\n\treturn Number(rightRevision) - Number(leftRevision)\n}\n\n/**\n * Reads the executable path of Playwright's pinned Chromium revision.\n *\n * @returns The pinned executable path, or `undefined` when this platform has none.\n *\n * @remarks\n * Playwright throws rather than returning a path when the current platform carries no initialized\n * executable, and an unguarded call would fail configuration evaluation for every project.\n *\n * @example\n * ```ts\n * resolvePinnedBrowser()\n * ```\n */\nexport function resolvePinnedBrowser(): string | undefined {\n\ttry {\n\t\tconst pinned = chromium.executablePath()\n\t\treturn pinned.length === 0 ? undefined : pinned\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Resolves a launchable Playwright-managed Chromium executable: the pinned revision when installed,\n * otherwise a `chromium` / `chromium.exe` alias or any other `chromium-*` revision under the same\n * Playwright browsers directory. A pinned-revision miss is not Chromium absence — managed\n * containers ship one usable build, often behind a revision-agnostic alias, for many Playwright\n * versions.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision.\n * @returns The managed executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveManagedBrowser('/root/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome')\n * ```\n */\nexport function resolveManagedBrowser(pinned: string): string | undefined {\n\tif (isBrowserExecutable(pinned)) return pinned\n\tlet revisionRoot = dirname(pinned)\n\tfor (;;) {\n\t\tif (CHROMIUM_ENTRY_PATTERN.test(basename(revisionRoot))) break\n\t\tconst parent = dirname(revisionRoot)\n\t\tif (parent === revisionRoot) return undefined\n\t\trevisionRoot = parent\n\t}\n\tconst browsersRoot = dirname(revisionRoot)\n\tfor (const alias of ['chromium', 'chromium.exe']) {\n\t\tconst candidate = resolvePath(browsersRoot, alias)\n\t\tif (isBrowserExecutable(candidate)) return candidate\n\t}\n\tlet entries: readonly string[]\n\ttry {\n\t\tentries = readdirSync(browsersRoot)\n\t} catch {\n\t\treturn undefined\n\t}\n\tconst revisions = entries\n\t\t.filter((entry) => CHROMIUM_ENTRY_PATTERN.test(entry))\n\t\t.sort(compareRevisions)\n\tfor (const revision of revisions) {\n\t\tfor (const layout of CHROMIUM_LAYOUTS) {\n\t\t\tconst candidate = resolvePath(browsersRoot, revision, layout)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the Chromium a managed Linux container bundles outside the Playwright cache.\n *\n * @param platform - The Node platform the container runs on.\n * @param root - The bundled browsers directory to search.\n * @returns The highest matching executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveBundledBrowser('linux', BUNDLED_BROWSERS_ROOT)\n * ```\n */\nexport function resolveBundledBrowser(platform: NodeJS.Platform, root: string): string | undefined {\n\tif (platform !== 'linux') return undefined\n\tfor (const layout of BUNDLED_CHROMIUM_LAYOUTS) {\n\t\tlet matches: readonly string[]\n\t\ttry {\n\t\t\tmatches = globSync(layout, { cwd: root })\n\t\t} catch {\n\t\t\treturn undefined\n\t\t}\n\t\tfor (const match of [...matches].sort(compareRevisions)) {\n\t\t\tconst candidate = resolvePath(root, match)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the first installed stable system Chromium channel.\n *\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying Windows installation roots.\n * @returns `chrome`, then `msedge`, or `undefined` when neither is executable.\n *\n * @example\n * ```ts\n * resolveSystemBrowser(process.platform, process.env)\n * ```\n */\nexport function resolveSystemBrowser(\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n): string | undefined {\n\tif (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') return undefined\n\tconst roots = new Set<string>()\n\tif (platform === 'win32') {\n\t\tfor (const root of [\n\t\t\tenvironment.LOCALAPPDATA,\n\t\t\tenvironment.PROGRAMFILES,\n\t\t\tenvironment['PROGRAMFILES(X86)'],\n\t\t]) {\n\t\t\tif (root !== undefined && root.length > 0) roots.add(root)\n\t\t}\n\t\tconst homeDrive = environment.HOMEDRIVE\n\t\tif (homeDrive !== undefined && homeDrive.length > 0) {\n\t\t\troots.add(join(homeDrive, 'Program Files'))\n\t\t\troots.add(join(homeDrive, 'Program Files (x86)'))\n\t\t}\n\t}\n\tfor (const browser of SYSTEM_BROWSER_CHANNELS) {\n\t\tif (platform === 'win32') {\n\t\t\tfor (const root of roots) {\n\t\t\t\tif (isBrowserExecutable(join(root, ...browser.layouts.win32))) return browser.channel\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (isBrowserExecutable(browser.layouts[platform])) return browser.channel\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves Playwright provider options for Chromium on this host.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision, when it has one.\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying operator overrides and Windows roots.\n * @param root - The managed-container bundled browsers directory to search.\n * @returns Provider options naming an executable, a WebSocket endpoint, or a channel.\n *\n * @remarks\n * Precedence, most important first: `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`,\n * `PLAYWRIGHT_CHANNEL`, the managed Playwright Chromium, the container's bundled Chromium, a\n * verified system channel, then the platform default channel. An operator override outranks\n * discovery and is returned exactly as given: none of those environment values is checked\n * against the filesystem, because verifying an override would defeat the override. The pinned\n * managed revision outranks anything found on the host because it is deterministic. The installed\n * pinned revision returns empty options so Playwright keeps its own default launch semantics. Only\n * a discovered system channel is verified before it is named. The platform default is unverified\n * as well and exists only as a last resort: Windows takes `msedge`, which ships with the OS and\n * never collides with a foreground Chrome.\n *\n * The resolver and the gate cover Chromium alone. Reopen engine selection when another\n * Playwright engine is installed and launches on the host with a `captureFrame` reading\n * back at its declared size, or when a journey or style divergence is recorded.\n *\n * @example\n * ```ts\n * resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)\n * ```\n */\nexport function resolveBrowser(\n\tpinned: string | undefined,\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n\troot: string = BUNDLED_BROWSERS_ROOT,\n): PlaywrightProviderOptions {\n\tconst executable = environment.PLAYWRIGHT_EXECUTABLE_PATH\n\tif (executable !== undefined && executable.length > 0) {\n\t\treturn { launchOptions: { executablePath: executable } }\n\t}\n\tconst endpoint = environment.PLAYWRIGHT_WS_ENDPOINT\n\tif (endpoint !== undefined && endpoint.length > 0) {\n\t\treturn { connectOptions: { wsEndpoint: endpoint } }\n\t}\n\tconst requested = environment.PLAYWRIGHT_CHANNEL\n\tif (requested !== undefined && requested.length > 0) {\n\t\treturn { launchOptions: { channel: requested } }\n\t}\n\tconst managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)\n\tif (managed !== undefined) {\n\t\treturn managed === pinned ? {} : { launchOptions: { executablePath: managed } }\n\t}\n\tconst bundled = resolveBundledBrowser(platform, root)\n\tif (bundled !== undefined) return { launchOptions: { executablePath: bundled } }\n\tconst fallback = platform === 'win32' ? 'msedge' : 'chrome'\n\treturn { launchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback } }\n}\n";
+          browsers: "// A generated browser workspace resolves its own Chromium here rather than in\n// `configs/helpers.ts`, because that leaf is vendored byte-identical to every\n// workspace and most of them declare no `playwright` to import.\n\nimport type { PlaywrightProviderOptions } from '@vitest/browser-playwright'\nimport { chromium } from 'playwright'\nimport { accessSync, constants as FS_CONSTANTS, globSync, readdirSync, statSync } from 'node:fs'\nimport { basename, dirname, join, resolve as resolvePath } from 'node:path'\n\n/**\n * Lists the Chromium executable layouts inside a `chromium-<revision>` browsers-directory\n * entry, per platform.\n *\n * @remarks\n * The current Playwright build ships Chrome for Testing on macOS. The trailing `Chromium.app`\n * layouts are what earlier builds shipped, so the list spans Playwright versions instead of\n * pinning to the installed one.\n */\nexport const CHROMIUM_LAYOUTS = Object.freeze([\n\t'chrome-linux/chrome',\n\t'chrome-linux64/chrome',\n\t'chrome-win/chrome.exe',\n\t'chrome-win64/chrome.exe',\n\t'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',\n\t'chrome-mac/Chromium.app/Contents/MacOS/Chromium',\n\t'chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium',\n])\n\n/** Matches the `chromium-<revision>` entry name Playwright installs one managed build into. */\nexport const CHROMIUM_ENTRY_PATTERN = /^chromium-\\d+$/\n\n/** Matches the revision number carried by any path containing a `chromium-<revision>` segment. */\nexport const CHROMIUM_REVISION_PATTERN = /chromium-(\\d+)/\n\n/** Names the directory a managed Linux container installs its bundled Playwright browsers into. */\nexport const BUNDLED_BROWSERS_ROOT = '/opt/pw-browsers'\n\n/**\n * Lists the bundled Chromium layouts under the managed-container browsers root, as glob patterns.\n *\n * @remarks\n * The revision directory and its inner layout both drift across Playwright builds, and the\n * container also carries a top-level `chromium` alias, so every known shape is globbed.\n */\nexport const BUNDLED_CHROMIUM_LAYOUTS = Object.freeze([\n\t'chromium',\n\t'chromium-*/chrome-linux64/chrome',\n\t'chromium-*/chrome-linux/chrome',\n])\n\n/** Lists the stable Playwright Chromium channels and their standard executable layouts. */\nexport const SYSTEM_BROWSER_CHANNELS = Object.freeze([\n\tObject.freeze({\n\t\tchannel: 'chrome',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/google/chrome/chrome',\n\t\t\tdarwin: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',\n\t\t\twin32: Object.freeze(['Google', 'Chrome', 'Application', 'chrome.exe']),\n\t\t}),\n\t}),\n\tObject.freeze({\n\t\tchannel: 'msedge',\n\t\tlayouts: Object.freeze({\n\t\t\tlinux: '/opt/microsoft/msedge/msedge',\n\t\t\tdarwin: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',\n\t\t\twin32: Object.freeze(['Microsoft', 'Edge', 'Application', 'msedge.exe']),\n\t\t}),\n\t}),\n])\n\n/**\n * Determines whether a path identifies an executable regular file.\n *\n * @param path - The filesystem path to inspect.\n * @returns True if the path is a regular file with execute access; false otherwise.\n *\n * @example\n * ```ts\n * isBrowserExecutable('/opt/google/chrome/chrome')\n * ```\n */\nexport function isBrowserExecutable(path: string): boolean {\n\ttry {\n\t\tif (!statSync(path).isFile()) return false\n\t\taccessSync(path, FS_CONSTANTS.X_OK)\n\t\treturn true\n\t} catch {\n\t\treturn false\n\t}\n}\n\n/**\n * Orders two Chromium paths so the highest revision sorts first.\n *\n * @param left - The first path or directory entry to compare.\n * @param right - The second path or directory entry to compare.\n * @returns A negative number when `left` sorts first, positive when `right` does.\n *\n * @remarks\n * Revisions are numbers, so `chromium-1200` outranks `chromium-999` despite sorting below it\n * lexically. A path carrying no revision falls back to descending name order.\n *\n * @example\n * ```ts\n * ['chromium-999', 'chromium-1200'].sort(compareRevisions)\n * ```\n */\nexport function compareRevisions(left: string, right: string): number {\n\tconst leftRevision = CHROMIUM_REVISION_PATTERN.exec(left)?.[1]\n\tconst rightRevision = CHROMIUM_REVISION_PATTERN.exec(right)?.[1]\n\tif (leftRevision === undefined || rightRevision === undefined) return right.localeCompare(left)\n\treturn Number(rightRevision) - Number(leftRevision)\n}\n\n/**\n * Reads the executable path of Playwright's pinned Chromium revision.\n *\n * @returns The pinned executable path, or `undefined` when this platform has none.\n *\n * @remarks\n * Playwright throws rather than returning a path when the current platform carries no initialized\n * executable, and an unguarded call would fail configuration evaluation for every project.\n *\n * @example\n * ```ts\n * resolvePinnedBrowser()\n * ```\n */\nexport function resolvePinnedBrowser(): string | undefined {\n\ttry {\n\t\tconst pinned = chromium.executablePath()\n\t\treturn pinned.length === 0 ? undefined : pinned\n\t} catch {\n\t\treturn undefined\n\t}\n}\n\n/**\n * Resolves a launchable Playwright-managed Chromium executable: the pinned revision when installed,\n * otherwise a `chromium` / `chromium.exe` alias or any other `chromium-*` revision under the same\n * Playwright browsers directory. A pinned-revision miss is not Chromium absence — managed\n * containers ship one usable build, often behind a revision-agnostic alias, for many Playwright\n * versions.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision.\n * @returns The managed executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveManagedBrowser('/root/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome')\n * ```\n */\nexport function resolveManagedBrowser(pinned: string): string | undefined {\n\tif (isBrowserExecutable(pinned)) return pinned\n\tlet revisionRoot = dirname(pinned)\n\tfor (;;) {\n\t\tif (CHROMIUM_ENTRY_PATTERN.test(basename(revisionRoot))) break\n\t\tconst parent = dirname(revisionRoot)\n\t\tif (parent === revisionRoot) return undefined\n\t\trevisionRoot = parent\n\t}\n\tconst browsersRoot = dirname(revisionRoot)\n\tfor (const alias of ['chromium', 'chromium.exe']) {\n\t\tconst candidate = resolvePath(browsersRoot, alias)\n\t\tif (isBrowserExecutable(candidate)) return candidate\n\t}\n\tlet entries: readonly string[]\n\ttry {\n\t\tentries = readdirSync(browsersRoot)\n\t} catch {\n\t\treturn undefined\n\t}\n\tconst revisions = entries\n\t\t.filter((entry) => CHROMIUM_ENTRY_PATTERN.test(entry))\n\t\t.sort(compareRevisions)\n\tfor (const revision of revisions) {\n\t\tfor (const layout of CHROMIUM_LAYOUTS) {\n\t\t\tconst candidate = resolvePath(browsersRoot, revision, layout)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the Chromium a managed Linux container bundles outside the Playwright cache.\n *\n * @param platform - The Node platform the container runs on.\n * @param root - The bundled browsers directory to search.\n * @returns The highest matching executable path, or `undefined` when none is executable.\n *\n * @example\n * ```ts\n * resolveBundledBrowser('linux', BUNDLED_BROWSERS_ROOT)\n * ```\n */\nexport function resolveBundledBrowser(platform: NodeJS.Platform, root: string): string | undefined {\n\tif (platform !== 'linux') return undefined\n\tfor (const layout of BUNDLED_CHROMIUM_LAYOUTS) {\n\t\tlet matches: readonly string[]\n\t\ttry {\n\t\t\tmatches = globSync(layout, { cwd: root })\n\t\t} catch {\n\t\t\treturn undefined\n\t\t}\n\t\tfor (const match of [...matches].sort(compareRevisions)) {\n\t\t\tconst candidate = resolvePath(root, match)\n\t\t\tif (isBrowserExecutable(candidate)) return candidate\n\t\t}\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves the first installed stable system Chromium channel.\n *\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying Windows installation roots.\n * @returns `chrome`, then `msedge`, or `undefined` when neither is executable.\n *\n * @example\n * ```ts\n * resolveSystemBrowser(process.platform, process.env)\n * ```\n */\nexport function resolveSystemBrowser(\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n): string | undefined {\n\tif (platform !== 'linux' && platform !== 'darwin' && platform !== 'win32') return undefined\n\tconst roots = new Set<string>()\n\tif (platform === 'win32') {\n\t\tfor (const root of [\n\t\t\tenvironment.LOCALAPPDATA,\n\t\t\tenvironment.PROGRAMFILES,\n\t\t\tenvironment['PROGRAMFILES(X86)'],\n\t\t]) {\n\t\t\tif (root !== undefined && root.length > 0) roots.add(root)\n\t\t}\n\t\tconst homeDrive = environment.HOMEDRIVE\n\t\tif (homeDrive !== undefined && homeDrive.length > 0) {\n\t\t\troots.add(join(homeDrive, 'Program Files'))\n\t\t\troots.add(join(homeDrive, 'Program Files (x86)'))\n\t\t}\n\t}\n\tfor (const browser of SYSTEM_BROWSER_CHANNELS) {\n\t\tif (platform === 'win32') {\n\t\t\tfor (const root of roots) {\n\t\t\t\tif (isBrowserExecutable(join(root, ...browser.layouts.win32))) return browser.channel\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif (isBrowserExecutable(browser.layouts[platform])) return browser.channel\n\t}\n\treturn undefined\n}\n\n/**\n * Resolves Playwright provider options for Chromium on this host.\n *\n * @param pinned - The executable path for Playwright's pinned Chromium revision, when it has one.\n * @param platform - The Node platform whose standard layouts this call probes.\n * @param environment - The process environment supplying operator overrides and Windows roots.\n * @param root - The managed-container bundled browsers directory to search.\n * @returns Provider options naming an executable, a WebSocket endpoint, or a channel.\n *\n * @remarks\n * Precedence, most important first: `PLAYWRIGHT_EXECUTABLE_PATH`, `PLAYWRIGHT_WS_ENDPOINT`,\n * `PLAYWRIGHT_CHANNEL`, the managed Playwright Chromium, the container's bundled Chromium, a\n * verified system channel, then the platform default channel. An operator override outranks\n * discovery and is returned exactly as given: none of those environment values is checked\n * against the filesystem, because verifying an override would defeat the override. The pinned\n * managed revision outranks anything found on the host because it is deterministic. The installed\n * pinned revision returns empty options unless `PLAYWRIGHT_SCROLLBARS=classic` is set. Only a\n * discovered system channel is verified before it is named. The platform default is unverified\n * as well and exists only as a last resort: Windows takes `msedge`, which ships with the OS and\n * never collides with a foreground Chrome.\n *\n * Set `PLAYWRIGHT_SCROLLBARS=classic` only for runs that measure scrollbar compensation, never\n * for a standing gate. Every Chromium launch in that run omits Playwright's `--hide-scrollbars`\n * default argument so classic scrollbars can take layout space in every case. An empty or unset\n * value preserves the launch defaults; any other value throws an `Error`. Pairing `classic`\n * with `PLAYWRIGHT_WS_ENDPOINT` throws an `Error`, even with an executable override, because the\n * server owns the launch.\n *\n * The resolver and the gate cover Chromium alone. Reopen engine selection when another\n * Playwright engine is installed and launches on the host with a `captureFrame` reading\n * back at its declared size, or when a journey or style divergence is recorded.\n *\n * @example\n * ```ts\n * resolveBrowser(resolvePinnedBrowser(), process.platform, process.env)\n * ```\n */\nexport function resolveBrowser(\n\tpinned: string | undefined,\n\tplatform: NodeJS.Platform,\n\tenvironment: NodeJS.ProcessEnv,\n\troot: string = BUNDLED_BROWSERS_ROOT,\n): PlaywrightProviderOptions {\n\tconst scrollbars = environment.PLAYWRIGHT_SCROLLBARS\n\tif (scrollbars !== undefined && scrollbars.length > 0 && scrollbars !== 'classic') {\n\t\tthrow new Error('PLAYWRIGHT_SCROLLBARS must be classic or empty')\n\t}\n\tconst endpoint = environment.PLAYWRIGHT_WS_ENDPOINT\n\tif (scrollbars === 'classic' && endpoint !== undefined && endpoint.length > 0) {\n\t\tthrow new Error('PLAYWRIGHT_SCROLLBARS=classic cannot be used with PLAYWRIGHT_WS_ENDPOINT')\n\t}\n\tconst launch: PlaywrightProviderOptions['launchOptions'] =\n\t\tscrollbars === 'classic' ? { ignoreDefaultArgs: ['--hide-scrollbars'] } : {}\n\tconst executable = environment.PLAYWRIGHT_EXECUTABLE_PATH\n\tif (executable !== undefined && executable.length > 0) {\n\t\treturn { launchOptions: { executablePath: executable, ...launch } }\n\t}\n\tif (endpoint !== undefined && endpoint.length > 0) {\n\t\treturn { connectOptions: { wsEndpoint: endpoint } }\n\t}\n\tconst requested = environment.PLAYWRIGHT_CHANNEL\n\tif (requested !== undefined && requested.length > 0) {\n\t\treturn { launchOptions: { channel: requested, ...launch } }\n\t}\n\tconst managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)\n\tif (managed !== undefined) {\n\t\tif (managed === pinned) return scrollbars === 'classic' ? { launchOptions: launch } : {}\n\t\treturn { launchOptions: { executablePath: managed, ...launch } }\n\t}\n\tconst bundled = resolveBundledBrowser(platform, root)\n\tif (bundled !== undefined) return { launchOptions: { executablePath: bundled, ...launch } }\n\tconst fallback = platform === 'win32' ? 'msedge' : 'chrome'\n\treturn {\n\t\tlaunchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback, ...launch },\n\t}\n}\n";
       }>;
 
       /** Names the official-tooling drift proof whose presence makes a workspace `conformance`. */

package/dist/src/core/index.js

@@ -3,7 +3,7 @@ import { fillTemplate } from "@orkestrel/template";
 import { Emitter } from "@orkestrel/emitter";
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.93",
+	version: "0.0.94",
 	description: "Scaffold workspaces with commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -2170,11 +2170,18 @@ export function resolveSystemBrowser(
  * discovery and is returned exactly as given: none of those environment values is checked
  * against the filesystem, because verifying an override would defeat the override. The pinned
  * managed revision outranks anything found on the host because it is deterministic. The installed
- * pinned revision returns empty options so Playwright keeps its own default launch semantics. Only
- * a discovered system channel is verified before it is named. The platform default is unverified
+ * pinned revision returns empty options unless \`PLAYWRIGHT_SCROLLBARS=classic\` is set. Only a
+ * discovered system channel is verified before it is named. The platform default is unverified
  * as well and exists only as a last resort: Windows takes \`msedge\`, which ships with the OS and
  * never collides with a foreground Chrome.
  *
+ * Set \`PLAYWRIGHT_SCROLLBARS=classic\` only for runs that measure scrollbar compensation, never
+ * for a standing gate. Every Chromium launch in that run omits Playwright's \`--hide-scrollbars\`
+ * default argument so classic scrollbars can take layout space in every case. An empty or unset
+ * value preserves the launch defaults; any other value throws an \`Error\`. Pairing \`classic\`
+ * with \`PLAYWRIGHT_WS_ENDPOINT\` throws an \`Error\`, even with an executable override, because the
+ * server owns the launch.
+ *
  * The resolver and the gate cover Chromium alone. Reopen engine selection when another
  * Playwright engine is installed and launches on the host with a \`captureFrame\` reading
  * back at its declared size, or when a journey or style divergence is recorded.
@@ -2190,26 +2197,38 @@ export function resolveBrowser(
 	environment: NodeJS.ProcessEnv,
 	root: string = BUNDLED_BROWSERS_ROOT,
 ): PlaywrightProviderOptions {
+	const scrollbars = environment.PLAYWRIGHT_SCROLLBARS
+	if (scrollbars !== undefined && scrollbars.length > 0 && scrollbars !== 'classic') {
+		throw new Error('PLAYWRIGHT_SCROLLBARS must be classic or empty')
+	}
+	const endpoint = environment.PLAYWRIGHT_WS_ENDPOINT
+	if (scrollbars === 'classic' && endpoint !== undefined && endpoint.length > 0) {
+		throw new Error('PLAYWRIGHT_SCROLLBARS=classic cannot be used with PLAYWRIGHT_WS_ENDPOINT')
+	}
+	const launch: PlaywrightProviderOptions['launchOptions'] =
+		scrollbars === 'classic' ? { ignoreDefaultArgs: ['--hide-scrollbars'] } : {}
 	const executable = environment.PLAYWRIGHT_EXECUTABLE_PATH
 	if (executable !== undefined && executable.length > 0) {
-		return { launchOptions: { executablePath: executable } }
+		return { launchOptions: { executablePath: executable, ...launch } }
 	}
-	const endpoint = environment.PLAYWRIGHT_WS_ENDPOINT
 	if (endpoint !== undefined && endpoint.length > 0) {
 		return { connectOptions: { wsEndpoint: endpoint } }
 	}
 	const requested = environment.PLAYWRIGHT_CHANNEL
 	if (requested !== undefined && requested.length > 0) {
-		return { launchOptions: { channel: requested } }
+		return { launchOptions: { channel: requested, ...launch } }
 	}
 	const managed = pinned === undefined ? undefined : resolveManagedBrowser(pinned)
 	if (managed !== undefined) {
-		return managed === pinned ? {} : { launchOptions: { executablePath: managed } }
+		if (managed === pinned) return scrollbars === 'classic' ? { launchOptions: launch } : {}
+		return { launchOptions: { executablePath: managed, ...launch } }
 	}
 	const bundled = resolveBundledBrowser(platform, root)
-	if (bundled !== undefined) return { launchOptions: { executablePath: bundled } }
+	if (bundled !== undefined) return { launchOptions: { executablePath: bundled, ...launch } }
 	const fallback = platform === 'win32' ? 'msedge' : 'chrome'
-	return { launchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback } }
+	return {
+		launchOptions: { channel: resolveSystemBrowser(platform, environment) ?? fallback, ...launch },
+	}
 }
 `
 });