@mysten-incubation/devstack 0.1.1 → 0.2.0

package/dist/build-integrations/playwright/global-setup.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"global-setup.mjs","names":[],"sources":["../../../src/build-integrations/playwright/global-setup.ts"],"sourcesContent":["// Playwright `globalSetup` hook.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright):\n//\n//   What it needs: the same manifest as Vite (...) but with a\n//   cold-start fallback (...) — Playwright config-load runs BEFORE\n//   the supervisor spawns to write the manifest.\n//\n//   How it hooks in: the spawned `pnpm dev` (default `command`) brings\n//   up the supervisor, which writes the real manifest. Playwright\n//   polls `webServer.url` until reachable.\n//\n// This module is the third hook in that chain (config-load → webServer\n// spawn → globalSetup). The public route can become reachable before\n// post-acquire codegen has finished, so globalSetup waits for the\n// supervisor's `codegen.emitted` event before specs load the app. That\n// keeps apps from importing stale generated package IDs.\n//\n// What it does NOT do:\n//   - Boot the supervisor. (`webServer.command` does that.)\n//   - Wait on `webServer.url`. (Playwright does that.)\n//   - Write any state. (Read-only.)\n//\n// Returns a teardown function (the inverse hook Playwright supports\n// via `globalTeardown` indirection — we return the teardown so the\n// preset's `globalTeardown` can call it).\n\nimport { closeSync, openSync, readSync, statSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\n\nimport { Schema } from 'effect';\n\nimport { BUILT_IN_ENDPOINT_ALIASES } from '../runtime/conventional-routes.ts';\nimport { discoverSingleStackManifestPath } from '../runtime/discover.ts';\nimport { resolveDiscoveryEnv } from '../runtime/resolve-discovery-env.ts';\nimport { WALLET_ENDPOINT_KEY } from '../runtime/wallet-paths.ts';\nimport {\n\tPLAYWRIGHT_STACK_CONTEXT_SLOT_KEY,\n\ttype PlaywrightStackFixture as RuntimePlaywrightStackFixture,\n} from '../runtime/playwright-stack-context-slot.ts';\nimport {\n\tPLAYWRIGHT_ENV,\n\treadStackContext,\n\ttype ResolveStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { PlaywrightManifestDiscoveryError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Public shape Playwright expects\n// -----------------------------------------------------------------------------\n\n/** Playwright's `globalSetup` signature is `() => Promise<void | (() =>\n *  Promise<void>)>` — we model it explicitly so the preset compiles\n *  without `@playwright/test`. */\nexport type PlaywrightGlobalSetup = () => Promise<void | (() => Promise<void>)>;\n\n// -----------------------------------------------------------------------------\n// Fixture payload\n// -----------------------------------------------------------------------------\n\n/**\n * The shape global-setup writes for in-spec tests to read. Tests do\n * NOT re-walk-up to find the manifest at every assertion — they read\n * this prepared fixture from `globalThis`, which is faster and avoids\n * a subtle cwd-mismatch class of failure when Playwright runs tests\n * from a worker process.\n *\n * Re-export of the substrate-owned `runtime/playwright-stack-context-slot`\n * shape so both consumer surfaces agree on one type. The matching\n * typed `declare global` block lives next to the slot key so callers\n * can read/write `globalThis[KEY]` without a cast.\n */\nexport type PlaywrightStackFixture = RuntimePlaywrightStackFixture;\n\n// -----------------------------------------------------------------------------\n// Configurable factory\n// -----------------------------------------------------------------------------\n\nexport interface DefineGlobalSetupOptions extends ResolveStackContextOptions {\n\t/**\n\t * Wait for the supervisor's post-acquire codegen event before the\n\t * browser loads the app. Default: `true`.\n\t */\n\treadonly waitForCodegen?: boolean;\n\n\t/** Maximum wait for the manifest + codegen-ready event. */\n\treadonly readyTimeoutMs?: number;\n\n\t/** Poll interval while waiting for the manifest + codegen-ready event. */\n\treadonly readyPollIntervalMs?: number;\n\n\t/**\n\t * Verify the manifest's `endpoints` has at least one entry. The\n\t * supervisor's manifest writer always emits at least the `app`\n\t * endpoint, so an empty `endpoints` lookup means the supervisor\n\t * crashed before reaching its eager snapshot-and-write — fail\n\t * fast here rather than letting tests time out.\n\t */\n\treadonly requireNonEmptyEndpoints?: boolean;\n\n\t/**\n\t * Verify the named endpoints exist in the manifest. Used to fail\n\t * fast when a test suite depends on a specific plugin (wallet,\n\t * sui-faucet) being present in the resolved stack.\n\t */\n\treadonly requireEndpoints?: ReadonlyArray<string>;\n\n\t/**\n\t * Pre-warm the stack context — read the manifest once and stash\n\t * the result on `globalThis` so tests don't repeat the disk read.\n\t * Default: `true`.\n\t */\n\treadonly preloadContext?: boolean;\n}\n\nconst DEFAULT_READY_TIMEOUT_MS = 300_000;\nconst DEFAULT_READY_POLL_INTERVAL_MS = 100;\n\nconst sleep = (ms: number): Promise<void> =>\n\tnew Promise((resolveSleep) => setTimeout(resolveSleep, ms));\n\nconst stackOptionWasExplicit = (options: DefineGlobalSetupOptions): boolean => {\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\treturn (\n\t\toptions.stack !== undefined ||\n\t\toptions.manifestPath !== undefined ||\n\t\tenv[PLAYWRIGHT_ENV.STACK] !== undefined ||\n\t\tenv[PLAYWRIGHT_ENV.MANIFEST_PATH] !== undefined\n\t);\n};\n\nconst findSingleStackManifestPath = (options: DefineGlobalSetupOptions): string | null => {\n\tif (stackOptionWasExplicit(options)) return null;\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\t// Shared ladder (option > DEVSTACK_RUNTIME_ROOT > DEVSTACK_STATE_DIR\n\t// > '.devstack'). Previously read only DEVSTACK_STATE_DIR, dropping\n\t// DEVSTACK_RUNTIME_ROOT — aligned via `resolveDiscoveryEnv`. The\n\t// single-stack walk only needs the state-dir rung; stack is ignored.\n\tconst { stateDir } = resolveDiscoveryEnv(env, {\n\t\t...(options.stateDir !== undefined ? { stateDir: options.stateDir } : {}),\n\t});\n\treturn discoverSingleStackManifestPath({\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\tstateDir,\n\t});\n};\n\nconst readContextForSetup = (options: DefineGlobalSetupOptions): StackContext => {\n\ttry {\n\t\treturn readStackContext(options);\n\t} catch (cause) {\n\t\tif (!(cause instanceof PlaywrightManifestDiscoveryError)) throw cause;\n\t\tconst inferredManifestPath = findSingleStackManifestPath(options);\n\t\tif (inferredManifestPath === null) throw cause;\n\t\treturn readStackContext({ ...options, manifestPath: inferredManifestPath });\n\t}\n};\n\n/**\n * Per-poll state for tail-following `events.ndjson`. We keep an open\n * file descriptor across polls and `readSync` only the bytes appended\n * since the previous tick. Re-opening every 100ms (the default poll\n * cadence) burned ~3000 syscalls per 5min wait; the open-once tail\n * collapses that to one open + one close at the bracket. Two cross-poll\n * counters track the latest `endpoint.registered name=app` and\n * `codegen.emitted` line numbers — codegen is fresh only when its\n * latest sighting is AFTER the latest app-endpoint registration (a\n * restart re-registers the endpoint, invalidating an earlier codegen).\n *\n * Lifecycle: `openCodegenWatch` allocates the fd; `advanceCodegenWatch`\n * reads forward; `closeCodegenWatch` releases. The caller MUST close\n * (the `waitForReadyStackContext` finally-block does this even on\n * timeout / exception paths).\n */\ninterface CodegenWatchState {\n\tfd: number | null;\n\toffset: number;\n\tlineIndex: number;\n\tcarry: string;\n\tlatestAppEndpointLine: number;\n\tlatestCodegenLine: number;\n\tlastFileSize: number;\n\tdecodeFailures: number;\n}\n\nconst createCodegenWatchState = (): CodegenWatchState => ({\n\tfd: null,\n\toffset: 0,\n\tlineIndex: 0,\n\tcarry: '',\n\tlatestAppEndpointLine: -1,\n\tlatestCodegenLine: -1,\n\tlastFileSize: 0,\n\tdecodeFailures: 0,\n});\n\nconst READ_CHUNK_BYTES = 64 * 1024;\n\n/**\n * Pinned-shape schema for the ndjson records we tail. The supervisor\n * emits a richer envelope (`protocol`/`seq`/`at` plus the full\n * `EngineEvent` union payload — see\n * `substrate/runtime/cross-process/command-channel/protocol.ts`\n * `EventRecordSchema`), but the watch only needs the discriminators\n * that route a record to `latestAppEndpointLine` / `latestCodegenLine`.\n *\n * The pin's job is to FAIL LOUDLY if one of those discriminators is\n * renamed upstream — a silent miss leaves the matchers permanently\n * unfired and deadlocks global-setup at the 5min `readyTimeout`. An\n * earlier version declared every field as `optional(Unknown)`, which\n * defeats that entirely: a `kind`→`recordKind` rename decoded to\n * `undefined` instead of throwing, so the watch silently stalled. We\n * therefore pin the stable discriminators as REQUIRED while keeping the\n * genuinely-variable axis (the engine `tag` value) permissive:\n *\n *   - The engine variant requires `kind: 'engine'` (the literal value\n *     the matchers test against, verified at `channel.ts` `publishEvent`)\n *     and a required `event.tag` STRING. Renaming `kind`, its `'engine'`\n *     value, the `event` key, or the `tag` key all fail decode — these\n *     are the deadlock-class discriminators. The `tag` VALUE stays open,\n *     so future `EngineEvent` tag additions need no change here.\n *   - `event.endpoint` is optional (most engine tags carry no endpoint),\n *     but WHERE present its `name` is REQUIRED. Renaming `name` on an\n *     `endpoint.registered` record therefore fails decode rather than\n *     silently leaving `latestAppEndpointLine` unset.\n *   - `ack` / `error` envelopes carry no `event`; a dedicated variant\n *     absorbs them so the supervisor's correlation replies don't flood\n *     `decodeFailures`. They are never routed.\n *\n * Deliberately NOT permissive about an unknown `kind`: a brand-new\n * envelope kind fails decode. That is a rare, intentional protocol\n * change (and would be made alongside updating consumers), and failing\n * loudly here is the same drift signal the engine-value pin provides.\n */\nconst WatchedEngineRecordSchema = Schema.Struct({\n\tkind: Schema.Literal('engine'),\n\tevent: Schema.Struct({\n\t\ttag: Schema.String,\n\t\tendpoint: Schema.optional(\n\t\t\tSchema.Struct({\n\t\t\t\tname: Schema.String,\n\t\t\t}),\n\t\t),\n\t}),\n});\n\nconst WatchedReplyRecordSchema = Schema.Struct({\n\tkind: Schema.Literals(['ack', 'error']),\n});\n\nconst WatchedRecordSchema = Schema.Union([WatchedEngineRecordSchema, WatchedReplyRecordSchema]);\n\ntype WatchedRecord = Schema.Schema.Type<typeof WatchedRecordSchema>;\ntype WatchedEngineRecord = Schema.Schema.Type<typeof WatchedEngineRecordSchema>;\n\n/**\n * @internal Exported only so the through-surface test can assert the\n * drift-detection contract directly (a renamed discriminator must\n * THROW, not decode to `undefined`). Not part of the public API.\n */\nexport const decodeWatchedRecord = Schema.decodeUnknownSync(WatchedRecordSchema);\n\nconst isEngineRecord = (record: WatchedRecord): record is WatchedEngineRecord =>\n\trecord.kind === 'engine';\n\nconst isAppEndpointRegistration = (record: WatchedRecord): boolean =>\n\tisEngineRecord(record) &&\n\trecord.event.tag === 'endpoint.registered' &&\n\trecord.event.endpoint?.name === BUILT_IN_ENDPOINT_ALIASES.app;\n\nconst isCodegenEmitted = (record: WatchedRecord): boolean =>\n\tisEngineRecord(record) && record.event.tag === 'codegen.emitted';\n\nconst DEBUG_ENABLED = (): boolean => process.env.DEVSTACK_PLAYWRIGHT_DEBUG === '1';\n\nconst debugLog = (message: string): void => {\n\tif (!DEBUG_ENABLED()) return;\n\ttry {\n\t\tprocess.stderr.write(`[devstack/playwright] ${message}\\n`);\n\t} catch {\n\t\t// stderr EPIPE — swallow; the debug channel is best-effort.\n\t}\n};\n\nconst ingestNdjsonLine = (state: CodegenWatchState, line: string): void => {\n\tif (line.length === 0) return;\n\tstate.lineIndex += 1;\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(line);\n\t} catch {\n\t\t// Partial / corrupt line — atomic-append from the supervisor can\n\t\t// land a half-flushed write between polls. Bump the counter so\n\t\t// repeated failures surface in debug mode (a steady stream means\n\t\t// the writer is malformed, not just race-y).\n\t\tstate.decodeFailures += 1;\n\t\tif (state.decodeFailures <= 3 || state.decodeFailures % 50 === 0) {\n\t\t\tdebugLog(\n\t\t\t\t`events.ndjson line ${state.lineIndex} failed JSON.parse (decodeFailures=${state.decodeFailures})`,\n\t\t\t);\n\t\t}\n\t\treturn;\n\t}\n\tlet record: WatchedRecord;\n\ttry {\n\t\trecord = decodeWatchedRecord(parsed);\n\t} catch (cause) {\n\t\t// Schema drift: the supervisor emitted a record that doesn't\n\t\t// fit the discriminator shape we pin against. Log so a future\n\t\t// engine refactor that renames `kind` / `event.tag` /\n\t\t// `event.endpoint.name` surfaces immediately instead of\n\t\t// silently stalling the codegen wait at the readyTimeout.\n\t\tstate.decodeFailures += 1;\n\t\tif (state.decodeFailures <= 3 || state.decodeFailures % 50 === 0) {\n\t\t\tdebugLog(\n\t\t\t\t`events.ndjson line ${state.lineIndex} failed Schema.decode (decodeFailures=${state.decodeFailures}): ${\n\t\t\t\t\tcause instanceof Error ? cause.message : String(cause)\n\t\t\t\t}`,\n\t\t\t);\n\t\t}\n\t\treturn;\n\t}\n\tif (isAppEndpointRegistration(record)) {\n\t\tstate.latestAppEndpointLine = state.lineIndex;\n\t}\n\tif (isCodegenEmitted(record)) {\n\t\tstate.latestCodegenLine = state.lineIndex;\n\t}\n};\n\n/**\n * Advance the watch state by reading any bytes appended since the\n * previous poll. The fd is allocated lazily on the first poll (so a\n * file that doesn't yet exist isn't a hard error) and stays open across\n * polls until `closeCodegenWatch`. Returns `true` when the file has a\n * codegen-fresh state ready for caller continuation.\n *\n * Truncation/rotation: when `statSync(...).size < state.lastFileSize`\n * the file rotated. We close the old fd, reopen, and restart the\n * counters so the new tail's events aren't shadowed by stale\n * cross-poll state.\n */\nconst advanceCodegenWatch = (state: CodegenWatchState, eventsPath: string): boolean => {\n\tif (state.fd === null) {\n\t\ttry {\n\t\t\tstate.fd = openSync(eventsPath, 'r');\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t}\n\ttry {\n\t\tconst size = statSync(eventsPath).size;\n\t\tif (size < state.lastFileSize) {\n\t\t\t// File was truncated / rotated — drop the stale fd and reopen\n\t\t\t// so we read the new tail from byte zero.\n\t\t\ttry {\n\t\t\t\tcloseSync(state.fd);\n\t\t\t} catch {\n\t\t\t\t// Best-effort close; the inode is gone anyway.\n\t\t\t}\n\t\t\tstate.fd = null;\n\t\t\tstate.offset = 0;\n\t\t\tstate.lineIndex = 0;\n\t\t\tstate.carry = '';\n\t\t\tstate.latestAppEndpointLine = -1;\n\t\t\tstate.latestCodegenLine = -1;\n\t\t\tstate.lastFileSize = 0;\n\t\t\ttry {\n\t\t\t\tstate.fd = openSync(eventsPath, 'r');\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\tstate.lastFileSize = size;\n\t\tconst buf = Buffer.allocUnsafe(READ_CHUNK_BYTES);\n\t\twhile (state.offset < size) {\n\t\t\tconst bytesRead = readSync(state.fd, buf, 0, READ_CHUNK_BYTES, state.offset);\n\t\t\tif (bytesRead <= 0) break;\n\t\t\tstate.offset += bytesRead;\n\t\t\tconst chunk = state.carry + buf.subarray(0, bytesRead).toString('utf8');\n\t\t\tconst segments = chunk.split(/\\r?\\n/);\n\t\t\tstate.carry = segments.pop() ?? '';\n\t\t\tfor (const segment of segments) {\n\t\t\t\tingestNdjsonLine(state, segment);\n\t\t\t}\n\t\t}\n\t} catch {\n\t\t// Treat read errors as \"no progress this poll\"; the fd stays\n\t\t// open so the next tick retries from `state.offset`.\n\t}\n\tif (state.latestCodegenLine < 0) return false;\n\tif (state.latestAppEndpointLine < 0) return true;\n\treturn state.latestCodegenLine > state.latestAppEndpointLine;\n};\n\nconst closeCodegenWatch = (state: CodegenWatchState): void => {\n\tif (state.fd === null) return;\n\ttry {\n\t\tcloseSync(state.fd);\n\t} catch {\n\t\t// Best-effort — we're done with the file regardless.\n\t}\n\tstate.fd = null;\n};\n\nconst waitForReadyStackContext = async (\n\toptions: DefineGlobalSetupOptions,\n): Promise<StackContext> => {\n\tconst timeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;\n\tconst intervalMs = options.readyPollIntervalMs ?? DEFAULT_READY_POLL_INTERVAL_MS;\n\tconst deadline = Date.now() + timeoutMs;\n\tlet lastError: unknown = null;\n\n\t// Phase 1: poll for the manifest itself. The supervisor writes it\n\t// eagerly during boot, but Playwright's `webServer.command` race\n\t// can land us here before the file exists. Once we've decoded a\n\t// manifest, we pin to its location for the remainder of the wait —\n\t// re-decoding on every tick (default 100ms over 5min) costs\n\t// thousands of JSON+Schema decodes for no information gain.\n\tlet ctx: StackContext | null = null;\n\twhile (Date.now() <= deadline) {\n\t\ttry {\n\t\t\tctx = readContextForSetup(options);\n\t\t\tbreak;\n\t\t} catch (cause) {\n\t\t\tlastError = cause;\n\t\t\tawait sleep(intervalMs);\n\t\t}\n\t}\n\tif (ctx === null) {\n\t\tthrow new Error(\n\t\t\t`devstack manifest did not appear within ${timeoutMs}ms` +\n\t\t\t\t(lastError instanceof Error ? `: ${lastError.message}` : ''),\n\t\t);\n\t}\n\n\t// Phase 2: tail `events.ndjson` for the codegen-fresh signal. Only\n\t// the events file changes during this phase — the manifest path is\n\t// fixed once Phase 1 succeeds. The watch holds an open fd across\n\t// polls; we close it on every exit path (success, timeout, throw).\n\tconst eventsPath = join(dirname(ctx.manifestPath), 'events.ndjson');\n\tconst watchState = createCodegenWatchState();\n\ttry {\n\t\twhile (Date.now() <= deadline) {\n\t\t\tif (advanceCodegenWatch(watchState, eventsPath)) return ctx;\n\t\t\tlastError = new Error(\n\t\t\t\t`devstack has not emitted codegen yet; waiting on events next to ${ctx.manifestPath}`,\n\t\t\t);\n\t\t\tawait sleep(intervalMs);\n\t\t}\n\t} finally {\n\t\tcloseCodegenWatch(watchState);\n\t}\n\n\tthrow new Error(\n\t\t`devstack did not reach post-acquire codegen within ${timeoutMs}ms` +\n\t\t\t(lastError instanceof Error ? `: ${lastError.message}` : ''),\n\t);\n};\n\n/**\n * Build a Playwright `globalSetup` function. The returned function\n * matches the signature Playwright expects (a default export of a\n * module path; we return the function so the preset can wire it).\n */\nexport const buildGlobalSetup = (options: DefineGlobalSetupOptions = {}): PlaywrightGlobalSetup => {\n\treturn async () => {\n\t\tconst ctx =\n\t\t\t(options.waitForCodegen ?? true)\n\t\t\t\t? await waitForReadyStackContext(options)\n\t\t\t\t: readContextForSetup(options);\n\n\t\tif (options.requireNonEmptyEndpoints === true) {\n\t\t\tif (ctx.endpointNames.length === 0) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`devstack manifest at ${ctx.manifestPath} has no endpoints. ` +\n\t\t\t\t\t\t`The supervisor likely failed before its eager snapshot ` +\n\t\t\t\t\t\t`write; check the dev server logs for plugin acquire errors.`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tconst required = options.requireEndpoints ?? [];\n\t\tconst missing: string[] = [];\n\t\tfor (const key of required) {\n\t\t\tif (ctx.endpointMaybe(key) === null) missing.push(key);\n\t\t}\n\t\tif (missing.length > 0) {\n\t\t\tthrow new Error(\n\t\t\t\t`devstack manifest at ${ctx.manifestPath} is missing required ` +\n\t\t\t\t\t`endpoints: ${missing.join(', ')}. ` +\n\t\t\t\t\t`available endpoint names: ${ctx.endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t\t`raw manifest keys: ${ctx.manifestEndpointKeys.join(', ') || '(none)'}.`,\n\t\t\t);\n\t\t}\n\n\t\tif (options.preloadContext ?? true) {\n\t\t\tstashStackContext(ctx);\n\t\t}\n\n\t\t// Return value: `void` (no teardown). Playwright accepts\n\t\t// `() => Promise<void>` here.\n\t};\n};\n\n/** Default export shape that mirrors what Playwright's\n *  `defineConfig.globalSetup` resolves: a module whose default export\n *  is the setup function. */\nexport default buildGlobalSetup();\n\n// -----------------------------------------------------------------------------\n// Global stash\n// -----------------------------------------------------------------------------\n\n/** The slot on `globalThis` where the prewarmed stack context lives.\n *  In-spec helpers (`wallet-context.ts`) read from here when present\n *  to avoid a second disk read. Re-exported from the runtime slot\n *  module so consumers can import either side. */\nexport const STACK_CONTEXT_SLOT = PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY;\n\n/** Monotonic counter for fixture rotations within a single Node process.\n *  Survives across `stashStackContext` calls so a Playwright retry that\n *  re-runs global-setup stamps a fresh `generation` even though the\n *  module never reloads. */\nlet stashGeneration = 0;\n\nconst stashStackContext = (ctx: StackContext): void => {\n\t// Include alias keys in the stashed endpoints map so consumers\n\t// iterating `fixture.endpoints` see the same contract as callers\n\t// of `endpoint(alias)`. Without this, `fixture.endpoints['app']`\n\t// would miss while `ctx.endpoint('app')` resolves to `'dev'` —\n\t// the asymmetry surprises consumers reading the raw dict.\n\tconst endpoints: Record<string, string> = Object.fromEntries(\n\t\tctx.endpointNames.map((name) => [name, ctx.endpoint(name)]),\n\t);\n\tfor (const [alias, canonical] of Object.entries(BUILT_IN_ENDPOINT_ALIASES)) {\n\t\tif (alias in endpoints) continue;\n\t\tconst url = endpoints[canonical];\n\t\tif (url !== undefined) endpoints[alias] = url;\n\t}\n\tstashGeneration += 1;\n\tconst fixture: PlaywrightStackFixture = {\n\t\tendpoints,\n\t\twalletEndpoint: ctx.endpointMaybe(WALLET_ENDPOINT_KEY),\n\t\tmanifestPath: ctx.manifestPath,\n\t\tstack: ctx.manifest.identity.stack,\n\t\tapp: ctx.manifest.identity.app,\n\t\tgeneration: stashGeneration,\n\t};\n\t// Surface a one-line advisory when we overwrite an existing slot —\n\t// a second populate means global-setup ran twice (Playwright retry\n\t// with `reuseExistingServer:false`, or operator wiring both\n\t// `globalSetup` and an inline preset boot). The previous fixture\n\t// may be pointing at a stack that has since been torn down, so any\n\t// helper that cached the prior reference would silently read stale\n\t// state. The bumped `generation` lets cache-holders detect the\n\t// rotation and re-fetch.\n\tconst previous = globalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY];\n\tif (previous !== undefined) {\n\t\ttry {\n\t\t\tprocess.stderr.write(\n\t\t\t\t`[devstack/playwright] global-setup re-ran (generation ${previous.generation} → ${fixture.generation}); ` +\n\t\t\t\t\t`downstream consumers should re-read globalThis[${PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY}].\\n`,\n\t\t\t);\n\t\t} catch {\n\t\t\t// stderr EPIPE — swallow; the warning is best-effort.\n\t\t}\n\t}\n\tglobalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY] = fixture;\n};\n\n/** Read the slot. Returns `null` if global-setup didn't run (e.g. the\n *  user opted out by passing `globalSetup: null`). */\nexport const readStashedFixture = (): PlaywrightStackFixture | null =>\n\tglobalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY] ?? null;\n"],"mappings":"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"}
+{"version":3,"file":"global-setup.mjs","names":[],"sources":["../../../src/build-integrations/playwright/global-setup.ts"],"sourcesContent":["// Playwright `globalSetup` that boots a dedicated stack for the run and\n// tears it down on completion — the PROGRAMMATIC mirror of the vitest\n// global-setup (`build-integrations/vitest/global-setup.ts`).\n//\n// Why this exists / why NOT `webServer`: Playwright's `webServer` shells\n// out (`pnpm dev` → sh → node) and, on teardown, `process.kill(-pid)`s the\n// group but resolves graceful-close the instant the LAUNCHED process closes\n// — pnpm exits in ~200ms, long before the supervisor finishes its container\n// drain, after which Playwright SIGKILLs the group and orphans the Docker\n// containers. So we DON'T use `webServer` at all: we boot the stack in-process\n// here via `runStack` (whose `start` awaits readiness AND post-acquire codegen)\n// and tear it down via `handle.stop` + `awaitShutdown` (a clean graceful drain\n// that stops the containers), exactly like the vitest path.\n//\n// Lifecycle:\n//   setup    → load config, runStack(identity.stack=<DEVSTACK_STACK>), await ready\n//   handoff  → publish DEVSTACK_STACK + DEVSTACK_MANIFEST_PATH, stash the\n//              fixture on globalThis for in-runner helpers (spec workers fall\n//              back to a disk manifest read keyed on DEVSTACK_STACK + cwd)\n//   teardown → return a fn that stops the supervisor + best-effort `wipe`\n//\n// Escape hatch (reuse an already-running stack — or read-only validation):\n//   `DEVSTACK_TEST_REUSE=1` / `{ reuse: true }` / an explicit `manifestPath`\n//   take the read-only path: no boot, no teardown — just validate + stash\n//   against the existing manifest.\n//\n// This module imports only the CLI-free `api/` surface (`runStack`,\n// `loadDevstackConfig`) so the playwright entry never pulls the CLI/TUI graph.\n\nimport { spawn } from 'node:child_process';\nimport { existsSync } from 'node:fs';\nimport { dirname } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nimport { Effect } from 'effect';\n\nimport { loadDevstackConfig } from '../../api/load-config.ts';\nimport { runStack, type RunHandle } from '../../api/run-stack.ts';\nimport { BUILT_IN_ENDPOINT_ALIASES } from '../runtime/conventional-routes.ts';\nimport { discoverSingleStackManifestPath } from '../runtime/discover.ts';\nimport { resolveDiscoveryEnv } from '../runtime/resolve-discovery-env.ts';\nimport { WALLET_ENDPOINT_KEY } from '../runtime/wallet-paths.ts';\nimport {\n\tPLAYWRIGHT_STACK_CONTEXT_SLOT_KEY,\n\ttype PlaywrightStackFixture as RuntimePlaywrightStackFixture,\n} from '../runtime/playwright-stack-context-slot.ts';\nimport {\n\tPLAYWRIGHT_ENV,\n\treadStackContext,\n\ttype ResolveStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { PlaywrightManifestDiscoveryError } from './errors.ts';\n\n// -----------------------------------------------------------------------------\n// Public shapes\n// -----------------------------------------------------------------------------\n\n/** Playwright's `globalSetup` signature: a setup function that optionally\n *  returns a teardown function. We model it explicitly so the preset\n *  compiles without `@playwright/test`. */\nexport type PlaywrightGlobalSetup = () => Promise<void | (() => Promise<void>)>;\n\n/**\n * Re-export of the substrate-owned fixture shape (the slot global-setup\n * stashes for in-runner helpers). Spec WORKERS don't see this globalThis\n * slot — they read the manifest off disk — but in-runner code and a\n * single-process driver do.\n */\nexport type PlaywrightStackFixture = RuntimePlaywrightStackFixture;\n\nexport interface DefineGlobalSetupOptions extends ResolveStackContextOptions {\n\t/** Stack to boot. Default: `DEVSTACK_STACK` if set, else `'test'`.\n\t *  (Browser e2e examples set `DEVSTACK_STACK=e2e` in their `test:e2e`\n\t *  script, isolating them from a developer's dev stack.) */\n\treadonly stack?: string;\n\t/** Path to the app's `devstack.config.ts`. Default: walk-up from cwd. */\n\treadonly configPath?: string;\n\t/** Runtime root holding `stacks/<stack>/manifest.json`. Default:\n\t *  `DEVSTACK_RUNTIME_ROOT` / `DEVSTACK_STATE_DIR` / `.devstack`. */\n\treadonly runtimeRoot?: string;\n\t/** Read-only path: attach to an already-running stack (no boot, no\n\t *  teardown). Default `false`; also enabled by `DEVSTACK_TEST_REUSE=1`\n\t *  or by passing an explicit `manifestPath`. */\n\treadonly reuse?: boolean;\n\t/** Hard cap (ms) for the stack to reach ready. Default 300_000 (5 min). */\n\treadonly bootTimeoutMs?: number;\n\t/** Fail fast if the resolved manifest exposes zero endpoints. */\n\treadonly requireNonEmptyEndpoints?: boolean;\n\t/** Fail fast if any of these endpoint names is absent. */\n\treadonly requireEndpoints?: ReadonlyArray<string>;\n\t/** Stash the resolved context on `globalThis` for in-runner helpers.\n\t *  Default `true`. */\n\treadonly preloadContext?: boolean;\n}\n\n// -----------------------------------------------------------------------------\n// Defaults + small helpers (mirrored from the vitest global-setup)\n// -----------------------------------------------------------------------------\n\nconst DEFAULT_BOOT_TIMEOUT_MS = 300_000;\nconst DEFAULT_RUNTIME_ROOT = '.devstack';\n/** Default stack when `DEVSTACK_STACK` is unset. Examples override via the\n *  `test:e2e` script; this is only the bare fallback. */\nconst DEFAULT_TEST_STACK = 'test';\n\nconst isTruthyEnv = (value: string | undefined): boolean =>\n\tvalue === '1' || value === 'true' || value === 'yes';\n\nconst resolveStackName = (\n\toptions: DefineGlobalSetupOptions,\n\tenv: Record<string, string | undefined>,\n): string => {\n\tconst fromEnv = env[PLAYWRIGHT_ENV.STACK];\n\treturn options.stack ?? (fromEnv && fromEnv !== '' ? fromEnv : DEFAULT_TEST_STACK);\n};\n\nconst resolveRuntimeRoot = (\n\toptions: DefineGlobalSetupOptions,\n\tenv: Record<string, string | undefined>,\n): string =>\n\toptions.runtimeRoot ??\n\t(env.DEVSTACK_RUNTIME_ROOT || env.DEVSTACK_STATE_DIR || undefined) ??\n\tDEFAULT_RUNTIME_ROOT;\n\nconst withTimeout = async <A>(promise: Promise<A>, ms: number, label: string): Promise<A> => {\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tconst timeout = new Promise<never>((_, reject) => {\n\t\ttimer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);\n\t});\n\ttry {\n\t\treturn await Promise.race([promise, timeout]);\n\t} finally {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t}\n};\n\nconst safeStop = async (handle: RunHandle): Promise<void> => {\n\ttry {\n\t\tawait Effect.runPromise(handle.stop);\n\t} catch {\n\t\t// best-effort — fall through to awaitShutdown\n\t}\n\ttry {\n\t\tawait Effect.runPromise(handle.awaitShutdown);\n\t} catch {\n\t\t// supervisor may have already exited; nothing more to do\n\t}\n};\n\n/** After the in-process supervisor exits, graceful shutdown only STOPS the\n *  stack's containers (devstack keeps them for warm restarts). An ephemeral\n *  e2e stack should leave nothing behind, so run the production `devstack\n *  wipe` verb (force-removes containers + networks + volumes + per-stack\n *  state). Best-effort: failure never fails the test run, and a leftover\n *  stopped stack is force-recreated by the next boot. Skip with\n *  `DEVSTACK_TEST_KEEP=1` to leave the stack up for debugging. */\nconst wipeStack = (stack: string, runtimeRoot: string, cwd: string): Promise<void> =>\n\tnew Promise((resolve) => {\n\t\t// The CLI entry ships beside this module in the built package:\n\t\t// dist/build-integrations/playwright/global-setup.mjs → dist/cli/main.mjs.\n\t\tconst cliEntry = fileURLToPath(new URL('../../cli/main.mjs', import.meta.url));\n\t\tif (!existsSync(cliEntry)) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tconst child = spawn(process.execPath, [cliEntry, 'wipe', '--yes'], {\n\t\t\tcwd,\n\t\t\tenv: { ...process.env, DEVSTACK_STACK: stack, DEVSTACK_RUNTIME_ROOT: runtimeRoot },\n\t\t\tstdio: 'ignore',\n\t\t});\n\t\tchild.unref();\n\t\tconst done = (): void => resolve();\n\t\tchild.on('error', done);\n\t\tchild.on('exit', done);\n\t\tconst timer = setTimeout(() => {\n\t\t\tchild.kill();\n\t\t\tresolve();\n\t\t}, 120_000);\n\t\ttimer.unref?.();\n\t});\n\nconst publishHandoff = (stack: string, manifestPath: string): void => {\n\tprocess.env[PLAYWRIGHT_ENV.STACK] = stack;\n\tprocess.env[PLAYWRIGHT_ENV.MANIFEST_PATH] = manifestPath;\n};\n\n// -----------------------------------------------------------------------------\n// Context read (reuse / post-boot) + single-stack fallback\n// -----------------------------------------------------------------------------\n\nconst stackOptionWasExplicit = (options: ResolveStackContextOptions): boolean => {\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\treturn (\n\t\toptions.stack !== undefined ||\n\t\toptions.manifestPath !== undefined ||\n\t\tenv[PLAYWRIGHT_ENV.STACK] !== undefined ||\n\t\tenv[PLAYWRIGHT_ENV.MANIFEST_PATH] !== undefined\n\t);\n};\n\nconst findSingleStackManifestPath = (options: ResolveStackContextOptions): string | null => {\n\tif (stackOptionWasExplicit(options)) return null;\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\tconst { stateDir } = resolveDiscoveryEnv(\n\t\tenv,\n\t\toptions.stateDir !== undefined ? { stateDir: options.stateDir } : {},\n\t);\n\treturn discoverSingleStackManifestPath({\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\tstateDir,\n\t});\n};\n\nconst readContextForSetup = (options: ResolveStackContextOptions): StackContext => {\n\ttry {\n\t\treturn readStackContext(options);\n\t} catch (cause) {\n\t\tif (!(cause instanceof PlaywrightManifestDiscoveryError)) throw cause;\n\t\tconst inferredManifestPath = findSingleStackManifestPath(options);\n\t\tif (inferredManifestPath === null) throw cause;\n\t\treturn readStackContext({ ...options, manifestPath: inferredManifestPath });\n\t}\n};\n\nconst validateContext = (ctx: StackContext, options: DefineGlobalSetupOptions): void => {\n\tif (options.requireNonEmptyEndpoints === true && ctx.endpointNames.length === 0) {\n\t\tthrow new Error(\n\t\t\t`devstack manifest at ${ctx.manifestPath} has no endpoints. ` +\n\t\t\t\t`The supervisor likely failed before its eager snapshot write; ` +\n\t\t\t\t`check the boot logs for plugin acquire errors.`,\n\t\t);\n\t}\n\tconst required = options.requireEndpoints ?? [];\n\tconst missing: string[] = [];\n\tfor (const key of required) {\n\t\tif (ctx.endpointMaybe(key) === null) missing.push(key);\n\t}\n\tif (missing.length > 0) {\n\t\tthrow new Error(\n\t\t\t`devstack manifest at ${ctx.manifestPath} is missing required endpoints: ` +\n\t\t\t\t`${missing.join(', ')}. available endpoint names: ` +\n\t\t\t\t`${ctx.endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t`raw manifest keys: ${ctx.manifestEndpointKeys.join(', ') || '(none)'}.`,\n\t\t);\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Global stash (in-runner fixture; spec workers fall back to disk)\n// -----------------------------------------------------------------------------\n\n/** The slot on `globalThis` where the prewarmed stack context lives.\n *  In-spec helpers (`wallet-context.ts`) read from here when present. */\nexport const STACK_CONTEXT_SLOT = PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY;\n\nlet stashGeneration = 0;\n\nconst stashStackContext = (ctx: StackContext): void => {\n\tconst endpoints: Record<string, string> = Object.fromEntries(\n\t\tctx.endpointNames.map((name) => [name, ctx.endpoint(name)]),\n\t);\n\tfor (const [alias, canonical] of Object.entries(BUILT_IN_ENDPOINT_ALIASES)) {\n\t\tif (alias in endpoints) continue;\n\t\tconst url = endpoints[canonical];\n\t\tif (url !== undefined) endpoints[alias] = url;\n\t}\n\tstashGeneration += 1;\n\tconst fixture: PlaywrightStackFixture = {\n\t\tendpoints,\n\t\twalletEndpoint: ctx.endpointMaybe(WALLET_ENDPOINT_KEY),\n\t\tmanifestPath: ctx.manifestPath,\n\t\tstack: ctx.manifest.identity.stack,\n\t\tapp: ctx.manifest.identity.app,\n\t\tgeneration: stashGeneration,\n\t};\n\t// Advise on overwrite: a second populate means global-setup ran twice in\n\t// one process (a Playwright retry re-running it). The bumped `generation`\n\t// lets cache-holders detect the rotation and re-read.\n\tconst previous = globalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY];\n\tif (previous !== undefined) {\n\t\ttry {\n\t\t\tprocess.stderr.write(\n\t\t\t\t`[devstack/playwright] global-setup re-ran (generation ${previous.generation} → ` +\n\t\t\t\t\t`${fixture.generation}); downstream consumers should re-read ` +\n\t\t\t\t\t`globalThis[${PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY}].\\n`,\n\t\t\t);\n\t\t} catch {\n\t\t\t// stderr EPIPE — swallow; the advisory is best-effort.\n\t\t}\n\t}\n\tglobalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY] = fixture;\n};\n\n/** Read the slot. Returns `null` if global-setup didn't run in this process\n *  (e.g. a spec worker, or `globalSetup: null`). Callers MUST fall back to a\n *  disk manifest read. */\nexport const readStashedFixture = (): PlaywrightStackFixture | null =>\n\tglobalThis[PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY] ?? null;\n\n// -----------------------------------------------------------------------------\n// Builder\n// -----------------------------------------------------------------------------\n\n/**\n * Build a Playwright `globalSetup` that boots (or, in reuse/read-only mode,\n * attaches to) a dedicated stack and returns a teardown. Wire it as the\n * config's `globalSetup` module path — `devstackPlaywrightBaseConfig`\n * references this module's default export.\n */\nexport const buildGlobalSetup = (options: DefineGlobalSetupOptions = {}): PlaywrightGlobalSetup => {\n\treturn async () => {\n\t\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\t\tconst readOnly =\n\t\t\t(options.reuse ?? isTruthyEnv(env.DEVSTACK_TEST_REUSE)) || options.manifestPath !== undefined;\n\n\t\t// Read-only path: attach to / validate an existing manifest. No boot,\n\t\t// no teardown. (Reuse escape hatch + the unit-test seam.)\n\t\tif (readOnly) {\n\t\t\tconst ctx = readContextForSetup(options);\n\t\t\tvalidateContext(ctx, options);\n\t\t\tif (options.preloadContext ?? true) stashStackContext(ctx);\n\t\t\treturn async () => {};\n\t\t}\n\n\t\t// Fresh boot (default): load the app's stack the same way the CLI does\n\t\t// and run it in-process. `start` resolves once every plugin is ready\n\t\t// AND post-acquire codegen has emitted.\n\t\tconst stack = resolveStackName(options, env);\n\t\tconst runtimeRoot = resolveRuntimeRoot(options, env);\n\t\tconst loaded = await Effect.runPromise(loadDevstackConfig(options.configPath)).catch(\n\t\t\t(cause: unknown) => {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`devstack playwright globalSetup: failed to load devstack config — ${\n\t\t\t\t\t\tcause instanceof Error ? cause.message : String(cause)\n\t\t\t\t\t}`,\n\t\t\t\t\t{ cause },\n\t\t\t\t);\n\t\t\t},\n\t\t);\n\t\tconst appRoot = dirname(loaded.resolvedConfigPath);\n\n\t\tconst handle = runStack(loaded.stack, {\n\t\t\tidentity: { stack },\n\t\t\tappRoot,\n\t\t\truntimeRoot,\n\t\t\t...(loaded.engine.options.codegen !== undefined\n\t\t\t\t? { codegen: loaded.engine.options.codegen }\n\t\t\t\t: {}),\n\t\t});\n\n\t\ttry {\n\t\t\tawait withTimeout(\n\t\t\t\tEffect.runPromise(handle.start),\n\t\t\t\toptions.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS,\n\t\t\t\t`devstack playwright globalSetup: '${stack}' stack boot`,\n\t\t\t);\n\t\t} catch (cause) {\n\t\t\tawait safeStop(handle);\n\t\t\tthrow new Error(\n\t\t\t\t`devstack playwright globalSetup: failed to boot the '${stack}' stack. ` +\n\t\t\t\t\t`If a '${stack}' stack is already running, set DEVSTACK_TEST_REUSE=1 to ` +\n\t\t\t\t\t`run against it. Cause: ${cause instanceof Error ? cause.message : String(cause)}`,\n\t\t\t\t{ cause },\n\t\t\t);\n\t\t}\n\n\t\tconst ctx = readContextForSetup({ ...options, stack, stateDir: runtimeRoot, cwd: appRoot });\n\t\tvalidateContext(ctx, options);\n\t\tpublishHandoff(stack, ctx.manifestPath);\n\t\tif (options.preloadContext ?? true) stashStackContext(ctx);\n\n\t\tconst keep = isTruthyEnv(env.DEVSTACK_TEST_KEEP);\n\t\treturn async () => {\n\t\t\tawait safeStop(handle);\n\t\t\tif (!keep) await wipeStack(stack, runtimeRoot, appRoot);\n\t\t};\n\t};\n};\n\n/** Default export = a ready-to-use Playwright `globalSetup` (boots the stack\n *  resolved from `DEVSTACK_STACK`, tears it down on completion). This is what\n *  `globalSetup: '@mysten-incubation/devstack/playwright/global-setup'`\n *  resolves to. */\nexport default buildGlobalSetup();\n"],"mappings":"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"}

package/dist/build-integrations/playwright/index.d.mts

@@ -2,7 +2,7 @@ import { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY } from "../runtime/playwright-stack-c
 import { WALLET_ENDPOINT_KEY } from "../../contracts/wallet-protocol.mjs";
 import { PLAYWRIGHT_ENV, ResolveStackContextOptions, ResolvedEndpoint, StackContext, conventionalUrlFor, discoverManifestPath, makeStackContext, readManifestSync, readStackContext, resolveEndpointUrl } from "./stack-context.mjs";
 import { DefineGlobalSetupOptions, PlaywrightGlobalSetup, PlaywrightStackFixture, STACK_CONTEXT_SLOT, buildGlobalSetup, readStashedFixture } from "./global-setup.mjs";
-import { DevstackPlaywrightBaseConfigOptions, DevstackPlaywrightEndpointOptions, DevstackPlaywrightProjectsOptions, DevstackPlaywrightUseOptions, DevstackPlaywrightWebServerOptions, PlaywrightBaseConfigShape, PlaywrightProjectShape, PlaywrightUseConfigShape, PlaywrightWebServerConfigShape, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, resolveDevstackPlaywrightBaseURL } from "./config.mjs";
+import { DevstackPlaywrightBaseConfigOptions, DevstackPlaywrightEndpointOptions, DevstackPlaywrightProjectsOptions, DevstackPlaywrightUseOptions, PlaywrightBaseConfigShape, PlaywrightProjectShape, PlaywrightUseConfigShape, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, resolveDevstackPlaywrightBaseURL } from "./config.mjs";
 import { DAPP_KIT_SLOT, DevAccount, PlaywrightPageLike, SignTxRequest, SignTxResponse, WalletAdapter, WalletAdapterOptions, connectAs, createWalletAdapter, loadStackManifest, selectAccount } from "./wallet-context.mjs";
 import { PlaywrightEndpointNotFoundError, PlaywrightIntegrationError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, PlaywrightWalletAdapterError } from "./errors.mjs";
-export { DAPP_KIT_SLOT, type DefineGlobalSetupOptions, type DevAccount, type DevstackPlaywrightBaseConfigOptions, type DevstackPlaywrightEndpointOptions, type DevstackPlaywrightProjectsOptions, type DevstackPlaywrightUseOptions, type DevstackPlaywrightWebServerOptions, PLAYWRIGHT_ENV, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, type PlaywrightBaseConfigShape, PlaywrightEndpointNotFoundError, type PlaywrightGlobalSetup, type PlaywrightIntegrationError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, type PlaywrightPageLike, type PlaywrightProjectShape, type PlaywrightStackFixture, type PlaywrightUseConfigShape, PlaywrightWalletAdapterError, type PlaywrightWebServerConfigShape, type ResolveStackContextOptions, type ResolvedEndpoint, STACK_CONTEXT_SLOT, type SignTxRequest, type SignTxResponse, type StackContext, WALLET_ENDPOINT_KEY, type WalletAdapter, type WalletAdapterOptions, buildGlobalSetup, connectAs, conventionalUrlFor, createWalletAdapter, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, discoverManifestPath, loadStackManifest, makeStackContext, readManifestSync, readStackContext, readStashedFixture, resolveDevstackPlaywrightBaseURL, resolveEndpointUrl, selectAccount };
+export { DAPP_KIT_SLOT, type DefineGlobalSetupOptions, type DevAccount, type DevstackPlaywrightBaseConfigOptions, type DevstackPlaywrightEndpointOptions, type DevstackPlaywrightProjectsOptions, type DevstackPlaywrightUseOptions, PLAYWRIGHT_ENV, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, type PlaywrightBaseConfigShape, PlaywrightEndpointNotFoundError, type PlaywrightGlobalSetup, type PlaywrightIntegrationError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, type PlaywrightPageLike, type PlaywrightProjectShape, type PlaywrightStackFixture, type PlaywrightUseConfigShape, PlaywrightWalletAdapterError, type ResolveStackContextOptions, type ResolvedEndpoint, STACK_CONTEXT_SLOT, type SignTxRequest, type SignTxResponse, type StackContext, WALLET_ENDPOINT_KEY, type WalletAdapter, type WalletAdapterOptions, buildGlobalSetup, connectAs, conventionalUrlFor, createWalletAdapter, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, discoverManifestPath, loadStackManifest, makeStackContext, readManifestSync, readStackContext, readStashedFixture, resolveDevstackPlaywrightBaseURL, resolveEndpointUrl, selectAccount };

package/dist/build-integrations/playwright/index.mjs

@@ -2,7 +2,7 @@ import { WALLET_ENDPOINT_KEY } from "../../contracts/wallet-protocol.mjs";
 import { PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY } from "../runtime/playwright-stack-context-slot.mjs";
 import { PlaywrightEndpointNotFoundError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, PlaywrightWalletAdapterError } from "./errors.mjs";
 import { PLAYWRIGHT_ENV, conventionalUrlFor, discoverManifestPath, makeStackContext, readManifestSync, readStackContext, resolveEndpointUrl } from "./stack-context.mjs";
-import { devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, resolveDevstackPlaywrightBaseURL } from "./config.mjs";
+import { devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, resolveDevstackPlaywrightBaseURL } from "./config.mjs";
 import { STACK_CONTEXT_SLOT, buildGlobalSetup, readStashedFixture } from "./global-setup.mjs";
 import { DAPP_KIT_SLOT, connectAs, createWalletAdapter, loadStackManifest, selectAccount } from "./wallet-context.mjs";
-export { DAPP_KIT_SLOT, PLAYWRIGHT_ENV, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, PlaywrightEndpointNotFoundError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, PlaywrightWalletAdapterError, STACK_CONTEXT_SLOT, WALLET_ENDPOINT_KEY, buildGlobalSetup, connectAs, conventionalUrlFor, createWalletAdapter, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, devstackPlaywrightWebServer, discoverManifestPath, loadStackManifest, makeStackContext, readManifestSync, readStackContext, readStashedFixture, resolveDevstackPlaywrightBaseURL, resolveEndpointUrl, selectAccount };
+export { DAPP_KIT_SLOT, PLAYWRIGHT_ENV, PLAYWRIGHT_STACK_CONTEXT_SLOT_KEY, PlaywrightEndpointNotFoundError, PlaywrightManifestDiscoveryError, PlaywrightManifestShapeError, PlaywrightWalletAdapterError, STACK_CONTEXT_SLOT, WALLET_ENDPOINT_KEY, buildGlobalSetup, connectAs, conventionalUrlFor, createWalletAdapter, devstackPlaywrightBaseConfig, devstackPlaywrightProjects, devstackPlaywrightUse, discoverManifestPath, loadStackManifest, makeStackContext, readManifestSync, readStackContext, readStashedFixture, resolveDevstackPlaywrightBaseURL, resolveEndpointUrl, selectAccount };

package/dist/build-integrations/playwright/stack-context.d.mts

@@ -17,7 +17,9 @@ interface ResolveStackContextOptions {
   /** Explicit `<stateDir>` root override. Combined with `stack` to
    *  form `<root>/stacks/<stack>/manifest.json`. */
   readonly stateDir?: string;
-  /** Stack name override. Defaults to env `DEVSTACK_STACK`. */
+  /** Stack name override. Defaults to env `DEVSTACK_STACK`, then the
+   *  nearest package.json `name` above `cwd` (the CLI's stack-
+   *  inference rung), then `'main'`. */
   readonly stack?: string;
   /** Env bag (defaults to `process.env`). Injectable for tests. */
   readonly env?: Readonly<Record<string, string | undefined>>;

package/dist/build-integrations/playwright/stack-context.mjs

@@ -36,15 +36,17 @@ const endpointRegistryFromEnvelope = (envelope) => {
 };
 const buildRuntimeDiscoverOpts = (options) => {
 	const env = options.env ?? process.env;
+	const cwd = options.cwd ?? process.cwd();
 	const { stack, stateDir } = resolveDiscoveryEnv(env, {
 		...options.stack !== void 0 ? { stack: options.stack } : {},
-		...options.stateDir !== void 0 ? { stateDir: options.stateDir } : {}
+		...options.stateDir !== void 0 ? { stateDir: options.stateDir } : {},
+		cwd
 	});
 	return {
 		env,
 		stack,
 		stateDir,
-		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+		cwd,
 		...options.manifestPath !== void 0 ? { override: options.manifestPath } : {}
 	};
 };

package/dist/build-integrations/playwright/stack-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stack-context.mjs","names":["runtimeDiscoverManifestPath","readStackContextRuntime","runtimeColdStartUrl"],"sources":["../../../src/build-integrations/playwright/stack-context.ts"],"sourcesContent":["// Stack-context surface for the Playwright preset — thin wrapper\n// over `runtime/`'s sync read API.\n//\n// Playwright config-load is synchronous; it runs BEFORE the supervisor\n// spawns, so the preset MUST support a cold-start fallback that picks\n// a conventional URL when the manifest isn't on disk yet. The\n// decode + version-gate + walk-up live in `runtime/`; this surface\n// re-shapes the result into playwright-flavored typed errors and the\n// endpoint-name accessors in-spec helpers use.\n\nimport {\n\tDEFAULT_ROUTER_ENTRYPOINT_PORT,\n\tbuiltInConventionalRoutes,\n\tdiscoverManifestPath as runtimeDiscoverManifestPath,\n\tcoldStartUrl as runtimeColdStartUrl,\n\tEndpointRegistry,\n\tmanifestEnvelopeFromStackContext,\n\tManifestDiscoveryError,\n\tManifestShapeError,\n\treadStackContext as readStackContextRuntime,\n\tresolveBuiltInEndpointAlias,\n\tresolveDiscoveryEnv,\n\ttype DiscoverManifestPathOptions,\n\ttype EndpointEntry,\n\ttype ManifestEnvelope,\n\ttype ResolvedEndpoint as RuntimeResolvedEndpoint,\n\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport {\n\tPlaywrightEndpointNotFoundError,\n\tPlaywrightManifestDiscoveryError,\n\tPlaywrightManifestShapeError,\n} from './errors.ts';\n\n/** Centralized env-var names this surface consults. Kept in sync with\n *  the CLI's `ENV_VARS` table. */\nexport const PLAYWRIGHT_ENV = {\n\tSTATE_DIR: 'DEVSTACK_STATE_DIR',\n\tSTACK: 'DEVSTACK_STACK',\n\tMANIFEST_PATH: 'DEVSTACK_MANIFEST_PATH',\n\tROUTER_HOST_SUFFIX: 'DEVSTACK_ROUTER_HOST_SUFFIX',\n\tROUTER_PORT: 'DEVSTACK_ROUTER_PORT',\n} as const;\n\nexport interface ResolveStackContextOptions {\n\t/** Working directory to start the walk-up from. */\n\treadonly cwd?: string;\n\t/** Explicit manifest path. Wins over discovery + env. */\n\treadonly manifestPath?: string;\n\t/** Explicit `<stateDir>` root override. Combined with `stack` to\n\t *  form `<root>/stacks/<stack>/manifest.json`. */\n\treadonly stateDir?: string;\n\t/** Stack name override. Defaults to env `DEVSTACK_STACK`. */\n\treadonly stack?: string;\n\t/** Env bag (defaults to `process.env`). Injectable for tests. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n}\n\nexport interface StackContext {\n\treadonly manifest: ManifestEnvelope;\n\treadonly manifestPath: string;\n\treadonly endpointNames: ReadonlyArray<string>;\n\treadonly manifestEndpointKeys: ReadonlyArray<string>;\n\treadonly endpoint: (endpointNameOrAlias: string) => string;\n\treadonly endpointMaybe: (endpointNameOrAlias: string) => string | null;\n\treadonly endpointEntry: (endpointNameOrAlias: string) => EndpointEntry;\n}\n\nexport interface ResolvedEndpoint {\n\treadonly url: string;\n\treadonly source: 'manifest' | 'conventional';\n\treadonly endpointKey: string;\n\treadonly endpointName: string;\n}\n\n// Endpoint aliases + default port live in `runtime/conventional-routes.ts`\n// so vitest / Playwright / any future build integration share one table.\n// Playwright contributes nothing of its own here — every per-endpoint\n// fact is substrate-supplied.\n\n/** Resolve a user-typed endpoint name or alias to the canonical\n *  endpoint name the manifest stores. Delegates to the canonical\n *  alias resolver in `runtime/conventional-routes.ts` so vitest and\n *  Playwright share one alias table. */\nexport const playwrightEndpointNameFor = (endpointNameOrAlias: string): string =>\n\tresolveBuiltInEndpointAlias(endpointNameOrAlias);\n\nconst endpointRegistryFromEnvelope = (envelope: ManifestEnvelope): EndpointRegistry => {\n\tconst entries: RuntimeResolvedEndpoint[] = [];\n\tfor (const raw of Object.values(envelope.endpoints)) {\n\t\tentries.push({\n\t\t\tname: raw.name,\n\t\t\turl: raw.url,\n\t\t\tdisplayUrl: raw.displayUrl,\n\t\t\twireProtocol: raw.wireProtocol,\n\t\t\tpluginKey: raw.pluginKey,\n\t\t\tendpointKey: raw.endpointKey,\n\t\t});\n\t}\n\treturn new EndpointRegistry(entries);\n};\n\n// -----------------------------------------------------------------------------\n// Discovery\n// -----------------------------------------------------------------------------\n\nconst buildRuntimeDiscoverOpts = (\n\toptions: ResolveStackContextOptions,\n): DiscoverManifestPathOptions => {\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\t// Shared ladder: option > DEVSTACK_RUNTIME_ROOT > DEVSTACK_STATE_DIR\n\t// > '.devstack'. This surface previously read only DEVSTACK_STATE_DIR\n\t// and silently ignored DEVSTACK_RUNTIME_ROOT — routing through\n\t// `resolveDiscoveryEnv` aligns it with the vitest + runtime surfaces.\n\tconst { stack, stateDir } = resolveDiscoveryEnv(env, {\n\t\t...(options.stack !== undefined ? { stack: options.stack } : {}),\n\t\t...(options.stateDir !== undefined ? { stateDir: options.stateDir } : {}),\n\t});\n\treturn {\n\t\tenv,\n\t\tstack,\n\t\tstateDir,\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t...(options.manifestPath !== undefined ? { override: options.manifestPath } : {}),\n\t};\n};\n\n/**\n * Find the stack-scoped manifest by walking up from `cwd` looking for\n * `.devstack/stacks/<stack>/manifest.json`. Returns the absolute path\n * + the list of paths probed, or `null` on miss.\n */\nexport const discoverManifestPath = (\n\toptions: ResolveStackContextOptions = {},\n): { readonly path: string; readonly searched: ReadonlyArray<string> } | null => {\n\tconst path = runtimeDiscoverManifestPath(buildRuntimeDiscoverOpts(options));\n\tif (path === undefined) return null;\n\t// Runtime resolver doesn't surface intermediate probe paths today.\n\t// We expose the resolved path in the `searched` array so the\n\t// PlaywrightManifestDiscoveryError can still cite at least one\n\t// concrete path.\n\treturn { path, searched: [path] };\n};\n\n// -----------------------------------------------------------------------------\n// Synchronous read + decode\n// -----------------------------------------------------------------------------\n\n/**\n * Synchronously read + decode the manifest at `manifestPath`. Throws\n * `PlaywrightManifestShapeError` on JSON-parse or schema-decode\n * failure, or version mismatch. Used by callers that already know\n * the path (preset's webServer.url resolution + global-setup).\n */\nexport const readManifestSync = (manifestPath: string): ManifestEnvelope => {\n\ttry {\n\t\treturn manifestEnvelopeFromStackContext(readStackContextRuntime({ manifestPath }));\n\t} catch (cause) {\n\t\tif (cause instanceof ManifestShapeError) {\n\t\t\tthrow new PlaywrightManifestShapeError({\n\t\t\t\tmessage:\n\t\t\t\t\tcause.phase === 'version'\n\t\t\t\t\t\t? `manifest at ${manifestPath} version mismatch: ${cause.message}`\n\t\t\t\t\t\t: `manifest at ${manifestPath} does not match the envelope schema`,\n\t\t\t\tmanifestPath,\n\t\t\t\tphase: cause.phase === 'version' ? 'version-mismatch' : 'shape',\n\t\t\t\trecoveryHint:\n\t\t\t\t\tcause.phase === 'version'\n\t\t\t\t\t\t? `Re-run \\`devstack up\\` to write a manifest at the current version, ` +\n\t\t\t\t\t\t\t`or upgrade @mysten-incubation/devstack to a build-integration ` +\n\t\t\t\t\t\t\t`that understands the new envelope.`\n\t\t\t\t\t\t: `Delete \\`${manifestPath}\\` and run \\`devstack up\\`. If the error ` +\n\t\t\t\t\t\t\t`persists, the build-integration is older than the supervisor.`,\n\t\t\t\tcause,\n\t\t\t});\n\t\t}\n\t\tif (cause instanceof ManifestDiscoveryError) {\n\t\t\t// A discovery error (missing file at a known path) is NOT a\n\t\t\t// shape error — surface the typed discovery tag so callers\n\t\t\t// can `catchTag` the two failure modes independently.\n\t\t\tthrow new PlaywrightManifestDiscoveryError({\n\t\t\t\tmessage:\n\t\t\t\t\tcause.message !== ''\n\t\t\t\t\t\t? cause.message\n\t\t\t\t\t\t: `manifest at ${manifestPath} could not be read`,\n\t\t\t\tsearchedPaths: cause.path !== undefined ? [cause.path] : [manifestPath],\n\t\t\t\trecoveryHint:\n\t\t\t\t\t`Confirm the file exists and is readable. Run \\`devstack up\\` to ` +\n\t\t\t\t\t`regenerate it if the supervisor was interrupted mid-write.`,\n\t\t\t});\n\t\t}\n\t\tthrow cause;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Conventional URL fallback\n// -----------------------------------------------------------------------------\n\n/**\n * Cold-start URL fallback for endpoints with a conventional host\n * pattern. Playwright config-load runs BEFORE the supervisor writes\n * the manifest; the preset MUST be able to resolve a `baseURL`\n * without a manifest read.\n *\n * The route table shape matches `runtime/coldStartUrl`; Playwright\n * only supplies its conventional endpoint hints while the shared\n * runtime helper owns host formatting.\n */\nexport const conventionalUrlFor = (\n\tendpointKey: string,\n\topts: {\n\t\treadonly stack?: string;\n\t\treadonly hostSuffix?: string;\n\t\treadonly port?: number;\n\t\treadonly app?: string;\n\t\treadonly cwd?: string;\n\t\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t} = {},\n): string | null => {\n\tconst stack = opts.stack ?? 'main';\n\tconst env = opts.env ?? (process.env as Record<string, string | undefined>);\n\tconst envPort = Number.parseInt(env[PLAYWRIGHT_ENV.ROUTER_PORT] ?? '', 10);\n\tconst resolvedPort =\n\t\topts.port ??\n\t\t(Number.isFinite(envPort) && envPort > 0 ? envPort : undefined) ??\n\t\tDEFAULT_ROUTER_ENTRYPOINT_PORT;\n\n\tif (!Number.isFinite(resolvedPort) || resolvedPort <= 0) {\n\t\treturn null;\n\t}\n\n\tconst routes = builtInConventionalRoutes(resolvedPort);\n\tif (!routes.has(endpointKey)) return null;\n\n\treturn runtimeColdStartUrl(endpointKey, {\n\t\troutes,\n\t\tstack,\n\t\t...(opts.app !== undefined ? { app: opts.app } : {}),\n\t\t...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\t// Thread the caller env bag so `runtimeColdStartUrl` resolves\n\t\t// `DEVSTACK_STACK` / `DEVSTACK_APP` from the test-injected\n\t\t// fixture rather than silently falling back to `process.env`.\n\t\t...(opts.env !== undefined ? { env: opts.env } : {}),\n\t});\n};\n\n// -----------------------------------------------------------------------------\n// Public readers\n// -----------------------------------------------------------------------------\n\n/**\n * Synchronously resolve the full stack context. Throws on missing\n * manifest (no cold-start fallback here — caller wants the typed\n * envelope, not a guessed URL).\n */\nexport const readStackContext = (options: ResolveStackContextOptions = {}): StackContext => {\n\ttry {\n\t\tconst ctx = readStackContextRuntime(buildRuntimeDiscoverOpts(options));\n\t\treturn projectFromRuntime(ctx);\n\t} catch (err) {\n\t\tif (err instanceof ManifestDiscoveryError) {\n\t\t\tthrow new PlaywrightManifestDiscoveryError({\n\t\t\t\tmessage: 'no manifest found along walk-up path or env override',\n\t\t\t\tsearchedPaths: err.path !== undefined ? [err.path] : [],\n\t\t\t\trecoveryHint:\n\t\t\t\t\t`Run \\`devstack up\\` from your example app's directory to write ` +\n\t\t\t\t\t`the manifest, or set DEVSTACK_MANIFEST_PATH to an explicit path.`,\n\t\t\t});\n\t\t}\n\t\tif (err instanceof ManifestShapeError) {\n\t\t\tthrow new PlaywrightManifestShapeError({\n\t\t\t\tmessage: err.message,\n\t\t\t\tmanifestPath: err.path,\n\t\t\t\tphase: err.phase === 'version' ? 'version-mismatch' : err.phase,\n\t\t\t\trecoveryHint: `Delete \\`${err.path}\\` and run \\`devstack up\\` to regenerate.`,\n\t\t\t\tcause: err,\n\t\t\t});\n\t\t}\n\t\tthrow err;\n\t}\n};\n\nconst projectFromRuntime = (ctx: RuntimeStackContext): StackContext => {\n\tconst envelope = manifestEnvelopeFromStackContext(ctx);\n\treturn makeStackContext(envelope, ctx.manifestPath);\n};\n\n/** Project an in-memory envelope (test fixtures use this) into the\n *  same accessor shape as the on-disk read. */\nexport const makeStackContext = (\n\tenvelope: ManifestEnvelope,\n\tmanifestPath: string,\n): StackContext => {\n\tconst endpoints = endpointRegistryFromEnvelope(envelope);\n\tconst manifestEndpointKeys = Object.keys(envelope.endpoints).sort();\n\tconst endpointNames = endpoints.names();\n\tconst notFound = (endpointKey: string, endpointName: string): PlaywrightEndpointNotFoundError =>\n\t\tnew PlaywrightEndpointNotFoundError({\n\t\t\tmessage:\n\t\t\t\t`no endpoint \\`${endpointKey}\\` (resolved endpoint name \\`${endpointName}\\`) ` +\n\t\t\t\t`in manifest at ${manifestPath}`,\n\t\t\tendpointKey,\n\t\t\tendpointName,\n\t\t\tavailable: endpointNames,\n\t\t\tmanifestKeys: manifestEndpointKeys,\n\t\t\trecoveryHint:\n\t\t\t\t`Available endpoint names: ${endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t`Raw manifest keys: ${manifestEndpointKeys.join(', ') || '(none)'}. ` +\n\t\t\t\t`Check the plugin emitting this endpoint is present in your stack, ` +\n\t\t\t\t`or check for a typo in the endpoint name.`,\n\t\t});\n\tconst findEndpoint = (endpointNameOrAlias: string): RuntimeResolvedEndpoint | undefined =>\n\t\tendpoints.byName(playwrightEndpointNameFor(endpointNameOrAlias));\n\tconst rawEntryFor = (resolved: RuntimeResolvedEndpoint): EndpointEntry => {\n\t\tconst byMapKey = envelope.endpoints[resolved.endpointKey];\n\t\tif (byMapKey !== undefined) return byMapKey;\n\t\tconst byEntryKey = Object.values(envelope.endpoints).find(\n\t\t\t(entry) => entry.endpointKey === resolved.endpointKey,\n\t\t);\n\t\tif (byEntryKey !== undefined) return byEntryKey;\n\t\treturn {\n\t\t\tname: resolved.name,\n\t\t\turl: resolved.url,\n\t\t\tdisplayUrl: resolved.displayUrl,\n\t\t\twireProtocol: resolved.wireProtocol,\n\t\t\tpluginKey: resolved.pluginKey,\n\t\t\tendpointKey: resolved.endpointKey,\n\t\t};\n\t};\n\n\treturn {\n\t\tmanifest: envelope,\n\t\tmanifestPath,\n\t\tendpointNames,\n\t\tmanifestEndpointKeys,\n\t\tendpoint: (endpointNameOrAlias: string): string => {\n\t\t\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\t\t\tconst entry = findEndpoint(endpointNameOrAlias);\n\t\t\tif (entry === undefined) {\n\t\t\t\tthrow notFound(endpointNameOrAlias, endpointName);\n\t\t\t}\n\t\t\treturn entry.url;\n\t\t},\n\t\tendpointMaybe: (endpointNameOrAlias: string): string | null =>\n\t\t\tfindEndpoint(endpointNameOrAlias)?.url ?? null,\n\t\tendpointEntry: (endpointNameOrAlias: string): EndpointEntry => {\n\t\t\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\t\t\tconst entry = findEndpoint(endpointNameOrAlias);\n\t\t\tif (entry === undefined) {\n\t\t\t\tthrow notFound(endpointNameOrAlias, endpointName);\n\t\t\t}\n\t\t\treturn rawEntryFor(entry);\n\t\t},\n\t};\n};\n\n/**\n * Resolve a URL for a single endpoint with cold-start fallback to the\n * conventional URL when the manifest is absent. Throws when both the\n * manifest and the conventional table miss.\n */\nexport const resolveEndpointUrl = (\n\tendpointNameOrAlias: string,\n\toptions: ResolveStackContextOptions & {\n\t\treadonly port?: number;\n\t\treadonly hostSuffix?: string;\n\t} = {},\n): ResolvedEndpoint => {\n\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\tlet ctx: StackContext | undefined;\n\ttry {\n\t\tctx = readStackContext(options);\n\t} catch (err) {\n\t\tif (!(err instanceof PlaywrightManifestDiscoveryError)) throw err;\n\t}\n\tif (ctx !== undefined) {\n\t\tconst entry = ctx.endpointEntry(endpointNameOrAlias);\n\t\treturn { url: entry.url, source: 'manifest', endpointKey: entry.endpointKey, endpointName };\n\t}\n\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\tconst stack = options.stack ?? env[PLAYWRIGHT_ENV.STACK] ?? 'main';\n\tconst fallback = conventionalUrlFor(endpointNameOrAlias, {\n\t\tstack,\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t...(options.hostSuffix !== undefined\n\t\t\t? { hostSuffix: options.hostSuffix }\n\t\t\t: env[PLAYWRIGHT_ENV.ROUTER_HOST_SUFFIX] !== undefined\n\t\t\t\t? { hostSuffix: env[PLAYWRIGHT_ENV.ROUTER_HOST_SUFFIX] }\n\t\t\t\t: {}),\n\t\t...(options.port !== undefined ? { port: options.port } : {}),\n\t\t...(options.env !== undefined ? { env: options.env } : {}),\n\t});\n\tif (fallback !== null) {\n\t\treturn {\n\t\t\turl: fallback,\n\t\t\tsource: 'conventional',\n\t\t\tendpointKey: endpointNameOrAlias,\n\t\t\tendpointName,\n\t\t};\n\t}\n\n\tthrow new PlaywrightManifestDiscoveryError({\n\t\tmessage:\n\t\t\t`no manifest found and no conventional fallback for endpoint ` +\n\t\t\t`\\`${endpointNameOrAlias}\\` (resolved endpoint name \\`${endpointName}\\`)`,\n\t\tsearchedPaths: [],\n\t\tendpointKey: endpointNameOrAlias,\n\t\trecoveryHint:\n\t\t\t`Run \\`devstack up\\` to materialize the manifest before invoking ` +\n\t\t\t`playwright, or pass an explicit \\`baseURL\\`.`,\n\t});\n};\n"],"mappings":"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"}
+{"version":3,"file":"stack-context.mjs","names":["runtimeDiscoverManifestPath","readStackContextRuntime","runtimeColdStartUrl"],"sources":["../../../src/build-integrations/playwright/stack-context.ts"],"sourcesContent":["// Stack-context surface for the Playwright preset — thin wrapper\n// over `runtime/`'s sync read API.\n//\n// Playwright config-load is synchronous; it runs BEFORE the supervisor\n// spawns, so the preset MUST support a cold-start fallback that picks\n// a conventional URL when the manifest isn't on disk yet. The\n// decode + version-gate + walk-up live in `runtime/`; this surface\n// re-shapes the result into playwright-flavored typed errors and the\n// endpoint-name accessors in-spec helpers use.\n\nimport {\n\tDEFAULT_ROUTER_ENTRYPOINT_PORT,\n\tbuiltInConventionalRoutes,\n\tdiscoverManifestPath as runtimeDiscoverManifestPath,\n\tcoldStartUrl as runtimeColdStartUrl,\n\tEndpointRegistry,\n\tmanifestEnvelopeFromStackContext,\n\tManifestDiscoveryError,\n\tManifestShapeError,\n\treadStackContext as readStackContextRuntime,\n\tresolveBuiltInEndpointAlias,\n\tresolveDiscoveryEnv,\n\ttype DiscoverManifestPathOptions,\n\ttype EndpointEntry,\n\ttype ManifestEnvelope,\n\ttype ResolvedEndpoint as RuntimeResolvedEndpoint,\n\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport {\n\tPlaywrightEndpointNotFoundError,\n\tPlaywrightManifestDiscoveryError,\n\tPlaywrightManifestShapeError,\n} from './errors.ts';\n\n/** Centralized env-var names this surface consults. Kept in sync with\n *  the CLI's `ENV_VARS` table. */\nexport const PLAYWRIGHT_ENV = {\n\tSTATE_DIR: 'DEVSTACK_STATE_DIR',\n\tSTACK: 'DEVSTACK_STACK',\n\tMANIFEST_PATH: 'DEVSTACK_MANIFEST_PATH',\n\tROUTER_HOST_SUFFIX: 'DEVSTACK_ROUTER_HOST_SUFFIX',\n\tROUTER_PORT: 'DEVSTACK_ROUTER_PORT',\n} as const;\n\nexport interface ResolveStackContextOptions {\n\t/** Working directory to start the walk-up from. */\n\treadonly cwd?: string;\n\t/** Explicit manifest path. Wins over discovery + env. */\n\treadonly manifestPath?: string;\n\t/** Explicit `<stateDir>` root override. Combined with `stack` to\n\t *  form `<root>/stacks/<stack>/manifest.json`. */\n\treadonly stateDir?: string;\n\t/** Stack name override. Defaults to env `DEVSTACK_STACK`, then the\n\t *  nearest package.json `name` above `cwd` (the CLI's stack-\n\t *  inference rung), then `'main'`. */\n\treadonly stack?: string;\n\t/** Env bag (defaults to `process.env`). Injectable for tests. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n}\n\nexport interface StackContext {\n\treadonly manifest: ManifestEnvelope;\n\treadonly manifestPath: string;\n\treadonly endpointNames: ReadonlyArray<string>;\n\treadonly manifestEndpointKeys: ReadonlyArray<string>;\n\treadonly endpoint: (endpointNameOrAlias: string) => string;\n\treadonly endpointMaybe: (endpointNameOrAlias: string) => string | null;\n\treadonly endpointEntry: (endpointNameOrAlias: string) => EndpointEntry;\n}\n\nexport interface ResolvedEndpoint {\n\treadonly url: string;\n\treadonly source: 'manifest' | 'conventional';\n\treadonly endpointKey: string;\n\treadonly endpointName: string;\n}\n\n// Endpoint aliases + default port live in `runtime/conventional-routes.ts`\n// so vitest / Playwright / any future build integration share one table.\n// Playwright contributes nothing of its own here — every per-endpoint\n// fact is substrate-supplied.\n\n/** Resolve a user-typed endpoint name or alias to the canonical\n *  endpoint name the manifest stores. Delegates to the canonical\n *  alias resolver in `runtime/conventional-routes.ts` so vitest and\n *  Playwright share one alias table. */\nexport const playwrightEndpointNameFor = (endpointNameOrAlias: string): string =>\n\tresolveBuiltInEndpointAlias(endpointNameOrAlias);\n\nconst endpointRegistryFromEnvelope = (envelope: ManifestEnvelope): EndpointRegistry => {\n\tconst entries: RuntimeResolvedEndpoint[] = [];\n\tfor (const raw of Object.values(envelope.endpoints)) {\n\t\tentries.push({\n\t\t\tname: raw.name,\n\t\t\turl: raw.url,\n\t\t\tdisplayUrl: raw.displayUrl,\n\t\t\twireProtocol: raw.wireProtocol,\n\t\t\tpluginKey: raw.pluginKey,\n\t\t\tendpointKey: raw.endpointKey,\n\t\t});\n\t}\n\treturn new EndpointRegistry(entries);\n};\n\n// -----------------------------------------------------------------------------\n// Discovery\n// -----------------------------------------------------------------------------\n\nconst buildRuntimeDiscoverOpts = (\n\toptions: ResolveStackContextOptions,\n): DiscoverManifestPathOptions => {\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\tconst cwd = options.cwd ?? process.cwd();\n\t// Shared ladder: option > DEVSTACK_RUNTIME_ROOT > DEVSTACK_STATE_DIR\n\t// > '.devstack'. Routing through `resolveDiscoveryEnv` keeps this\n\t// surface aligned with the vitest + runtime surfaces. The stack rung\n\t// threads the walk-up start so the package-name inference (the CLI's\n\t// `resolveStackName` rung) applies before the 'main' fallback.\n\tconst { stack, stateDir } = resolveDiscoveryEnv(env, {\n\t\t...(options.stack !== undefined ? { stack: options.stack } : {}),\n\t\t...(options.stateDir !== undefined ? { stateDir: options.stateDir } : {}),\n\t\tcwd,\n\t});\n\treturn {\n\t\tenv,\n\t\tstack,\n\t\tstateDir,\n\t\tcwd,\n\t\t...(options.manifestPath !== undefined ? { override: options.manifestPath } : {}),\n\t};\n};\n\n/**\n * Find the stack-scoped manifest by walking up from `cwd` looking for\n * `.devstack/stacks/<stack>/manifest.json`. Returns the absolute path\n * + the list of paths probed, or `null` on miss.\n */\nexport const discoverManifestPath = (\n\toptions: ResolveStackContextOptions = {},\n): { readonly path: string; readonly searched: ReadonlyArray<string> } | null => {\n\tconst path = runtimeDiscoverManifestPath(buildRuntimeDiscoverOpts(options));\n\tif (path === undefined) return null;\n\t// Runtime resolver doesn't surface intermediate probe paths today.\n\t// We expose the resolved path in the `searched` array so the\n\t// PlaywrightManifestDiscoveryError can still cite at least one\n\t// concrete path.\n\treturn { path, searched: [path] };\n};\n\n// -----------------------------------------------------------------------------\n// Synchronous read + decode\n// -----------------------------------------------------------------------------\n\n/**\n * Synchronously read + decode the manifest at `manifestPath`. Throws\n * `PlaywrightManifestShapeError` on JSON-parse or schema-decode\n * failure, or version mismatch. Used by callers that already know\n * the path (preset's webServer.url resolution + global-setup).\n */\nexport const readManifestSync = (manifestPath: string): ManifestEnvelope => {\n\ttry {\n\t\treturn manifestEnvelopeFromStackContext(readStackContextRuntime({ manifestPath }));\n\t} catch (cause) {\n\t\tif (cause instanceof ManifestShapeError) {\n\t\t\tthrow new PlaywrightManifestShapeError({\n\t\t\t\tmessage:\n\t\t\t\t\tcause.phase === 'version'\n\t\t\t\t\t\t? `manifest at ${manifestPath} version mismatch: ${cause.message}`\n\t\t\t\t\t\t: `manifest at ${manifestPath} does not match the envelope schema`,\n\t\t\t\tmanifestPath,\n\t\t\t\tphase: cause.phase === 'version' ? 'version-mismatch' : 'shape',\n\t\t\t\trecoveryHint:\n\t\t\t\t\tcause.phase === 'version'\n\t\t\t\t\t\t? `Re-run \\`devstack up\\` to write a manifest at the current version, ` +\n\t\t\t\t\t\t\t`or upgrade @mysten-incubation/devstack to a build-integration ` +\n\t\t\t\t\t\t\t`that understands the new envelope.`\n\t\t\t\t\t\t: `Delete \\`${manifestPath}\\` and run \\`devstack up\\`. If the error ` +\n\t\t\t\t\t\t\t`persists, the build-integration is older than the supervisor.`,\n\t\t\t\tcause,\n\t\t\t});\n\t\t}\n\t\tif (cause instanceof ManifestDiscoveryError) {\n\t\t\t// A discovery error (missing file at a known path) is NOT a\n\t\t\t// shape error — surface the typed discovery tag so callers\n\t\t\t// can `catchTag` the two failure modes independently.\n\t\t\tthrow new PlaywrightManifestDiscoveryError({\n\t\t\t\tmessage:\n\t\t\t\t\tcause.message !== '' ? cause.message : `manifest at ${manifestPath} could not be read`,\n\t\t\t\tsearchedPaths: cause.path !== undefined ? [cause.path] : [manifestPath],\n\t\t\t\trecoveryHint:\n\t\t\t\t\t`Confirm the file exists and is readable. Run \\`devstack up\\` to ` +\n\t\t\t\t\t`regenerate it if the supervisor was interrupted mid-write.`,\n\t\t\t});\n\t\t}\n\t\tthrow cause;\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Conventional URL fallback\n// -----------------------------------------------------------------------------\n\n/**\n * Cold-start URL fallback for endpoints with a conventional host\n * pattern. Playwright config-load runs BEFORE the supervisor writes\n * the manifest; the preset MUST be able to resolve a `baseURL`\n * without a manifest read.\n *\n * The route table shape matches `runtime/coldStartUrl`; Playwright\n * only supplies its conventional endpoint hints while the shared\n * runtime helper owns host formatting.\n */\nexport const conventionalUrlFor = (\n\tendpointKey: string,\n\topts: {\n\t\treadonly stack?: string;\n\t\treadonly hostSuffix?: string;\n\t\treadonly port?: number;\n\t\treadonly app?: string;\n\t\treadonly cwd?: string;\n\t\treadonly env?: Readonly<Record<string, string | undefined>>;\n\t} = {},\n): string | null => {\n\tconst stack = opts.stack ?? 'main';\n\tconst env = opts.env ?? (process.env as Record<string, string | undefined>);\n\tconst envPort = Number.parseInt(env[PLAYWRIGHT_ENV.ROUTER_PORT] ?? '', 10);\n\tconst resolvedPort =\n\t\topts.port ??\n\t\t(Number.isFinite(envPort) && envPort > 0 ? envPort : undefined) ??\n\t\tDEFAULT_ROUTER_ENTRYPOINT_PORT;\n\n\tif (!Number.isFinite(resolvedPort) || resolvedPort <= 0) {\n\t\treturn null;\n\t}\n\n\tconst routes = builtInConventionalRoutes(resolvedPort);\n\tif (!routes.has(endpointKey)) return null;\n\n\treturn runtimeColdStartUrl(endpointKey, {\n\t\troutes,\n\t\tstack,\n\t\t...(opts.app !== undefined ? { app: opts.app } : {}),\n\t\t...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\t// Thread the caller env bag so `runtimeColdStartUrl` resolves\n\t\t// `DEVSTACK_STACK` / `DEVSTACK_APP` from the test-injected\n\t\t// fixture rather than silently falling back to `process.env`.\n\t\t...(opts.env !== undefined ? { env: opts.env } : {}),\n\t});\n};\n\n// -----------------------------------------------------------------------------\n// Public readers\n// -----------------------------------------------------------------------------\n\n/**\n * Synchronously resolve the full stack context. Throws on missing\n * manifest (no cold-start fallback here — caller wants the typed\n * envelope, not a guessed URL).\n */\nexport const readStackContext = (options: ResolveStackContextOptions = {}): StackContext => {\n\ttry {\n\t\tconst ctx = readStackContextRuntime(buildRuntimeDiscoverOpts(options));\n\t\treturn projectFromRuntime(ctx);\n\t} catch (err) {\n\t\tif (err instanceof ManifestDiscoveryError) {\n\t\t\tthrow new PlaywrightManifestDiscoveryError({\n\t\t\t\tmessage: 'no manifest found along walk-up path or env override',\n\t\t\t\tsearchedPaths: err.path !== undefined ? [err.path] : [],\n\t\t\t\trecoveryHint:\n\t\t\t\t\t`Run \\`devstack up\\` from your example app's directory to write ` +\n\t\t\t\t\t`the manifest, or set DEVSTACK_MANIFEST_PATH to an explicit path.`,\n\t\t\t});\n\t\t}\n\t\tif (err instanceof ManifestShapeError) {\n\t\t\tthrow new PlaywrightManifestShapeError({\n\t\t\t\tmessage: err.message,\n\t\t\t\tmanifestPath: err.path,\n\t\t\t\tphase: err.phase === 'version' ? 'version-mismatch' : err.phase,\n\t\t\t\trecoveryHint: `Delete \\`${err.path}\\` and run \\`devstack up\\` to regenerate.`,\n\t\t\t\tcause: err,\n\t\t\t});\n\t\t}\n\t\tthrow err;\n\t}\n};\n\nconst projectFromRuntime = (ctx: RuntimeStackContext): StackContext => {\n\tconst envelope = manifestEnvelopeFromStackContext(ctx);\n\treturn makeStackContext(envelope, ctx.manifestPath);\n};\n\n/** Project an in-memory envelope (test fixtures use this) into the\n *  same accessor shape as the on-disk read. */\nexport const makeStackContext = (\n\tenvelope: ManifestEnvelope,\n\tmanifestPath: string,\n): StackContext => {\n\tconst endpoints = endpointRegistryFromEnvelope(envelope);\n\tconst manifestEndpointKeys = Object.keys(envelope.endpoints).sort();\n\tconst endpointNames = endpoints.names();\n\tconst notFound = (endpointKey: string, endpointName: string): PlaywrightEndpointNotFoundError =>\n\t\tnew PlaywrightEndpointNotFoundError({\n\t\t\tmessage:\n\t\t\t\t`no endpoint \\`${endpointKey}\\` (resolved endpoint name \\`${endpointName}\\`) ` +\n\t\t\t\t`in manifest at ${manifestPath}`,\n\t\t\tendpointKey,\n\t\t\tendpointName,\n\t\t\tavailable: endpointNames,\n\t\t\tmanifestKeys: manifestEndpointKeys,\n\t\t\trecoveryHint:\n\t\t\t\t`Available endpoint names: ${endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t`Raw manifest keys: ${manifestEndpointKeys.join(', ') || '(none)'}. ` +\n\t\t\t\t`Check the plugin emitting this endpoint is present in your stack, ` +\n\t\t\t\t`or check for a typo in the endpoint name.`,\n\t\t});\n\tconst findEndpoint = (endpointNameOrAlias: string): RuntimeResolvedEndpoint | undefined =>\n\t\tendpoints.byName(playwrightEndpointNameFor(endpointNameOrAlias));\n\tconst rawEntryFor = (resolved: RuntimeResolvedEndpoint): EndpointEntry => {\n\t\tconst byMapKey = envelope.endpoints[resolved.endpointKey];\n\t\tif (byMapKey !== undefined) return byMapKey;\n\t\tconst byEntryKey = Object.values(envelope.endpoints).find(\n\t\t\t(entry) => entry.endpointKey === resolved.endpointKey,\n\t\t);\n\t\tif (byEntryKey !== undefined) return byEntryKey;\n\t\treturn {\n\t\t\tname: resolved.name,\n\t\t\turl: resolved.url,\n\t\t\tdisplayUrl: resolved.displayUrl,\n\t\t\twireProtocol: resolved.wireProtocol,\n\t\t\tpluginKey: resolved.pluginKey,\n\t\t\tendpointKey: resolved.endpointKey,\n\t\t};\n\t};\n\n\treturn {\n\t\tmanifest: envelope,\n\t\tmanifestPath,\n\t\tendpointNames,\n\t\tmanifestEndpointKeys,\n\t\tendpoint: (endpointNameOrAlias: string): string => {\n\t\t\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\t\t\tconst entry = findEndpoint(endpointNameOrAlias);\n\t\t\tif (entry === undefined) {\n\t\t\t\tthrow notFound(endpointNameOrAlias, endpointName);\n\t\t\t}\n\t\t\treturn entry.url;\n\t\t},\n\t\tendpointMaybe: (endpointNameOrAlias: string): string | null =>\n\t\t\tfindEndpoint(endpointNameOrAlias)?.url ?? null,\n\t\tendpointEntry: (endpointNameOrAlias: string): EndpointEntry => {\n\t\t\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\t\t\tconst entry = findEndpoint(endpointNameOrAlias);\n\t\t\tif (entry === undefined) {\n\t\t\t\tthrow notFound(endpointNameOrAlias, endpointName);\n\t\t\t}\n\t\t\treturn rawEntryFor(entry);\n\t\t},\n\t};\n};\n\n/**\n * Resolve a URL for a single endpoint with cold-start fallback to the\n * conventional URL when the manifest is absent. Throws when both the\n * manifest and the conventional table miss.\n */\nexport const resolveEndpointUrl = (\n\tendpointNameOrAlias: string,\n\toptions: ResolveStackContextOptions & {\n\t\treadonly port?: number;\n\t\treadonly hostSuffix?: string;\n\t} = {},\n): ResolvedEndpoint => {\n\tconst endpointName = playwrightEndpointNameFor(endpointNameOrAlias);\n\tlet ctx: StackContext | undefined;\n\ttry {\n\t\tctx = readStackContext(options);\n\t} catch (err) {\n\t\tif (!(err instanceof PlaywrightManifestDiscoveryError)) throw err;\n\t}\n\tif (ctx !== undefined) {\n\t\tconst entry = ctx.endpointEntry(endpointNameOrAlias);\n\t\treturn { url: entry.url, source: 'manifest', endpointKey: entry.endpointKey, endpointName };\n\t}\n\n\tconst env = options.env ?? (process.env as Record<string, string | undefined>);\n\tconst stack = options.stack ?? env[PLAYWRIGHT_ENV.STACK] ?? 'main';\n\tconst fallback = conventionalUrlFor(endpointNameOrAlias, {\n\t\tstack,\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t...(options.hostSuffix !== undefined\n\t\t\t? { hostSuffix: options.hostSuffix }\n\t\t\t: env[PLAYWRIGHT_ENV.ROUTER_HOST_SUFFIX] !== undefined\n\t\t\t\t? { hostSuffix: env[PLAYWRIGHT_ENV.ROUTER_HOST_SUFFIX] }\n\t\t\t\t: {}),\n\t\t...(options.port !== undefined ? { port: options.port } : {}),\n\t\t...(options.env !== undefined ? { env: options.env } : {}),\n\t});\n\tif (fallback !== null) {\n\t\treturn {\n\t\t\turl: fallback,\n\t\t\tsource: 'conventional',\n\t\t\tendpointKey: endpointNameOrAlias,\n\t\t\tendpointName,\n\t\t};\n\t}\n\n\tthrow new PlaywrightManifestDiscoveryError({\n\t\tmessage:\n\t\t\t`no manifest found and no conventional fallback for endpoint ` +\n\t\t\t`\\`${endpointNameOrAlias}\\` (resolved endpoint name \\`${endpointName}\\`)`,\n\t\tsearchedPaths: [],\n\t\tendpointKey: endpointNameOrAlias,\n\t\trecoveryHint:\n\t\t\t`Run \\`devstack up\\` to materialize the manifest before invoking ` +\n\t\t\t`playwright, or pass an explicit \\`baseURL\\`.`,\n\t});\n};\n"],"mappings":"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"}

package/dist/build-integrations/playwright/wallet-context.mjs

@@ -88,6 +88,8 @@ const createWalletAdapter = (options = {}) => {
 *  canonical contract — kept here as a name alias for the
 *  in-spec-helpers' import path. */
 const DAPP_KIT_SLOT = DAPP_KIT_SLOT_KEY;
+const SELECT_ACCOUNT_SLOT_TIMEOUT_MS = 1e4;
+const SELECT_ACCOUNT_SLOT_POLL_MS = 50;
 /**
 * Connect/switch the app's active dev-wallet account through the dapp-kit
 * slot the app populates at boot.
@@ -113,27 +115,50 @@ const connectAs = async (page, accountName) => {
 * faster + less flaky than clicking the wallet's UI.
 */
 const selectAccount = async (page, accountName) => {
-	const result = await page.evaluate(async (name) => {
-		const slot = globalThis.__devstackDAppKit__;
-		if (slot === void 0 || slot.selectAccount === void 0) return {
-			ok: false,
-			reason: "slot-not-populated"
-		};
+	const deadline = Date.now() + SELECT_ACCOUNT_SLOT_TIMEOUT_MS;
+	let lastEvaluateError;
+	for (;;) {
+		let result;
 		try {
-			await slot.selectAccount(name);
-			return { ok: true };
-		} catch (err) {
-			return {
-				ok: false,
-				reason: err instanceof Error ? err.message : String(err)
-			};
+			result = await page.evaluate(async (name) => {
+				const slot = globalThis.__devstackDAppKit__;
+				if (slot === void 0 || slot.selectAccount === void 0) return {
+					ok: false,
+					reason: "slot-not-populated"
+				};
+				try {
+					await slot.selectAccount(name);
+					return { ok: true };
+				} catch (err) {
+					return {
+						ok: false,
+						reason: err instanceof Error ? err.message : String(err)
+					};
+				}
+			}, accountName);
+		} catch (cause) {
+			lastEvaluateError = cause;
+			if (Date.now() < deadline) {
+				await new Promise((resolve) => setTimeout(resolve, SELECT_ACCOUNT_SLOT_POLL_MS));
+				continue;
+			}
+			throw new PlaywrightWalletAdapterError({
+				message: `selectAccount("${accountName}") failed: page evaluation did not settle before ${SELECT_ACCOUNT_SLOT_TIMEOUT_MS}ms. Confirm the app finished loading before calling connectAs().`,
+				operation: "switch-account",
+				cause: lastEvaluateError
+			});
 		}
-	}, accountName);
-	if (!result.ok) throw new PlaywrightWalletAdapterError({
-		message: `selectAccount("${accountName}") failed: ${result.reason ?? "unknown"}. Confirm \`globalThis.${DAPP_KIT_SLOT}\` is populated by the app's dapp-kit module at boot.`,
-		operation: "switch-account",
-		cause: result.reason
-	});
+		if (result.ok) return;
+		if (result.reason === "slot-not-populated" && Date.now() < deadline) {
+			await new Promise((resolve) => setTimeout(resolve, SELECT_ACCOUNT_SLOT_POLL_MS));
+			continue;
+		}
+		throw new PlaywrightWalletAdapterError({
+			message: `selectAccount("${accountName}") failed: ${result.reason ?? "unknown"}. Confirm \`globalThis.${DAPP_KIT_SLOT}\` is populated by the app's dapp-kit module at boot.`,
+			operation: "switch-account",
+			cause: result.reason
+		});
+	}
 };
 /** Test-side accessor for the full manifest (already decoded). */
 const loadStackManifest = (options = {}) => readStackContext(options);

package/dist/build-integrations/playwright/wallet-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"wallet-context.mjs","names":[],"sources":["../../../src/build-integrations/playwright/wallet-context.ts"],"sourcesContent":["// Wallet-context test helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright /\n// \"What it produces\"):\n//\n//   In-spec helpers (`connectAs`, `selectAccount`) and the\n//   `loadStackManifest` artifact loader. (`loadStackKeypair` is not\n//   implemented — keys never leave the wallet plugin; tests sign via\n//   the wallet's HTTP API.)\n//\n// And (per the user task brief): tests sign txs via the wallet's HTTP\n// API rather than driving the browser's wallet-UI flow. That is the\n// load-bearing wallet-context contract: a tiny typed HTTP client over\n// the dev wallet's endpoint exposed in the manifest.\n//\n// Discipline:\n//   - This module performs NO browser interaction. The `page` arg in\n//     `connectAs` is the Playwright `Page` (kept structural — we do\n//     not import `@playwright/test`), but the helpers here only use\n//     it to expose the dev-wallet selection / account-switch flow\n//     through `evaluate`. The actual key handling stays server-side\n//     in the wallet plugin.\n//   - HTTP calls go through `fetch`. We do NOT pull in `@mysten/sui`\n//     here — txs are constructed by tests, serialized, and POSTed\n//     to the wallet for signing. The wallet plugin is the\n//     authoritative key holder.\n//   - Account-switch via the global slot (`globalThis.__devstackDAppKit__`)\n//     for dapp-kit-driven in-browser context; HTTP wallet helpers\n//     are the spec-level lower-friction path.\n\nimport {\n\treadStackContext,\n\ttype ResolveStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { readStashedFixture } from './global-setup.ts';\nimport { PlaywrightWalletAdapterError } from './errors.ts';\nimport { DAPP_KIT_SLOT_KEY, type DAppKitSlot } from '../runtime/dapp-kit-slot.ts';\n// The wallet plugin owns the wire-protocol path constants AND the\n// canonical endpoint name. Both are surfaced through the L5 runtime\n// bridge so this adapter never reaches into L2 plugin code directly\n// (ARCHITECTURE.md § Layer table — L5 reads only the runtime bridge).\nimport { WalletHttpPath, WALLET_ENDPOINT_KEY } from '../runtime/wallet-paths.ts';\n\n// -----------------------------------------------------------------------------\n// Structural Playwright `Page` shape — we keep `@playwright/test` an\n// optional peer.\n// -----------------------------------------------------------------------------\n\n/** Subset of `Page` we use. */\nexport interface PlaywrightPageLike {\n\treadonly evaluate: <T>(fn: (arg: unknown) => T, arg?: unknown) => Promise<T>;\n}\n\n// -----------------------------------------------------------------------------\n// Wallet adapter — HTTP client targeting the wallet plugin's endpoint\n// -----------------------------------------------------------------------------\n\n// `WALLET_ENDPOINT_KEY` is the short form Playwright/vitest helpers look\n// up — the manifest stores the canonical endpoint name\n// (`WALLET_ENDPOINT_NAME` — `'wallet-app'`) but the substrate's alias\n// resolver folds the key to the canonical name. Re-exported from the L5\n// runtime bridge so the spelling + canonical pairing stay aligned with\n// the wallet plugin.\nexport { WALLET_ENDPOINT_KEY };\n\nexport interface WalletAdapterOptions extends ResolveStackContextOptions {\n\t/** Override the resolved wallet URL. Useful for tests targeting a\n\t *  remote / non-default stack. */\n\treadonly walletUrl?: string;\n\t/** Custom `fetch` for tests. Defaults to `globalThis.fetch`. */\n\treadonly fetch?: typeof fetch;\n\t/** Per-request timeout in ms. Default: 5_000. */\n\treadonly timeoutMs?: number;\n}\n\n/** Public shape of the wallet adapter — typed by-key methods plus the\n *  raw `request` escape hatch. */\nexport interface WalletAdapter {\n\t/** Resolved base URL of the wallet plugin. */\n\treadonly walletUrl: string;\n\n\t/** List dev-wallet account names + addresses. */\n\treadonly listAccounts: () => Promise<ReadonlyArray<DevAccount>>;\n\n\t/** Sign + execute a serialized transaction as `accountName`.\n\t *  `txBytes` is the canonical Sui tx bytes (base64). Returns the\n\t *  wallet's response body (typed `unknown` — caller decodes).\n\t *\n\t *  NOTE on account switching: the HTTP wallet server has no\n\t *  `/accounts/switch` endpoint — active-account selection is owned\n\t *  by the dapp-kit slot. Use `selectAccount` / `connectAs` below. */\n\treadonly signTransaction: (input: SignTxRequest) => Promise<SignTxResponse>;\n\n\t/** Raw POST escape hatch. Used by the helpers above and by tests\n\t *  that need a wallet-endpoint not in the typed surface. */\n\treadonly request: <T>(path: string, body?: Record<string, unknown>) => Promise<T>;\n}\n\nexport interface DevAccount {\n\treadonly name: string;\n\treadonly address: string;\n}\n\nexport interface SignTxRequest {\n\treadonly accountName: string;\n\t/** Canonical Sui tx bytes, base64-encoded. */\n\treadonly txBytesBase64: string;\n\t/** Optional caller-supplied label for correlated trace output. */\n\treadonly label?: string;\n}\n\nexport interface SignTxResponse {\n\treadonly digest: string;\n\treadonly signature: string;\n\t/** Raw response payload (wallet-plugin-versioned shape). */\n\treadonly raw: unknown;\n}\n\n// -----------------------------------------------------------------------------\n// Resolver: locate the wallet URL via fixture > manifest > error\n// -----------------------------------------------------------------------------\n\n/**\n * Resolve the dev-wallet URL. Precedence:\n *   1. `options.walletUrl` (explicit override).\n *   2. The fixture stashed by `globalSetup` on `globalThis`.\n *   3. A fresh manifest read.\n *\n * Throws `PlaywrightWalletAdapterError` when every path misses. */\nconst resolveWalletUrl = (options: WalletAdapterOptions): string => {\n\tif (options.walletUrl !== undefined) return options.walletUrl;\n\n\tconst fixture = readStashedFixture();\n\tif (fixture !== null && fixture.walletEndpoint !== null) {\n\t\treturn fixture.walletEndpoint;\n\t}\n\n\tlet ctx: StackContext;\n\ttry {\n\t\tctx = readStackContext(options);\n\t} catch (cause) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`unable to resolve dev-wallet URL — no globalSetup fixture and ` + `manifest read failed`,\n\t\t\toperation: 'fetch',\n\t\t\tcause,\n\t\t});\n\t}\n\tconst walletUrl = ctx.endpointMaybe(WALLET_ENDPOINT_KEY);\n\tif (walletUrl === null) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`manifest has no \\`${WALLET_ENDPOINT_KEY}\\` endpoint (alias for ` +\n\t\t\t\t`\\`wallet-app\\`) — is the dev-wallet plugin present in your stack? ` +\n\t\t\t\t`Available endpoint names: ${ctx.endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t`Raw manifest keys: ${ctx.manifestEndpointKeys.join(', ') || '(none)'}.`,\n\t\t\toperation: 'fetch',\n\t\t});\n\t}\n\treturn walletUrl;\n};\n\n// -----------------------------------------------------------------------------\n// Factory\n// -----------------------------------------------------------------------------\n\n/**\n * Build a wallet adapter. Most tests call this once per `test`\n * fixture; the resolution is sync (a hash-lookup on the\n * fixture / manifest) so this is cheap.\n */\nexport const createWalletAdapter = (options: WalletAdapterOptions = {}): WalletAdapter => {\n\tconst walletUrl = resolveWalletUrl(options).replace(/\\/$/, '');\n\tconst fetchImpl = options.fetch ?? globalThis.fetch;\n\t// 30s default — Playwright's webServer cold-start (vite + first\n\t// devstack bring-up) routinely exceeds 5s under CI parallelism; the\n\t// shorter default surfaces as a spurious AbortError before the\n\t// wallet plugin has finished publishing its HTTP route. Callers can\n\t// still tighten via `options.timeoutMs` for hot-path assertions.\n\tconst timeoutMs = options.timeoutMs ?? 30_000;\n\n\tconst request = async <T>(path: string, body?: Record<string, unknown>): Promise<T> => {\n\t\tconst url = `${walletUrl}${path.startsWith('/') ? path : `/${path}`}`;\n\t\tconst controller = new AbortController();\n\t\tconst handle = setTimeout(() => controller.abort(), timeoutMs);\n\t\ttry {\n\t\t\tconst res = await fetchImpl(url, {\n\t\t\t\tmethod: body === undefined ? 'GET' : 'POST',\n\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\tbody: body === undefined ? undefined : JSON.stringify(body),\n\t\t\t\tsignal: controller.signal,\n\t\t\t});\n\t\t\tif (!res.ok) {\n\t\t\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\t\t\tmessage: `wallet request ${path} failed: HTTP ${res.status}`,\n\t\t\t\t\toperation: 'fetch',\n\t\t\t\t\turl,\n\t\t\t\t\tstatus: res.status,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn (await res.json()) as T;\n\t\t} catch (cause) {\n\t\t\tif (cause instanceof PlaywrightWalletAdapterError) throw cause;\n\t\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\t\tmessage: `wallet request ${path} threw`,\n\t\t\t\toperation: 'fetch',\n\t\t\t\turl,\n\t\t\t\tcause,\n\t\t\t});\n\t\t} finally {\n\t\t\tclearTimeout(handle);\n\t\t}\n\t};\n\n\treturn {\n\t\twalletUrl,\n\t\t// Paths come from the wallet plugin's canonical wire-protocol\n\t\t// module. Hard-coded literals here would silently 404 the moment\n\t\t// `WalletHttpPath` is reorganised, with no compile-time signal.\n\t\tlistAccounts: () => request<ReadonlyArray<DevAccount>>(WalletHttpPath.ACCOUNTS),\n\t\tsignTransaction: (input: SignTxRequest) =>\n\t\t\trequest<SignTxResponse>(WalletHttpPath.SIGN_TRANSACTION, {\n\t\t\t\taccountName: input.accountName,\n\t\t\t\ttxBytesBase64: input.txBytesBase64,\n\t\t\t\tlabel: input.label,\n\t\t\t}),\n\t\trequest,\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// In-spec helpers — `connectAs` and `selectAccount`\n// -----------------------------------------------------------------------------\n\n/** Slot name owned by the app's `dapp-kit.ts`. The build integration\n *  reads it; the app populates it. Re-exported from `runtime/`'s\n *  canonical contract — kept here as a name alias for the\n *  in-spec-helpers' import path. */\nexport const DAPP_KIT_SLOT = DAPP_KIT_SLOT_KEY;\n\n/**\n * Connect/switch the app's active dev-wallet account through the dapp-kit\n * slot the app populates at boot.\n *\n * This intentionally avoids driving the wallet UI. The app-side slot\n * implementation still goes through dapp-kit + wallet-standard, so pairing,\n * origin, and account discovery failures surface as real browser failures.\n */\nexport const connectAs = async (page: PlaywrightPageLike, accountName: string): Promise<void> => {\n\ttry {\n\t\tawait selectAccount(page, accountName);\n\t} catch (cause) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage: `connectAs(\"${accountName}\") failed`,\n\t\t\toperation: 'switch-account',\n\t\t\tcause,\n\t\t});\n\t}\n};\n\n/**\n * Switch the dev-wallet's active account by routing through the\n * dapp-kit global slot the app populates at module init. Strictly\n * faster + less flaky than clicking the wallet's UI.\n */\nexport const selectAccount = async (\n\tpage: PlaywrightPageLike,\n\taccountName: string,\n): Promise<void> => {\n\t// `evaluate`'s closure is serialized into the browser; the slot\n\t// shape (`DAppKitSlot`) lives in `runtime/dapp-kit-slot.ts` — the\n\t// in-browser closure can't import it, but the global-augmentation\n\t// `globalThis.__devstackDAppKit__` is the typed contract both sides\n\t// rely on.\n\tconst result = await page.evaluate(async (name): Promise<{ ok: boolean; reason?: string }> => {\n\t\tconst slot = (globalThis as { __devstackDAppKit__?: DAppKitSlot }).__devstackDAppKit__;\n\t\tif (slot === undefined || slot.selectAccount === undefined) {\n\t\t\treturn { ok: false, reason: 'slot-not-populated' };\n\t\t}\n\t\ttry {\n\t\t\tawait slot.selectAccount(name as string);\n\t\t\treturn { ok: true };\n\t\t} catch (err) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\treason: err instanceof Error ? err.message : String(err),\n\t\t\t};\n\t\t}\n\t}, accountName);\n\tif (!result.ok) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`selectAccount(\"${accountName}\") failed: ${result.reason ?? 'unknown'}. ` +\n\t\t\t\t`Confirm \\`globalThis.${DAPP_KIT_SLOT}\\` is populated by the app's ` +\n\t\t\t\t`dapp-kit module at boot.`,\n\t\t\toperation: 'switch-account',\n\t\t\t// `cause` survives the `page.evaluate` boundary as a string —\n\t\t\t// the browser-side `Error` instance is lost across the bridge,\n\t\t\t// but the message is the load-bearing diagnostic. Preserving\n\t\t\t// it on the typed error keeps the underlying detail attached\n\t\t\t// when consumers inspect `cause` rather than `message`.\n\t\t\tcause: result.reason,\n\t\t});\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Artifact loaders\n// -----------------------------------------------------------------------------\n\n/** Test-side accessor for the full manifest (already decoded). */\nexport const loadStackManifest = (options: ResolveStackContextOptions = {}): StackContext =>\n\treadStackContext(options);\n"],"mappings":"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"}
+{"version":3,"file":"wallet-context.mjs","names":[],"sources":["../../../src/build-integrations/playwright/wallet-context.ts"],"sourcesContent":["// Wallet-context test helpers.\n//\n// Architecture (distilled/23-build-integrations.md § Playwright /\n// \"What it produces\"):\n//\n//   In-spec helpers (`connectAs`, `selectAccount`) and the\n//   `loadStackManifest` artifact loader. (`loadStackKeypair` is not\n//   implemented — keys never leave the wallet plugin; tests sign via\n//   the wallet's HTTP API.)\n//\n// And (per the user task brief): tests sign txs via the wallet's HTTP\n// API rather than driving the browser's wallet-UI flow. That is the\n// load-bearing wallet-context contract: a tiny typed HTTP client over\n// the dev wallet's endpoint exposed in the manifest.\n//\n// Discipline:\n//   - This module performs NO browser interaction. The `page` arg in\n//     `connectAs` is the Playwright `Page` (kept structural — we do\n//     not import `@playwright/test`), but the helpers here only use\n//     it to expose the dev-wallet selection / account-switch flow\n//     through `evaluate`. The actual key handling stays server-side\n//     in the wallet plugin.\n//   - HTTP calls go through `fetch`. We do NOT pull in `@mysten/sui`\n//     here — txs are constructed by tests, serialized, and POSTed\n//     to the wallet for signing. The wallet plugin is the\n//     authoritative key holder.\n//   - Account-switch via the global slot (`globalThis.__devstackDAppKit__`)\n//     for dapp-kit-driven in-browser context; HTTP wallet helpers\n//     are the spec-level lower-friction path.\n\nimport {\n\treadStackContext,\n\ttype ResolveStackContextOptions,\n\ttype StackContext,\n} from './stack-context.ts';\nimport { readStashedFixture } from './global-setup.ts';\nimport { PlaywrightWalletAdapterError } from './errors.ts';\nimport { DAPP_KIT_SLOT_KEY, type DAppKitSlot } from '../runtime/dapp-kit-slot.ts';\n// The wallet plugin owns the wire-protocol path constants AND the\n// canonical endpoint name. Both are surfaced through the L5 runtime\n// bridge so this adapter never reaches into L2 plugin code directly\n// (ARCHITECTURE.md § Layer table — L5 reads only the runtime bridge).\nimport { WalletHttpPath, WALLET_ENDPOINT_KEY } from '../runtime/wallet-paths.ts';\n\n// -----------------------------------------------------------------------------\n// Structural Playwright `Page` shape — we keep `@playwright/test` an\n// optional peer.\n// -----------------------------------------------------------------------------\n\n/** Subset of `Page` we use. */\nexport interface PlaywrightPageLike {\n\treadonly evaluate: <T>(fn: (arg: unknown) => T, arg?: unknown) => Promise<T>;\n}\n\n// -----------------------------------------------------------------------------\n// Wallet adapter — HTTP client targeting the wallet plugin's endpoint\n// -----------------------------------------------------------------------------\n\n// `WALLET_ENDPOINT_KEY` is the short form Playwright/vitest helpers look\n// up — the manifest stores the canonical endpoint name\n// (`WALLET_ENDPOINT_NAME` — `'wallet-app'`) but the substrate's alias\n// resolver folds the key to the canonical name. Re-exported from the L5\n// runtime bridge so the spelling + canonical pairing stay aligned with\n// the wallet plugin.\nexport { WALLET_ENDPOINT_KEY };\n\nexport interface WalletAdapterOptions extends ResolveStackContextOptions {\n\t/** Override the resolved wallet URL. Useful for tests targeting a\n\t *  remote / non-default stack. */\n\treadonly walletUrl?: string;\n\t/** Custom `fetch` for tests. Defaults to `globalThis.fetch`. */\n\treadonly fetch?: typeof fetch;\n\t/** Per-request timeout in ms. Default: 5_000. */\n\treadonly timeoutMs?: number;\n}\n\n/** Public shape of the wallet adapter — typed by-key methods plus the\n *  raw `request` escape hatch. */\nexport interface WalletAdapter {\n\t/** Resolved base URL of the wallet plugin. */\n\treadonly walletUrl: string;\n\n\t/** List dev-wallet account names + addresses. */\n\treadonly listAccounts: () => Promise<ReadonlyArray<DevAccount>>;\n\n\t/** Sign + execute a serialized transaction as `accountName`.\n\t *  `txBytes` is the canonical Sui tx bytes (base64). Returns the\n\t *  wallet's response body (typed `unknown` — caller decodes).\n\t *\n\t *  NOTE on account switching: the HTTP wallet server has no\n\t *  `/accounts/switch` endpoint — active-account selection is owned\n\t *  by the dapp-kit slot. Use `selectAccount` / `connectAs` below. */\n\treadonly signTransaction: (input: SignTxRequest) => Promise<SignTxResponse>;\n\n\t/** Raw POST escape hatch. Used by the helpers above and by tests\n\t *  that need a wallet-endpoint not in the typed surface. */\n\treadonly request: <T>(path: string, body?: Record<string, unknown>) => Promise<T>;\n}\n\nexport interface DevAccount {\n\treadonly name: string;\n\treadonly address: string;\n}\n\nexport interface SignTxRequest {\n\treadonly accountName: string;\n\t/** Canonical Sui tx bytes, base64-encoded. */\n\treadonly txBytesBase64: string;\n\t/** Optional caller-supplied label for correlated trace output. */\n\treadonly label?: string;\n}\n\nexport interface SignTxResponse {\n\treadonly digest: string;\n\treadonly signature: string;\n\t/** Raw response payload (wallet-plugin-versioned shape). */\n\treadonly raw: unknown;\n}\n\n// -----------------------------------------------------------------------------\n// Resolver: locate the wallet URL via fixture > manifest > error\n// -----------------------------------------------------------------------------\n\n/**\n * Resolve the dev-wallet URL. Precedence:\n *   1. `options.walletUrl` (explicit override).\n *   2. The fixture stashed by `globalSetup` on `globalThis`.\n *   3. A fresh manifest read.\n *\n * Throws `PlaywrightWalletAdapterError` when every path misses. */\nconst resolveWalletUrl = (options: WalletAdapterOptions): string => {\n\tif (options.walletUrl !== undefined) return options.walletUrl;\n\n\tconst fixture = readStashedFixture();\n\tif (fixture !== null && fixture.walletEndpoint !== null) {\n\t\treturn fixture.walletEndpoint;\n\t}\n\n\tlet ctx: StackContext;\n\ttry {\n\t\tctx = readStackContext(options);\n\t} catch (cause) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`unable to resolve dev-wallet URL — no globalSetup fixture and ` + `manifest read failed`,\n\t\t\toperation: 'fetch',\n\t\t\tcause,\n\t\t});\n\t}\n\tconst walletUrl = ctx.endpointMaybe(WALLET_ENDPOINT_KEY);\n\tif (walletUrl === null) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`manifest has no \\`${WALLET_ENDPOINT_KEY}\\` endpoint (alias for ` +\n\t\t\t\t`\\`wallet-app\\`) — is the dev-wallet plugin present in your stack? ` +\n\t\t\t\t`Available endpoint names: ${ctx.endpointNames.join(', ') || '(none)'}. ` +\n\t\t\t\t`Raw manifest keys: ${ctx.manifestEndpointKeys.join(', ') || '(none)'}.`,\n\t\t\toperation: 'fetch',\n\t\t});\n\t}\n\treturn walletUrl;\n};\n\n// -----------------------------------------------------------------------------\n// Factory\n// -----------------------------------------------------------------------------\n\n/**\n * Build a wallet adapter. Most tests call this once per `test`\n * fixture; the resolution is sync (a hash-lookup on the\n * fixture / manifest) so this is cheap.\n */\nexport const createWalletAdapter = (options: WalletAdapterOptions = {}): WalletAdapter => {\n\tconst walletUrl = resolveWalletUrl(options).replace(/\\/$/, '');\n\tconst fetchImpl = options.fetch ?? globalThis.fetch;\n\t// 30s default — Playwright's webServer cold-start (vite + first\n\t// devstack bring-up) routinely exceeds 5s under CI parallelism; the\n\t// shorter default surfaces as a spurious AbortError before the\n\t// wallet plugin has finished publishing its HTTP route. Callers can\n\t// still tighten via `options.timeoutMs` for hot-path assertions.\n\tconst timeoutMs = options.timeoutMs ?? 30_000;\n\n\tconst request = async <T>(path: string, body?: Record<string, unknown>): Promise<T> => {\n\t\tconst url = `${walletUrl}${path.startsWith('/') ? path : `/${path}`}`;\n\t\tconst controller = new AbortController();\n\t\tconst handle = setTimeout(() => controller.abort(), timeoutMs);\n\t\ttry {\n\t\t\tconst res = await fetchImpl(url, {\n\t\t\t\tmethod: body === undefined ? 'GET' : 'POST',\n\t\t\t\theaders: { 'content-type': 'application/json' },\n\t\t\t\tbody: body === undefined ? undefined : JSON.stringify(body),\n\t\t\t\tsignal: controller.signal,\n\t\t\t});\n\t\t\tif (!res.ok) {\n\t\t\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\t\t\tmessage: `wallet request ${path} failed: HTTP ${res.status}`,\n\t\t\t\t\toperation: 'fetch',\n\t\t\t\t\turl,\n\t\t\t\t\tstatus: res.status,\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn (await res.json()) as T;\n\t\t} catch (cause) {\n\t\t\tif (cause instanceof PlaywrightWalletAdapterError) throw cause;\n\t\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\t\tmessage: `wallet request ${path} threw`,\n\t\t\t\toperation: 'fetch',\n\t\t\t\turl,\n\t\t\t\tcause,\n\t\t\t});\n\t\t} finally {\n\t\t\tclearTimeout(handle);\n\t\t}\n\t};\n\n\treturn {\n\t\twalletUrl,\n\t\t// Paths come from the wallet plugin's canonical wire-protocol\n\t\t// module. Hard-coded literals here would silently 404 the moment\n\t\t// `WalletHttpPath` is reorganised, with no compile-time signal.\n\t\tlistAccounts: () => request<ReadonlyArray<DevAccount>>(WalletHttpPath.ACCOUNTS),\n\t\tsignTransaction: (input: SignTxRequest) =>\n\t\t\trequest<SignTxResponse>(WalletHttpPath.SIGN_TRANSACTION, {\n\t\t\t\taccountName: input.accountName,\n\t\t\t\ttxBytesBase64: input.txBytesBase64,\n\t\t\t\tlabel: input.label,\n\t\t\t}),\n\t\trequest,\n\t};\n};\n\n// -----------------------------------------------------------------------------\n// In-spec helpers — `connectAs` and `selectAccount`\n// -----------------------------------------------------------------------------\n\n/** Slot name owned by the app's `dapp-kit.ts`. The build integration\n *  reads it; the app populates it. Re-exported from `runtime/`'s\n *  canonical contract — kept here as a name alias for the\n *  in-spec-helpers' import path. */\nexport const DAPP_KIT_SLOT = DAPP_KIT_SLOT_KEY;\n\nconst SELECT_ACCOUNT_SLOT_TIMEOUT_MS = 10_000;\nconst SELECT_ACCOUNT_SLOT_POLL_MS = 50;\n\n/**\n * Connect/switch the app's active dev-wallet account through the dapp-kit\n * slot the app populates at boot.\n *\n * This intentionally avoids driving the wallet UI. The app-side slot\n * implementation still goes through dapp-kit + wallet-standard, so pairing,\n * origin, and account discovery failures surface as real browser failures.\n */\nexport const connectAs = async (page: PlaywrightPageLike, accountName: string): Promise<void> => {\n\ttry {\n\t\tawait selectAccount(page, accountName);\n\t} catch (cause) {\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage: `connectAs(\"${accountName}\") failed`,\n\t\t\toperation: 'switch-account',\n\t\t\tcause,\n\t\t});\n\t}\n};\n\n/**\n * Switch the dev-wallet's active account by routing through the\n * dapp-kit global slot the app populates at module init. Strictly\n * faster + less flaky than clicking the wallet's UI.\n */\nexport const selectAccount = async (\n\tpage: PlaywrightPageLike,\n\taccountName: string,\n): Promise<void> => {\n\tconst deadline = Date.now() + SELECT_ACCOUNT_SLOT_TIMEOUT_MS;\n\tlet lastEvaluateError: unknown;\n\t// `evaluate`'s closure is serialized into the browser; the slot\n\t// shape (`DAppKitSlot`) lives in `runtime/dapp-kit-slot.ts` — the\n\t// in-browser closure can't import it, but the global-augmentation\n\t// `globalThis.__devstackDAppKit__` is the typed contract both sides\n\t// rely on.\n\tfor (;;) {\n\t\tlet result: { ok: boolean; reason?: string };\n\t\ttry {\n\t\t\tresult = await page.evaluate(async (name): Promise<{ ok: boolean; reason?: string }> => {\n\t\t\t\tconst slot = (globalThis as { __devstackDAppKit__?: DAppKitSlot }).__devstackDAppKit__;\n\t\t\t\tif (slot === undefined || slot.selectAccount === undefined) {\n\t\t\t\t\treturn { ok: false, reason: 'slot-not-populated' };\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\tawait slot.selectAccount(name as string);\n\t\t\t\t\treturn { ok: true };\n\t\t\t\t} catch (err) {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tok: false,\n\t\t\t\t\t\treason: err instanceof Error ? err.message : String(err),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t}, accountName);\n\t\t} catch (cause) {\n\t\t\tlastEvaluateError = cause;\n\t\t\tif (Date.now() < deadline) {\n\t\t\t\tawait new Promise((resolve) => setTimeout(resolve, SELECT_ACCOUNT_SLOT_POLL_MS));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\t\tmessage:\n\t\t\t\t\t`selectAccount(\"${accountName}\") failed: page evaluation did not settle before ` +\n\t\t\t\t\t`${SELECT_ACCOUNT_SLOT_TIMEOUT_MS}ms. Confirm the app finished loading before ` +\n\t\t\t\t\t`calling connectAs().`,\n\t\t\t\toperation: 'switch-account',\n\t\t\t\tcause: lastEvaluateError,\n\t\t\t});\n\t\t}\n\n\t\tif (result.ok) return;\n\t\tif (result.reason === 'slot-not-populated' && Date.now() < deadline) {\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, SELECT_ACCOUNT_SLOT_POLL_MS));\n\t\t\tcontinue;\n\t\t}\n\n\t\tthrow new PlaywrightWalletAdapterError({\n\t\t\tmessage:\n\t\t\t\t`selectAccount(\"${accountName}\") failed: ${result.reason ?? 'unknown'}. ` +\n\t\t\t\t`Confirm \\`globalThis.${DAPP_KIT_SLOT}\\` is populated by the app's ` +\n\t\t\t\t`dapp-kit module at boot.`,\n\t\t\toperation: 'switch-account',\n\t\t\t// `cause` survives the `page.evaluate` boundary as a string —\n\t\t\t// the browser-side `Error` instance is lost across the bridge,\n\t\t\t// but the message is the load-bearing diagnostic. Preserving\n\t\t\t// it on the typed error keeps the underlying detail attached\n\t\t\t// when consumers inspect `cause` rather than `message`.\n\t\t\tcause: result.reason,\n\t\t});\n\t}\n};\n\n// -----------------------------------------------------------------------------\n// Artifact loaders\n// -----------------------------------------------------------------------------\n\n/** Test-side accessor for the full manifest (already decoded). */\nexport const loadStackManifest = (options: ResolveStackContextOptions = {}): StackContext =>\n\treadStackContext(options);\n"],"mappings":"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"}

package/dist/build-integrations/runtime/cold-start-url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cold-start-url.mjs","names":[],"sources":["../../../src/build-integrations/runtime/cold-start-url.ts"],"sourcesContent":["// Cold-start URL — conventional-route fallback for callers that need\n// an endpoint URL BEFORE the supervisor has written the manifest.\n//\n// Playwright's config loader runs ahead of the supervisor (it's the\n// process that spawns `pnpm dev`, which boots the supervisor, which\n// then writes the manifest). For `webServer.url` / `use.baseURL` to\n// be resolvable at config-load time, the build-integration needs a\n// derivation that doesn't require the manifest on disk.\n//\n// The derivation:\n//\n//   <service>.<stack-prefix>.<app>.localhost:<port>\n//\n// where:\n//   - `<service>` and `<port>` come from the endpoint's Routable\n//     declaration (its `conventional` hint, populated by the router\n//     plugin).\n//   - `<app>` is the un-scoped app name (from cwd's `package.json` or\n//     an explicit override).\n//   - `<stack-prefix>` comes from an explicit stack, `DEVSTACK_STACK`,\n//     or the `main` default. Package metadata is not a stack selector\n//     for build integrations; it only supplies the app name.\n//   - `<stack-prefix>` is empty for the `main` stack and `.<stack>`\n//     otherwise. Matches the router's hostname-minting rule so\n//     conventional and post-manifest URLs converge.\n//\n// Architecture § invariants: \"conventional URL convergence\" — the\n// fallback this function returns MUST equal the URL the supervisor's\n// router publishes once the manifest exists. The shared invariant is\n// enforced by deriving both from the same Routable declaration.\n//\n// This module does NOT import any service-specific endpoint names.\n// The conventional-route table is supplied by the caller; the router\n// plugin populates it from `RoutableDecl[].upstream` + a hard-coded\n// conventional-port map. (Architecture: \"engine knows zero service\n// names\" — the table is plugin-emitted.)\n\nimport { basename } from 'node:path';\n\nimport { NoConventionalRouteError } from './errors.ts';\nimport { readAppName, resolveBuildIntegrationStack } from './discover.ts';\n\n/** One row of the conventional-route table. The supervisor's router\n *  plugin emits a `Map<endpointName, ConventionalRoute>` from its\n *  Routable contributions; cold-start URL resolution keys off it. */\nexport interface ConventionalRoute {\n\t/** `<service>` segment of the hostname — typically the\n\t *  routable's `dispatchId.role`. */\n\treadonly service: string;\n\t/** Traefik entrypoint port — the router's public-facing port for\n\t *  this endpoint kind. */\n\treadonly port: number;\n\t/** Wire protocol — `http` or `h2c`. Determines the URL scheme. */\n\treadonly wireProtocol: 'http' | 'h2c';\n}\n\nexport interface ColdStartUrlOptions {\n\t/** Conventional-route table to consult. Supplied by the caller\n\t *  (build integration), populated from the router plugin's\n\t *  `RoutableDecl` contributions. Empty by default — calls that\n\t *  don't pass a table will always throw, which is the right\n\t *  behavior for \"no router plugin = no fallback\". */\n\treadonly routes: ReadonlyMap<string, ConventionalRoute>;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */\n\treadonly stack?: string;\n\t/** App name (un-scoped). Defaults to reading `package.json` at\n\t *  `cwd` (with the `@scope/` prefix stripped) and finally to\n\t *  `basename(cwd)`. Injectable so unit tests don't depend on\n\t *  filesystem state. */\n\treadonly app?: string;\n\t/** Starting directory for the app-name lookup. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Host suffix owned by the router. Default: `.localhost`. */\n\treadonly hostSuffix?: string;\n\t/** Env bag consulted before falling back to `process.env`. Lets\n\t *  callers (build integrations under test) inject a hermetic env\n\t *  so `DEVSTACK_STACK` / `DEVSTACK_APP` are read from the bag\n\t *  rather than leaking through the ambient environment. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n}\n\nexport interface ConventionalRouteHostInput {\n\treadonly service: string;\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hostSuffix?: string;\n}\n\nexport interface ConventionalRouteUrlInput extends ConventionalRouteHostInput {\n\treadonly route: ConventionalRoute;\n\treadonly scheme?: 'http' | 'https';\n\treadonly trailingSlash?: boolean;\n}\n\nexport interface ConventionalRouteHint {\n\treadonly endpoint: string;\n\treadonly service: string;\n\treadonly wireProtocol?: 'http' | 'h2c';\n}\n\nexport const conventionalRouteHost = (input: ConventionalRouteHostInput): string => {\n\tconst hostSuffix = input.hostSuffix ?? '.localhost';\n\treturn input.stack === 'main'\n\t\t? `${input.service}.${input.app}${hostSuffix}`\n\t\t: `${input.service}.${input.stack}.${input.app}${hostSuffix}`;\n};\n\nexport const conventionalRouteUrl = (input: ConventionalRouteUrlInput): string => {\n\tconst scheme = input.scheme ?? 'http';\n\tconst host = conventionalRouteHost(input);\n\tconst url = `${scheme}://${host}:${input.route.port}`;\n\treturn input.trailingSlash === true ? `${url}/` : url;\n};\n\nexport const conventionalRoutesFromHints = (\n\thints: ReadonlyArray<ConventionalRouteHint>,\n\tport: number,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tnew Map(\n\t\thints.map((hint): [string, ConventionalRoute] => [\n\t\t\thint.endpoint,\n\t\t\t{\n\t\t\t\tservice: hint.service,\n\t\t\t\tport,\n\t\t\t\twireProtocol: hint.wireProtocol ?? 'http',\n\t\t\t},\n\t\t]),\n\t);\n\n/**\n * Compute the conventional URL for `endpoint`. Throws\n * `NoConventionalRouteError` when the endpoint isn't in the supplied\n * `routes` table.\n *\n * Callers that prefer a `undefined`-on-miss surface should catch the\n * error or use `tryColdStartUrl` instead.\n */\nexport const coldStartUrl = (endpoint: string, opts: ColdStartUrlOptions): string => {\n\tconst route = opts.routes.get(endpoint);\n\tif (route === undefined) {\n\t\tconst supported = [...opts.routes.keys()].sort();\n\t\tthrow new NoConventionalRouteError({\n\t\t\tendpoint,\n\t\t\tsupported,\n\t\t\tmessage:\n\t\t\t\t`[devstack] endpoint ${JSON.stringify(endpoint)} has no conventional URL fallback. ` +\n\t\t\t\t`Supported endpoints: ${supported.length === 0 ? '(none)' : supported.join(', ')}. ` +\n\t\t\t\t`Check the endpoint name or write the manifest first via \\`devstack up\\`.`,\n\t\t});\n\t}\n\tconst cwd = opts.cwd ?? process.cwd();\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst stack = resolveBuildIntegrationStack(opts.stack, env);\n\t// `DEVSTACK_APP` is the caller-injectable app name; `readAppName(cwd)` is\n\t// the package.json walk-up. The env bag wins so test fixtures don't leak\n\t// the host's package metadata into the cold-start URL.\n\tconst app = opts.app ?? env.DEVSTACK_APP ?? readAppName(cwd) ?? basename(cwd);\n\treturn conventionalRouteUrl({\n\t\troute,\n\t\tservice: route.service,\n\t\tapp,\n\t\tstack,\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\t// h2c shares port 80 with HTTP/1 via Traefik; both wire\n\t\t// protocols expose `http://` URLs at the entrypoint.\n\t\tscheme: 'http',\n\t});\n};\n\n/** `undefined`-on-miss variant. */\nexport const tryColdStartUrl = (\n\tendpoint: string,\n\topts: ColdStartUrlOptions,\n): string | undefined => {\n\tif (!opts.routes.has(endpoint)) return undefined;\n\treturn coldStartUrl(endpoint, opts);\n};\n"],"mappings":";;;;AAqGA,MAAa,yBAAyB,UAA8C;CACnF,MAAM,aAAa,MAAM,cAAc;AACvC,QAAO,MAAM,UAAU,SACpB,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,eAChC,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,GAAG,MAAM,MAAM;;AAGnD,MAAa,wBAAwB,UAA6C;CAGjF,MAAM,MAAM,GAFG,MAAM,UAAU,OAET,KADT,sBAAsB,MACJ,CAAC,GAAG,MAAM,MAAM;AAC/C,QAAO,MAAM,kBAAkB,OAAO,GAAG,IAAI,KAAK;;AAGnD,MAAa,+BACZ,OACA,SAEA,IAAI,IACH,MAAM,KAAK,SAAsC,CAChD,KAAK,UACL;CACC,SAAS,KAAK;CACd;CACA,cAAc,KAAK,gBAAgB;CACnC,CACD,CAAC,CACF;;;;;;;;;AAUF,MAAa,gBAAgB,UAAkB,SAAsC;CACpF,MAAM,QAAQ,KAAK,OAAO,IAAI,SAAS;AACvC,KAAI,UAAU,KAAA,GAAW;EACxB,MAAM,YAAY,CAAC,GAAG,KAAK,OAAO,MAAM,CAAC,CAAC,MAAM;AAChD,QAAM,IAAI,yBAAyB;GAClC;GACA;GACA,SACC,uBAAuB,KAAK,UAAU,SAAS,CAAC,0DACxB,UAAU,WAAW,IAAI,WAAW,UAAU,KAAK,KAAK,CAAC;GAElF,CAAC;;CAEH,MAAM,MAAM,KAAK,OAAO,QAAQ,KAAK;CACrC,MAAM,MAAM,KAAK,OAAQ,QAAQ;CACjC,MAAM,QAAQ,6BAA6B,KAAK,OAAO,IAAI;CAI3D,MAAM,MAAM,KAAK,OAAO,IAAI,gBAAgB,YAAY,IAAI,IAAI,SAAS,IAAI;AAC7E,QAAO,qBAAqB;EAC3B;EACA,SAAS,MAAM;EACf;EACA;EACA,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,YAAY,GAAG,EAAE;EAGxE,QAAQ;EACR,CAAC;;;AAIH,MAAa,mBACZ,UACA,SACwB;AACxB,KAAI,CAAC,KAAK,OAAO,IAAI,SAAS,CAAE,QAAO,KAAA;AACvC,QAAO,aAAa,UAAU,KAAK"}
+{"version":3,"file":"cold-start-url.mjs","names":[],"sources":["../../../src/build-integrations/runtime/cold-start-url.ts"],"sourcesContent":["// Cold-start URL — conventional-route fallback for callers that need\n// an endpoint URL BEFORE the supervisor has written the manifest.\n//\n// Playwright's config loader runs ahead of the supervisor (it's the\n// process that spawns `pnpm dev`, which boots the supervisor, which\n// then writes the manifest). For `webServer.url` / `use.baseURL` to\n// be resolvable at config-load time, the build-integration needs a\n// derivation that doesn't require the manifest on disk.\n//\n// The derivation:\n//\n//   <service>.<stack-prefix>.<app>.localhost:<port>\n//\n// where:\n//   - `<service>` and `<port>` come from the endpoint's Routable\n//     declaration (its `conventional` hint, populated by the router\n//     plugin).\n//   - `<app>` is the un-scoped app name (from cwd's `package.json` or\n//     an explicit override).\n//   - `<stack-prefix>` comes from an explicit stack, `DEVSTACK_STACK`,\n//     or the `main` default. Unlike manifest discovery\n//     (`resolveDiscoveryEnv`'s package-name rung), the cold-start path\n//     does NOT infer a stack from package metadata — here it supplies\n//     only the app name. Inferring it here too would double the package\n//     name into every minted hostname\n//     (`<service>.<pkg>.<pkg>.localhost`); pinned by the cold-start\n//     tests, revisit deliberately if convergence for inferred stacks is\n//     ever needed pre-manifest.\n//   - `<stack-prefix>` is empty for the `main` stack and `.<stack>`\n//     otherwise. Matches the router's hostname-minting rule so\n//     conventional and post-manifest URLs converge.\n//\n// Architecture § invariants: \"conventional URL convergence\" — the\n// fallback this function returns MUST equal the URL the supervisor's\n// router publishes once the manifest exists. The shared invariant is\n// enforced by deriving both from the same Routable declaration.\n//\n// This module does NOT import any service-specific endpoint names.\n// The conventional-route table is supplied by the caller; the router\n// plugin populates it from `RoutableDecl[].upstream` + a hard-coded\n// conventional-port map. (Architecture: \"engine knows zero service\n// names\" — the table is plugin-emitted.)\n\nimport { basename } from 'node:path';\n\nimport { NoConventionalRouteError } from './errors.ts';\nimport { readAppName, resolveBuildIntegrationStack } from './discover.ts';\n\n/** One row of the conventional-route table. The supervisor's router\n *  plugin emits a `Map<endpointName, ConventionalRoute>` from its\n *  Routable contributions; cold-start URL resolution keys off it. */\nexport interface ConventionalRoute {\n\t/** `<service>` segment of the hostname — typically the\n\t *  routable's `dispatchId.role`. */\n\treadonly service: string;\n\t/** Traefik entrypoint port — the router's public-facing port for\n\t *  this endpoint kind. */\n\treadonly port: number;\n\t/** Wire protocol — `http` or `h2c`. Determines the URL scheme. */\n\treadonly wireProtocol: 'http' | 'h2c';\n}\n\nexport interface ColdStartUrlOptions {\n\t/** Conventional-route table to consult. Supplied by the caller\n\t *  (build integration), populated from the router plugin's\n\t *  `RoutableDecl` contributions. Empty by default — calls that\n\t *  don't pass a table will always throw, which is the right\n\t *  behavior for \"no router plugin = no fallback\". */\n\treadonly routes: ReadonlyMap<string, ConventionalRoute>;\n\t/** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */\n\treadonly stack?: string;\n\t/** App name (un-scoped). Defaults to reading `package.json` at\n\t *  `cwd` (with the `@scope/` prefix stripped) and finally to\n\t *  `basename(cwd)`. Injectable so unit tests don't depend on\n\t *  filesystem state. */\n\treadonly app?: string;\n\t/** Starting directory for the app-name lookup. Defaults to\n\t *  `process.cwd()`. */\n\treadonly cwd?: string;\n\t/** Host suffix owned by the router. Default: `.localhost`. */\n\treadonly hostSuffix?: string;\n\t/** Env bag consulted before falling back to `process.env`. Lets\n\t *  callers (build integrations under test) inject a hermetic env\n\t *  so `DEVSTACK_STACK` / `DEVSTACK_APP` are read from the bag\n\t *  rather than leaking through the ambient environment. */\n\treadonly env?: Readonly<Record<string, string | undefined>>;\n}\n\nexport interface ConventionalRouteHostInput {\n\treadonly service: string;\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly hostSuffix?: string;\n}\n\nexport interface ConventionalRouteUrlInput extends ConventionalRouteHostInput {\n\treadonly route: ConventionalRoute;\n\treadonly scheme?: 'http' | 'https';\n\treadonly trailingSlash?: boolean;\n}\n\nexport interface ConventionalRouteHint {\n\treadonly endpoint: string;\n\treadonly service: string;\n\treadonly wireProtocol?: 'http' | 'h2c';\n}\n\nexport const conventionalRouteHost = (input: ConventionalRouteHostInput): string => {\n\tconst hostSuffix = input.hostSuffix ?? '.localhost';\n\treturn input.stack === 'main'\n\t\t? `${input.service}.${input.app}${hostSuffix}`\n\t\t: `${input.service}.${input.stack}.${input.app}${hostSuffix}`;\n};\n\nexport const conventionalRouteUrl = (input: ConventionalRouteUrlInput): string => {\n\tconst scheme = input.scheme ?? 'http';\n\tconst host = conventionalRouteHost(input);\n\tconst url = `${scheme}://${host}:${input.route.port}`;\n\treturn input.trailingSlash === true ? `${url}/` : url;\n};\n\nexport const conventionalRoutesFromHints = (\n\thints: ReadonlyArray<ConventionalRouteHint>,\n\tport: number,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tnew Map(\n\t\thints.map((hint): [string, ConventionalRoute] => [\n\t\t\thint.endpoint,\n\t\t\t{\n\t\t\t\tservice: hint.service,\n\t\t\t\tport,\n\t\t\t\twireProtocol: hint.wireProtocol ?? 'http',\n\t\t\t},\n\t\t]),\n\t);\n\n/**\n * Compute the conventional URL for `endpoint`. Throws\n * `NoConventionalRouteError` when the endpoint isn't in the supplied\n * `routes` table.\n *\n * Callers that prefer a `undefined`-on-miss surface should catch the\n * error or use `tryColdStartUrl` instead.\n */\nexport const coldStartUrl = (endpoint: string, opts: ColdStartUrlOptions): string => {\n\tconst route = opts.routes.get(endpoint);\n\tif (route === undefined) {\n\t\tconst supported = [...opts.routes.keys()].sort();\n\t\tthrow new NoConventionalRouteError({\n\t\t\tendpoint,\n\t\t\tsupported,\n\t\t\tmessage:\n\t\t\t\t`[devstack] endpoint ${JSON.stringify(endpoint)} has no conventional URL fallback. ` +\n\t\t\t\t`Supported endpoints: ${supported.length === 0 ? '(none)' : supported.join(', ')}. ` +\n\t\t\t\t`Check the endpoint name or write the manifest first via \\`devstack up\\`.`,\n\t\t});\n\t}\n\tconst cwd = opts.cwd ?? process.cwd();\n\tconst env = opts.env ?? (process.env as Readonly<Record<string, string | undefined>>);\n\tconst stack = resolveBuildIntegrationStack(opts.stack, env);\n\t// `DEVSTACK_APP` is the caller-injectable app name; `readAppName(cwd)` is\n\t// the package.json walk-up. The env bag wins so test fixtures don't leak\n\t// the host's package metadata into the cold-start URL.\n\tconst app = opts.app ?? env.DEVSTACK_APP ?? readAppName(cwd) ?? basename(cwd);\n\treturn conventionalRouteUrl({\n\t\troute,\n\t\tservice: route.service,\n\t\tapp,\n\t\tstack,\n\t\t...(opts.hostSuffix !== undefined ? { hostSuffix: opts.hostSuffix } : {}),\n\t\t// h2c shares port 80 with HTTP/1 via Traefik; both wire\n\t\t// protocols expose `http://` URLs at the entrypoint.\n\t\tscheme: 'http',\n\t});\n};\n\n/** `undefined`-on-miss variant. */\nexport const tryColdStartUrl = (\n\tendpoint: string,\n\topts: ColdStartUrlOptions,\n): string | undefined => {\n\tif (!opts.routes.has(endpoint)) return undefined;\n\treturn coldStartUrl(endpoint, opts);\n};\n"],"mappings":";;;;AA2GA,MAAa,yBAAyB,UAA8C;CACnF,MAAM,aAAa,MAAM,cAAc;CACvC,OAAO,MAAM,UAAU,SACpB,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,eAChC,GAAG,MAAM,QAAQ,GAAG,MAAM,MAAM,GAAG,MAAM,MAAM;AACnD;AAEA,MAAa,wBAAwB,UAA6C;CAGjF,MAAM,MAAM,GAFG,MAAM,UAAU,OAET,KADT,sBAAsB,KACL,EAAE,GAAG,MAAM,MAAM;CAC/C,OAAO,MAAM,kBAAkB,OAAO,GAAG,IAAI,KAAK;AACnD;AAEA,MAAa,+BACZ,OACA,SAEA,IAAI,IACH,MAAM,KAAK,SAAsC,CAChD,KAAK,UACL;CACC,SAAS,KAAK;CACd;CACA,cAAc,KAAK,gBAAgB;AACpC,CACD,CAAC,CACF;;;;;;;;;AAUD,MAAa,gBAAgB,UAAkB,SAAsC;CACpF,MAAM,QAAQ,KAAK,OAAO,IAAI,QAAQ;CACtC,IAAI,UAAU,KAAA,GAAW;EACxB,MAAM,YAAY,CAAC,GAAG,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK;EAC/C,MAAM,IAAI,yBAAyB;GAClC;GACA;GACA,SACC,uBAAuB,KAAK,UAAU,QAAQ,EAAE,0DACxB,UAAU,WAAW,IAAI,WAAW,UAAU,KAAK,IAAI,EAAE;EAEnF,CAAC;CACF;CACA,MAAM,MAAM,KAAK,OAAO,QAAQ,IAAI;CACpC,MAAM,MAAM,KAAK,OAAQ,QAAQ;CACjC,MAAM,QAAQ,6BAA6B,KAAK,OAAO,GAAG;CAI1D,MAAM,MAAM,KAAK,OAAO,IAAI,gBAAgB,YAAY,GAAG,KAAK,SAAS,GAAG;CAC5E,OAAO,qBAAqB;EAC3B;EACA,SAAS,MAAM;EACf;EACA;EACA,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;EAGvE,QAAQ;CACT,CAAC;AACF;;AAGA,MAAa,mBACZ,UACA,SACwB;CACxB,IAAI,CAAC,KAAK,OAAO,IAAI,QAAQ,GAAG,OAAO,KAAA;CACvC,OAAO,aAAa,UAAU,IAAI;AACnC"}

package/dist/build-integrations/runtime/conventional-routes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"conventional-routes.mjs","names":["aliases"],"sources":["../../../src/build-integrations/runtime/conventional-routes.ts"],"sourcesContent":["// Conventional-routes table — substrate-owned defaults for the\n// \"config-load before manifest\" cold-start path.\n//\n// Build integrations (Playwright, vitest, …) that need an endpoint URL\n// BEFORE the supervisor has written the manifest go through\n// `coldStartUrl(endpoint, { routes, ... })`. The route table itself is\n// a parameter — `runtime/coldStartUrl` deliberately stays\n// service-name-blind. THIS module supplies the conventional table the\n// router plugin would populate at supervise-time, so build integrations\n// don't each carry their own copy.\n//\n// Add a new built-in service: add one entry here AND ship a Routable\n// plugin that publishes the matching `<service>` hostname at the same\n// port. Architecture invariant \"conventional URL convergence\" — the\n// fallback returned by `coldStartUrl({ routes })` MUST equal the URL\n// the router publishes once the manifest exists.\n//\n// This is the L5 cold-start mirror of the router plugin's runtime\n// table. The L5 surface (Playwright / vitest) consults it once; the\n// runtime table wins as soon as the manifest is on disk.\n\nimport {\n\tconventionalRoutesFromHints,\n\ttype ConventionalRoute,\n\ttype ConventionalRouteHint,\n} from './cold-start-url.ts';\nimport { WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME } from './wallet-paths.ts';\n\n/**\n * The Traefik entrypoint port the supervisor's router maps every\n * conventional endpoint to. All built-in routes share this single port\n * because Traefik dispatches by Host header, not by port. If a future\n * plugin requires a distinct entrypoint port it would extend\n * `BUILT_IN_CONVENTIONAL_HINTS` AND extend the router profile to add\n * the entrypoint; until then, one port covers every built-in.\n */\nexport const DEFAULT_ROUTER_ENTRYPOINT_PORT = 5175 as const;\n\n/**\n * Endpoint-name aliases the conventional-route resolver folds before\n * looking up a row. Lets in-spec helpers reach `endpoint('app')` or\n * `endpoint('wallet')` without knowing the router's canonical\n * spelling (`'dev'` / `'wallet-app'`). Aliases are bidirectional in\n * intent — the table key is the alias users type; the value is the\n * service segment routed in the manifest.\n *\n * The wallet entry sources both sides from the name-blind contract\n * (via the L5 bridge in `wallet-paths.ts`) so there is exactly one\n * source of truth for the alias/canonical pairing — see\n * `WALLET_ENDPOINT_KEY` in `contracts/wallet-protocol.ts`.\n */\nexport const BUILT_IN_ENDPOINT_ALIASES = {\n\tapp: 'dev',\n\t[WALLET_ENDPOINT_KEY]: WALLET_ENDPOINT_NAME,\n} as const;\n\n/**\n * Conventional endpoint→service hints for every built-in plugin that\n * publishes a Routable. Build integrations consume this through\n * `builtInConventionalRoutes()` rather than each carrying their own\n * copy. The substrate stays open: callers may extend by passing extra\n * hints to `coldStartUrl` directly.\n */\nexport const BUILT_IN_CONVENTIONAL_HINTS: ReadonlyArray<ConventionalRouteHint> = [\n\t{ endpoint: 'app', service: 'dev' },\n\t{ endpoint: 'dev', service: 'dev' },\n\t{ endpoint: 'sui-rpc', service: 'sui-rpc' },\n\t{ endpoint: 'sui-faucet', service: 'sui-faucet' },\n\t{ endpoint: 'walrus-aggregator', service: 'walrus-aggregator' },\n\t{ endpoint: 'walrus-publisher', service: 'walrus-publisher' },\n\t{ endpoint: 'seal', service: 'seal' },\n\t{ endpoint: WALLET_ENDPOINT_KEY, service: 'api' },\n\t{ endpoint: WALLET_ENDPOINT_NAME, service: 'api' },\n];\n\n/**\n * Resolve the built-in conventional route table. `port` overrides the\n * default entrypoint port (set by env / explicit caller option). The\n * resulting `Map` is the shape `coldStartUrl({ routes })` consumes.\n */\nexport const builtInConventionalRoutes = (\n\tport: number = DEFAULT_ROUTER_ENTRYPOINT_PORT,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tconventionalRoutesFromHints(BUILT_IN_CONVENTIONAL_HINTS, port);\n\n/**\n * Look up the alias-resolved endpoint key for a user-typed name.\n * Returns the input unchanged when no alias is registered.\n */\nexport const resolveBuiltInEndpointAlias = (endpointNameOrAlias: string): string => {\n\tconst aliases: Readonly<Record<string, string>> = BUILT_IN_ENDPOINT_ALIASES;\n\treturn aliases[endpointNameOrAlias] ?? endpointNameOrAlias;\n};\n"],"mappings":";;;;;;;;;;;;AAoCA,MAAa,iCAAiC;;;;;;;;;;;;;;AAe9C,MAAa,4BAA4B;CACxC,KAAK;EACJ,sBAAsB;CACvB;;;;;;;;AASD,MAAa,8BAAoE;CAChF;EAAE,UAAU;EAAO,SAAS;EAAO;CACnC;EAAE,UAAU;EAAO,SAAS;EAAO;CACnC;EAAE,UAAU;EAAW,SAAS;EAAW;CAC3C;EAAE,UAAU;EAAc,SAAS;EAAc;CACjD;EAAE,UAAU;EAAqB,SAAS;EAAqB;CAC/D;EAAE,UAAU;EAAoB,SAAS;EAAoB;CAC7D;EAAE,UAAU;EAAQ,SAAS;EAAQ;CACrC;EAAE,UAAU;EAAqB,SAAS;EAAO;CACjD;EAAE,UAAU;EAAsB,SAAS;EAAO;CAClD;;;;;;AAOD,MAAa,6BACZ,OAAe,mCAEf,4BAA4B,6BAA6B,KAAK;;;;;AAM/D,MAAa,+BAA+B,wBAAwC;AAEnF,QAAOA,0BAAQ,wBAAwB"}
+{"version":3,"file":"conventional-routes.mjs","names":["aliases"],"sources":["../../../src/build-integrations/runtime/conventional-routes.ts"],"sourcesContent":["// Conventional-routes table — substrate-owned defaults for the\n// \"config-load before manifest\" cold-start path.\n//\n// Build integrations (Playwright, vitest, …) that need an endpoint URL\n// BEFORE the supervisor has written the manifest go through\n// `coldStartUrl(endpoint, { routes, ... })`. The route table itself is\n// a parameter — `runtime/coldStartUrl` deliberately stays\n// service-name-blind. THIS module supplies the conventional table the\n// router plugin would populate at supervise-time, so build integrations\n// don't each carry their own copy.\n//\n// Add a new built-in service: add one entry here AND ship a Routable\n// plugin that publishes the matching `<service>` hostname at the same\n// port. Architecture invariant \"conventional URL convergence\" — the\n// fallback returned by `coldStartUrl({ routes })` MUST equal the URL\n// the router publishes once the manifest exists.\n//\n// This is the L5 cold-start mirror of the router plugin's runtime\n// table. The L5 surface (Playwright / vitest) consults it once; the\n// runtime table wins as soon as the manifest is on disk.\n\nimport {\n\tconventionalRoutesFromHints,\n\ttype ConventionalRoute,\n\ttype ConventionalRouteHint,\n} from './cold-start-url.ts';\nimport { WALLET_ENDPOINT_KEY, WALLET_ENDPOINT_NAME } from './wallet-paths.ts';\n\n/**\n * The Traefik entrypoint port the supervisor's router maps every\n * conventional endpoint to. All built-in routes share this single port\n * because Traefik dispatches by Host header, not by port. If a future\n * plugin requires a distinct entrypoint port it would extend\n * `BUILT_IN_CONVENTIONAL_HINTS` AND extend the router profile to add\n * the entrypoint; until then, one port covers every built-in.\n */\nexport const DEFAULT_ROUTER_ENTRYPOINT_PORT = 5175 as const;\n\n/**\n * Endpoint-name aliases the conventional-route resolver folds before\n * looking up a row. Lets in-spec helpers reach `endpoint('app')` or\n * `endpoint('wallet')` without knowing the router's canonical\n * spelling (`'dev'` / `'wallet-app'`). Aliases are bidirectional in\n * intent — the table key is the alias users type; the value is the\n * service segment routed in the manifest.\n *\n * The wallet entry sources both sides from the name-blind contract\n * (via the L5 bridge in `wallet-paths.ts`) so there is exactly one\n * source of truth for the alias/canonical pairing — see\n * `WALLET_ENDPOINT_KEY` in `contracts/wallet-protocol.ts`.\n */\nexport const BUILT_IN_ENDPOINT_ALIASES = {\n\tapp: 'dev',\n\t[WALLET_ENDPOINT_KEY]: WALLET_ENDPOINT_NAME,\n} as const;\n\n/**\n * Conventional endpoint→service hints for every built-in plugin that\n * publishes a Routable. Build integrations consume this through\n * `builtInConventionalRoutes()` rather than each carrying their own\n * copy. The substrate stays open: callers may extend by passing extra\n * hints to `coldStartUrl` directly.\n */\nexport const BUILT_IN_CONVENTIONAL_HINTS: ReadonlyArray<ConventionalRouteHint> = [\n\t{ endpoint: 'app', service: 'dev' },\n\t{ endpoint: 'dev', service: 'dev' },\n\t{ endpoint: 'sui-rpc', service: 'sui-rpc' },\n\t{ endpoint: 'sui-faucet', service: 'sui-faucet' },\n\t{ endpoint: 'walrus-aggregator', service: 'walrus-aggregator' },\n\t{ endpoint: 'walrus-publisher', service: 'walrus-publisher' },\n\t{ endpoint: 'seal', service: 'seal' },\n\t{ endpoint: WALLET_ENDPOINT_KEY, service: 'api' },\n\t{ endpoint: WALLET_ENDPOINT_NAME, service: 'api' },\n];\n\n/**\n * Resolve the built-in conventional route table. `port` overrides the\n * default entrypoint port (set by env / explicit caller option). The\n * resulting `Map` is the shape `coldStartUrl({ routes })` consumes.\n */\nexport const builtInConventionalRoutes = (\n\tport: number = DEFAULT_ROUTER_ENTRYPOINT_PORT,\n): ReadonlyMap<string, ConventionalRoute> =>\n\tconventionalRoutesFromHints(BUILT_IN_CONVENTIONAL_HINTS, port);\n\n/**\n * Look up the alias-resolved endpoint key for a user-typed name.\n * Returns the input unchanged when no alias is registered.\n */\nexport const resolveBuiltInEndpointAlias = (endpointNameOrAlias: string): string => {\n\tconst aliases: Readonly<Record<string, string>> = BUILT_IN_ENDPOINT_ALIASES;\n\treturn aliases[endpointNameOrAlias] ?? endpointNameOrAlias;\n};\n"],"mappings":";;;;;;;;;;;;AAoCA,MAAa,iCAAiC;;;;;;;;;;;;;;AAe9C,MAAa,4BAA4B;CACxC,KAAK;EACJ,sBAAsB;AACxB;;;;;;;;AASA,MAAa,8BAAoE;CAChF;EAAE,UAAU;EAAO,SAAS;CAAM;CAClC;EAAE,UAAU;EAAO,SAAS;CAAM;CAClC;EAAE,UAAU;EAAW,SAAS;CAAU;CAC1C;EAAE,UAAU;EAAc,SAAS;CAAa;CAChD;EAAE,UAAU;EAAqB,SAAS;CAAoB;CAC9D;EAAE,UAAU;EAAoB,SAAS;CAAmB;CAC5D;EAAE,UAAU;EAAQ,SAAS;CAAO;CACpC;EAAE,UAAU;EAAqB,SAAS;CAAM;CAChD;EAAE,UAAU;EAAsB,SAAS;CAAM;AAClD;;;;;;AAOA,MAAa,6BACZ,OAAe,mCAEf,4BAA4B,6BAA6B,IAAI;;;;;AAM9D,MAAa,+BAA+B,wBAAwC;CAEnF,OAAOA,0BAAQ,wBAAwB;AACxC"}

package/dist/build-integrations/runtime/dapp-kit-slot.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"dapp-kit-slot.mjs","names":[],"sources":["../../../src/build-integrations/runtime/dapp-kit-slot.ts"],"sourcesContent":["// Typed contract for the `globalThis.__devstackDAppKit__` test bridge.\n//\n// This is intentionally narrow: app code writes only the account\n// switcher Playwright needs. It is not a place to stash the full\n// dAppKit instance or manifest projection.\n//\n// This module evaluates in browser bundles and in Node build\n// integration callers. Discipline: no `node:*` imports here.\n\n/** The literal property name on `globalThis` that the app writes the\n *  kit handle to. Renames here cascade through every consumer\n *  (Playwright config-load, in-spec helpers, app-side dapp-kit-config\n *  emit). The slot's name is part of the contract. */\nexport const DAPP_KIT_SLOT_KEY = '__devstackDAppKit__' as const;\n\nexport interface DAppKitSlot {\n\t/** Account switcher entry point consumed by Playwright's\n\t *  `connectAs` / `selectAccount` helpers. */\n\treadonly selectAccount?: (accountName: string) => void | Promise<void>;\n}\n\ndeclare global {\n\t// eslint-disable-next-line no-var\n\tvar __devstackDAppKit__: DAppKitSlot | undefined;\n}\n"],"mappings":";;;;;AAaA,MAAa,oBAAoB"}
+{"version":3,"file":"dapp-kit-slot.mjs","names":[],"sources":["../../../src/build-integrations/runtime/dapp-kit-slot.ts"],"sourcesContent":["// Typed contract for the `globalThis.__devstackDAppKit__` test bridge.\n//\n// This is intentionally narrow: app code writes only the account\n// switcher Playwright needs. It is not a place to stash the full\n// dAppKit instance or manifest projection.\n//\n// This module evaluates in browser bundles and in Node build\n// integration callers. Discipline: no `node:*` imports here.\n\n/** The literal property name on `globalThis` that the app writes the\n *  kit handle to. Renames here cascade through every consumer\n *  (Playwright config-load, in-spec helpers, app-side dapp-kit-config\n *  emit). The slot's name is part of the contract. */\nexport const DAPP_KIT_SLOT_KEY = '__devstackDAppKit__' as const;\n\nexport interface DAppKitSlot {\n\t/** Account switcher entry point consumed by Playwright's\n\t *  `connectAs` / `selectAccount` helpers. App dev-account UIs do NOT\n\t *  read accounts from this slot — they read the connected wallet's\n\t *  account list directly from dApp Kit (each account's `label` is the\n\t *  devstack account name). */\n\treadonly selectAccount?: (accountName: string) => void | Promise<void>;\n}\n\ndeclare global {\n\t// eslint-disable-next-line no-var\n\tvar __devstackDAppKit__: DAppKitSlot | undefined;\n}\n"],"mappings":";;;;;AAaA,MAAa,oBAAoB"}

package/dist/build-integrations/runtime/discover.d.mts

@@ -4,8 +4,8 @@
  *  doesn't reach into the substrate package. Re-export of the
  *  shared-resolver default so this module's public surface is stable. */
 declare const DEFAULT_STATE_DIR = ".devstack";
-/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`
- *  yields a useful value. */
+/** Default stack name when neither `opts.stack`, `$DEVSTACK_STACK`,
+ *  nor the package-name walk-up yields a useful value. */
 declare const DEFAULT_STACK = "main";
 interface DiscoverManifestPathOptions {
   /** Caller-supplied override path. Bypasses the walk-up but is still
@@ -15,10 +15,12 @@ interface DiscoverManifestPathOptions {
   /** Starting directory for the walk-up. Defaults to
    *  `process.cwd()`. */
   readonly cwd?: string;
-  /** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */
+  /** Stack name. Defaults through `$DEVSTACK_STACK`, then the nearest
+   *  package.json `name` above `cwd` (the CLI's stack-inference rung),
+   *  then `'main'`. */
   readonly stack?: string;
   /** State-dir name. Defaults through `$DEVSTACK_RUNTIME_ROOT`, then
-   *  the legacy `$DEVSTACK_STATE_DIR`, then `'.devstack'` (see
+   *  `$DEVSTACK_STATE_DIR`, then `'.devstack'` (see
    *  `resolveDiscoveryEnv`). Absolute paths are honored — the walk-up
    *  degenerates into a single existence check in that case. */
   readonly stateDir?: string;