@hexclave/next 1.0.51 → 1.0.53

package/dist/{quetzal-translations-XeH3zQ9l.d.ts.map → quetzal-translations-CK45_4Dm.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"quetzal-translations-XeH3zQ9l.d.ts","names":[],"sources":["../src/generated/quetzal-translations.ts"],"mappings":";cAUa,WAAA,EAAW,GAAA;AAAA,cAqTX,cAAA,EAAc,GAAA,mIAAA,GAAA,66qBAAA,GAAA,usnBAAA,GAAA,iyrBAAA,GAAA,g+qBAAA,GAAA,8srBAAA,GAAA,2trBAAA,GAAA,41pBAAA,GAAA,m3eAAA,GAAA,oreAAA,GAAA,swpBAAA,GAAA,+0qBAAA,GAAA,8wbAAA,GAAA"}
+{"version":3,"file":"quetzal-translations-CK45_4Dm.d.ts","names":[],"sources":["../src/generated/quetzal-translations.ts"],"mappings":";cAUa,WAAA,EAAW,GAAA;AAAA,cAqTX,cAAA,EAAc,GAAA,mIAAA,GAAA,66qBAAA,GAAA,usnBAAA,GAAA,iyrBAAA,GAAA,g+qBAAA,GAAA,8srBAAA,GAAA,2trBAAA,GAAA,41pBAAA,GAAA,m3eAAA,GAAA,oreAAA,GAAA,swpBAAA,GAAA,+0qBAAA,GAAA,8wbAAA,GAAA"}

package/dist/sign-out-DBnSkfDz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sign-out-DBnSkfDz.d.ts","names":[],"sources":["../src/components-page/sign-out.tsx"],"mappings":";iBAyBgB,OAAA,CAAQ,KAAA;EAAS,QAAA;EAAoB,YAAA,GAAe,MAAM;AAAA,gCAAkB,GAAA,CAAA,OAAA"}
+{"version":3,"file":"sign-out-DBnSkfDz.d.ts","names":[],"sources":["../src/components-page/sign-out.tsx"],"mappings":";iBA0CgB,OAAA,CAAQ,KAAA;EAAS,QAAA;EAAoB,YAAA,GAAe,MAAM;AAAA,gCAAkB,GAAA,CAAA,OAAA"}

package/dist/{translation-provider-WOaZXqAz.d.ts → translation-provider-DQ3BJepJ.d.ts}

@@ -1,4 +1,4 @@
-import { n as quetzalLocales } from "./quetzal-translations-XeH3zQ9l.js";
+import { n as quetzalLocales } from "./quetzal-translations-CK45_4Dm.js";
 
 //#region src/providers/translation-provider.d.ts
 declare function TranslationProvider({
@@ -12,4 +12,4 @@ declare function TranslationProvider({
 }): import("react/jsx-runtime").JSX.Element;
 //#endregion
 export { TranslationProvider as t };
-//# sourceMappingURL=translation-provider-WOaZXqAz.d.ts.map
+//# sourceMappingURL=translation-provider-DQ3BJepJ.d.ts.map

package/dist/{translation-provider-WOaZXqAz.d.ts.map → translation-provider-DQ3BJepJ.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"translation-provider-WOaZXqAz.d.ts","names":[],"sources":["../src/providers/translation-provider.tsx"],"mappings":";;;iBAQgB,mBAAA;EAAsB,IAAA;EAAM,oBAAA;EAAsB;AAAA;EAChE,IAAA,EAAM,UAAA,QAAkB,cAAA,CAAe,GAAA;EACvC,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA,gCACjB,GAAA,CAAA,OAAA"}
+{"version":3,"file":"translation-provider-DQ3BJepJ.d.ts","names":[],"sources":["../src/providers/translation-provider.tsx"],"mappings":";;;iBAQgB,mBAAA;EAAsB,IAAA;EAAM,oBAAA;EAAsB;AAAA;EAChE,IAAA,EAAM,UAAA,QAAkB,cAAA,CAAe,GAAA;EACvC,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;AAAA,gCACjB,GAAA,CAAA,OAAA"}

package/dist/utils/session-storage.d.ts

@@ -0,0 +1,12 @@
+//#region src/utils/session-storage.d.ts
+/**
+ * Guarded sessionStorage access for resilience layers (redirect loop breaking, redirect-back state
+ * mirroring). These layers must degrade to "no stored value" when storage is unavailable, instead
+ * of breaking the auth flow they are trying to protect.
+ */
+declare function readSessionStorageItem(key: string): string | null;
+declare function writeSessionStorageItem(key: string, value: string): void;
+declare function removeSessionStorageItem(key: string): void;
+//#endregion
+export { readSessionStorageItem, removeSessionStorageItem, writeSessionStorageItem };
+//# sourceMappingURL=session-storage.d.ts.map

package/dist/utils/session-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.d.ts","names":[],"sources":["../../src/utils/session-storage.ts"],"mappings":";;AAUA;;;;iBAAgB,sBAAA,CAAuB,GAAW;AAAA,iBAalC,uBAAA,CAAwB,GAAA,UAAa,KAAa;AAAA,iBAYlD,wBAAA,CAAyB,GAAW"}

package/dist/utils/session-storage.js

@@ -0,0 +1,33 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/utils/session-storage.ts
+/**
+* Guarded sessionStorage access for resilience layers (redirect loop breaking, redirect-back state
+* mirroring). These layers must degrade to "no stored value" when storage is unavailable, instead
+* of breaking the auth flow they are trying to protect.
+*/
+function readSessionStorageItem(key) {
+	if (typeof window === "undefined") return null;
+	try {
+		return window.sessionStorage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+function writeSessionStorageItem(key, value) {
+	if (typeof window === "undefined") return;
+	try {
+		window.sessionStorage.setItem(key, value);
+	} catch {}
+}
+function removeSessionStorageItem(key) {
+	if (typeof window === "undefined") return;
+	try {
+		window.sessionStorage.removeItem(key);
+	} catch {}
+}
+//#endregion
+exports.readSessionStorageItem = readSessionStorageItem;
+exports.removeSessionStorageItem = removeSessionStorageItem;
+exports.writeSessionStorageItem = writeSessionStorageItem;
+
+//# sourceMappingURL=session-storage.js.map

package/dist/utils/session-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.js","names":[],"sources":["../../src/utils/session-storage.ts"],"sourcesContent":["\n//===========================================\n// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template\n//===========================================\n/**\n * Guarded sessionStorage access for resilience layers (redirect loop breaking, redirect-back state\n * mirroring). These layers must degrade to \"no stored value\" when storage is unavailable, instead\n * of breaking the auth flow they are trying to protect.\n */\n\nexport function readSessionStorageItem(key: string): string | null {\n  if (typeof window === \"undefined\") {\n    return null;\n  }\n  try {\n    return window.sessionStorage.getItem(key);\n  } catch {\n    // Storage can be blocked entirely (private browsing, sandboxed iframes, disabled cookies), in\n    // which case accessing window.sessionStorage throws. Treat that as \"nothing stored\".\n    return null;\n  }\n}\n\nexport function writeSessionStorageItem(key: string, value: string): void {\n  if (typeof window === \"undefined\") {\n    return;\n  }\n  try {\n    window.sessionStorage.setItem(key, value);\n  } catch {\n    // Storage can be blocked or full; see readSessionStorageItem. Values written here are only\n    // used as a fallback, so failing to persist must not fail the caller.\n  }\n}\n\nexport function removeSessionStorageItem(key: string): void {\n  if (typeof window === \"undefined\") {\n    return;\n  }\n  try {\n    window.sessionStorage.removeItem(key);\n  } catch {\n    // See readSessionStorageItem.\n  }\n}\n"],"mappings":";;;;;;;AAUA,SAAgB,uBAAuB,KAA4B;CACjE,IAAI,OAAO,WAAW,aACpB,OAAO;CAET,IAAI;EACF,OAAO,OAAO,eAAe,QAAQ,GAAG;CAC1C,QAAQ;EAGN,OAAO;CACT;AACF;AAEA,SAAgB,wBAAwB,KAAa,OAAqB;CACxE,IAAI,OAAO,WAAW,aACpB;CAEF,IAAI;EACF,OAAO,eAAe,QAAQ,KAAK,KAAK;CAC1C,QAAQ,CAGR;AACF;AAEA,SAAgB,yBAAyB,KAAmB;CAC1D,IAAI,OAAO,WAAW,aACpB;CAEF,IAAI;EACF,OAAO,eAAe,WAAW,GAAG;CACtC,QAAQ,CAER;AACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template (FOR package.json FILES, PLEASE EDIT package-template.json)",
   "name": "@hexclave/next",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "repository": "https://github.com/hexclave/hexclave",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -74,9 +74,9 @@
     "tailwindcss-animate": "^1.0.7",
     "rrweb": "^1.1.3",
     "yup": "^1.7.1",
-    "@hexclave/sc": "1.0.51",
-    "@hexclave/shared": "1.0.51",
-    "@hexclave/ui": "1.0.51"
+    "@hexclave/sc": "1.0.53",
+    "@hexclave/shared": "1.0.53",
+    "@hexclave/ui": "1.0.53"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",

package/src/components-page/sign-out.test.tsx

@@ -0,0 +1,190 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+// @vitest-environment jsdom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CurrentUser } from "../lib/hexclave-app";
+import type { StackClientApp } from "../lib/hexclave-app/apps/interfaces/client-app";
+import { hexclaveAppInternalsSymbol } from "../lib/hexclave-app/common";
+import { TranslationProviderClient } from "../providers/translation-provider-client";
+import { SignOut } from "./sign-out";
+
+const appMockState = vi.hoisted(() => ({
+  app: null as unknown,
+  user: null as unknown,
+}));
+
+vi.mock("..", () => ({
+  useStackApp: () => {
+    if (appMockState.app == null) {
+      throw new Error("Expected test app to be set before rendering.");
+    }
+    return appMockState.app;
+  },
+  useUser: () => appMockState.user,
+}));
+
+// The real `use` delegates to React.use, which breaks in this test setup because the shared
+// package and react-dom resolve different React instances. Replace it with an equivalent
+// Suspense-compatible implementation that doesn't depend on the React dispatcher.
+vi.mock("@hexclave/shared/dist/utils/react", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@hexclave/shared/dist/utils/react")>();
+  type PromiseState = { status: "pending" } | { status: "ok", value: unknown } | { status: "error", error: unknown };
+  const promiseStates = new WeakMap<Promise<unknown>, PromiseState>();
+  return {
+    ...original,
+    use: <T,>(promise: Promise<T>): T => {
+      const state = promiseStates.get(promise);
+      if (state == null) {
+        promiseStates.set(promise, { status: "pending" });
+        promise.then(
+          (value) => promiseStates.set(promise, { status: "ok", value }),
+          (error) => promiseStates.set(promise, { status: "error", error }),
+        );
+        throw promise;
+      }
+      switch (state.status) {
+        case "pending": {
+          throw promise;
+        }
+        case "error": {
+          throw state.error;
+        }
+        case "ok": {
+          // This cast is safe because the value was stored from this exact promise's resolution;
+          // the WeakMap just can't express the per-key type relationship.
+          return state.value as T;
+        }
+      }
+    },
+  };
+});
+
+vi.mock("@hexclave/ui", async () => {
+  const React = await import("react");
+  return {
+    Button: (props: { children: React.ReactNode, onClick?: () => void }) => (
+      <button type="button" onClick={props.onClick}>{props.children}</button>
+    ),
+    Typography: (props: { children: React.ReactNode }) => <div>{props.children}</div>,
+    cn: (...classes: (string | false | null | undefined)[]) => classes.filter(Boolean).join(" "),
+  };
+});
+
+const previousActEnvironment = Reflect.get(globalThis, "IS_REACT_ACT_ENVIRONMENT");
+
+function createAppTestDouble(options: {
+  trustedUrls: string[],
+}) {
+  const app = {
+    redirectToSignIn: vi.fn(async () => {}),
+    [hexclaveAppInternalsSymbol]: {
+      isTrustedRedirectUrl: vi.fn(async (url: string) => options.trustedUrls.includes(url)),
+    },
+  };
+
+  // This test double intentionally implements only the StackClientApp surface that SignOut and
+  // the rendered signed-out card touch.
+  return app as unknown as StackClientApp<true>;
+}
+
+function createUserTestDouble() {
+  const user = {
+    signOut: vi.fn(async () => {}),
+  };
+  // Same as the app test double: only the surface SignOut touches.
+  return user as unknown as CurrentUser & { signOut: ReturnType<typeof vi.fn> };
+}
+
+// jsdom's window.location is not configurable, so it can't be spied on; replace it wholesale.
+const originalLocation = window.location;
+let locationReplaceMock = vi.fn();
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+async function renderSignOut(options: {
+  app: StackClientApp<true>,
+  user: unknown,
+  searchParams?: Record<string, string>,
+}) {
+  appMockState.app = options.app;
+  appMockState.user = options.user;
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+  await act(async () => {
+    root?.render(
+      <TranslationProviderClient quetzalKeys={new Map()} quetzalLocale={new Map()}>
+        <React.Suspense fallback={<div data-testid="suspense-fallback" />}>
+          <SignOut searchParams={options.searchParams} />
+        </React.Suspense>
+      </TranslationProviderClient>
+    );
+  });
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+}
+
+describe("SignOut", () => {
+  beforeEach(() => {
+    Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+    locationReplaceMock = vi.fn();
+    Reflect.deleteProperty(window, "location");
+    Reflect.set(window, "location", { href: "https://demo.example.test/handler/sign-out", replace: locationReplaceMock });
+  });
+
+  afterEach(() => {
+    act(() => {
+      root?.unmount();
+    });
+    container?.remove();
+    root = null;
+    container = null;
+    appMockState.app = null;
+    appMockState.user = null;
+    Reflect.set(window, "location", originalLocation);
+    vi.restoreAllMocks();
+    Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", previousActEnvironment);
+  });
+
+  it("signs out with a trusted after_auth_return_to redirect URL", async () => {
+    const app = createAppTestDouble({ trustedUrls: ["/dashboard"] });
+    const user = createUserTestDouble();
+
+    await renderSignOut({ app, user, searchParams: { after_auth_return_to: "/dashboard" } });
+
+    expect(user.signOut).toHaveBeenCalledWith({ redirectUrl: "/dashboard" });
+  });
+
+  it("ignores an untrusted after_auth_return_to and falls back to the default sign-out redirect", async () => {
+    const app = createAppTestDouble({ trustedUrls: [] });
+    const user = createUserTestDouble();
+
+    await renderSignOut({ app, user, searchParams: { after_auth_return_to: "https://evil.example.test/phishing" } });
+
+    // The untrusted URL is dropped entirely; sign-out proceeds with the default destination.
+    expect(user.signOut).toHaveBeenCalledWith({ redirectUrl: undefined });
+  });
+
+  it("does not follow an untrusted after_auth_return_to when already signed out", async () => {
+    const app = createAppTestDouble({ trustedUrls: [] });
+
+    await renderSignOut({ app, user: null, searchParams: { after_auth_return_to: "https://evil.example.test/phishing-signed-out" } });
+
+    expect(locationReplaceMock).not.toHaveBeenCalled();
+  });
+
+  it("follows a trusted after_auth_return_to when already signed out", async () => {
+    const app = createAppTestDouble({ trustedUrls: ["/trusted-dashboard"] });
+
+    await renderSignOut({ app, user: null, searchParams: { after_auth_return_to: "/trusted-dashboard" } });
+
+    expect(locationReplaceMock).toHaveBeenCalledWith("/trusted-dashboard");
+  });
+});

package/src/components-page/sign-out.tsx

@@ -6,9 +6,26 @@
 //===========================================
 
 import { cacheFunction } from "@hexclave/shared/dist/utils/caches";
+import { captureError } from "@hexclave/shared/dist/utils/errors";
 import { use } from "@hexclave/shared/dist/utils/react";
-import { CurrentUser, useUser } from "..";
+import { CurrentUser, useStackApp, useUser } from "..";
 import { PredefinedMessageCard } from "../components/message-cards/predefined-message-card";
+import { StackClientApp, hexclaveAppInternalsSymbol } from "../lib/hexclave-app";
+
+// The sign-out page's `after_auth_return_to` comes straight from the query string, so it is
+// attacker-craftable (open-redirect shaped). Only follow it if it passes the same trust validation
+// as every other SDK redirect; otherwise ignore it and fall back to the default after-sign-out
+// destination.
+const cacheGetTrustedRedirectUrl = cacheFunction(async (app: StackClientApp<true, string>, redirectUrl: string | undefined): Promise<string | undefined> => {
+  if (redirectUrl == null) {
+    return undefined;
+  }
+  if (await app[hexclaveAppInternalsSymbol].isTrustedRedirectUrl(redirectUrl)) {
+    return redirectUrl;
+  }
+  captureError("sign-out-untrusted-redirect-url", new Error(`Ignoring untrusted after_auth_return_to query parameter on the sign-out page: ${redirectUrl}`));
+  return undefined;
+});
 
 const cacheSignOut = cacheFunction(async (user: CurrentUser, redirectUrl: string | undefined) => {
   return await user.signOut({ redirectUrl });
@@ -24,13 +41,15 @@ const cacheRedirectIfAlreadySignedOut = cacheFunction(async (redirectUrl: string
 });
 
 export function SignOut(props: { fullPage?: boolean, searchParams?: Record<string, string> }) {
+  const app = useStackApp();
   const user = useUser({ or: "return-null" });
   const redirectUrl = props.searchParams?.after_auth_return_to;
+  const trustedRedirectUrl = use(cacheGetTrustedRedirectUrl(app, redirectUrl));
 
   if (user) {
-    use(cacheSignOut(user, redirectUrl));
+    use(cacheSignOut(user, trustedRedirectUrl));
   } else {
-    use(cacheRedirectIfAlreadySignedOut(redirectUrl));
+    use(cacheRedirectIfAlreadySignedOut(trustedRedirectUrl));
   }
 
   return <PredefinedMessageCard type='signedOut' fullPage={props.fullPage} />;

package/src/dev-tool/dev-tool-core.ts

@@ -8,7 +8,6 @@ import { DEV_TOOL_ROOT_ID } from "@hexclave/shared/dist/utils/dev-tool";
 import { runAsynchronously, runAsynchronouslyWithAlert } from "@hexclave/shared/dist/utils/promises";
 import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
 import type { StackClientApp } from "../lib/hexclave-app";
-import { envVars } from "../generated/env";
 import { getGlobalUiInstance, h, hasAppendChild, setGlobalUiInstance, setHtml, type UiGlobalInstance } from "../in-page-ui/dom";
 import { getBaseUrl } from "../lib/hexclave-app/apps/implementations/common";
 import type { HandlerUrlOptions, HandlerUrls, HandlerUrlTarget } from "../lib/hexclave-app/common";
@@ -63,6 +62,11 @@ const MAX_LOG_ENTRIES = 500;
 const CONSOLE_LOG_BATCH_SIZE = 100;
 const DRAG_THRESHOLD = 5;
 const DOCS_URL = 'https://docs.hexclave.com';
+// The local development-environment dashboard always listens on this loopback
+// port (see the CLI's DEFAULT_DASHBOARD_PORT). The dev tool runs inside the
+// customer's own app, so it can't read the CLI's env vars — the port is fixed.
+const LOCAL_DASHBOARD_ORIGIN = 'http://localhost:26700';
+const HOSTED_DASHBOARD_URL = 'https://app.hexclave.com';
 
 const TABS: { id: TabId; label: string; icon: string }[] = [
   { id: 'overview', label: 'Overview', icon: '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="3" y="3" width="7" height="7"/><rect x="14" y="3" width="7" height="7"/><rect x="14" y="14" width="7" height="7"/><rect x="3" y="14" width="7" height="7"/></svg>' },
@@ -193,42 +197,60 @@ function resolveApiBaseUrl(app: StackClientApp<true>): string {
   return getBaseUrl(opts.baseUrl);
 }
 
-function shouldShowDashboardTab(app: StackClientApp<true>): boolean {
-  return envVars.HEXCLAVE_IS_LOCAL_EMULATOR === "true" && isLocalhost(resolveApiBaseUrl(app));
+function localDashboardProjectUrl(app: StackClientApp<true>): string {
+  return `${LOCAL_DASHBOARD_ORIGIN}/projects/${encodeURIComponent(app.projectId)}`;
 }
 
-function getTabsForApp(app: StackClientApp<true>): { id: TabId; label: string; icon: string }[] {
-  if (shouldShowDashboardTab(app)) {
-    return TABS;
-  }
-  return TABS.filter((tab) => tab.id !== 'dashboard');
+function parseProjectAvailabilityResponse(body: unknown): boolean {
+  if (typeof body !== 'object' || body === null) return false;
+  return 'project_available' in body && body.project_available === true;
+}
+
+// How long to wait for the availability probe before giving up. A refused
+// connection rejects almost immediately, but a host that accepts the socket yet
+// never responds would otherwise leave the tab stuck on "Checking…" forever.
+const LOCAL_DASHBOARD_PROBE_TIMEOUT_MS = 3000;
+
+// Whether the current page can even talk to the HTTP-only local dashboard.
+// LOCAL_DASHBOARD_ORIGIN is `http://localhost:26700`, so the page itself must be
+// an http: localhost origin: an https: page (e.g. an HTTPS dev server) would
+// have both the probe fetch and the iframe embed blocked as mixed content, so
+// we treat that as "not available" and fall back to the hosted dashboard.
+function canReachLocalDashboard(): boolean {
+  return isLocalhost(window.location.href) && window.location.protocol === 'http:';
 }
 
-function deriveDashboardBaseUrl(apiBaseUrl: string): string {
+// Decides whether the Dashboard tab can embed the locally-running
+// development-environment dashboard. Rather than inferring from build-time env
+// vars (which don't reflect whether the dev environment is actually up right
+// now), we ask the running development environment directly:
+//   1. We must be viewing the app from an http: localhost origin — the HTTP-only
+//      dashboard on :26700 is only reachable from, and only relevant to, a local
+//      browser (and an https: page can't reach it without mixed-content errors).
+//   2. The development environment must be running AND already own this exact
+//      project (see the project-availability route it answers).
+// Any failure — dev environment not running (connection refused), probe timeout,
+// project unknown, or a malformed response — resolves to `false`, which shows
+// the hosted-dashboard hint instead.
+async function isLocalDashboardProjectAvailable(app: StackClientApp<true>): Promise<boolean> {
+  if (!canReachLocalDashboard()) return false;
+  const url = `${LOCAL_DASHBOARD_ORIGIN}/api/development-environment/project-availability?project_id=${encodeURIComponent(app.projectId)}`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_DASHBOARD_PROBE_TIMEOUT_MS);
   try {
-    const url = new URL(apiBaseUrl);
-    if (url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]') {
-      const port = url.port;
-      if (port && port.endsWith('02')) {
-        url.port = port.slice(0, -2) + '01';
-      }
-      return url.origin;
-    }
-    if (url.hostname.startsWith('api.')) {
-      url.hostname = 'app.' + url.hostname.slice(4);
-      return url.origin;
-    }
-    return url.origin;
+    const response = await fetch(url, { method: 'GET', signal: controller.signal });
+    if (!response.ok) return false;
+    return parseProjectAvailabilityResponse(await response.json());
   } catch {
-    return 'https://app.hexclave.com';
+    // Reachability probe: when the local development environment isn't running,
+    // the fetch rejects (connection refused); when it hangs, the AbortController
+    // aborts it. Either way that simply means "not available".
+    return false;
+  } finally {
+    clearTimeout(timeout);
   }
 }
 
-function resolveDashboardUrl(app: StackClientApp<true>): string {
-  const base = deriveDashboardBaseUrl(resolveApiBaseUrl(app));
-  return `${base}/projects/${encodeURIComponent(app.projectId)}`;
-}
-
 function formatTimestamp(ts: number): string {
   return new Date(ts).toLocaleTimeString([], {
     hour: '2-digit',
@@ -563,8 +585,8 @@ function createTabBar(
 // Iframe helper
 // ---------------------------------------------------------------------------
 
-function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026', errorMsg = 'Unable to load content', errorDetail?: string, openExternallyLabel?: string): HTMLElement {
-  const container = h('div', { className: 'sdt-iframe-container' });
+function populateIframeTab(container: HTMLElement, src: string, title: string, loadingMsg = 'Loading\u2026', errorMsg = 'Unable to load content', errorDetail?: string, openExternallyLabel?: string): void {
+  container.innerHTML = '';
   if (openExternallyLabel != null) {
     container.appendChild(h('div', { className: 'sdt-iframe-toolbar' },
       h('a', { href: src, target: '_blank', rel: 'noopener noreferrer', className: 'sdt-iframe-open-link' }, openExternallyLabel),
@@ -594,7 +616,7 @@ function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026
     }
     const retryBtn = h('button', { className: 'sdt-iframe-error-btn' }, 'Retry');
     retryBtn.addEventListener('click', () => {
-      container.replaceWith(createIframeTab(src, title, loadingMsg, errorMsg, errorDetail, openExternallyLabel));
+      populateIframeTab(container, src, title, loadingMsg, errorMsg, errorDetail, openExternallyLabel);
     });
     errDiv.appendChild(retryBtn);
     const link = h('a', { href: src, target: '_blank', rel: 'noopener noreferrer', style: { color: 'var(--sdt-accent)', fontSize: '12px', textDecoration: 'none' } }, 'Open in new tab');
@@ -603,7 +625,6 @@ function createIframeTab(src: string, title: string, loadingMsg = 'Loading\u2026
   });
 
   container.appendChild(iframe);
-  return container;
 }
 
 // ===========================================================================================
@@ -1681,8 +1702,52 @@ function createAITab(app: StackClientApp<true>): HTMLElement {
 // ---------------------------------------------------------------------------
 
 function createDashboardTab(app: StackClientApp<true>): HTMLElement {
-  const dashboardUrl = resolveDashboardUrl(app);
-  return createIframeTab(dashboardUrl, 'Hexclave Dashboard', 'Loading dashboard\u2026', 'Unable to load dashboard', 'The dashboard may require authentication or block framing', 'Open in New Tab');
+  const container = h('div', { className: 'sdt-iframe-container' });
+
+  function showChecking() {
+    container.innerHTML = '';
+    container.appendChild(h('div', { className: 'sdt-iframe-loading' }, 'Checking development environment\u2026'));
+  }
+
+  function showUnavailable() {
+    container.innerHTML = '';
+    const message = h('div', { className: 'sdt-dashboard-unavailable' });
+    const text = h('div', { className: 'sdt-dashboard-unavailable-text' });
+    text.appendChild(document.createTextNode('Navigate to '));
+    text.appendChild(h('a', {
+      className: 'sdt-dashboard-unavailable-link',
+      href: HOSTED_DASHBOARD_URL,
+      target: '_blank',
+      rel: 'noopener noreferrer',
+    }, HOSTED_DASHBOARD_URL));
+    text.appendChild(document.createTextNode(" to view this project's dashboard"));
+    message.appendChild(text);
+    container.appendChild(message);
+  }
+
+  async function check() {
+    showChecking();
+    const available = await isLocalDashboardProjectAvailable(app);
+    // The dev tool may have been torn down while we were probing; only mutate
+    // the DOM if this container is still mounted.
+    if (!container.isConnected) return;
+    if (available) {
+      populateIframeTab(
+        container,
+        localDashboardProjectUrl(app),
+        'Hexclave Dashboard',
+        'Loading dashboard\u2026',
+        'Unable to load dashboard',
+        'The dashboard may require authentication or block framing',
+        'Open in New Tab',
+      );
+    } else {
+      showUnavailable();
+    }
+  }
+
+  runAsynchronously(check);
+  return container;
 }
 
 // ---------------------------------------------------------------------------
@@ -2112,7 +2177,7 @@ function createPanel(
     panel.style.height = state.get().panelHeight + 'px';
   }
 
-  const tabs = getTabsForApp(app);
+  const tabs = TABS;
   const storedActiveTab = state.get().activeTab;
   const activeTab = tabs.some((tab) => tab.id === storedActiveTab) ? storedActiveTab : DEFAULT_STATE.activeTab;
 

package/src/dev-tool/dev-tool-styles.ts

@@ -328,6 +328,14 @@ export const devToolCSS = getInPageUiBaseCSS('.hexclave-devtool') + `
     z-index: 1;
   }
 
+  /* Iframe panes lay their content out as a flex column so the embedded
+     dashboard (or the fallback message) fills the pane height. Uses two
+     classes to win over the plain .sdt-tab-pane-active { display: block }. */
+  .hexclave-devtool .sdt-tab-pane-iframe.sdt-tab-pane-active {
+    display: flex;
+    flex-direction: column;
+  }
+
   /* ===== Overview tab — single column ===== */
 
   .hexclave-devtool .sdt-ov {
@@ -1235,6 +1243,33 @@ export const devToolCSS = getInPageUiBaseCSS('.hexclave-devtool') + `
     background: var(--sdt-accent-hover);
   }
 
+  .hexclave-devtool .sdt-dashboard-unavailable {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    padding: 24px;
+    text-align: center;
+    color: var(--sdt-text-secondary);
+    font-size: 14px;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-text {
+    max-width: 420px;
+    line-height: 1.5;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-link {
+    color: var(--sdt-accent);
+    text-decoration: none;
+  }
+
+  .hexclave-devtool .sdt-dashboard-unavailable-link:hover {
+    text-decoration: underline;
+  }
+
   /* Shared content fade animation */
   .hexclave-devtool .sdt-tab-content-fade {
     animation: sdt-tab-fade-in 0.15s ease-out;