@ultimat3/cli 21.0.0 → 22.1.0

package/src/index.ts

@@ -2,226 +2,66 @@
 // on these, and a barrel that re-exports everything would make every internal a compatibility
 // promise.
 
+// The CLI's own codes and titles, registered for every process that imports this barrel — the
+// gate's registry check (`scripts/verify.ts` → `registeredErrorCodes`) reads the registry, and the
+// command modules that used to import `error-codes.ts` on the way load lazily since 22.0.0.
+import './error-codes';
+
 /** The app's own API over HTTP — the one table `x dev` and a container both mount. */
 export { apiRoutes } from './api-routes';
-export type { BoundaryCode, SourceFile } from './app-boundaries';
+export type { SourceFile } from './app-boundaries';
 export {
   appImportGraph,
-  BOUNDARY_CODES,
   checkAppBoundaries,
-  checkImportRules,
   readAppSources,
   resolveSpecifier,
   scanRuntimeImports,
 } from './app-boundaries';
-export type { LoadedApp } from './app-load';
-export { loadApp, resetAppLoad } from './app-load';
-export type { AppManifest } from './app-manifest';
-export { appManifest, policyFacts, readAppManifest, writeAppManifest } from './app-manifest';
-export { OPENAPI_FILE, openApiJson } from './app-openapi';
-export type { AppRoot } from './app-root';
-export { findAppRoot, requireAppRoot, requireBunVersion, versionAtLeast } from './app-root';
-export type { BoundaryCut, BoundarySplit } from './boundary-cuts';
-export { planBoundaryCuts } from './boundary-cuts';
-export type { BuildStats, RouteStats } from './budgets';
-export {
-  BUILD_STATS_FILE,
-  checkBudgets,
-  FRAMEWORK_INLINE_SCRIPTS,
-  FRAMEWORK_SCRIPTS,
-  readBuildStats,
-} from './budgets';
-// The raw-CDP browser the driver above runs on. `openE2eBrowserIfAvailable()` is what an app's
-// test preload calls: it answers `undefined` on a machine with no Chrome, so the browser-backed
-// suite SKIPS rather than turning a gate red for a reason unrelated to the change.
-export type { E2eBrowser, OpenE2eBrowserOptions } from './cdp-browser';
-export {
-  DEFAULT_CDP_TIMEOUT_MS,
-  openE2eBrowser,
-  openE2eBrowserIfAvailable,
-} from './cdp-browser';
-export type { CdpConnection, CdpConnectionOptions, CdpResult } from './cdp-connection';
-export { cdpConnect } from './cdp-connection';
-export type { CdpE2eTabOptions, E2eTab } from './cdp-e2e-page';
-export { cdpE2eTab } from './cdp-e2e-page';
-export type { CdpE2eSessionOptions, E2eSession } from './cdp-e2e-session';
-export { cdpE2eSession } from './cdp-e2e-session';
-export {
-  CdpBrowserMissingError,
-  CdpCallFailedError,
-  CdpLaunchFailedError,
-  CdpTimeoutError,
-} from './cdp-errors';
-export type { LaunchedBrowser, LaunchOptions } from './cdp-launch';
-export {
-  CHROME_CANDIDATES,
-  CHROME_PATH_ENV,
-  findChrome,
-  launchChrome,
-  launchFoundChrome,
-} from './cdp-launch';
-export type { BuildTarget } from './cmd-build';
-export {
-  argsFor,
-  BUILD_ENTRY,
-  BUILD_TARGETS,
-  buildCommand,
-  readTarget,
-  requireEntry,
-} from './cmd-build';
+export { loadApp } from './app-load';
+export { appManifest, writeAppManifest } from './app-manifest';
+export { requireAppRoot } from './app-root';
+export type { RouteStats } from './budgets';
+export { checkBudgets, FRAMEWORK_INLINE_SCRIPTS, FRAMEWORK_SCRIPTS } from './budgets';
+export { BUILD_ENTRY, BUILD_TARGETS, readTarget } from './cmd-build';
 export { dbCommand } from './cmd-db';
-export { runBranchCommand } from './cmd-db-branch';
-export type { DeployPlan } from './cmd-deploy';
-export { deployCommand, planDeploy } from './cmd-deploy';
-export type { DevServer, StartDevOptions } from './cmd-dev';
-export { devCommand, startDev } from './cmd-dev';
-export type { DoctorProbe, EmbeddedDatabase } from './cmd-doctor';
-export {
-  doctorCommand,
-  ENV_DEVELOPMENT,
-  embeddedDatabaseFinding,
-  probeFor,
-  runDoctor,
-} from './cmd-doctor';
-export { ERRORS_SUBCOMMANDS, errorsCommand } from './cmd-errors';
-export { FIX_SUBCOMMANDS, fixCommand } from './cmd-fix';
+export { planDeploy } from './cmd-deploy';
+export { startDev } from './cmd-dev';
+export type { DoctorProbe } from './cmd-doctor';
 export type { GenerateOptions, Generator } from './cmd-generate';
-export { GENERATORS, generate, generateCommand, writeFiles } from './cmd-generate';
-export { createHelpCommand, createVersionCommand, renderHelp } from './cmd-help';
-export { buildDrainTarget, JOBS_SUBCOMMANDS, jobsCommand } from './cmd-jobs';
-export { manifestCommand } from './cmd-manifest';
-export type { McpHttpServer } from './cmd-mcp';
-export { mcpCommand, startMcpHttp } from './cmd-mcp';
-export type { NewAppOptions, WrittenApp } from './cmd-new';
+export { GENERATORS, generate, writeFiles } from './cmd-generate';
+export { JOBS_SUBCOMMANDS } from './cmd-jobs';
 export { newCommand, planNewApp, writeNewApp } from './cmd-new';
-export type { PlannedCommand, PlannedSubcommand } from './cmd-planned';
-export {
-  PLANNED_COMMANDS,
-  PLANNED_SUBCOMMANDS,
-  plannedCommands,
-  plannedSubcommand,
-} from './cmd-planned';
+export { PLANNED_COMMANDS, PLANNED_SUBCOMMANDS, plannedSubcommand } from './cmd-planned';
 // `shotCommand`, `prCommand` and `ciCommand` are deliberately NOT re-exported here. They reach
 // `x` through `registry.ts`, which is the only thing that makes a command exist — and the barrel
-// is the surface an APP imports. Exporting them puts `cmd-shot.ts` in the module graph of every
-// app that imports `@ultimat3/cli`, which then has to resolve `@ultimat3/scraping` — a browser
-// driver it never uses. Measured: it reds `tsc -b` on `dummy/social-media-clone` with five
-// TS2307s in files that app never calls. The app path does not pay for the tool path.
-export { actionsCommand, entitiesCommand, queriesCommand } from './cmd-registries';
-export { renderRouteTable, routesCommand } from './cmd-routes';
-export { testCommand } from './cmd-test';
+// is the surface an APP imports. Exporting them would put the browser driver and the GitHub client
+// in the module graph of every app that imports `@ultimat3/cli`, for tools it never calls. The app
+// path does not pay for the tool path.
+export { renderRouteTable } from './cmd-routes';
 export { runVerify, VERIFY_STEPS, verifyCommand, verifyStepNames } from './cmd-verify';
-export type { CliCommand, CommandContext } from './command';
+export type { CliCommand } from './command';
 export { failed, ok } from './command';
-export { acceptCreatedTables, createdTables } from './db-accept-created';
-export type { BranchRow, BranchSubcommand } from './db-branch';
-export {
-  BRANCH_SUBCOMMANDS,
-  branchDatabaseName,
-  branchNameOf,
-  isBranchSubcommand,
-  pgliteBranchName,
-  previewUrl,
-} from './db-branch';
-export type { GeneratedFiles, GenerateMigrationOptions, GenerateOutcome } from './db-generate';
-export { generateAppMigration, migrationSql } from './db-generate';
-export type { SubscribingQuery } from './db-subscribes';
+export { acceptCreatedTables } from './db-accept-created';
+export type { BranchRow } from './db-branch';
+export { BRANCH_SUBCOMMANDS, branchDatabaseName, branchNameOf } from './db-branch';
+export type { GeneratedFiles } from './db-generate';
+export { generateAppMigration } from './db-generate';
 export { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
-export type { AssetRoutesOptions } from './dev-assets';
-export {
-  assetRoutes,
-  MEDIA_BASE_PATH,
-} from './dev-assets';
-export type { DevDashboardInput, DevStatus } from './dev-dashboard';
-export { devDashboardRoutes, devPanels, devSources } from './dev-dashboard';
-export { devHooks } from './dev-hooks';
-export type { DevDbClient, RunningQueue } from './dev-queue';
-export { startQueue } from './dev-queue';
-export type { DevRenderOptions, DevRouteData } from './dev-render';
-export { appRoutes, routeDocument } from './dev-render';
-export type { RunningRoles, StartRolesOptions, WebBinding } from './dev-roles';
-export { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
-export type { RunningServices } from './dev-runtime';
-export { startServices } from './dev-runtime';
-export type { DevServices, ServiceBinding } from './dev-services';
-export { describeServices, resolveServices } from './dev-services';
-export type { DispatchOptions } from './dispatch';
 export { dispatch } from './dispatch';
-export type { DeclaredEntityCount, HashReconciliation } from './drift';
-export {
-  checkSourceDrift,
-  reconcileSchemaHash,
-  recordedHashes,
-  schemaHash,
-  writeSchemaHash,
-} from './drift';
-// The browser-backed e2e driver. `installE2eDriver` is the ONE entry point an app's test preload
-// calls; everything below it is exported because the adapter's own pieces are what a driver author
-// re-uses, and a deep import into `src/` would make each of them a compatibility promise anyway.
-export type { E2eApp, E2eAppMode, StartE2eAppOptions } from './e2e-app';
-export { startE2eApp } from './e2e-app';
-export { e2eApp, e2eBaseUrl, e2eBrowser } from './e2e-browser-handle';
-export type { E2eDriverOptions } from './e2e-driver';
-export { e2eFixtures, installE2eDriver } from './e2e-driver';
-export {
-  E2eAppFailedError,
-  E2eEvaluateCapturedError,
-  E2eEvaluateThrewError,
-  E2eEvaluateUnsupportedError,
-  E2eLocatorAmbiguousError,
-  E2eLocatorEmptyError,
-  E2eServiceWorkerAbsentError,
-} from './e2e-errors';
-export type { EvaluablePage } from './e2e-evaluate';
-export { closureSource, evaluateClosure, evaluateExpression } from './e2e-evaluate';
-export type { LocatablePage } from './e2e-locator';
-export { e2eLocator, resetLocatorMarks } from './e2e-locator';
-export type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
-export { DEFAULT_E2E_TIMEOUT_MS, DEFAULT_SERVICE_WORKER_TIMEOUT_MS, e2ePage } from './e2e-page';
-export type { E2eResolution, E2eSelection } from './e2e-selection';
-export {
-  MARK_ATTRIBUTE,
-  markSelector,
-  selectionCall,
-  selectionExpression,
-  unmarkExpression,
-} from './e2e-selection';
-export type { ErrorCatalog } from './error-catalog';
-export {
-  buildErrorCatalog,
-  CATALOG_OPTIONAL_HOSTS,
-  CATALOG_PACKAGES,
-  loadErrorCatalog,
-  registeredErrorCodes,
-  resetErrorCatalog,
-} from './error-catalog';
+export { checkSourceDrift, reconcileSchemaHash, writeSchemaHash } from './drift';
+export { registeredErrorCodes } from './error-catalog';
 export type { CliErrorCode } from './error-codes';
-export { CLI_ERROR_CODES, CLI_ERROR_TITLES } from './error-codes';
-export type { ErrorFixReport } from './error-contract';
 export {
   BANNED_PHRASES,
   COMMAND_TOKENS,
   checkErrorCodeDocs,
   checkErrorCodeRegistry,
-  checkErrorCodeResolution,
   checkErrorFixes,
-  checkErrorFixReport,
   collectDeclaredCodes,
   documentedCodes,
   fixProblem,
-  liveCodes,
-  RESERVED_HEADING,
   staticFix,
 } from './error-contract';
-export type { CodeFixIndex, CodeFixScan } from './error-fixes';
-export {
-  codeFixes,
-  codeFixScan,
-  loadCodeFixes,
-  resetCodeFixes,
-  scanScopeFixes,
-} from './error-fixes';
-export type { CodeUse } from './error-unthrown';
 export { checkErrorCodesThrown } from './error-unthrown';
 export {
   BadFlagError,
@@ -244,14 +84,7 @@ export {
 } from './errors';
 export type { ExecOptions, ExecResult, Runner } from './exec';
 export { exec, execOutput } from './exec';
-export {
-  defaultFavicon,
-  FAVICON_PATH,
-  FAVICON_SOURCE,
-  faviconResponse,
-  faviconRoute,
-} from './favicon';
-export type { CitationFault, CitationRules, CommandCatalog, FixCitation } from './fix-command';
+export type { CitationFault, CommandCatalog, FixCitation } from './fix-command';
 export {
   citationFault,
   citationProblem,
@@ -259,193 +92,79 @@ export {
   fixCitations,
   loadCommandCatalog,
 } from './fix-command';
-export type { HelperResolver } from './fix-imports';
-export { candidatePaths, createHelperResolver, scanImports } from './fix-imports';
-export {
-  CITED_FILE_EXTENSIONS,
-  citedPathProblem,
-  FILE_TOKEN_PATTERN,
-  pathCitations,
-} from './fix-path';
-export type { FixHelper, FixScan } from './fix-scan';
-export { scanFixes, scanFixHelpers, scanFixSites } from './fix-scan';
-export type { DeclaredFlag } from './flag-reads';
-export { checkFlagReads, declaredFlags, readsFlag } from './flag-reads';
-export type { FrameworkSchema, SchemaExecutor } from './framework-schema';
+export { candidatePaths, scanImports } from './fix-imports';
+export type { FixScan } from './fix-scan';
+export { scanFixes } from './fix-scan';
+export { checkFlagReads } from './flag-reads';
 // The framework's own tables, as data. Exported so `scripts/` can read the applier's list without
 // re-deriving it — the shape a ratchet over declared-but-never-applied DDL needs.
-export {
-  applyFrameworkSchema,
-  FRAMEWORK_SCHEMA,
-  frameworkTableNames,
-  schemaStatements,
-} from './framework-schema';
+export { FRAMEWORK_SCHEMA } from './framework-schema';
 export type { Guard } from './guards';
-export { findingProblem, GUARD_DIR, guardFindings, guardPaths } from './guards';
-export {
-  hasSourceIcon,
-  ICON_BASE_PATH,
-  ICON_SOURCE,
-  iconPlan,
-  iconRenderer,
-} from './icon-assets';
+export { findingProblem, guardFindings, guardPaths } from './guards';
+export { ICON_BASE_PATH, ICON_SOURCE } from './icon-assets';
 // The island bundler, and only its entry point. An island is the one module Ultimate ships to a
 // browser, so an app has to be able to build one to TEST one — `mountIsland` from
 // `@ultimat3/testing` takes this function as its `build` parameter (issue #260). `discoverIslands`,
 // `islandBundle`, `writeIslands`, `ISLAND_BASE_PATH` and `ISLAND_GLOB` stay internal: they are
 // `x build`'s and `x dev`'s wiring, and every name here is a semver promise forever.
-export type { IslandBundle, IslandChunk } from './island-bundle';
-export { buildIslands, clearIslandChunkCache } from './island-bundle';
-export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
-export { drainJobs } from './jobs-drain';
-export type { JobsListFilter, JobsListResult } from './jobs-report';
-export { JOB_STATES, listJobs, retryJob, showJob } from './jobs-report';
+export type { IslandChunk } from './island-bundle';
+export { buildIslands } from './island-bundle';
+export { JOB_STATES } from './jobs-report';
 export { renderJobTable } from './jobs-table';
-export type { CliMcpServer, DevHostInput } from './mcp-host';
-export { createDevMcpServer, DEV_TOOL_SCOPES, localCaller } from './mcp-host';
-export { messageKeys, msg } from './messages';
-export type { MetricsEndpoint, MetricsEndpointOptions } from './metrics-endpoint';
+export { msg } from './messages';
 export { DEFAULT_METRICS_PORT, startMetricsEndpoint } from './metrics-endpoint';
-export {
-  hashFileName,
-  MIGRATIONS_DIR,
-  migrationName,
-  parseMigrationSql,
-  readMigrations,
-  snapshotFileName,
-} from './migrations';
-export type { CommandResult, Finding, JsonValue, StepResult } from './output';
-export {
-  exitCodeFor,
-  findingFrom,
-  isUltimateErrorShape,
-  render,
-  renderFinding,
-  renderHuman,
-  renderJson,
-  renderUltimateError,
-} from './output';
+export { parseMigrationSql, readMigrations } from './migrations';
+export type { CommandResult, Finding, JsonValue } from './output';
+export { exitCodeFor, findingFrom, render, renderFinding, renderHuman } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
-export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
+export type { PrerenderedPage, PrerenderReport } from './prerender';
 export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export type { PwaArtifacts } from './pwa-artifacts';
-export {
-  loadPwaArtifacts,
-  pwaManifestRoute,
-  WEB_MANIFEST_PATH,
-  writePwaIcons,
-} from './pwa-artifacts';
-export { COMMANDS, cliVersion, commandFor, SPECS } from './registry';
-export type { SchemaDifference, SchemaDirection, SchemaPart } from './schema-diff';
-export { diffDeclaredSchema } from './schema-diff';
+export { loadPwaArtifacts } from './pwa-artifacts';
+export { COMMANDS, cliVersion, SPECS } from './registry';
+export type { RunningRoles, WebBinding } from './role-start';
+export { DEV_BINDING, DEV_ROLES, startRoles } from './role-start';
+export { assetRoutes, MEDIA_BASE_PATH } from './runtime-assets';
+export { resolveServices } from './runtime-bindings';
+export { devHooks } from './runtime-hooks';
+export { startQueue } from './runtime-queue';
+export { appRoutes, routeDocument } from './runtime-render';
+export type { RunningServices } from './runtime-services';
+export { startServices } from './runtime-services';
 // The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
-export type { DeclaredEntities } from './schema-drift';
 export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
 export { FrameworkSchemaFailedError } from './schema-errors';
-export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
+export type { MigratedApp, ServeOptions } from './serve';
 export {
   CONTAINER_BINDING,
   DEFAULT_PORT,
-  metricsPortFromEnv,
-  portFromEnv,
   roleFromEnv,
   runMigrations,
   runRole,
   serveApp,
 } from './serve';
 export { quoteArg } from './shell-quote';
-export {
-  eachSourceFile,
-  isGenerated,
-  isTest,
-  isVendored,
-  SOURCE_GLOBS,
-} from './source-files';
-export type {
-  EmittedPage,
-  RouteFacts,
-  SkippedRoute,
-  SkipReason,
-  StaticReport,
-  UnmeasuredRoute,
-} from './static-report';
-export {
-  parseStaticReport,
-  readStaticReport,
-  removeStaticReport,
-  renderStaticReport,
-  SKIP_REASONS,
-  STATIC_REPORT_FILE,
-  skippedRoute,
-  skipReasonFor,
-  writeStaticReport,
-} from './static-report';
-export type { StyleBundle, StyleChunk } from './style-bundle';
-export { STYLE_BASE_PATH, styleBundle } from './style-bundle';
-export type { TestCounts } from './test-counts';
-export { countsOf } from './test-counts';
-export type { TestFile } from './test-select';
-export { belongsToType, discoverTests, sampleFiles } from './test-select';
-export type { ReproduceOptions, RunShardsOptions } from './test-shards';
-export { filesIn, reproduceFor, runShards, testArgs } from './test-shards';
-export { availableCpus, defaultWorkers, WORKER_CEILING } from './test-workers';
-export type {
-  CodeFixSite,
-  CodeScan,
-  CodeSite,
-  FixSite,
-  SourceSite,
-  UnresolvedCodeSite,
-} from './ts-scan';
-export {
-  isCodeRegistry,
-  maskLiterals,
-  scanBorrowedCodes,
-  scanCodeDeclarations,
-  scanCodeFixSites,
-  scanCodes,
-  stripComments,
-} from './ts-scan';
+export { eachSourceFile, isGenerated, isTest, SOURCE_GLOBS } from './source-files';
+export type { SkippedRoute, StaticReport } from './static-report';
+export { parseStaticReport } from './static-report';
+export { filesIn, testArgs } from './test-shards';
+export { defaultWorkers } from './test-workers';
+export { scanCodeDeclarations, scanCodeFixSites, scanCodes } from './ts-scan';
 // The one spelling rule for a `references` entry. Exported because the two gate scripts ask the
 // same question this package's `package-shape` step does, and three answers is a duplicate entry.
 export { normalizeReferencePath } from './tsconfig-references';
-export type { VerifyFloor } from './verify-floor';
-export {
-  floorProblemFindings,
-  floorRequires,
-  parseVerifyFloor,
-  readVerifyFloor,
-  skippedSuiteFinding,
-  VERIFY_FLOOR_FILE,
-  vanishedSuiteFinding,
-} from './verify-floor';
-export type {
-  HostCheck,
-  StepOutcome,
-  VerifyContext,
-  VerifyStep,
-  VerifyStepName,
-} from './verify-step';
+export { readVerifyFloor, skippedSuiteFinding, VERIFY_FLOOR_FILE } from './verify-floor';
+export type { HostCheck, StepOutcome, VerifyStep, VerifyStepName } from './verify-step';
 export { VERIFY_STEP_NAMES } from './verify-step';
 export type { TestType } from './verify-tests';
-export { TEST_STEPS, TEST_TYPES, testStepCommand, typeFiltersOf } from './verify-tests';
-export type { ManifestFacts, PackageShapeOptions } from './workspace-checks';
+export { TEST_TYPES } from './verify-tests';
 export {
   checkFileSizes,
   checkLockstep,
   checkPackageShape,
-  frameworkDepsOf,
-  hasWorkspacePackages,
   LINE_CEILING,
   PACKAGE_FILES,
   SEMVER,
-  workspacePackages,
 } from './workspace-checks';
-export type { WorkspaceNode, WorkspaceScan } from './workspace-graph';
-// The graph itself, not just the gate's verdict on it: issue #239's complaint is that a
-// scaffolded repo's dependency graph exists only inside `tsc`, so an app's own tooling has
-// nothing to read. `checkWorkspaceDependencies` stays internal — it is reached through
-// `x verify`, which is the one way a rule is enforced here.
-export { readWorkspaceGraph, scanWorkspaces } from './workspace-graph';
 export { writeErrorLine, writeLine } from './write-line';

package/src/invocation-flags.ts

@@ -0,0 +1,26 @@
+// The flags a caller set, spelled so pasting them reproduces the same run. A `fix:` that re-runs a
+// command with `--force` and loses `--feature` or `--dir` writes somewhere the caller never asked
+// for — `x g`'s conflict fix wrote a second slice, `x new`'s a second app in the cwd.
+
+import type { CommandSpec, ParsedArgs } from './parse';
+import { quoteArg } from './shell-quote';
+
+/** Never reproduced: the fix adds its own `--force`, and output flags do not change what runs. */
+const NOT_REPRODUCED = new Set(['force', 'dry-run', 'json', 'help', 'verbose', 'cwd']);
+
+/**
+ * Every declared flag whose value differs from its default, in the spec's order: a string as
+ * `--name <quoted>`, a boolean as `--name` or `--no-name`. A default is nobody's request, so it is
+ * left for the default to supply again.
+ */
+export function reproducedFlags(spec: CommandSpec, args: ParsedArgs): readonly string[] {
+  const out: string[] = [];
+  for (const flag of spec.flags ?? []) {
+    if (NOT_REPRODUCED.has(flag.name)) continue;
+    const value = args.flags.get(flag.name);
+    if (value === undefined || value === flag.default) continue;
+    if (typeof value === 'string') out.push(`--${flag.name}`, quoteArg(value));
+    else out.push(value ? `--${flag.name}` : `--no-${flag.name}`);
+  }
+  return out;
+}

package/src/island-bundle.ts

@@ -85,7 +85,12 @@ async function buildOne(root: string, file: string): Promise<IslandChunk> {
   // the real path here and the `success` test below is the belt for a future default.
   // Only an island whose own graph reaches `@ultimat3/realtime` is wrapped (`island-realtime.ts`);
   // every other one is built from its own file, byte for byte what it was.
-  const realtime = await reachesRealtime(root, file);
+  // Inside the refusal too: the realtime probe PARSES the island's graph, and a file that will not
+  // parse rejected with a raw `AggregateError: Failed to scan imports` — out of the web boot, with
+  // no code, no file and no fix — before `Bun.build` ever ran to raise the one below.
+  const realtime = await reachesRealtime(root, file).catch((error: unknown) => {
+    throw new IslandBuildFailedError({ file, logs: describeBuildError(error) });
+  });
   let built: Awaited<ReturnType<typeof Bun.build>>;
   try {
     built = await Bun.build({

package/src/island-capture.ts

@@ -5,10 +5,10 @@
 // why: no Bun native joins a path; `Bun.write` takes one already joined.
 import { join } from 'node:path';
 import { finiteCount } from '@ultimat3/core';
-import type { CaptureClip, ScrapeDriver, ScrapeSession } from '@ultimat3/scraping';
-import { systemScrapeClock } from '@ultimat3/scraping';
 import type { IslandShotTarget, IslandViewport } from '@ultimat3/testing';
 import { islandStatesFile } from '@ultimat3/testing';
+import type { CaptureClip, ShotDriver, ShotSession } from './browser-launcher-port';
+import { systemShotClock } from './cdp-shot-clock';
 import { ISLAND_HARNESS_PATH } from './island-harness';
 import { readinessProbe } from './island-harness-script';
 import { IslandRequestUnstubbedError, IslandUnphotographableError } from './island-shot-errors';
@@ -43,7 +43,7 @@ export const ISLAND_CROP_MARGIN_PX = 8;
  * takes the viewport as a LAUNCH option (`LocalBrowserOptions.options`) and a state declares its
  * own — so "photograph this state at 480x320" is a different browser, not a different call.
  */
-export type IslandBrowser = (viewport: IslandViewport) => Promise<ScrapeDriver>;
+export type IslandBrowser = (viewport: IslandViewport) => Promise<ShotDriver>;
 
 interface Refusal {
   readonly reason: string;
@@ -181,13 +181,13 @@ export async function captureIslandState(
   floor: number,
 ): Promise<IslandStateShot> {
   const url = new URL(`${ISLAND_HARNESS_PATH}${target.query}`, server.url).toString();
-  let session: ScrapeSession | undefined;
+  let session: ShotSession | undefined;
   try {
     const driver = await options.driver(target.viewport);
     session = await driver.open({
       name: 'x shot --island',
       rules: { allowHosts: allowHostsFrom(server.url, options.extraHosts) },
-      clock: systemScrapeClock,
+      clock: systemShotClock,
       timeoutMs: options.timeoutMs,
     });
     const page = session.page;
@@ -237,7 +237,7 @@ export async function captureIslandState(
     // around, and which nothing passed until 2026-08-26 (issue #338).
     //
     // The clip ALONE. `fullPage: false` beside it is accepted — `assertCaptureFraming` refuses only
-    // `=== true`, and `cdp-target.ts` sends `{ clip }` and nothing else either way — but it is a
+    // `=== true`, and `cdp-shot-page.ts` sends `{ clip }` and nothing else either way — but it is a
     // field that says nothing: the two are exclusive, and spelling out the default of the one you
     // did not ask for reads as a choice.
     // `??` screens null and undefined and NOTHING else, so `cropMarginPx: NaN` reached `clipFor`,

package/src/island-harness-script.ts

@@ -147,12 +147,16 @@ Intl.DateTimeFormat=ShotDTF;
 
 /**
  * Ready is quiet, not idle. Fonts first — a picture taken mid-swap photographs the fallback face —
- * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled.
+ * then `QUIET_FRAMES` consecutive frames in which nothing started and nothing settled, counted only
+ * once the island has MOUNTED or FAILED (#474): an `idle` island mounts in idle time, after frames
+ * that were quiet only because nothing had started yet. A page with no island host is not waited on.
  */
 const readyScript = (): string => `
 var last=-1;var still=0;
+function answered(){var h=document.querySelector("[data-x-island]");
+return !h||h.hasAttribute("data-x-mounted")||h.hasAttribute("data-x-failed")}
 function tick(){var seen=W.activity;
-if(seen===last)still+=1;else{still=0;last=seen}
+if(!answered()){still=0;last=seen}else if(seen===last)still+=1;else{still=0;last=seen}
 if(still>=${QUIET_FRAMES}){W.ready=true;return}
 requestAnimationFrame(tick)}
 (document.fonts?document.fonts.ready:Promise.resolve()).then(function(){requestAnimationFrame(tick)});

package/src/island-realtime.ts

@@ -56,12 +56,15 @@ export function realtimeIslandFiles(): ReadonlySet<string> {
 const ENTRY_SOURCE = `import '${INSTALL}';\nexport * from '${MODULE}';\n`;
 
 /**
- * The install resolves `@ultimat3/realtime` from the ISLAND's own directory — the resolution the
- * island itself gets — so the bundle holds one copy and the signal lands where the hooks read it.
+ * The install names `@ultimat3/realtime` BARE, and `islandRealtimePlugin` resolves it from the
+ * ISLAND's own directory — the resolution the island itself gets — so the bundle holds one copy
+ * and the signal lands where the hooks read it. Never the resolved absolute path spliced in: this
+ * source is part of the chunk's `sourcesContent`, which is what `graphHash` names the URL from, so
+ * a path in it gave the same island a different URL in every checkout and every image build.
  * `solid-js` goes through `island-solid-dedupe.ts` like every other import in the graph.
  */
-const INSTALL_SOURCE = (realtime: string): string =>
-  `import { installRealtime } from ${JSON.stringify(realtime)};\n` +
+const INSTALL_SOURCE =
+  `import { installRealtime } from '${REALTIME}';\n` +
   `import { createSignal } from 'solid-js';\n` +
   `installRealtime({ signal: createSignal });\n`;
 
@@ -79,11 +82,15 @@ export function islandRealtimePlugin(root: string, file: string): BunPlugin {
         namespace: NAMESPACE,
       }));
       build.onResolve({ filter: /^ultimate:island-module$/ }, () => ({ path: island }));
+      // Every bare `@ultimat3/realtime` in this build, the virtual install's included — a virtual
+      // module has no directory to resolve from. The island's directory for all of them, which is
+      // what the island itself would get, and one copy in the bundle is the requirement anyway:
+      // the signal the install sets is only read by hooks from the same module instance.
+      build.onResolve({ filter: /^@ultimat3\/realtime$/ }, () => ({
+        path: Bun.resolveSync(REALTIME, dirname(island)),
+      }));
       build.onLoad({ filter: /.*/, namespace: NAMESPACE }, (args) => ({
-        contents:
-          args.path === 'entry'
-            ? ENTRY_SOURCE
-            : INSTALL_SOURCE(Bun.resolveSync(REALTIME, dirname(island))),
+        contents: args.path === 'entry' ? ENTRY_SOURCE : INSTALL_SOURCE,
         loader: 'js',
       }));
     },