@hexclave/next 1.0.74 → 1.0.76

package/dist/esm/setup-error-overlay/index.js

@@ -0,0 +1,106 @@
+import { canMountIntoDom, getGlobalUiInstance, h, setGlobalUiInstance } from "../in-page-ui/dom.js";
+import { HexclaveSetupError, captureError, errorToNiceString } from "@hexclave/shared/dist/utils/errors";
+import { isLikelyDevelopmentEnvironment } from "../in-page-ui/dev-environment.js";
+import { getIssueCardCSS, renderIssueCard, renderIssuePill, trapFocusInIssueCard } from "../in-page-ui/issue-card.js";
+//#region src/setup-error-overlay/index.ts
+/** Exported so tests can drop the singleton; every other consumer should go through `showSetupErrorOverlay`. */
+const SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY = "__hexclave-setup-error-overlay";
+const css = getIssueCardCSS(".hexclave-setup-error-overlay");
+const unexpectedErrorHowToFix = [
+	"Check the browser console and your Hexclave dashboard's logs for the full error.",
+	"Make sure your Hexclave SDK packages are up to date.",
+	"If the error looks like a bug in Hexclave, report it at https://github.com/hexclave/hexclave/issues."
+];
+function toSetupIssue(error) {
+	if (HexclaveSetupError.isSetupError(error)) return {
+		title: error.title,
+		message: error.message,
+		howToFix: error.howToFix,
+		isFatal: true
+	};
+	return {
+		title: "Hexclave could not finish an authentication flow",
+		message: errorToNiceString(error),
+		howToFix: unexpectedErrorHowToFix,
+		isFatal: false
+	};
+}
+function buildAiPrompt(issue) {
+	return [
+		"Help me fix this Hexclave setup error.",
+		"",
+		"Hexclave reminder:",
+		"This error was thrown by the Hexclave SDK in the browser while it was resolving an authentication flow, and the flow was aborted because of it. It is a problem with how my project is set up, not something my users can work around. Use your web fetch tool to read https://skill.hexclave.com to learn more about Hexclave.",
+		"",
+		"Error message:",
+		issue.message,
+		"",
+		"Hexclave suggests:",
+		...issue.howToFix.map((step) => `- ${step}`),
+		"",
+		"Please explain the likely cause and suggest the smallest safe fix."
+	].join("\n");
+}
+/**
+* Shows `error` as an error card on the current page.
+*
+* Setup errors are always shown, because the flow they aborted cannot complete no matter what the end user does, and
+* their messages are written for exactly this purpose. Any other error is only shown while developing — those messages
+* are internal diagnostics, so in production they stay in captureError's hands.
+*
+* Returns a cleanup function that removes the card again.
+*/
+function showSetupErrorOverlay(error) {
+	if (!canMountIntoDom()) return () => {};
+	if (!HexclaveSetupError.isSetupError(error) && !isLikelyDevelopmentEnvironment()) return () => {};
+	const issue = toSetupIssue(error);
+	if (getGlobalUiInstance("__hexclave-setup-error-overlay") != null) return () => {};
+	const root = h("div", { className: "hexclave-setup-error-overlay" });
+	const style = h("style", null, css);
+	root.appendChild(style);
+	document.body.appendChild(root);
+	let focusTrap = null;
+	const render = (minimized) => {
+		focusTrap?.release();
+		focusTrap = null;
+		root.replaceChildren(style);
+		if (minimized) {
+			root.appendChild(renderIssuePill({
+				kind: "error",
+				label: "Setup error",
+				ariaLabel: "Show Hexclave setup error",
+				onClick: () => render(false)
+			}));
+			return;
+		}
+		root.appendChild(renderIssueCard({
+			kind: "error",
+			badge: "Setup error",
+			title: issue.title,
+			bodyText: issue.isFatal ? "Hexclave stopped the authentication flow that ran into this error, so nobody can sign in through it until it is fixed." : "Hexclave aborted the authentication flow that ran into this error. Errors like this one may also be transient, in which case retrying the flow works.",
+			messageLabel: "Error message",
+			message: issue.message,
+			howToFix: issue.howToFix,
+			footerText: issue.isFatal ? "This card is shown by the Hexclave SDK. Fix the problem above and reload the page to try the flow again." : "This card is shown by the Hexclave SDK while developing, and never in production.",
+			ariaLabel: "Hexclave setup error",
+			aiPrompt: buildAiPrompt(issue),
+			onCopyError: (copyError) => captureError("setup-error-overlay-copy", copyError),
+			onCopyAiPromptError: (copyError) => captureError("setup-error-overlay-copy-ai-prompt", copyError),
+			onMinimize: () => render(true)
+		}));
+		focusTrap = trapFocusInIssueCard(root);
+	};
+	render(false);
+	const cleanup = () => {
+		focusTrap?.release();
+		focusTrap = null;
+		root.remove();
+		if (getGlobalUiInstance("__hexclave-setup-error-overlay")?.cleanup === cleanup) setGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, null);
+	};
+	setGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, { cleanup });
+	return cleanup;
+}
+//#endregion
+export { SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, showSetupErrorOverlay };
+
+//# sourceMappingURL=index.js.map

package/dist/esm/setup-error-overlay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/setup-error-overlay/index.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// Renders an error card on the page when an auth flow dies because of a setup problem in the developer's project (a\n// domain missing from the trusted domains, for example). Those failures used to be logged with captureError only, which\n// meant the flow just quietly stopped: the developer saw a page that never signed anybody in, with the explanation\n// buried in the console or in Sentry. Setup errors are always the developer's to fix and never recoverable at runtime,\n// so they get the same treatment as a broken pushed config: a card that is impossible to miss.\n\nimport { HexclaveSetupError, captureError, errorToNiceString } from \"@hexclave/shared/dist/utils/errors\";\nimport { isLikelyDevelopmentEnvironment } from \"../in-page-ui/dev-environment\";\nimport { canMountIntoDom, getGlobalUiInstance, h, setGlobalUiInstance } from \"../in-page-ui/dom\";\nimport { getIssueCardCSS, renderIssueCard, renderIssuePill, trapFocusInIssueCard, type IssueCardFocusTrap } from \"../in-page-ui/issue-card\";\n\n/** Exported so tests can drop the singleton; every other consumer should go through `showSetupErrorOverlay`. */\nexport const SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY = \"__hexclave-setup-error-overlay\";\n\nconst css = getIssueCardCSS(\".hexclave-setup-error-overlay\");\n\nconst unexpectedErrorHowToFix = [\n  \"Check the browser console and your Hexclave dashboard's logs for the full error.\",\n  \"Make sure your Hexclave SDK packages are up to date.\",\n  \"If the error looks like a bug in Hexclave, report it at https://github.com/hexclave/hexclave/issues.\",\n] as const;\n\ntype SetupIssue = {\n  title: string,\n  message: string,\n  howToFix: readonly string[],\n  // Setup errors are known to be fatal for their flow, so the card says so. Anything else may well be transient (a\n  // network blip while resolving a session, say), and claiming that nobody can sign in anymore would be misleading.\n  isFatal: boolean,\n};\n\nfunction toSetupIssue(error: unknown): SetupIssue {\n  if (HexclaveSetupError.isSetupError(error)) {\n    return {\n      title: error.title,\n      message: error.message,\n      howToFix: error.howToFix,\n      isFatal: true,\n    };\n  }\n  return {\n    title: \"Hexclave could not finish an authentication flow\",\n    message: errorToNiceString(error),\n    howToFix: unexpectedErrorHowToFix,\n    isFatal: false,\n  };\n}\n\nfunction buildAiPrompt(issue: SetupIssue): string {\n  return [\n    \"Help me fix this Hexclave setup error.\",\n    \"\",\n    \"Hexclave reminder:\",\n    \"This error was thrown by the Hexclave SDK in the browser while it was resolving an authentication flow, and the flow was aborted because of it. It is a problem with how my project is set up, not something my users can work around. Use your web fetch tool to read https://skill.hexclave.com to learn more about Hexclave.\",\n    \"\",\n    \"Error message:\",\n    issue.message,\n    \"\",\n    \"Hexclave suggests:\",\n    ...issue.howToFix.map((step) => `- ${step}`),\n    \"\",\n    \"Please explain the likely cause and suggest the smallest safe fix.\",\n  ].join(\"\\n\");\n}\n\n/**\n * Shows `error` as an error card on the current page.\n *\n * Setup errors are always shown, because the flow they aborted cannot complete no matter what the end user does, and\n * their messages are written for exactly this purpose. Any other error is only shown while developing — those messages\n * are internal diagnostics, so in production they stay in captureError's hands.\n *\n * Returns a cleanup function that removes the card again.\n */\nexport function showSetupErrorOverlay(error: unknown): () => void {\n  if (!canMountIntoDom()) {\n    return () => {};\n  }\n  if (!HexclaveSetupError.isSetupError(error) && !isLikelyDevelopmentEnvironment()) {\n    return () => {};\n  }\n\n  const issue = toSetupIssue(error);\n  const existingInstance = getGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY);\n  if (existingInstance != null) {\n    // A single broken setup usually throws the same error on every page load and sometimes from several flows at once.\n    // Stacking cards on top of each other would only hide the first (and most relevant) one, so later errors keep to\n    // captureError and leave the card that is already up alone.\n    return () => {};\n  }\n\n  const root = h(\"div\", { className: \"hexclave-setup-error-overlay\" });\n  const style = h(\"style\", null, css);\n  root.appendChild(style);\n  document.body.appendChild(root);\n\n  let focusTrap: IssueCardFocusTrap | null = null;\n  const render = (minimized: boolean) => {\n    focusTrap?.release();\n    focusTrap = null;\n    root.replaceChildren(style);\n    if (minimized) {\n      root.appendChild(renderIssuePill({\n        kind: \"error\",\n        label: \"Setup error\",\n        ariaLabel: \"Show Hexclave setup error\",\n        onClick: () => render(false),\n      }));\n      return;\n    }\n    root.appendChild(renderIssueCard({\n      kind: \"error\",\n      badge: \"Setup error\",\n      title: issue.title,\n      bodyText: issue.isFatal\n        ? \"Hexclave stopped the authentication flow that ran into this error, so nobody can sign in through it until it is fixed.\"\n        : \"Hexclave aborted the authentication flow that ran into this error. Errors like this one may also be transient, in which case retrying the flow works.\",\n      messageLabel: \"Error message\",\n      message: issue.message,\n      howToFix: issue.howToFix,\n      footerText: issue.isFatal\n        ? \"This card is shown by the Hexclave SDK. Fix the problem above and reload the page to try the flow again.\"\n        : \"This card is shown by the Hexclave SDK while developing, and never in production.\",\n      ariaLabel: \"Hexclave setup error\",\n      aiPrompt: buildAiPrompt(issue),\n      onCopyError: (copyError) => captureError(\"setup-error-overlay-copy\", copyError),\n      onCopyAiPromptError: (copyError) => captureError(\"setup-error-overlay-copy-ai-prompt\", copyError),\n      onMinimize: () => render(true),\n    }));\n    focusTrap = trapFocusInIssueCard(root);\n  };\n  render(false);\n\n  const cleanup = () => {\n    focusTrap?.release();\n    focusTrap = null;\n    root.remove();\n    if (getGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY)?.cleanup === cleanup) {\n      setGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, null);\n    }\n  };\n  setGlobalUiInstance(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, { cleanup });\n  return cleanup;\n}\n\n"],"mappings":";;;;;;AAiBA,MAAa,0CAA0C;AAEvD,MAAM,MAAM,gBAAgB,+BAA+B;AAE3D,MAAM,0BAA0B;CAC9B;CACA;CACA;AACF;AAWA,SAAS,aAAa,OAA4B;CAChD,IAAI,mBAAmB,aAAa,KAAK,GACvC,OAAO;EACL,OAAO,MAAM;EACb,SAAS,MAAM;EACf,UAAU,MAAM;EAChB,SAAS;CACX;CAEF,OAAO;EACL,OAAO;EACP,SAAS,kBAAkB,KAAK;EAChC,UAAU;EACV,SAAS;CACX;AACF;AAEA,SAAS,cAAc,OAA2B;CAChD,OAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA,MAAM;EACN;EACA;EACA,GAAG,MAAM,SAAS,KAAK,SAAS,KAAK,MAAM;EAC3C;EACA;CACF,CAAC,CAAC,KAAK,IAAI;AACb;;;;;;;;;;AAWA,SAAgB,sBAAsB,OAA4B;CAChE,IAAI,CAAC,gBAAgB,GACnB,aAAa,CAAC;CAEhB,IAAI,CAAC,mBAAmB,aAAa,KAAK,KAAK,CAAC,+BAA+B,GAC7E,aAAa,CAAC;CAGhB,MAAM,QAAQ,aAAa,KAAK;CAEhC,IADyB,oBAAA,gCACN,KAAK,MAItB,aAAa,CAAC;CAGhB,MAAM,OAAO,EAAE,OAAO,EAAE,WAAW,+BAA+B,CAAC;CACnE,MAAM,QAAQ,EAAE,SAAS,MAAM,GAAG;CAClC,KAAK,YAAY,KAAK;CACtB,SAAS,KAAK,YAAY,IAAI;CAE9B,IAAI,YAAuC;CAC3C,MAAM,UAAU,cAAuB;EACrC,WAAW,QAAQ;EACnB,YAAY;EACZ,KAAK,gBAAgB,KAAK;EAC1B,IAAI,WAAW;GACb,KAAK,YAAY,gBAAgB;IAC/B,MAAM;IACN,OAAO;IACP,WAAW;IACX,eAAe,OAAO,KAAK;GAC7B,CAAC,CAAC;GACF;EACF;EACA,KAAK,YAAY,gBAAgB;GAC/B,MAAM;GACN,OAAO;GACP,OAAO,MAAM;GACb,UAAU,MAAM,UACZ,2HACA;GACJ,cAAc;GACd,SAAS,MAAM;GACf,UAAU,MAAM;GAChB,YAAY,MAAM,UACd,6GACA;GACJ,WAAW;GACX,UAAU,cAAc,KAAK;GAC7B,cAAc,cAAc,aAAa,4BAA4B,SAAS;GAC9E,sBAAsB,cAAc,aAAa,sCAAsC,SAAS;GAChG,kBAAkB,OAAO,IAAI;EAC/B,CAAC,CAAC;EACF,YAAY,qBAAqB,IAAI;CACvC;CACA,OAAO,KAAK;CAEZ,MAAM,gBAAgB;EACpB,WAAW,QAAQ;EACnB,YAAY;EACZ,KAAK,OAAO;EACZ,IAAI,oBAAA,gCAA2D,CAAC,EAAE,YAAY,SAC5E,oBAAoB,yCAAyC,IAAI;CAErE;CACA,oBAAoB,yCAAyC,EAAE,QAAQ,CAAC;CACxE,OAAO;AACT"}

package/dist/esm/setup-error-overlay/index.test.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/esm/setup-error-overlay/index.test.js

@@ -0,0 +1,125 @@
+import { HexclaveSetupError } from "@hexclave/shared/dist/utils/errors";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, showSetupErrorOverlay } from "./index.js";
+//#region src/setup-error-overlay/index.test.ts
+// @vitest-environment jsdom
+function createSetupError() {
+	return new HexclaveSetupError({
+		title: "A domain in your authentication flow is not one of your project's trusted domains",
+		message: "Nested cross-domain auth callback URL https://demo.example.test/ is not trusted.",
+		howToFix: ["Add https://demo.example.test to your project's trusted domains."]
+	});
+}
+function overlayRoots() {
+	return document.querySelectorAll(".hexclave-setup-error-overlay");
+}
+describe("setup error overlay", () => {
+	afterEach(() => {
+		vi.unstubAllEnvs();
+		for (const root of overlayRoots()) root.remove();
+		Reflect.deleteProperty(window, SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY);
+	});
+	it("renders setup errors with their fix instructions, even outside development", () => {
+		vi.stubEnv("NODE_ENV", "production");
+		const error = createSetupError();
+		const cleanup = showSetupErrorOverlay(error);
+		try {
+			expect(overlayRoots()).toHaveLength(1);
+			const text = document.body.textContent;
+			expect(text).toContain(error.title);
+			expect(text).toContain(error.message);
+			expect(text).toContain(error.howToFix[0]);
+			expect(document.querySelector("[role='alertdialog']")).not.toBeNull();
+		} finally {
+			cleanup();
+		}
+		expect(overlayRoots()).toHaveLength(0);
+	});
+	it("minimizes into a pill and back", () => {
+		vi.stubEnv("NODE_ENV", "production");
+		const cleanup = showSetupErrorOverlay(createSetupError());
+		try {
+			const minimizeButton = document.querySelector("[aria-label='Minimize Hexclave setup error']");
+			expect(minimizeButton).not.toBeNull();
+			minimizeButton?.click();
+			expect(document.querySelector("[role='alertdialog']")).toBeNull();
+			const pill = document.querySelector("[aria-label='Show Hexclave setup error']");
+			expect(pill).not.toBeNull();
+			pill?.click();
+			expect(document.querySelector("[role='alertdialog']")).not.toBeNull();
+		} finally {
+			cleanup();
+		}
+	});
+	it("keeps keyboard focus inside the card and gives it back afterwards", () => {
+		vi.stubEnv("NODE_ENV", "production");
+		const pageButton = document.body.appendChild(document.createElement("button"));
+		pageButton.focus();
+		const cleanup = showSetupErrorOverlay(createSetupError());
+		try {
+			const card = document.querySelector("[role='alertdialog']");
+			expect(document.activeElement).toBe(card);
+			const cardButtons = [...card?.querySelectorAll("button") ?? []];
+			expect(cardButtons.length).toBeGreaterThan(1);
+			cardButtons[cardButtons.length - 1].focus();
+			document.dispatchEvent(new KeyboardEvent("keydown", {
+				key: "Tab",
+				bubbles: true,
+				cancelable: true
+			}));
+			expect(document.activeElement).toBe(cardButtons[0]);
+			document.dispatchEvent(new KeyboardEvent("keydown", {
+				key: "Tab",
+				bubbles: true,
+				cancelable: true,
+				shiftKey: true
+			}));
+			expect(document.activeElement).toBe(cardButtons[cardButtons.length - 1]);
+			pageButton.focus();
+			document.dispatchEvent(new KeyboardEvent("keydown", {
+				key: "Tab",
+				bubbles: true,
+				cancelable: true
+			}));
+			expect(document.activeElement).toBe(cardButtons[0]);
+		} finally {
+			cleanup();
+		}
+		expect(document.activeElement).toBe(pageButton);
+		pageButton.remove();
+	});
+	it("keeps the first card instead of stacking later errors on top of it", () => {
+		vi.stubEnv("NODE_ENV", "production");
+		const firstError = createSetupError();
+		const cleanup = showSetupErrorOverlay(firstError);
+		try {
+			showSetupErrorOverlay(new HexclaveSetupError({
+				title: "Another setup error",
+				message: "Another setup error happened.",
+				howToFix: ["Fix the other thing."]
+			}))();
+			expect(overlayRoots()).toHaveLength(1);
+			expect(document.body.textContent).toContain(firstError.message);
+			expect(document.body.textContent).not.toContain("Another setup error happened.");
+		} finally {
+			cleanup();
+		}
+	});
+	it("only shows errors that are not setup errors while developing", () => {
+		vi.stubEnv("NODE_ENV", "production");
+		showSetupErrorOverlay(/* @__PURE__ */ new Error("Some internal failure."))();
+		expect(overlayRoots()).toHaveLength(0);
+		vi.stubEnv("NODE_ENV", "development");
+		const cleanup = showSetupErrorOverlay(/* @__PURE__ */ new Error("Some internal failure."));
+		try {
+			expect(overlayRoots()).toHaveLength(1);
+			expect(document.body.textContent).toContain("Some internal failure.");
+		} finally {
+			cleanup();
+		}
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=index.test.js.map

package/dist/esm/setup-error-overlay/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","names":[],"sources":["../../../src/setup-error-overlay/index.test.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// @vitest-environment jsdom\n\nimport { HexclaveSetupError } from \"@hexclave/shared/dist/utils/errors\";\nimport { afterEach, describe, expect, it, vi } from \"vitest\";\nimport { SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, showSetupErrorOverlay } from \".\";\n\nfunction createSetupError() {\n  return new HexclaveSetupError({\n    title: \"A domain in your authentication flow is not one of your project's trusted domains\",\n    message: \"Nested cross-domain auth callback URL https://demo.example.test/ is not trusted.\",\n    howToFix: [\"Add https://demo.example.test to your project's trusted domains.\"],\n  });\n}\n\nfunction overlayRoots() {\n  return document.querySelectorAll(\".hexclave-setup-error-overlay\");\n}\n\ndescribe(\"setup error overlay\", () => {\n  afterEach(() => {\n    vi.unstubAllEnvs();\n    for (const root of overlayRoots()) {\n      root.remove();\n    }\n    Reflect.deleteProperty(window, SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY);\n  });\n\n  it(\"renders setup errors with their fix instructions, even outside development\", () => {\n    vi.stubEnv(\"NODE_ENV\", \"production\");\n    const error = createSetupError();\n\n    const cleanup = showSetupErrorOverlay(error);\n    try {\n      expect(overlayRoots()).toHaveLength(1);\n      const text = document.body.textContent;\n      expect(text).toContain(error.title);\n      expect(text).toContain(error.message);\n      expect(text).toContain(error.howToFix[0]);\n      expect(document.querySelector(\"[role='alertdialog']\")).not.toBeNull();\n    } finally {\n      cleanup();\n    }\n\n    expect(overlayRoots()).toHaveLength(0);\n  });\n\n  it(\"minimizes into a pill and back\", () => {\n    vi.stubEnv(\"NODE_ENV\", \"production\");\n    const cleanup = showSetupErrorOverlay(createSetupError());\n    try {\n      const minimizeButton = document.querySelector<HTMLButtonElement>(\"[aria-label='Minimize Hexclave setup error']\");\n      expect(minimizeButton).not.toBeNull();\n      minimizeButton?.click();\n      expect(document.querySelector(\"[role='alertdialog']\")).toBeNull();\n\n      const pill = document.querySelector<HTMLButtonElement>(\"[aria-label='Show Hexclave setup error']\");\n      expect(pill).not.toBeNull();\n      pill?.click();\n      expect(document.querySelector(\"[role='alertdialog']\")).not.toBeNull();\n    } finally {\n      cleanup();\n    }\n  });\n\n  it(\"keeps keyboard focus inside the card and gives it back afterwards\", () => {\n    vi.stubEnv(\"NODE_ENV\", \"production\");\n    const pageButton = document.body.appendChild(document.createElement(\"button\"));\n    pageButton.focus();\n\n    const cleanup = showSetupErrorOverlay(createSetupError());\n    try {\n      const card = document.querySelector<HTMLElement>(\"[role='alertdialog']\");\n      expect(document.activeElement).toBe(card);\n\n      const cardButtons = [...(card?.querySelectorAll(\"button\") ?? [])];\n      expect(cardButtons.length).toBeGreaterThan(1);\n      cardButtons[cardButtons.length - 1].focus();\n      document.dispatchEvent(new KeyboardEvent(\"keydown\", { key: \"Tab\", bubbles: true, cancelable: true }));\n      expect(document.activeElement).toBe(cardButtons[0]);\n      document.dispatchEvent(new KeyboardEvent(\"keydown\", { key: \"Tab\", bubbles: true, cancelable: true, shiftKey: true }));\n      expect(document.activeElement).toBe(cardButtons[cardButtons.length - 1]);\n\n      // Tabbing away from the card is what the trap exists to prevent, even when the page itself moves focus.\n      pageButton.focus();\n      document.dispatchEvent(new KeyboardEvent(\"keydown\", { key: \"Tab\", bubbles: true, cancelable: true }));\n      expect(document.activeElement).toBe(cardButtons[0]);\n    } finally {\n      cleanup();\n    }\n\n    expect(document.activeElement).toBe(pageButton);\n    pageButton.remove();\n  });\n\n  it(\"keeps the first card instead of stacking later errors on top of it\", () => {\n    vi.stubEnv(\"NODE_ENV\", \"production\");\n    const firstError = createSetupError();\n    const cleanup = showSetupErrorOverlay(firstError);\n    try {\n      const secondCleanup = showSetupErrorOverlay(new HexclaveSetupError({\n        title: \"Another setup error\",\n        message: \"Another setup error happened.\",\n        howToFix: [\"Fix the other thing.\"],\n      }));\n      secondCleanup();\n\n      expect(overlayRoots()).toHaveLength(1);\n      expect(document.body.textContent).toContain(firstError.message);\n      expect(document.body.textContent).not.toContain(\"Another setup error happened.\");\n    } finally {\n      cleanup();\n    }\n  });\n\n  it(\"only shows errors that are not setup errors while developing\", () => {\n    vi.stubEnv(\"NODE_ENV\", \"production\");\n    showSetupErrorOverlay(new Error(\"Some internal failure.\"))();\n    expect(overlayRoots()).toHaveLength(0);\n\n    vi.stubEnv(\"NODE_ENV\", \"development\");\n    const cleanup = showSetupErrorOverlay(new Error(\"Some internal failure.\"));\n    try {\n      expect(overlayRoots()).toHaveLength(1);\n      expect(document.body.textContent).toContain(\"Some internal failure.\");\n    } finally {\n      cleanup();\n    }\n  });\n});\n"],"mappings":"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"}

package/dist/generated/quetzal-translations.d.ts

@@ -1,2 +1,2 @@
-import { n as quetzalLocales, t as quetzalKeys } from "../quetzal-translations-XeH3zQ9l.js";
+import { n as quetzalLocales, t as quetzalKeys } from "../quetzal-translations-CK45_4Dm.js";
 export { quetzalKeys, quetzalLocales };

package/dist/{hexclave-provider-BKxi3Vy-.d.ts → hexclave-provider-BA97jMlx.d.ts}

@@ -1,5 +1,5 @@
 import { N as StackAdminApp, a as StackClientApp, z as StackServerApp } from "./client-app-BCT5p_70.js";
-import { t as TranslationProvider } from "./translation-provider-WOaZXqAz.js";
+import { t as TranslationProvider } from "./translation-provider-DQ3BJepJ.js";
 import React from "react";
 
 //#region src/providers/hexclave-provider.d.ts
@@ -26,4 +26,4 @@ declare const HexclaveProvider: typeof NextStackProvider;
 declare const StackProvider: typeof NextStackProvider;
 //#endregion
 export { HexclaveProvider as n, StackProvider as r, ActiveProvider as t };
-//# sourceMappingURL=hexclave-provider-BKxi3Vy-.d.ts.map
+//# sourceMappingURL=hexclave-provider-BA97jMlx.d.ts.map

package/dist/{hexclave-provider-BKxi3Vy-.d.ts.map → hexclave-provider-BA97jMlx.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"hexclave-provider-BKxi3Vy-.d.ts","names":[],"sources":["../src/providers/hexclave-provider.tsx"],"mappings":";;;;;iBASS,iBAAA;EACP,QAAA;EACA,GAAA;EACA,IAAA;EACA;AAAA;EAEA,IAAA,GAAO,KAAA,CAAM,cAAA,QAAsB,mBAAA;;AARwB;;;;;EAe3D,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;EAEhB,GAAA,EAAK,cAAA,SAAuB,cAAA,SAAuB,aAAA;AAAA,gCACpD,GAAA,CAAA,OAAA;AAAA,cAcK,cAAA,SAAc,iBAAoB;AAAA,cAI3B,gBAAA,SAAgB,iBAAiB;;cAEjC,aAAA,SAAa,iBAAiB"}
+{"version":3,"file":"hexclave-provider-BA97jMlx.d.ts","names":[],"sources":["../src/providers/hexclave-provider.tsx"],"mappings":";;;;;iBASS,iBAAA;EACP,QAAA;EACA,GAAA;EACA,IAAA;EACA;AAAA;EAEA,IAAA,GAAO,KAAA,CAAM,cAAA,QAAsB,mBAAA;;AARwB;;;;;EAe3D,oBAAA,GAAuB,MAAA;EACvB,QAAA,EAAU,KAAA,CAAM,SAAA;EAEhB,GAAA,EAAK,cAAA,SAAuB,cAAA,SAAuB,aAAA;AAAA,gCACpD,GAAA,CAAA,OAAA;AAAA,cAcK,cAAA,SAAc,iBAAoB;AAAA,cAI3B,gBAAA,SAAgB,iBAAiB;;cAEjC,aAAA,SAAa,iBAAiB"}

package/dist/in-page-ui/dev-environment.d.ts

@@ -0,0 +1,5 @@
+//#region src/in-page-ui/dev-environment.d.ts
+declare function isLikelyDevelopmentEnvironment(): boolean;
+//#endregion
+export { isLikelyDevelopmentEnvironment };
+//# sourceMappingURL=dev-environment.d.ts.map

package/dist/in-page-ui/dev-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-environment.d.ts","names":[],"sources":["../../src/in-page-ui/dev-environment.ts"],"mappings":";iBAWgB,8BAAA"}

package/dist/in-page-ui/dev-environment.js

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _hexclave_shared_dist_utils_urls = require("@hexclave/shared/dist/utils/urls");
+let ___generated_env_js = require("../generated/env.js");
+//#region src/in-page-ui/dev-environment.ts
+function isLikelyDevelopmentEnvironment() {
+	const nodeEnv = ___generated_env_js.envVars.NODE_ENV;
+	if (nodeEnv !== void 0) return nodeEnv === "development";
+	if (typeof window === "undefined") return false;
+	try {
+		if (new URL(window.location.href).protocol === "file:") return true;
+	} catch {
+		return false;
+	}
+	return (0, _hexclave_shared_dist_utils_urls.isLocalhost)(window.location.href);
+}
+//#endregion
+exports.isLikelyDevelopmentEnvironment = isLikelyDevelopmentEnvironment;
+
+//# sourceMappingURL=dev-environment.js.map

package/dist/in-page-ui/dev-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-environment.js","names":["envVars"],"sources":["../../src/in-page-ui/dev-environment.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// Shared \"are we in a development-like environment?\" check for Hexclave's in-page UIs. Some of them (eg. surfacing an\n// unexpected internal error) are only appropriate while developing, and the SDK cannot ask the server about it because\n// the check has to work synchronously and before the app is authenticated.\n\nimport { isLocalhost } from \"@hexclave/shared/dist/utils/urls\";\nimport { envVars } from \"../generated/env\";\n\nexport function isLikelyDevelopmentEnvironment(): boolean {\n  // NODE_ENV is the most reliable signal, but plenty of bundlers (eg. Vite-based ones) don't define it in the browser\n  // bundle at all, so fall back to guessing from the current URL.\n  const nodeEnv = envVars.NODE_ENV;\n  if (nodeEnv !== undefined) {\n    return nodeEnv === \"development\";\n  }\n\n  if (typeof window === \"undefined\") {\n    return false;\n  }\n\n  try {\n    const url = new URL(window.location.href);\n    if (url.protocol === \"file:\") {\n      return true;\n    }\n  } catch {\n    return false;\n  }\n  return isLocalhost(window.location.href);\n}\n"],"mappings":";;;;AAWA,SAAgB,iCAA0C;CAGxD,MAAM,UAAUA,oBAAAA,QAAQ;CACxB,IAAI,YAAY,KAAA,GACd,OAAO,YAAY;CAGrB,IAAI,OAAO,WAAW,aACpB,OAAO;CAGT,IAAI;EAEF,IAAI,IADY,IAAI,OAAO,SAAS,IAC9B,CAAC,CAAC,aAAa,SACnB,OAAO;CAEX,QAAQ;EACN,OAAO;CACT;CACA,QAAA,GAAA,iCAAA,YAAA,CAAmB,OAAO,SAAS,IAAI;AACzC"}

package/dist/in-page-ui/issue-card.d.ts

@@ -0,0 +1,52 @@
+//#region src/in-page-ui/issue-card.d.ts
+type IssueCardKind = "error" | "warning";
+declare function getIssueCardCSS(scopeSelector: string): string;
+declare function copyTextToClipboard(text: string): Promise<void>;
+type IssueCardOptions = {
+  kind: IssueCardKind; /** Short uppercase label in the card's badge, eg. "Config error". */
+  badge: string;
+  title: string; /** One or two sentences on what this means for the running app. */
+  bodyText: string;
+  messageLabel: string;
+  message: string; /** Concrete steps the developer should take; rendered as a list above the footer. */
+  howToFix?: readonly string[];
+  footerText: string;
+  ariaLabel: string; /** Prompt for the "copy AI prompt" button, ie. the message plus enough context for a coding agent to fix it. */
+  aiPrompt: string;
+  onCopyError: (error: unknown) => void;
+  onCopyAiPromptError: (error: unknown) => void;
+  onMinimize: () => void;
+};
+declare function renderIssueCard(options: IssueCardOptions): HTMLElement;
+type IssueCardFocusTrap = {
+  /**
+   * Whatever had focus before the card first appeared. Callers that rebind the trap to a re-rendered card pass it back
+   * in, so focus still returns to where the developer left it once the card is gone for good.
+   */
+  previouslyFocused: HTMLElement | null;
+  release: (releaseOptions?: {
+    restoreFocus?: boolean;
+  }) => void;
+};
+/**
+ * Keeps keyboard focus inside a mounted card, which claims to be an `aria-modal` alertdialog and therefore has to behave
+ * like one: the flow behind the card is dead until the problem is fixed, so tabbing into it would only let a keyboard
+ * user wander through a page that cannot work while the card stays invisible to them.
+ *
+ * Call right after mounting the card, and release the trap when the card is minimized, replaced or removed. Releasing
+ * hands focus back to `previouslyFocused` unless `restoreFocus: false` is passed, which is what a caller that is about
+ * to rebind the trap to a freshly rendered card wants.
+ */
+declare function trapFocusInIssueCard(cardRoot: HTMLElement, options?: {
+  moveFocusIntoCard?: boolean;
+  previouslyFocused?: HTMLElement | null;
+}): IssueCardFocusTrap;
+declare function renderIssuePill(options: {
+  kind: IssueCardKind;
+  label: string;
+  ariaLabel: string;
+  onClick: () => void;
+}): HTMLElement;
+//#endregion
+export { IssueCardFocusTrap, IssueCardKind, IssueCardOptions, copyTextToClipboard, getIssueCardCSS, renderIssueCard, renderIssuePill, trapFocusInIssueCard };
+//# sourceMappingURL=issue-card.d.ts.map

package/dist/in-page-ui/issue-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-card.d.ts","names":[],"sources":["../../src/in-page-ui/issue-card.ts"],"mappings":";KAcY,aAAA;AAAA,iBAII,eAAA,CAAgB,aAAqB;AAAA,iBAyP/B,mBAAA,CAAoB,IAAA,WAAe,OAAO;AAAA,KAkEpD,gBAAA;EACV,IAAA,EAAM,aAAa,EAhUI;EAkUvB,KAAA;EACA,KAAA;EAEA,QAAA;EACA,YAAA;EACA,OAAA,UA1EuC;EA4EvC,QAAA;EACA,UAAA;EACA,SAAA,UAZU;EAcV,QAAA;EACA,WAAA,GAAc,KAAA;EACd,mBAAA,GAAsB,KAAA;EACtB,UAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,OAAA,EAAS,gBAAA,GAAmB,WAAW;AAAA,KA+D3D,kBAAA;EA7EV;;;;EAkFA,iBAAA,EAAmB,WAAW;EAC9B,OAAA,GAAU,cAAA;IAAmB,YAAA;EAAA;AAAA;;;;;AAxEnB;AAGZ;;;;iBAiFgB,oBAAA,CAAqB,QAAA,EAAU,WAAA,EAAa,OAAA;EAC1D,iBAAA;EACA,iBAAA,GAAoB,WAAA;AAAA,IACb,kBAAA;AAAA,iBA6CO,eAAA,CAAgB,OAAA;EAC9B,IAAA,EAAM,aAAA;EACN,KAAA;EACA,SAAA;EACA,OAAA;AAAA,IACE,WAAW"}