@tempo-ai/mcp 0.0.102 → 0.0.103

package/dist/bin.js

@@ -2,7 +2,7 @@
 import { createRequire as __tempoCreateRequire } from 'node:module'; const require = __tempoCreateRequire(import.meta.url);
 import {
   run
-} from "./chunk-6P4PI7CS.js";
+} from "./chunk-C3J4LFJI.js";
 import "./chunk-KQNQSVOA.js";
 
 // src/bin.ts

package/dist/{call-TNF2AXMX.js → call-XYOJSSYR.js}

@@ -8,7 +8,7 @@ import {
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 async function connectAggregate(options) {
-  const { createTempoAggregate } = await import("./serve-NGUFKD5I.js");
+  const { createTempoAggregate } = await import("./serve-P7M4UFJS.js");
   const handle = await createTempoAggregate(options);
   const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
   const client = new Client({ name: "tempo-mcp-cli", version: "0" });
@@ -127,4 +127,4 @@ export {
   runCall,
   runTools
 };
-//# sourceMappingURL=call-TNF2AXMX.js.map
+//# sourceMappingURL=call-XYOJSSYR.js.map

package/dist/{chunk-6P4PI7CS.js → chunk-C3J4LFJI.js}

@@ -157,7 +157,7 @@ async function run(argv) {
         process.stderr.write(USAGE);
         return 1;
       }
-      const { runServe } = await import("./serve-NGUFKD5I.js");
+      const { runServe } = await import("./serve-P7M4UFJS.js");
       return await runServe(options);
     }
     switch (subcommand) {
@@ -172,11 +172,11 @@ async function run(argv) {
         return await runToken(rest);
       }
       case "tools": {
-        const { runTools } = await import("./call-TNF2AXMX.js");
+        const { runTools } = await import("./call-XYOJSSYR.js");
         return await runTools(rest);
       }
       case "call": {
-        const { runCall } = await import("./call-TNF2AXMX.js");
+        const { runCall } = await import("./call-XYOJSSYR.js");
         return await runCall(rest);
       }
       default:
@@ -195,4 +195,4 @@ async function run(argv) {
 export {
   run
 };
-//# sourceMappingURL=chunk-6P4PI7CS.js.map
+//# sourceMappingURL=chunk-C3J4LFJI.js.map

package/dist/index.js

@@ -1,7 +1,7 @@
 import { createRequire as __tempoCreateRequire } from 'node:module'; const require = __tempoCreateRequire(import.meta.url);
 import {
   run
-} from "./chunk-6P4PI7CS.js";
+} from "./chunk-C3J4LFJI.js";
 import "./chunk-KQNQSVOA.js";
 export {
   run

package/dist/{serve-NGUFKD5I.js → serve-P7M4UFJS.js}

@@ -15520,11 +15520,11 @@ scaffolded project.
 | \`scripts.start\` | string | Canvas-host launcher (runs from the tempo root). Prefer a foreground process. Tempo substitutes every literal \`\${PORT}\`, exports the same port as \`TEMPO_PORT\`, and sets \`TEMPO=true\`. |
 | \`scripts.stop\` | string? | Matching teardown for a daemonized/external host. Tempo substitutes \`\${PORT}\` and runs this before signalling the launcher group. Required when \`scripts.start\` exits successfully while the host continues in the background. |
 | \`urls.tempoHost\` | URL string? | Public \`/tempo-host\` URL to probe when stdout cannot describe the reachable boundary (containers, tunnels, remotes). May contain \`\${PORT}\`; e.g. \`http://127.0.0.1:\${PORT}/tempo-host\`. |
-| \`apps\` | array? | \`[{ "appDir"?, "appStart"? }]\` \u2014 one entry per client app; only \`apps[0]\` is active today. \`apps[0].appStart\` is the user's REAL app dev-server command, supervised by Tempo for route storyboards; must contain \`\${PORT}\` (see "Route Storyboards & the app dev command"). Legacy \`scripts.appStart\` / top-level \`appDir\` still read and auto-migrate. |
+| \`apps\` | array? | \`[{ "appDir"?, "start"?, "url"? }]\` \u2014 one entry per client app; only \`apps[0]\` is active today. \`start\` launches the user's REAL app for route storyboards and may be any foreground command; \`url\` optionally supplies the independent HTTP(S) readiness target and route base. \`\${APP_PORT}\` is an optional allocated-port helper and legacy \`\${PORT}\` remains supported. Legacy \`apps[].appStart\`, \`scripts.appStart\`, and top-level \`appDir\` still read and auto-migrate. |
 
 **Every command in this file runs through the platform shell \u2014 \`cmd.exe\` on
 Windows, not PowerShell.** That applies to \`scripts.install\` and
-\`scripts.start\` exactly as it does to \`appStart\`. Write plain, cross-platform
+\`scripts.start\` exactly as it does to app \`start\`. Write plain, cross-platform
 invocations; \`&&\` and \`cd\` are fine (cmd supports both). Never use PowerShell
 syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\` \u2014 because
 cmd.exe cannot parse it and aborts with "X was unexpected at this time" BEFORE
@@ -15565,8 +15565,10 @@ For Svelte 5, setup is complete only when all applicable items below hold:
    \`tempo/vite.config.ts\`\u2014includes \`tempoVitePlugin()\` and its active Svelte
    preprocessing chain starts with \`tempoSveltePreprocess(...)\`. Preserve all
    existing preprocessors after Tempo's preprocessor.
-4. Route storyboards additionally have an \`apps[0].appStart\` command containing
-   the literal \`\${PORT}\` token. Configure it with \`set_app_dev_command\`.
+4. Route storyboards additionally have an \`apps[0].start\` command and should
+   set \`apps[0].url\` when the HTTP(S) liveness target is known. The command
+   may use the optional \`\${APP_PORT}\` helper (legacy \`\${PORT}\` also
+   works). Configure both with \`set_app_dev_command\`.
 
 The official Svelte Vite plugin compiles \`.svelte\` modules; Tempo's Vite
 plugin injects the projection runtime; and Tempo's Svelte preprocessor records
@@ -15918,7 +15920,7 @@ export default function AuthComponentsCanvas() {
 
 Canvases created before the React format use object exports instead of JSX \u2014 \`export const Login: TempoStoryboard = { render: () => <LoginForm />, layout: {\u2026} }\` with a \`TempoCanvasConfig\` default export. Tempo migrates these to the React format automatically when they are opened in the Design tab. If you encounter one, run \`canvas_migrate_to_latest\` on it BEFORE making any edit \u2014 never hand-write legacy declarations, and never mix the two formats in one file.
 
-### Route Storyboards & the app dev command (\`apps[0].appStart\`)
+### Route Storyboards & the app dev config (\`apps[0].start\` / \`url\`)
 
 Route storyboards (\`<RouteStoryboard>\`) load **the user's real app** in the iframe, NOT the canvas sidecar. They need a second supervised process \u2014 the user's actual app dev server \u2014 which Tempo manages from the app dev command in \`tempo.config.json\`, stored canonically on the \`apps[]\` list (one entry per client app; only \`apps[0]\` is active today):
 
@@ -15931,13 +15933,14 @@ Route storyboards (\`<RouteStoryboard>\`) load **the user's real app** in the if
   "apps": [
     {
       "appDir": "client",                          // app package dir, relative to repo root (omit for autodetect)
-      "appStart": "npm run dev -- --port=\${PORT}"  // user's real app
+      "start": "npm exec vite --port=\${APP_PORT}",    // arbitrary foreground command
+      "url": "http://127.0.0.1:\${APP_PORT}"           // optional HTTP(S) liveness target
     }
   ]
 }
 \`\`\`
 
-(Files written by older Tempo versions may still carry the legacy \`scripts.appStart\` / top-level \`appDir\` spelling \u2014 those read fine and auto-migrate to \`apps[]\` the next time the config is written.)
+(Files written by older Tempo versions may still carry \`apps[].appStart\`, \`scripts.appStart\`, or top-level \`appDir\`. They read normally and migrate to canonical \`apps[].start\` on the next config write.)
 
 **The app's own bundler config MUST include the Tempo annotation plugin.** Route storyboards are served by the user's app dev server (NOT the \`tempo/\` sidecar), so the canvas can only select/edit their elements if THAT server injects the \`data-tempo-*\` annotations \u2014 i.e. the **app's own** framework config carries the Tempo plugin, active under \`TEMPO=true\`. Without it the app still renders in the iframe, but every click collapses to one unmappable root and the user reports *"route storyboard elements are not clickable."* This is separate from the \`tempo/\` sidecar's plugin (\xA74.2) \u2014 both configs need it, for different servers. Add the plugin to the app package (and add \`tempo-sdk\` to the app's deps) per framework:
 
@@ -15990,13 +15993,13 @@ Route storyboards (\`<RouteStoryboard>\`) load **the user's real app** in the if
   };
   \`\`\`
 
-The plugin no-ops unless \`TEMPO=true\` (which the supervisor sets when it runs \`appStart\`), so it is safe to keep in the config permanently.
+The plugin no-ops unless \`TEMPO=true\` (which the supervisor sets when it runs app \`start\`), so it is safe to keep in the config permanently.
 
 Mechanics:
 
-- The supervisor allocates a free TCP port per workspace, persisted at \`<workspaceRoot>/.tempo/app-devserver.json\` (gitignored, per-worktree).
-- The literal \`\${PORT}\` token in the command is substituted at spawn time, so multiple worktrees of the same project never collide on the same port.
-- The renderer resolves route storyboard URLs to the app server's URL, so \`route: "/dashboard"\` becomes \`http://127.0.0.1:<allocated>/dashboard\` automatically.
+- The supervisor always allocates a free local TCP port per workspace and persists it at \`<workspaceRoot>/.tempo/app-devserver.json\` (gitignored, per-worktree).
+- A \`url\` containing \`\${APP_PORT}\` (or legacy \`\${PORT}\`) uses that allocated helper value. A literal URL is an opaque HTTP(S) readiness target and route base: its hostname and port never control local allocation, so it may point through a container, tunnel, or remote machine.
+- Every literal \`\${APP_PORT}\` or legacy \`\${PORT}\` in app \`start\` and \`url\` is substituted before spawn/probe. The renderer resolves route storyboard paths against the resulting URL.
 - Lifecycle: warm with a 5-minute idle stop \u2014 the supervisor stays alive while a canvas with route storyboards is open and stops 5 minutes after the last canvas closes.
 - While starting, an overlay reads "Starting your app dev server\u2026" on every route storyboard.
 
@@ -16006,16 +16009,29 @@ Mechanics:
 
 | Framework | Command shape |
 |-----------|---------------|
-| Vite | \`<pm> exec vite --port=\${PORT} --strictPort\` (e.g. \`pnpm exec vite \u2026\`, \`npx vite \u2026\`) |
-| Next.js | \`<pm> exec next dev -p \${PORT}\` |
-| Expo (web) | \`npx expo start --web --port \${PORT}\` |
-| CRA / Remix / generic | \`PORT=\${PORT} npm run dev\` |
+| Vite | \`<pm> exec vite --port=\${APP_PORT} --strictPort\` (e.g. \`pnpm exec vite \u2026\`, \`npx vite \u2026\`) |
+| Next.js | \`<pm> exec next dev -p \${APP_PORT}\` |
+| Expo (web) | \`npx expo start --web --port \${APP_PORT}\` |
+| CRA / Remix / generic | \`PORT=\${APP_PORT} npm run dev\` |
 
-**Invoke the bundler binary directly \u2014 do NOT route the port flag through \`<pm> run dev -- --port=\${PORT}\`.** When the \`dev\` script is a bare \`vite\` (the common case) and the project uses **pnpm**, \`pnpm run dev -- --port=\${PORT}\` forwards the literal \`--\` separator through to Vite, which treats it as a positional arg, ignores \`--port\`, and binds its default 5173 instead of the supervisor's allocated \`\${PORT}\` \u2014 so every route storyboard then points at the wrong server. npm strips the first \`--\` so it happens to work there, but the direct-exec form (\`pnpm exec vite \u2026\` / \`npx vite \u2026\`) is correct under every package manager. (\`--strictPort\` makes the mismatch fail loudly instead of silently falling back.)
+**When using the allocated helper port, invoke the bundler binary directly \u2014 do NOT route the port flag through \`<pm> run dev -- --port=\${APP_PORT}\`.** When the \`dev\` script is a bare \`vite\` (the common case) and the project uses **pnpm**, that form can forward the literal \`--\` separator through to Vite, which treats it as a positional arg and ignores \`--port\`. The direct-exec form (\`pnpm exec vite \u2026\` / \`npx vite \u2026\`) is correct under every package manager. (\`--strictPort\` makes a mismatch fail loudly.)
 
-The command MUST contain the literal \`\${PORT}\` token. Without it the supervisor would land on the framework's default port and race with sibling workspaces or unrelated processes; the validator refuses commands missing the token.
+The command is otherwise arbitrary. The allocated helper token is optional, and a configured \`url\` is always the liveness target Tempo probes.
 
-**Keep the command plain and cross-platform \u2014 one invocation, no shell conditionals.** Tempo spawns it through the platform shell (**cmd.exe on Windows**, not PowerShell) and substitutes \`\${PORT}\` to a literal port BEFORE spawning, so a bare \`npm\`/\`node\` command runs identically on cmd.exe and POSIX shells. A leading \`NAME=value\` prefix \u2014 the CRA/Remix shape \`PORT=\${PORT} npm run dev\` \u2014 is also safe on every OS: the supervisor lifts it into the spawn environment instead of handing it to the shell (cmd.exe would otherwise parse \`PORT=3001\` as a program name), and it always sets \`PORT\`/\`TEMPO_APP_PORT\` in the environment regardless. Never use PowerShell syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\`, \`Get-\`/\`Set-\` cmdlets \u2014 cmd.exe can't parse it and aborts with "X was unexpected at this time" BEFORE running anything (\`set_app_dev_command\` rejects PowerShell-shaped commands at author time, and the supervisor refuses to spawn one that reaches it via a hand-edited config). Chaining with \`&&\` is fine \u2014 cmd supports it \u2014 but there should be no need for it here. If the app lives in a subdirectory, set \`appDir\` (in \`tempo.config.json\` or via \`set_app_dev_command\`) instead of \`cd\`/\`pushd\`-ing inside the command \u2014 the supervisor runs the command from \`appDir\` for you.
+**Independent readiness URL.** Use a literal \`url\` whenever the URL Tempo can reach differs from the locally allocated port, including a container, tunnel, or remote machine:
+
+\`\`\`json
+{
+  "apps": [{
+    "start": "npm run dev:remote",
+    "url": "https://preview.example.com"
+  }]
+}
+\`\`\`
+
+The supervisor probes \`url\` directly rather than waiting for stdout URL discovery and uses it as the public route base after it responds. The local helper port remains independently allocated and available to \`start\` through \`APP_PORT\`, \`PORT\`, and \`TEMPO_APP_PORT\`, even when the literal URL spells a completely different host or explicit port.
+
+**Keep the command plain and cross-platform \u2014 one invocation, no shell conditionals.** Tempo spawns it through the platform shell (**cmd.exe on Windows**, not PowerShell) and substitutes \`\${APP_PORT}\` (or legacy \`\${PORT}\`) before spawning. A leading \`NAME=value\` prefix \u2014 for example \`PORT=\${APP_PORT} npm run dev\` \u2014 is also safe on every OS: the supervisor lifts it into the spawn environment instead of handing it to the shell, and it always sets \`APP_PORT\`, \`PORT\`, and \`TEMPO_APP_PORT\` in the environment regardless. Never use PowerShell syntax \u2014 \`if (Test-Path \u2026) { \u2026 } else { \u2026 }\`, \`Test-Path\`, \`$env:FOO\`, \`Get-\`/\`Set-\` cmdlets \u2014 cmd.exe can't parse it and aborts before running anything. If the app lives in a subdirectory, set \`appDir\` instead of changing directories inside the command.
 
 **Driving the lifecycle directly.** Three sibling tools mirror the canvas-sidecar trio: \`check_app_dev_server\` / \`start_app_dev_server\` / \`stop_app_dev_server\` (vs \`check_canvas_devserver\` / \`start_canvas_devserver\` / \`stop_canvas_devserver\`). \`check_app_dev_server\` returns \`{configured, running, phase, port, url, error}\` \u2014 call it first when a route storyboard isn't loading, to disambiguate: \`configured: false\` \u2192 \`set_app_dev_command\`; \`configured: true, running: false\` \u2192 read \`error\`, then \`start_app_dev_server\`; \`running: true\` \u2192 the route itself is the problem, not the supervisor. After editing the app dev command, \`stop_app_dev_server\` then \`start_app_dev_server\` to pick up the new command.
 
@@ -16023,9 +16039,9 @@ The command MUST contain the literal \`\${PORT}\` token. Without it the supervis
 
 **Home canvas.** A project's home canvas (single \`route: "/"\` storyboard) backs the header Run (play) button and the turn-summary "Run app" card \u2014 both open it next to the app's dev-server output. When setting a project up for canvases or route storyboards, ensure one exists: \`canvas_project_init\` seeds it alongside the template canvas; if a \`route: "/"\` canvas already exists, mark it with \`canvas_set_home\` instead of duplicating; otherwise create one with \`canvas_create({ canvas_name: "Home", home: true, storyboards: [{ export_name: "Home", route: "/" }] })\`.
 
-Use the \`set_app_dev_command\` MCP tool to write this \u2014 don't hand-edit \`tempo.config.json\` for it. The tool validates the \`\${PORT}\` invariant and clears any cached supervisor so the next route storyboard load picks up the new command. \`create-canvas\` issues a soft-gate warning in its result when route storyboards are requested but the app dev command is missing \u2014 confirm the command with the user, then call \`set_app_dev_command\`. When you set it, you should also check the app's bundler plugin + \`tempo-sdk\` dep are in place (above), unless you already did.
+Use the \`set_app_dev_command\` MCP tool to write this \u2014 don't hand-edit \`tempo.config.json\` for it. The tool validates the fields and clears any cached supervisor so the next route storyboard load picks up the new config. \`create-canvas\` issues a soft-gate warning in its result when route storyboards are requested but app start is missing \u2014 confirm the command with the user, then call \`set_app_dev_command\`. When you set it, you should also check the app's bundler plugin + \`tempo-sdk\` dep are in place (above), unless you already did.
 
-Once set, \`appStart\` also appears automatically in the workspace header's Run (play) button under **Org run scripts** as a read-only "App dev server" entry (the default unless the user picks another) \u2014 never add a run script duplicating it, and when the route-storyboard supervisor is already up, point the user at its URL instead of suggesting they also hit play. Other Run-button commands (build, test, \u2026) are DB-backed (org-shared + per-user, per project) \u2014 add them with \`configure_run_script\` (\`tempo-scripts-tools\` MCP), not in this file. The home canvas + app dev command stay in the repo, so once the app runs, suggest committing them so teammates get the app Run entry too.
+Once set, app \`start\` also appears automatically in the workspace header's Run (play) button under **Org run scripts** as a read-only "App dev server" entry (the default unless the user picks another) \u2014 never add a run script duplicating it, and when the route-storyboard supervisor is already up, point the user at its URL instead of suggesting they also hit play. Other Run-button commands (build, test, \u2026) are DB-backed (org-shared + per-user, per project) \u2014 add them with \`configure_run_script\` (\`tempo-scripts-tools\` MCP), not in this file. The home canvas + app dev config stay in the repo, so once the app runs, suggest committing them so teammates get the app Run entry too.
 
 ### Import Resolution
 
@@ -23705,7 +23721,7 @@ function matchClass(line) {
   if (isShellParseAbortOutput(line)) {
     return {
       class: "shell-dialect-mismatch",
-      hint: "The dev command failed to PARSE in the shell (Tempo runs commands through cmd.exe on Windows) \u2014 nothing actually ran. This almost always means the command was written in PowerShell syntax, which cmd.exe cannot parse: `if (...) { ... } else { ... }`, `Test-Path`, `$env:FOO`. Rewrite it as a single, plain, cross-platform invocation with no shell conditionals \u2014 e.g. `npm exec -- next dev -p ${PORT}` or `npm run dev -- --port=${PORT}` (chaining with `&&` is fine; cmd supports it). Tempo substitutes `${PORT}` before spawning, so a bare npm/node command runs identically on cmd.exe and POSIX shells. If you need a conditional, cmd's native form is `if exist package.json (...) else (...)`; if the app lives in a subdirectory, set `appDir` in tempo.config.json instead of `cd`/`pushd`-ing inside the command."
+      hint: "The dev command failed to PARSE in the shell (Tempo runs commands through cmd.exe on Windows) \u2014 nothing actually ran. This almost always means the command was written in PowerShell syntax, which cmd.exe cannot parse: `if (...) { ... } else { ... }`, `Test-Path`, `$env:FOO`. Rewrite it as a single, plain, cross-platform invocation with no shell conditionals \u2014 e.g. `npm exec next dev -p ${APP_PORT}` or simply `npm run dev` when it does not need Tempo's optional allocated helper port (legacy `${PORT}` also works). Chaining with `&&` is fine; cmd supports it. If the app lives in a subdirectory, set `appDir` in tempo.config.json instead of `cd`/`pushd`-ing inside the command."
     };
   }
   if (isDevServerLockConflictOutput(line)) {
@@ -24453,6 +24469,7 @@ var AppDevServer = class _AppDevServer {
     this.hasParentDeathWatchdog = false;
     this.options = {
       command: options.command,
+      url: options.url,
       cwd: path12.resolve(options.cwd),
       workspaceRoot: path12.resolve(options.workspaceRoot),
       urlScrapeTimeoutMs: resolveUrlScrapeTimeout(options.urlScrapeTimeoutMs),
@@ -24713,7 +24730,7 @@ var AppDevServer = class _AppDevServer {
     this.recentOutput = [];
     const dialectIssue = findPowerShellSyntax(this.options.command);
     if (dialectIssue) {
-      const error = `The app dev command was rejected before spawn: it contains PowerShell-only syntax (${dialectIssue}), which the shell Tempo runs commands with (cmd.exe on Windows) cannot parse \u2014 nothing was started. Rewrite "appStart" in tempo.config.json as a single plain cross-platform command containing \${PORT} \u2014 e.g. "npm run dev -- --port=\${PORT}" \u2014 and if the app lives in a subdirectory set "appDir" instead of cd/pushd-ing inside the command (chaining with \`&&\` is fine; cmd supports it).`;
+      const error = `The app dev command was rejected before spawn: it contains PowerShell-only syntax (${dialectIssue}), which the shell Tempo runs commands with (cmd.exe on Windows) cannot parse \u2014 nothing was started. Rewrite "apps[0].start" in tempo.config.json as a single plain cross-platform command \u2014 use \${APP_PORT} only if it needs Tempo's allocated helper port \u2014 and if the app lives in a subdirectory set "appDir" instead of cd/pushd-ing inside the command (chaining with \`&&\` is fine; cmd supports it).`;
       devLog("app-devserver:shell-dialect-rejected", {
         command: this.options.command,
         construct: dialectIssue
@@ -24745,6 +24762,7 @@ var AppDevServer = class _AppDevServer {
       const command = lifted.command;
       const env = {
         ...process.env,
+        APP_PORT: String(port),
         PORT: String(port),
         TEMPO_APP_PORT: String(port),
         // Activate the Tempo annotation plugin (tempoVitePlugin /
@@ -24767,6 +24785,7 @@ var AppDevServer = class _AppDevServer {
       Object.assign(env, lifted.env);
       devLog("app-devserver:spawn", {
         command,
+        configuredUrl: this.options.url ?? null,
         liftedEnvKeys: Object.keys(lifted.env),
         cwd: this.options.cwd,
         port
@@ -25028,14 +25047,21 @@ Hint: ${hint.hint}` : ""}`;
     });
   }
   async waitForReady(port, signal) {
-    const scrapeDeadline = Date.now() + this.options.urlScrapeTimeoutMs;
-    while (!this.detectedBaseUrl && Date.now() < scrapeDeadline) {
-      throwIfAppLaunchAborted(signal);
-      if (!this.child) return null;
-      await sleepForAppLaunch(120, signal);
-    }
-    const baseUrl = this.detectedBaseUrl ?? `http://${PUBLIC_HOSTNAME}:${port}`;
-    const publicUrl = rewriteToPublicHost(baseUrl, port);
+    const configuredUrl = this.options.url ? substituteAppPort(this.options.url, port) : null;
+    if (!configuredUrl) {
+      const scrapeDeadline = Date.now() + this.options.urlScrapeTimeoutMs;
+      while (!this.detectedBaseUrl && Date.now() < scrapeDeadline) {
+        throwIfAppLaunchAborted(signal);
+        if (!this.child) return null;
+        await sleepForAppLaunch(120, signal);
+      }
+    }
+    const baseUrl = configuredUrl ?? this.detectedBaseUrl ?? `http://${PUBLIC_HOSTNAME}:${port}`;
+    const publicUrl = rewriteToPublicHost(
+      baseUrl,
+      port,
+      configuredUrl === null
+    );
     const start = Date.now();
     let lastProgressAt = start;
     while (true) {
@@ -25403,17 +25429,17 @@ function extractServerUrl(text) {
   }
   return null;
 }
-function rewriteToPublicHost(url, fallbackPort) {
+function rewriteToPublicHost(url, fallbackPort, applyFallbackPort = true) {
   try {
     const parsed = new URL(url);
     if (parsed.hostname === "0.0.0.0" || parsed.hostname === "::") {
       parsed.hostname = PUBLIC_HOSTNAME;
     }
-    if (!parsed.port) {
+    if (applyFallbackPort && !parsed.port) {
       parsed.port = String(fallbackPort);
     }
     const normalizedPath = parsed.pathname.replace(/\/+$/, "");
-    return `${parsed.origin}${normalizedPath}`;
+    return `${parsed.origin}${normalizedPath}${parsed.search}`;
   } catch {
     return `http://${PUBLIC_HOSTNAME}:${fallbackPort}`;
   }
@@ -25504,7 +25530,7 @@ function waitForWatchdogChildPid(watchdog, timeoutMs = 2e3) {
   });
 }
 function substituteAppPort(command, port) {
-  return command.replace(/\$\{PORT\}/g, String(port));
+  return command.replace(/\$\{(?:APP_PORT|PORT)\}/g, String(port));
 }
 async function findFreePort(range) {
   const maxAttempts = 50;
@@ -32291,9 +32317,25 @@ function validateAppStart(value, label = "scripts.appStart") {
     );
   }
   const trimmed2 = value.trim();
-  if (!trimmed2.includes("${PORT}")) {
+  return trimmed2;
+}
+function validateAppUrl(value, label) {
+  if (value === void 0 || value === null) return void 0;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(
+      `tempo.config.json field "${label}" must be a non-empty string when set`
+    );
+  }
+  const trimmed2 = value.trim();
+  let parsed;
+  try {
+    parsed = new URL(trimmed2.replace(/\$\{(?:APP_PORT|PORT)\}/g, "5173"));
+  } catch {
+    throw new Error(`tempo.config.json field "${label}" must be a valid URL`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(
-      `tempo.config.json field "${label}" must include the literal "\${PORT}" token so the supervisor can inject the allocated port (e.g. "npx vite --port=\${PORT} --strictPort" or "npm exec next dev -- -p \${PORT}")`
+      `tempo.config.json field "${label}" must use the "http:" or "https:" protocol`
     );
   }
   return trimmed2;
@@ -32385,9 +32427,7 @@ function validateApps(value) {
   const seenAppDirs = /* @__PURE__ */ new Set();
   return value.map((entry, i) => {
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-      throw new Error(
-        `tempo.config.json field "apps[${i}]" must be an object`
-      );
+      throw new Error(`tempo.config.json field "apps[${i}]" must be an object`);
     }
     const raw = entry;
     const appDir = validateAppDir(raw.appDir, `apps[${i}].appDir`);
@@ -32404,19 +32444,36 @@ function validateApps(value) {
       }
       seenAppDirs.add(appDir);
     }
-    const appStart = validateAppStart(raw.appStart, `apps[${i}].appStart`);
+    const url = validateAppUrl(raw.url, `apps[${i}].url`);
+    const start = validateAppStart(raw.start, `apps[${i}].start`);
+    const legacyAppStart = validateAppStart(
+      raw.appStart,
+      `apps[${i}].appStart`
+    );
+    if (start !== void 0 && legacyAppStart !== void 0 && start !== legacyAppStart) {
+      throw new Error(
+        `tempo.config.json fields "apps[${i}].start" and legacy "apps[${i}].appStart" disagree \u2014 make them match or drop "appStart"`
+      );
+    }
+    const effectiveStart = start ?? legacyAppStart;
+    if (url !== void 0 && effectiveStart === void 0) {
+      throw new Error(
+        `tempo.config.json field "apps[${i}].url" requires "apps[${i}].start"`
+      );
+    }
     const uiFramework = validateUiFramework(
       raw.uiFramework,
       `apps[${i}].uiFramework`
     );
-    if (appDir === void 0 && appStart === void 0 && uiFramework === void 0) {
+    if (appDir === void 0 && effectiveStart === void 0 && url === void 0 && uiFramework === void 0) {
       throw new Error(
-        `tempo.config.json field "apps[${i}]" must set "appDir", "appStart", and/or "uiFramework" \u2014 an empty entry encodes nothing`
+        `tempo.config.json field "apps[${i}]" must set "appDir", "start", "url", and/or "uiFramework" \u2014 an empty entry encodes nothing`
       );
     }
     return {
       ...appDir !== void 0 ? { appDir } : {},
-      ...appStart !== void 0 ? { appStart } : {},
+      ...effectiveStart !== void 0 ? { start: effectiveStart } : {},
+      ...url !== void 0 ? { url } : {},
       ...uiFramework !== void 0 ? { uiFramework } : {}
     };
   });
@@ -32470,11 +32527,10 @@ function validateTempoConfigFile(value) {
   const setupScript = validateSetupScript(raw.setupScript);
   const runScripts = validateRunScripts(raw.runScripts);
   const appStart = validateAppStart(
-    scripts.appStart
-  );
-  const stop = validateScriptsStop(
-    scripts.stop
+    scripts.appStart,
+    "scripts.appStart"
   );
+  const stop = validateScriptsStop(scripts.stop);
   if (apps) {
     const activeApp = apps[0];
     if (appDir !== void 0 && appDir !== activeApp.appDir) {
@@ -32482,9 +32538,9 @@ function validateTempoConfigFile(value) {
         `tempo.config.json fields "appDir" ("${appDir}") and "apps[0].appDir" ("${activeApp.appDir}") disagree \u2014 apps[0] is the active app; make them match or drop the legacy "appDir"`
       );
     }
-    if (appStart !== void 0 && appStart !== activeApp.appStart) {
+    if (appStart !== void 0 && appStart !== activeApp.start) {
       throw new Error(
-        'tempo.config.json fields "scripts.appStart" and "apps[0].appStart" disagree \u2014 apps[0] is the active app; make them match or drop the legacy "scripts.appStart"'
+        'tempo.config.json fields "scripts.appStart" and "apps[0].start" disagree \u2014 apps[0] is the active app; make them match or drop the legacy "scripts.appStart"'
       );
     }
   }
@@ -32495,12 +32551,12 @@ function validateTempoConfigFile(value) {
     normalizedApps = [
       {
         ...appDir !== void 0 ? { appDir } : {},
-        ...appStart !== void 0 ? { appStart } : {}
+        ...appStart !== void 0 ? { start: appStart } : {}
       }
     ];
   }
   const activeAppDir = normalizedApps ? normalizedApps[0].appDir : void 0;
-  const activeAppStart = normalizedApps ? normalizedApps[0].appStart : void 0;
+  const activeAppStart = normalizedApps ? normalizedApps[0].start : void 0;
   return {
     ...paths ? { paths } : {},
     ...urls ? { urls } : {},
@@ -32790,14 +32846,19 @@ async function resolveTempoConfig(projectRoot) {
   if (config.apps && config.apps.length > 0) {
     apps = config.apps.map((app) => ({
       appDir: app.appDir,
-      appStart: app.appStart ?? null,
+      start: app.start ?? null,
+      url: app.url ?? null,
+      appStart: app.start ?? null,
       ...app.uiFramework ? { uiFramework: app.uiFramework } : {}
     }));
   } else {
+    const legacyStart = config.scripts.appStart ?? null;
     apps = [
       {
         ...config.appDir !== void 0 ? { appDir: config.appDir } : {},
-        appStart: config.scripts.appStart ?? null
+        start: legacyStart,
+        url: null,
+        appStart: legacyStart
       }
     ];
   }
@@ -32814,6 +32875,7 @@ async function resolveTempoConfig(projectRoot) {
     viteConfigPath: path23.join(tempoRoot, "vite.config.ts"),
     tsconfigPath: path23.join(tempoRoot, "tsconfig.json"),
     tempoHostUrl: config.urls?.tempoHost ?? null,
+    appUrl: activeApp.url,
     scripts: {
       install: config.scripts.install,
       start: config.scripts.start,
@@ -44094,11 +44156,11 @@ function registerTools(server, context) {
                     ...output,
                     warnings: [
                       ...output.warnings ?? [],
-                      "This canvas contains a route storyboard (`<RouteStoryboard>`) but no app dev command (`apps[0].appStart`) is configured in tempo.config.json. Route iframes will fail to load until you configure the user's real app dev server. Read the project root's package.json `scripts.dev`, pick the right port-injection shape for the framework, and call `set_app_dev_command` (must include the literal `${PORT}` token)."
+                      "This canvas contains a route storyboard (`<RouteStoryboard>`) but no app dev command (`apps[0].start`) is configured in tempo.config.json. Route iframes will fail to load until you configure the user's real app dev server. Read the project root's package.json `scripts.dev`, then call `set_app_dev_command` with that foreground command and, when known, its HTTP(S) readiness URL. `${APP_PORT}` is an optional allocated-port helper; legacy `${PORT}` remains supported."
                     ],
                     app_dev_server: {
                       configured: false,
-                      next_step: "Call set_app_dev_command with a command that includes ${PORT}."
+                      next_step: "Call set_app_dev_command with start and, when needed, url."
                     }
                   },
                   null,
@@ -44298,7 +44360,7 @@ function registerTools(server, context) {
             start: scaffoldedConfig.scripts.start
           }
         } : void 0;
-        const reviewNotes = "UI source framework is explicit: omission means React. If this is a Svelte 5 app, set apps[0].uiFramework to \"svelte\" in tempo.config.json and rerun canvas_project_init before creating storyboards. That rerun fills the generated sidecar's missing svelte and @sveltejs/vite-plugin-svelte dependencies using starter defaults; it preserves existing sidecar package specs. For a Svelte route storyboard, setup is NOT complete until apps[0].appStart contains the literal ${PORT} token, the app's own package depends on tempo-sdk, and a standalone Svelte/Vite app directly dev-depends on @sveltejs/vite-plugin-svelte. Use set_app_dev_command for appStart. Add only missing app packages, choose versions compatible with its existing Svelte/Vite toolchain, and never replace configured versions with Tempo's starter defaults. The app's own Vite/Svelte config must use tempoVitePlugin() plus tempoSveltePreprocess(...) as the first Svelte preprocessor; the generated tempo/ sidecar config does not affect the separately running app. Preserve any existing Svelte preprocessors after Tempo's. Double-check initial_tempo_config's scripts.install against this repo before moving on. A plain package-manager install (bare `npm install`/`pnpm install`/\u2026 or Tempo's chained `cd .. && \u2026 && cd tempo && \u2026` form) means Tempo's DEFAULT behavior: it installs the project root and tempo/ itself with the detected package manager \u2014 correct for most single-package repos. Write a CUSTOM command instead when the default won't produce importable app code: the app lives in a workspace/monorepo subdirectory (install must run at the workspace root or with the right filter), the app needs postinstall codegen (e.g. `prisma generate`), a private registry needs .npmrc/env, or the repo has a non-standard install. A custom value runs verbatim from tempo/ (cmd.exe-compatible syntax only, cover BOTH roots' dependencies) and Tempo NEVER rewrites it. After editing, run start_canvas_devserver({ force_install: true }).";
+        const reviewNotes = "UI source framework is explicit: omission means React. If this is a Svelte 5 app, set apps[0].uiFramework to \"svelte\" in tempo.config.json and rerun canvas_project_init before creating storyboards. That rerun fills the generated sidecar's missing svelte and @sveltejs/vite-plugin-svelte dependencies using starter defaults; it preserves existing sidecar package specs. For a Svelte route storyboard, setup is NOT complete until apps[0].start is configured, the app's own package depends on tempo-sdk, and a standalone Svelte/Vite app directly dev-depends on @sveltejs/vite-plugin-svelte. Use set_app_dev_command for start and its HTTP(S) readiness URL when known; `${APP_PORT}` is an optional allocated-port helper and legacy `${PORT}` remains supported. Add only missing app packages, choose versions compatible with its existing Svelte/Vite toolchain, and never replace configured versions with Tempo's starter defaults. The app's own Vite/Svelte config must use tempoVitePlugin() plus tempoSveltePreprocess(...) as the first Svelte preprocessor; the generated tempo/ sidecar config does not affect the separately running app. Preserve any existing Svelte preprocessors after Tempo's. Double-check initial_tempo_config's scripts.install against this repo before moving on. A plain package-manager install (bare `npm install`/`pnpm install`/\u2026 or Tempo's chained `cd .. && \u2026 && cd tempo && \u2026` form) means Tempo's DEFAULT behavior: it installs the project root and tempo/ itself with the detected package manager \u2014 correct for most single-package repos. Write a CUSTOM command instead when the default won't produce importable app code: the app lives in a workspace/monorepo subdirectory (install must run at the workspace root or with the right filter), the app needs postinstall codegen (e.g. `prisma generate`), a private registry needs .npmrc/env, or the repo has a non-standard install. A custom value runs verbatim from tempo/ (cmd.exe-compatible syntax only, cover BOTH roots' dependencies) and Tempo NEVER rewrites it. After editing, run start_canvas_devserver({ force_install: true }).";
         return textResult2(
           JSON.stringify(
             {
@@ -44412,27 +44474,44 @@ function registerTools(server, context) {
   );
   server.tool(
     "set_app_dev_command",
-    "Configure the app dev command in tempo.config.json \u2014 the command that runs the user's REAL app dev server, stored canonically as `apps[0].appStart` (files with the legacy `scripts.appStart` spelling are still read and auto-migrate to `apps[]` on write). Required for route storyboards (`<RouteStoryboard>`) to load real app pages in the canvas iframe. The command MUST contain the literal `${PORT}` token; the per-workspace supervisor allocates a free port and substitutes it at spawn time, so workspaces never collide. Examples: `npx vite --port=${PORT} --strictPort` (Vite), `npm exec next dev -- -p ${PORT}` (Next), `PORT=${PORT} npm run dev` (CRA/Remix/generic), `npx expo start --web --port ${PORT}` (Expo). Invoke the bundler binary directly rather than `<pm> run dev -- --port=${PORT}` \u2014 pnpm forwards the literal `--` through to Vite, which then ignores the port flag and binds its default. Before calling, read the project root's package.json scripts.dev to learn how the user invokes their app, pick the right port-injection shape for the framework, and confirm with the user. When you set this, you should also check the app's own bundler config wires the Tempo plugin (`tempoVitePlugin()` / `tempoNextjsPlugin()` / `tempoExpoBabelPlugin`) and that `tempo-sdk` is an app dependency \u2014 add it if missing, or route storyboard elements won't be selectable. Keep the command a single plain cross-platform invocation \u2014 Tempo runs it via cmd.exe on Windows, substitutes `${PORT}` before spawn, and lifts a leading `NAME=value` prefix (the CRA/Remix shape) into the spawn environment, so all four example shapes work everywhere; never use PowerShell syntax (`if (Test-Path \u2026) { \u2026 } else { \u2026 }`, `Test-Path`, `$env:FOO`, `Get-`/`Set-` cmdlets) \u2014 cmd.exe cannot parse it, so this tool rejects PowerShell-shaped commands \u2014 and for a subdirectory set `appDir` instead of cd/pushd-ing (`&&` chaining is valid on cmd but shouldn't be needed here). Once set, it surfaces in the workspace header's Run (play) button under \"Org run scripts\" as a read-only \"App dev server\" entry \u2014 don't also add it as a run script. Pass null/empty to clear. Idempotent \u2014 safe to re-run with a revised command.",
+    "Configure the user's REAL app dev server in tempo.config.json, stored canonically as `apps[0].start` plus optional `apps[0].url`. Legacy `apps[0].appStart` and `scripts.appStart` still read and migrate to `start` on write. Required for route storyboards. `start` may be any foreground command. `url`, when set, is only the HTTP(S) readiness target and route base: it is probed as written, never controls local allocation, and may point through a container, tunnel, or remote machine. Tempo exposes its independently allocated helper port through `${APP_PORT}` and still accepts legacy `${PORT}` in app start/URL fields. Invoke commands directly, keep them cross-platform, and use appDir for subdirectory apps. At least one of command/url must be provided; null clears that field. Idempotent.",
     {
       command: z23.string().nullish().describe(
-        "The command string. Must include the literal `${PORT}` token. Pass null or an empty string to clear the setting."
+        "The canonical apps[0].start foreground command. It may be arbitrary; use `${APP_PORT}` when the command should consume Tempo's allocated helper port. Legacy `${PORT}` remains supported. Omit to leave unchanged; pass null/empty to clear the app server configuration."
+      ),
+      url: z23.string().nullish().describe(
+        "Optional canonical apps[0].url. This is the HTTP(S) readiness target and route base only. It may contain `${APP_PORT}` (or legacy `${PORT}`) or be any literal reachable HTTP(S) URL, including a container, tunnel, or remote host; it never controls local port allocation. Omit to leave unchanged; pass null/empty to clear only this field."
       ),
       ...appDevServerTargetArgs
     },
-    async ({ command, repo_root, app_dir }) => {
+    async ({ command, url, repo_root, app_dir }) => {
       if (!context.appDevServer)
         return unsupportedEnvironmentResult("appDevServer");
-      const value = typeof command === "string" && command.trim().length > 0 ? command.trim() : null;
+      if (command === void 0 && url === void 0) {
+        return errorResult9("Provide command and/or url to update.");
+      }
+      const startValue = command === void 0 ? void 0 : typeof command === "string" && command.trim().length > 0 ? command.trim() : null;
+      const urlValue = url === void 0 ? void 0 : typeof url === "string" && url.trim().length > 0 ? url.trim() : null;
       try {
-        await context.appDevServer.setCommand(
-          value,
+        await context.appDevServer.setConfig(
+          {
+            ...startValue !== void 0 ? { start: startValue } : {},
+            ...urlValue !== void 0 ? { url: urlValue } : {}
+          },
           toAppDevServerTarget({ repo_root, app_dir })
         );
         return textResult2(
           JSON.stringify(
             {
-              app_dev_command: value,
-              note: value ? "Saved. The supervisor will allocate a port and start the server when a canvas with route storyboards is opened. Before declaring setup complete, verify the app itself depends on tempo-sdk and its own bundler config carries Tempo instrumentation. For standalone Svelte/Vite, add @sveltejs/vite-plugin-svelte only if missing, using a version compatible with the app's existing toolchain; preserve configured versions. Use tempoVitePlugin() plus tempoSveltePreprocess(...) first in the Svelte preprocess chain. tempo/ only configures the sidecar." : "Cleared."
+              // Preserve the original result field for callers that inspect
+              // tool output instead of only the tool arguments.
+              ...startValue !== void 0 ? { app_dev_command: startValue } : {},
+              ...urlValue !== void 0 ? { app_dev_url: urlValue } : {},
+              app_dev_config_update: {
+                ...startValue !== void 0 ? { start: startValue } : {},
+                ...urlValue !== void 0 ? { url: urlValue } : {}
+              },
+              note: startValue === null ? "Cleared." : "Saved. The supervisor allocates the optional local `${APP_PORT}` helper independently (legacy `${PORT}` remains supported); a configured URL is probed exactly as the readiness target and route base. Before declaring setup complete, verify the app depends on tempo-sdk and its own bundler config carries Tempo instrumentation. For standalone Svelte/Vite, add @sveltejs/vite-plugin-svelte only if missing, preserve compatible configured versions, and use tempoVitePlugin() plus tempoSveltePreprocess(...) first in the app's preprocess chain; tempo/ only configures the sidecar."
             },
             null,
             2
@@ -44447,7 +44526,7 @@ function registerTools(server, context) {
   );
   server.tool(
     "check_app_dev_server",
-    "Check the per-workspace app dev server (the user's REAL app, supervised via the app dev command in tempo.config.json \u2014 `apps[0].appStart`, legacy `scripts.appStart` also read; used by route storyboards). Returns `{configured, running, phase, port, url, error}`. Use this when a route storyboard isn't rendering to confirm whether the server is up and where (port + url) \u2014 analogous to `check_canvas_devserver` for the canvas sidecar. `configured: false` means the app dev command is unset; call `set_app_dev_command` first. `phase: 'error'` carries the supervisor's stderr in `error` \u2014 the actual failure reason.",
+    "Check the per-workspace app dev server configured by canonical `apps[0].start`/`url` (legacy appStart spellings also read). Returns `{configured, running, phase, port, url, error}`. Use this when a route storyboard isn't rendering. `configured: false` means start is unset; `phase: 'error'` carries the supervisor failure.",
     { ...appDevServerTargetArgs },
     async ({ repo_root, app_dir }) => {
       if (!context.appDevServer)
@@ -44466,7 +44545,7 @@ function registerTools(server, context) {
   );
   server.tool(
     "start_app_dev_server",
-    "Start the per-workspace app dev server if it isn't already running. Spawns the configured app dev command (with `${PORT}` substituted to an allocated free port), persists the port assignment under `<workspaceRoot>/.tempo/app-devserver.json`, and HTTP-gates readiness. No-op if already running \u2014 returns the live status. When no app dev command is configured, returns `{configured: false}` and the agent should call `set_app_dev_command` first. Analogous to `start_canvas_devserver` but for the user's real app server, not the canvas sidecar. Use when the renderer-driven warm-on-canvas-mount path isn't enough (e.g. you're driving the canvas headlessly, the user explicitly asked to start it, or the supervisor reports `phase: 'stopped'` after the 5-minute idle-stop).",
+    "Start the per-workspace app dev server if it isn't already running. Spawns canonical `apps[0].start`, substitutes `${APP_PORT}` (or legacy `${PORT}`) in start/url, persists the independently selected local helper port under `<workspaceRoot>/.tempo/app-devserver.json`, and HTTP-gates readiness against the configured URL or detected local URL. A literal URL is probed as written and does not affect local allocation. No-op if already running. When start is unset, returns `{configured: false}`; call `set_app_dev_command` first.",
     { ...appDevServerTargetArgs },
     async ({ repo_root, app_dir }) => {
       if (!context.appDevServer)
@@ -45143,7 +45222,7 @@ function isExternallyExposed(toolName, opts) {
 }
 
 // src/version.ts
-var CLI_VERSION = "0.0.102";
+var CLI_VERSION = "0.0.103";
 
 // src/canvas-hooks.ts
 var import_pngjs3 = __toESM(require_png(), 1);
@@ -47117,4 +47196,4 @@ export {
   runServe,
   scopeParamsFor
 };
-//# sourceMappingURL=serve-NGUFKD5I.js.map
+//# sourceMappingURL=serve-P7M4UFJS.js.map