@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"stack-context.mjs","names":["runtimeDiscoverManifestPath","readStackContextRuntime","port","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\tdiscoverManifestPath as runtimeDiscoverManifestPath,\n\tcoldStartUrl as runtimeColdStartUrl,\n\tconventionalRoutesFromHints,\n\tEndpointRegistry,\n\tmanifestEnvelopeFromStackContext,\n\tManifestDiscoveryError,\n\tManifestShapeError,\n\treadStackContext as readStackContextRuntime,\n\ttype DiscoverManifestPathOptions,\n\ttype ResolvedEndpoint as RuntimeResolvedEndpoint,\n\ttype StackContext as RuntimeStackContext,\n} from '../runtime/index.ts';\nimport type { EndpointEntry, ManifestEnvelope } from '../../substrate/manifest.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\nconst PLAYWRIGHT_ENDPOINT_ALIASES: Readonly<Record<string, string>> = {\n\tapp: 'dev',\n\twallet: 'wallet-app',\n};\n\nconst PLAYWRIGHT_DEFAULT_ROUTER_PORTS: Readonly<Record<string, number>> = {\n\tapp: 5175,\n\tdev: 5175,\n\twallet: 5175,\n\t'wallet-app': 5175,\n};\n\nexport const playwrightEndpointNameFor = (endpointNameOrAlias: string): string =>\n\tPLAYWRIGHT_ENDPOINT_ALIASES[endpointNameOrAlias] ?? 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 as string,\n\t\t\tendpointKey: raw.endpointKey as string,\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 stack = options.stack ?? env[PLAYWRIGHT_ENV.STACK] ?? 'main';\n\tconst stateDir = options.stateDir ?? env[PLAYWRIGHT_ENV.STATE_DIR];\n\treturn {\n\t\tenv,\n\t\tstack,\n\t\t...(options.cwd !== undefined ? { cwd: options.cwd } : {}),\n\t\t...(options.manifestPath !== undefined ? { override: options.manifestPath } : {}),\n\t\t...(stateDir !== undefined && stateDir !== '' ? { stateDir } : {}),\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\tthrow new PlaywrightManifestShapeError({\n\t\t\t\tmessage: `failed to read manifest at ${manifestPath}`,\n\t\t\t\tmanifestPath,\n\t\t\t\tphase: 'parse',\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\tcause,\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\tPLAYWRIGHT_DEFAULT_ROUTER_PORTS[endpointKey];\n\n\tif (resolvedPort === undefined || !Number.isFinite(resolvedPort) || resolvedPort <= 0) {\n\t\treturn null;\n\t}\n\tconst port = resolvedPort;\n\n\tconst routes = conventionalRoutesFromHints(\n\t\t[\n\t\t\t{ endpoint: 'app', service: 'dev' },\n\t\t\t{ endpoint: 'dev', service: 'dev' },\n\t\t\t{ endpoint: 'sui-rpc', service: 'sui-rpc' },\n\t\t\t{ endpoint: 'sui-faucet', service: 'sui-faucet' },\n\t\t\t{ endpoint: 'walrus-aggregator', service: 'walrus-aggregator' },\n\t\t\t{ endpoint: 'walrus-publisher', service: 'walrus-publisher' },\n\t\t\t{ endpoint: 'seal', service: 'seal' },\n\t\t\t{ endpoint: 'wallet', service: 'api' },\n\t\t\t{ endpoint: 'wallet-app', service: 'api' },\n\t\t],\n\t\tport,\n\t);\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});\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 as string) === 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 as never,\n\t\t\tendpointKey: resolved.endpointKey as never,\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.d.mts

@@ -0,0 +1,87 @@
+import { ResolveStackContextOptions, StackContext } from "./stack-context.mjs";
+
+//#region src/build-integrations/playwright/wallet-context.d.ts
+/** Subset of `Page` we use. */
+interface PlaywrightPageLike {
+  readonly evaluate: <T>(fn: (arg: unknown) => T, arg?: unknown) => Promise<T>;
+}
+/** Public alias for the dev-wallet endpoint. The manifest stores raw
+ *  keys as `${pluginKey}:${endpointName}` and the actual endpoint name
+ *  is `wallet-app`; `readStackContext(...).endpointMaybe('wallet')`
+ *  maps this alias through the Playwright boundary. */
+declare const WALLET_ENDPOINT_KEY: "wallet";
+interface WalletAdapterOptions extends ResolveStackContextOptions {
+  /** Override the resolved wallet URL. Useful for tests targeting a
+   *  remote / non-default stack. */
+  readonly walletUrl?: string;
+  /** Custom `fetch` for tests. Defaults to `globalThis.fetch`. */
+  readonly fetch?: typeof fetch;
+  /** Per-request timeout in ms. Default: 5_000. */
+  readonly timeoutMs?: number;
+}
+/** Public shape of the wallet adapter — typed by-key methods plus the
+ *  raw `request` escape hatch. */
+interface WalletAdapter {
+  /** Resolved base URL of the wallet plugin. */
+  readonly walletUrl: string;
+  /** List dev-wallet account names + addresses. */
+  readonly listAccounts: () => Promise<ReadonlyArray<DevAccount>>;
+  /** Switch the active dev-wallet account by name. Posts to the
+   *  wallet's `switch-account` endpoint. */
+  readonly switchAccount: (accountName: string) => Promise<void>;
+  /** Sign + execute a serialized transaction as `accountName`.
+   *  `txBytes` is the canonical Sui tx bytes (base64). Returns the
+   *  wallet's response body (typed `unknown` — caller decodes). */
+  readonly signTransaction: (input: SignTxRequest) => Promise<SignTxResponse>;
+  /** Raw POST escape hatch. Used by the helpers above and by tests
+   *  that need a wallet-endpoint not in the typed surface. */
+  readonly request: <T>(path: string, body?: Record<string, unknown>) => Promise<T>;
+}
+interface DevAccount {
+  readonly name: string;
+  readonly address: string;
+}
+interface SignTxRequest {
+  readonly accountName: string;
+  /** Canonical Sui tx bytes, base64-encoded. */
+  readonly txBytesBase64: string;
+  /** Optional caller-supplied label for correlated trace output. */
+  readonly label?: string;
+}
+interface SignTxResponse {
+  readonly digest: string;
+  readonly signature: string;
+  /** Raw response payload (wallet-plugin-versioned shape). */
+  readonly raw: unknown;
+}
+/**
+ * Build a wallet adapter. Most tests call this once per `test`
+ * fixture; the resolution is sync (a hash-lookup on the
+ * fixture / manifest) so this is cheap.
+ */
+declare const createWalletAdapter: (options?: WalletAdapterOptions) => WalletAdapter;
+/** Slot name owned by the app's `dapp-kit.ts`. The build integration
+ *  reads it; the app populates it. Re-exported from `runtime/`'s
+ *  canonical contract — kept here as a name alias for the
+ *  in-spec-helpers' import path. */
+declare const DAPP_KIT_SLOT: "__devstackDAppKit__";
+/**
+ * Connect/switch the app's active dev-wallet account through the dapp-kit
+ * slot the app populates at boot.
+ *
+ * This intentionally avoids driving the wallet UI. The app-side slot
+ * implementation still goes through dapp-kit + wallet-standard, so pairing,
+ * origin, and account discovery failures surface as real browser failures.
+ */
+declare const connectAs: (page: PlaywrightPageLike, accountName: string) => Promise<void>;
+/**
+ * Switch the dev-wallet's active account by routing through the
+ * dapp-kit global slot the app populates at module init. Strictly
+ * faster + less flaky than clicking the wallet's UI.
+ */
+declare const selectAccount: (page: PlaywrightPageLike, accountName: string) => Promise<void>;
+/** Test-side accessor for the full manifest (already decoded). */
+declare const loadStackManifest: (options?: ResolveStackContextOptions) => StackContext;
+//#endregion
+export { DAPP_KIT_SLOT, DevAccount, PlaywrightPageLike, SignTxRequest, SignTxResponse, WALLET_ENDPOINT_KEY, WalletAdapter, WalletAdapterOptions, connectAs, createWalletAdapter, loadStackManifest, selectAccount };
+//# sourceMappingURL=wallet-context.d.mts.map

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

@@ -0,0 +1,148 @@
+import { PlaywrightWalletAdapterError } from "./errors.mjs";
+import { readStackContext } from "./stack-context.mjs";
+import { readStashedFixture } from "./global-setup.mjs";
+import { DAPP_KIT_SLOT_KEY } from "../runtime/dapp-kit-slot.mjs";
+//#region src/build-integrations/playwright/wallet-context.ts
+/** Public alias for the dev-wallet endpoint. The manifest stores raw
+*  keys as `${pluginKey}:${endpointName}` and the actual endpoint name
+*  is `wallet-app`; `readStackContext(...).endpointMaybe('wallet')`
+*  maps this alias through the Playwright boundary. */
+const WALLET_ENDPOINT_KEY = "wallet";
+/**
+* Resolve the dev-wallet URL. Precedence:
+*   1. `options.walletUrl` (explicit override).
+*   2. The fixture stashed by `globalSetup` on `globalThis`.
+*   3. A fresh manifest read.
+*
+* Throws `PlaywrightWalletAdapterError` when every path misses. */
+const resolveWalletUrl = (options) => {
+	if (options.walletUrl !== void 0) return options.walletUrl;
+	const fixture = readStashedFixture();
+	if (fixture !== null && fixture.walletEndpoint !== null) return fixture.walletEndpoint;
+	let ctx;
+	try {
+		ctx = readStackContext(options);
+	} catch (cause) {
+		throw new PlaywrightWalletAdapterError({
+			message: "unable to resolve dev-wallet URL — no globalSetup fixture and manifest read failed",
+			operation: "fetch",
+			cause
+		});
+	}
+	const walletUrl = ctx.endpointMaybe(WALLET_ENDPOINT_KEY);
+	if (walletUrl === null) throw new PlaywrightWalletAdapterError({
+		message: `manifest has no \`${WALLET_ENDPOINT_KEY}\` endpoint (alias for \`wallet-app\`) — is the dev-wallet plugin present in your stack? Available endpoint names: ${ctx.endpointNames.join(", ") || "(none)"}. Raw manifest keys: ${ctx.manifestEndpointKeys.join(", ") || "(none)"}.`,
+		operation: "fetch"
+	});
+	return walletUrl;
+};
+/**
+* Build a wallet adapter. Most tests call this once per `test`
+* fixture; the resolution is sync (a hash-lookup on the
+* fixture / manifest) so this is cheap.
+*/
+const createWalletAdapter = (options = {}) => {
+	const walletUrl = resolveWalletUrl(options).replace(/\/$/, "");
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 5e3;
+	const request = async (path, body) => {
+		const url = `${walletUrl}${path.startsWith("/") ? path : `/${path}`}`;
+		const controller = new AbortController();
+		const handle = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const res = await fetchImpl(url, {
+				method: body === void 0 ? "GET" : "POST",
+				headers: { "content-type": "application/json" },
+				body: body === void 0 ? void 0 : JSON.stringify(body),
+				signal: controller.signal
+			});
+			if (!res.ok) throw new PlaywrightWalletAdapterError({
+				message: `wallet request ${path} failed: HTTP ${res.status}`,
+				operation: "fetch",
+				url,
+				status: res.status
+			});
+			return await res.json();
+		} catch (cause) {
+			if (cause instanceof PlaywrightWalletAdapterError) throw cause;
+			throw new PlaywrightWalletAdapterError({
+				message: `wallet request ${path} threw`,
+				operation: "fetch",
+				url,
+				cause
+			});
+		} finally {
+			clearTimeout(handle);
+		}
+	};
+	return {
+		walletUrl,
+		listAccounts: () => request("/accounts"),
+		switchAccount: async (accountName) => {
+			await request("/accounts/switch", { accountName });
+		},
+		signTransaction: (input) => request("/sign-transaction", {
+			accountName: input.accountName,
+			txBytesBase64: input.txBytesBase64,
+			label: input.label
+		}),
+		request
+	};
+};
+/** Slot name owned by the app's `dapp-kit.ts`. The build integration
+*  reads it; the app populates it. Re-exported from `runtime/`'s
+*  canonical contract — kept here as a name alias for the
+*  in-spec-helpers' import path. */
+const DAPP_KIT_SLOT = DAPP_KIT_SLOT_KEY;
+/**
+* Connect/switch the app's active dev-wallet account through the dapp-kit
+* slot the app populates at boot.
+*
+* This intentionally avoids driving the wallet UI. The app-side slot
+* implementation still goes through dapp-kit + wallet-standard, so pairing,
+* origin, and account discovery failures surface as real browser failures.
+*/
+const connectAs = async (page, accountName) => {
+	try {
+		await selectAccount(page, accountName);
+	} catch (cause) {
+		throw new PlaywrightWalletAdapterError({
+			message: `connectAs("${accountName}") failed`,
+			operation: "switch-account",
+			cause
+		});
+	}
+};
+/**
+* Switch the dev-wallet's active account by routing through the
+* dapp-kit global slot the app populates at module init. Strictly
+* 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"
+		};
+		try {
+			await slot.selectAccount(name);
+			return { ok: true };
+		} catch (err) {
+			return {
+				ok: false,
+				reason: err instanceof Error ? err.message : String(err)
+			};
+		}
+	}, 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"
+	});
+};
+/** Test-side accessor for the full manifest (already decoded). */
+const loadStackManifest = (options = {}) => readStackContext(options);
+//#endregion
+export { DAPP_KIT_SLOT, WALLET_ENDPOINT_KEY, connectAs, createWalletAdapter, loadStackManifest, selectAccount };
+
+//# sourceMappingURL=wallet-context.mjs.map

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

@@ -0,0 +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 artifact\n//   loaders (`loadStackManifest`, `loadStackKeypair`).\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\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/** Public alias for the dev-wallet endpoint. The manifest stores raw\n *  keys as `${pluginKey}:${endpointName}` and the actual endpoint name\n *  is `wallet-app`; `readStackContext(...).endpointMaybe('wallet')`\n *  maps this alias through the Playwright boundary. */\nexport const WALLET_ENDPOINT_KEY = 'wallet' as const;\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/** Switch the active dev-wallet account by name. Posts to the\n\t *  wallet's `switch-account` endpoint. */\n\treadonly switchAccount: (accountName: string) => Promise<void>;\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\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\tconst timeoutMs = options.timeoutMs ?? 5_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\tlistAccounts: () => request<ReadonlyArray<DevAccount>>('/accounts'),\n\t\tswitchAccount: async (accountName: string) => {\n\t\t\tawait request<{ readonly ok: true }>('/accounts/switch', { accountName });\n\t\t},\n\t\tsignTransaction: (input: SignTxRequest) =>\n\t\t\trequest<SignTxResponse>('/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});\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.d.mts

@@ -0,0 +1,67 @@
+//#region src/build-integrations/runtime/cold-start-url.d.ts
+/** One row of the conventional-route table. The supervisor's router
+ *  plugin emits a `Map<endpointName, ConventionalRoute>` from its
+ *  Routable contributions; cold-start URL resolution keys off it. */
+interface ConventionalRoute {
+  /** `<service>` segment of the hostname — typically the
+   *  routable's `dispatchId.role`. */
+  readonly service: string;
+  /** Traefik entrypoint port — the router's public-facing port for
+   *  this endpoint kind. */
+  readonly port: number;
+  /** Wire protocol — `http` or `h2c`. Determines the URL scheme. */
+  readonly wireProtocol: 'http' | 'h2c';
+}
+interface ColdStartUrlOptions {
+  /** Conventional-route table to consult. Supplied by the caller
+   *  (build integration), populated from the router plugin's
+   *  `RoutableDecl` contributions. Empty by default — calls that
+   *  don't pass a table will always throw, which is the right
+   *  behavior for "no router plugin = no fallback". */
+  readonly routes: ReadonlyMap<string, ConventionalRoute>;
+  /** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */
+  readonly stack?: string;
+  /** App name (un-scoped). Defaults to reading `package.json` at
+   *  `cwd` (with the `@scope/` prefix stripped) and finally to
+   *  `basename(cwd)`. Injectable so unit tests don't depend on
+   *  filesystem state. */
+  readonly app?: string;
+  /** Starting directory for the app-name lookup. Defaults to
+   *  `process.cwd()`. */
+  readonly cwd?: string;
+  /** Host suffix owned by the router. Default: `.localhost`. */
+  readonly hostSuffix?: string;
+}
+interface ConventionalRouteHostInput {
+  readonly service: string;
+  readonly app: string;
+  readonly stack: string;
+  readonly hostSuffix?: string;
+}
+interface ConventionalRouteUrlInput extends ConventionalRouteHostInput {
+  readonly route: ConventionalRoute;
+  readonly scheme?: 'http' | 'https';
+  readonly trailingSlash?: boolean;
+}
+interface ConventionalRouteHint {
+  readonly endpoint: string;
+  readonly service: string;
+  readonly wireProtocol?: 'http' | 'h2c';
+}
+declare const conventionalRouteHost: (input: ConventionalRouteHostInput) => string;
+declare const conventionalRouteUrl: (input: ConventionalRouteUrlInput) => string;
+declare const conventionalRoutesFromHints: (hints: ReadonlyArray<ConventionalRouteHint>, port: number) => ReadonlyMap<string, ConventionalRoute>;
+/**
+ * Compute the conventional URL for `endpoint`. Throws
+ * `NoConventionalRouteError` when the endpoint isn't in the supplied
+ * `routes` table.
+ *
+ * Callers that prefer a `undefined`-on-miss surface should catch the
+ * error or use `tryColdStartUrl` instead.
+ */
+declare const coldStartUrl: (endpoint: string, opts: ColdStartUrlOptions) => string;
+/** `undefined`-on-miss variant. */
+declare const tryColdStartUrl: (endpoint: string, opts: ColdStartUrlOptions) => string | undefined;
+//#endregion
+export { ColdStartUrlOptions, ConventionalRoute, ConventionalRouteHint, ConventionalRouteHostInput, ConventionalRouteUrlInput, coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, tryColdStartUrl };
+//# sourceMappingURL=cold-start-url.d.mts.map

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

@@ -0,0 +1,56 @@
+import { NoConventionalRouteError } from "./errors.mjs";
+import { readAppName, resolveBuildIntegrationStack } from "./discover.mjs";
+import { basename } from "node:path";
+//#region src/build-integrations/runtime/cold-start-url.ts
+const conventionalRouteHost = (input) => {
+	const hostSuffix = input.hostSuffix ?? ".localhost";
+	return input.stack === "main" ? `${input.service}.${input.app}${hostSuffix}` : `${input.service}.${input.stack}.${input.app}${hostSuffix}`;
+};
+const conventionalRouteUrl = (input) => {
+	const url = `${input.scheme ?? "http"}://${conventionalRouteHost(input)}:${input.route.port}`;
+	return input.trailingSlash === true ? `${url}/` : url;
+};
+const conventionalRoutesFromHints = (hints, port) => new Map(hints.map((hint) => [hint.endpoint, {
+	service: hint.service,
+	port,
+	wireProtocol: hint.wireProtocol ?? "http"
+}]));
+/**
+* Compute the conventional URL for `endpoint`. Throws
+* `NoConventionalRouteError` when the endpoint isn't in the supplied
+* `routes` table.
+*
+* Callers that prefer a `undefined`-on-miss surface should catch the
+* error or use `tryColdStartUrl` instead.
+*/
+const coldStartUrl = (endpoint, opts) => {
+	const route = opts.routes.get(endpoint);
+	if (route === void 0) {
+		const supported = [...opts.routes.keys()].sort();
+		throw new NoConventionalRouteError({
+			endpoint,
+			supported,
+			message: `[devstack] endpoint ${JSON.stringify(endpoint)} has no conventional URL fallback. Supported endpoints: ${supported.length === 0 ? "(none)" : supported.join(", ")}. Check the endpoint name or write the manifest first via \`devstack up\`.`
+		});
+	}
+	const cwd = opts.cwd ?? process.cwd();
+	const stack = resolveBuildIntegrationStack(opts.stack);
+	const app = opts.app ?? readAppName(cwd) ?? basename(cwd);
+	return conventionalRouteUrl({
+		route,
+		service: route.service,
+		app,
+		stack,
+		...opts.hostSuffix !== void 0 ? { hostSuffix: opts.hostSuffix } : {},
+		scheme: route.wireProtocol === "h2c" ? "http" : "http"
+	});
+};
+/** `undefined`-on-miss variant. */
+const tryColdStartUrl = (endpoint, opts) => {
+	if (!opts.routes.has(endpoint)) return void 0;
+	return coldStartUrl(endpoint, opts);
+};
+//#endregion
+export { coldStartUrl, conventionalRouteHost, conventionalRouteUrl, conventionalRoutesFromHints, tryColdStartUrl };
+
+//# sourceMappingURL=cold-start-url.mjs.map

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

@@ -0,0 +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}\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 stack = resolveBuildIntegrationStack(opts.stack);\n\tconst app = opts.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\tscheme: route.wireProtocol === 'h2c' ? 'http' : '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":";;;;AAgGA,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,QAAQ,6BAA6B,KAAK,MAAM;CACtD,MAAM,MAAM,KAAK,OAAO,YAAY,IAAI,IAAI,SAAS,IAAI;AACzD,QAAO,qBAAqB;EAC3B;EACA,SAAS,MAAM;EACf;EACA;EACA,GAAI,KAAK,eAAe,KAAA,IAAY,EAAE,YAAY,KAAK,YAAY,GAAG,EAAE;EACxE,QAAQ,MAAM,iBAAiB,QAAQ,SAAS;EAChD,CAAC;;;AAIH,MAAa,mBACZ,UACA,SACwB;AACxB,KAAI,CAAC,KAAK,OAAO,IAAI,SAAS,CAAE,QAAO,KAAA;AACvC,QAAO,aAAa,UAAU,KAAK"}

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

@@ -0,0 +1,10 @@
+//#region src/build-integrations/runtime/dapp-kit-slot.ts
+/** The literal property name on `globalThis` that the app writes the
+*  kit handle to. Renames here cascade through every consumer
+*  (Playwright config-load, in-spec helpers, app-side dapp-kit-config
+*  emit). The slot's name is part of the contract. */
+const DAPP_KIT_SLOT_KEY = "__devstackDAppKit__";
+//#endregion
+export { DAPP_KIT_SLOT_KEY };
+
+//# sourceMappingURL=dapp-kit-slot.mjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,78 @@
+//#region src/build-integrations/runtime/discover.d.ts
+/** Default name of the supervisor's per-user state directory. Mirrors
+ *  the L0 path resolver. Held here as a literal so the discover walk
+ *  doesn't reach into the substrate package. */
+declare const DEFAULT_STATE_DIR = ".devstack";
+/** Default stack name when neither `opts.stack` nor `$DEVSTACK_STACK`
+ *  yields a useful value. */
+declare const DEFAULT_STACK = "main";
+interface DiscoverManifestPathOptions {
+  /** Caller-supplied override path. Bypasses the walk-up but is still
+   *  existence-checked. Lower precedence than
+   *  `DEVSTACK_MANIFEST_PATH`. */
+  readonly override?: string;
+  /** Starting directory for the walk-up. Defaults to
+   *  `process.cwd()`. */
+  readonly cwd?: string;
+  /** Stack name. Defaults through `$DEVSTACK_STACK`, then `'main'`. */
+  readonly stack?: string;
+  /** State-dir name. Defaults to `$DEVSTACK_STATE_DIR ?? '.devstack'`.
+   *  Absolute paths are honored — the walk-up degenerates into a
+   *  single existence check in that case. */
+  readonly stateDir?: string;
+  /** Env bag for the env-precedence step. Defaults to `process.env`.
+   *  Tests pass a fixture (often `{}`) to suppress leaks from the
+   *  ambient environment. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** When `true`, throw `ManifestDiscoveryError` on miss instead of
+   *  returning `undefined`. Default `false` (lets callers that treat
+   *  "no manifest" as cold-start branch cleanly). */
+  readonly required?: boolean;
+}
+interface BuildIntegrationIdentity {
+  readonly app: string | undefined;
+  readonly stack: string;
+  readonly stateDir: string;
+  readonly manifestPath: string;
+}
+interface DiscoverBuildIntegrationIdentityOptions {
+  /** Resolution cwd. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Explicit app name. Overrides env + package.json walk-up. */
+  readonly app?: string;
+  /** Explicit stack name. Overrides `DEVSTACK_STACK`; otherwise
+   *  defaults to `main`. */
+  readonly stack?: string;
+  /** Explicit state-dir name. Overrides `DEVSTACK_STATE_DIR`. */
+  readonly stateDir?: string;
+  /** Env bag for tests and config loaders. Defaults to `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/** Read `name` out of `<dir>/package.json`, strip the `@scope/`
+ *  prefix and any leading non-alphanumerics. Returns `undefined`
+ *  when the file is missing / unreadable / has no name field. */
+declare const readAppName: (dir: string) => string | undefined;
+/** Walk up from `cwd` to find the closest `package.json` and return
+ *  its un-scoped `name` field. Returns `undefined` if no package.json
+ *  is reachable. Bounded to 32 levels — defense against pathological
+ *  symlink loops. */
+declare const readAppNameWalkup: (cwd: string) => string | undefined;
+/** Resolve the framework-neutral identity tuple build integrations
+ *  need at config-load time. The manifest path is returned even when
+ *  it does not exist yet so cold-start callers can still compute
+ *  conventional URLs and watch-ignore paths. */
+declare const discoverBuildIntegrationIdentity: (options?: DiscoverBuildIntegrationIdentityOptions) => BuildIntegrationIdentity;
+/**
+ * Locate an existing devstack manifest on disk. Sync — Playwright's
+ * config loader and apps' startup paths both depend on this being
+ * synchronous.
+ *
+ * Returns the absolute path of the first match per the precedence
+ * documented at the top of this module, or `undefined` if no candidate
+ * exists. Pass `{ required: true }` to throw `ManifestDiscoveryError`
+ * on miss instead.
+ */
+declare function discoverManifestPath(opts?: DiscoverManifestPathOptions): string | undefined;
+//#endregion
+export { BuildIntegrationIdentity, DEFAULT_STACK, DEFAULT_STATE_DIR, DiscoverBuildIntegrationIdentityOptions, DiscoverManifestPathOptions, discoverBuildIntegrationIdentity, discoverManifestPath, readAppName, readAppNameWalkup };
+//# sourceMappingURL=discover.d.mts.map