@hexclave/next 1.0.75 → 1.0.76

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/setup-error-overlay/index.d.ts

@@ -0,0 +1,16 @@
+//#region src/setup-error-overlay/index.d.ts
+/** Exported so tests can drop the singleton; every other consumer should go through `showSetupErrorOverlay`. */
+declare const SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY = "__hexclave-setup-error-overlay";
+/**
+ * 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.
+ */
+declare function showSetupErrorOverlay(error: unknown): () => void;
+//#endregion
+export { SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, showSetupErrorOverlay };
+//# sourceMappingURL=index.d.ts.map

package/dist/setup-error-overlay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/setup-error-overlay/index.ts"],"mappings":";;cAiBa,uCAAA;;;;AAAuC;AA8DpD;;;;AAAoD;iBAApC,qBAAA,CAAsB,KAAc"}

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

@@ -0,0 +1,108 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let ___in_page_ui_dom_js = require("../in-page-ui/dom.js");
+let _hexclave_shared_dist_utils_errors = require("@hexclave/shared/dist/utils/errors");
+let ___in_page_ui_dev_environment_js = require("../in-page-ui/dev-environment.js");
+let ___in_page_ui_issue_card_js = require("../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 = (0, ___in_page_ui_issue_card_js.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 (_hexclave_shared_dist_utils_errors.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: (0, _hexclave_shared_dist_utils_errors.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 (!(0, ___in_page_ui_dom_js.canMountIntoDom)()) return () => {};
+	if (!_hexclave_shared_dist_utils_errors.HexclaveSetupError.isSetupError(error) && !(0, ___in_page_ui_dev_environment_js.isLikelyDevelopmentEnvironment)()) return () => {};
+	const issue = toSetupIssue(error);
+	if ((0, ___in_page_ui_dom_js.getGlobalUiInstance)("__hexclave-setup-error-overlay") != null) return () => {};
+	const root = (0, ___in_page_ui_dom_js.h)("div", { className: "hexclave-setup-error-overlay" });
+	const style = (0, ___in_page_ui_dom_js.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((0, ___in_page_ui_issue_card_js.renderIssuePill)({
+				kind: "error",
+				label: "Setup error",
+				ariaLabel: "Show Hexclave setup error",
+				onClick: () => render(false)
+			}));
+			return;
+		}
+		root.appendChild((0, ___in_page_ui_issue_card_js.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) => (0, _hexclave_shared_dist_utils_errors.captureError)("setup-error-overlay-copy", copyError),
+			onCopyAiPromptError: (copyError) => (0, _hexclave_shared_dist_utils_errors.captureError)("setup-error-overlay-copy-ai-prompt", copyError),
+			onMinimize: () => render(true)
+		}));
+		focusTrap = (0, ___in_page_ui_issue_card_js.trapFocusInIssueCard)(root);
+	};
+	render(false);
+	const cleanup = () => {
+		focusTrap?.release();
+		focusTrap = null;
+		root.remove();
+		if ((0, ___in_page_ui_dom_js.getGlobalUiInstance)("__hexclave-setup-error-overlay")?.cleanup === cleanup) (0, ___in_page_ui_dom_js.setGlobalUiInstance)(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, null);
+	};
+	(0, ___in_page_ui_dom_js.setGlobalUiInstance)(SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY, { cleanup });
+	return cleanup;
+}
+//#endregion
+exports.SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY = SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY;
+exports.showSetupErrorOverlay = showSetupErrorOverlay;
+
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["HexclaveSetupError"],"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,OAAA,GAAA,4BAAA,gBAAA,CAAsB,+BAA+B;AAE3D,MAAM,0BAA0B;CAC9B;CACA;CACA;AACF;AAWA,SAAS,aAAa,OAA4B;CAChD,IAAIA,mCAAAA,mBAAmB,aAAa,KAAK,GACvC,OAAO;EACL,OAAO,MAAM;EACb,SAAS,MAAM;EACf,UAAU,MAAM;EAChB,SAAS;CACX;CAEF,OAAO;EACL,OAAO;EACP,UAAA,GAAA,mCAAA,kBAAA,CAA2B,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,EAAA,GAAA,qBAAA,gBAAA,CAAiB,GACnB,aAAa,CAAC;CAEhB,IAAI,CAACA,mCAAAA,mBAAmB,aAAa,KAAK,KAAK,EAAA,GAAA,iCAAA,+BAAA,CAAgC,GAC7E,aAAa,CAAC;CAGhB,MAAM,QAAQ,aAAa,KAAK;CAEhC,KAAA,GAAA,qBAAA,oBAAA,CAAA,gCAAmB,KAAK,MAItB,aAAa,CAAC;CAGhB,MAAM,QAAA,GAAA,qBAAA,EAAA,CAAS,OAAO,EAAE,WAAW,+BAA+B,CAAC;CACnE,MAAM,SAAA,GAAA,qBAAA,EAAA,CAAU,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,aAAA,GAAA,4BAAA,gBAAA,CAA4B;IAC/B,MAAM;IACN,OAAO;IACP,WAAW;IACX,eAAe,OAAO,KAAK;GAC7B,CAAC,CAAC;GACF;EACF;EACA,KAAK,aAAA,GAAA,4BAAA,gBAAA,CAA4B;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,eAAA,GAAA,mCAAA,aAAA,CAA2B,4BAA4B,SAAS;GAC9E,sBAAsB,eAAA,GAAA,mCAAA,aAAA,CAA2B,sCAAsC,SAAS;GAChG,kBAAkB,OAAO,IAAI;EAC/B,CAAC,CAAC;EACF,aAAA,GAAA,4BAAA,qBAAA,CAAiC,IAAI;CACvC;CACA,OAAO,KAAK;CAEZ,MAAM,gBAAgB;EACpB,WAAW,QAAQ;EACnB,YAAY;EACZ,KAAK,OAAO;EACZ,KAAA,GAAA,qBAAA,oBAAA,CAAA,gCAA+D,CAAC,EAAE,YAAY,SAC5E,CAAA,GAAA,qBAAA,oBAAA,CAAoB,yCAAyC,IAAI;CAErE;CACA,CAAA,GAAA,qBAAA,oBAAA,CAAoB,yCAAyC,EAAE,QAAQ,CAAC;CACxE,OAAO;AACT"}

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

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

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","names":["HexclaveSetupError","SETUP_ERROR_OVERLAY_GLOBAL_INSTANCE_KEY"],"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/{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/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.75",
+  "version": "1.0.76",
   "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.75",
-    "@hexclave/ui": "1.0.75",
-    "@hexclave/shared": "1.0.75"
+    "@hexclave/shared": "1.0.76",
+    "@hexclave/ui": "1.0.76",
+    "@hexclave/sc": "1.0.76"
   },
   "peerDependencies": {
     "@types/react": ">=18.0.0",

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

@@ -9,6 +9,7 @@ import { runAsynchronously, runAsynchronouslyWithAlert } from "@hexclave/shared/
 import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
 import type { StackClientApp } from "../lib/hexclave-app";
 import { getGlobalUiInstance, h, hasAppendChild, setGlobalUiInstance, setHtml, type UiGlobalInstance } from "../in-page-ui/dom";
+import { HEXCLAVE_LOGO_SVG } from "../in-page-ui/logo";
 import { getBaseUrl } from "../lib/hexclave-app/apps/implementations/common";
 import type { HandlerUrlOptions, HandlerUrls, HandlerUrlTarget } from "../lib/hexclave-app/common";
 import { hexclaveAppInternalsSymbol } from "../lib/hexclave-app/common";
@@ -88,10 +89,6 @@ const DEFAULT_STATE: DevToolState = {
   panelHeight: 520,
 };
 
-// Hexclave mark — hexagon outline with three radial bars, monochrome via currentColor
-// so it inherits the trigger logo's color. Sourced from apps/dashboard/public/hexclave-icon.svg
-// (gradient + glow stripped; this is a tiny trigger glyph, not the full brand mark).
-const HEXCLAVE_LOGO_SVG = '<svg width="16" height="16" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="3" stroke-linejoin="miter"><path d="M 24 4 L 41.32 14 L 41.32 34 L 24 44 L 6.68 34 L 6.68 14 Z"/><path d="M 11 16.87 L 14 15.13 L 14 32.87 L 11 31.13 Z" fill="currentColor" stroke="none"/><path d="M 11 16.87 L 14 15.13 L 14 32.87 L 11 31.13 Z" fill="currentColor" stroke="none" transform="rotate(120 24 24)"/><path d="M 11 16.87 L 14 15.13 L 14 32.87 L 11 31.13 Z" fill="currentColor" stroke="none" transform="rotate(240 24 24)"/></svg>';
 
 // ---------------------------------------------------------------------------
 // State management

package/src/dev-tool/index.ts

@@ -6,9 +6,8 @@
 import type { StackClientApp } from "../lib/hexclave-app";
 import { captureError } from "@hexclave/shared/dist/utils/errors";
 import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
-import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
+import { isLikelyDevelopmentEnvironment } from "../in-page-ui/dev-environment";
 import { canMountIntoDom } from "../in-page-ui/dom";
-import { envVars } from "../generated/env";
 import type { createDevTool as CreateDevToolFn } from "./dev-tool-core";
 
 // Hexclave rebrand: UI-only local pref — straight rename (one-time reset is harmless)
@@ -38,19 +37,9 @@ function shouldShow(): boolean {
   // consuming app itself was built or hosted as production.
   if (activeProjectIsDevelopmentEnvironment) return true;
 
-  // "auto" behavior (the default):
-  const nodeEnv = envVars.NODE_ENV;
-  if (nodeEnv !== undefined) {
-    // NODE_ENV is available (bundler/process env exists) — only show in development
-    return nodeEnv === "development";
-  }
-
-  // NODE_ENV not found (no process.env/import.meta) — show on localhost or file: protocol
-  try {
-    const url = new URL(window.location.href);
-    if (url.protocol === "file:") return true;
-  } catch {}
-  return isLocalhost(window.location.href);
+  // "auto" behavior (the default): every in-page UI that is only appropriate while developing shares one heuristic, so
+  // the dev tool and the error cards can never disagree about whether this looks like a development environment.
+  return isLikelyDevelopmentEnvironment();
 }
 
 let activeCleanup: (() => void) | null = null;

package/src/in-page-ui/dev-environment.ts

@@ -0,0 +1,33 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+// Shared "are we in a development-like environment?" check for Hexclave's in-page UIs. Some of them (eg. surfacing an
+// unexpected internal error) are only appropriate while developing, and the SDK cannot ask the server about it because
+// the check has to work synchronously and before the app is authenticated.
+
+import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
+import { envVars } from "../generated/env";
+
+export function isLikelyDevelopmentEnvironment(): boolean {
+  // NODE_ENV is the most reliable signal, but plenty of bundlers (eg. Vite-based ones) don't define it in the browser
+  // bundle at all, so fall back to guessing from the current URL.
+  const nodeEnv = envVars.NODE_ENV;
+  if (nodeEnv !== undefined) {
+    return nodeEnv === "development";
+  }
+
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  try {
+    const url = new URL(window.location.href);
+    if (url.protocol === "file:") {
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  return isLocalhost(window.location.href);
+}

package/src/in-page-ui/issue-card.test.ts

@@ -0,0 +1,67 @@
+
+//===========================================
+// 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 { afterEach, describe, expect, it } from "vitest";
+import { renderIssueCard, trapFocusInIssueCard } from "./issue-card";
+
+function mountCard(): HTMLElement {
+  const root = document.body.appendChild(document.createElement("div"));
+  root.appendChild(renderIssueCard({
+    kind: "error",
+    badge: "Config error",
+    title: "Something is misconfigured",
+    bodyText: "Body",
+    messageLabel: "Error message",
+    message: "Message",
+    footerText: "Footer",
+    ariaLabel: "Hexclave config error",
+    aiPrompt: "prompt",
+    onCopyError: () => {},
+    onCopyAiPromptError: () => {},
+    onMinimize: () => {},
+  }));
+  return root;
+}
+
+function pressTab() {
+  document.dispatchEvent(new KeyboardEvent("keydown", { key: "Tab", bubbles: true, cancelable: true }));
+}
+
+function cardButtons(root: HTMLElement): HTMLButtonElement[] {
+  return [...root.querySelectorAll<HTMLButtonElement>(".hic-card button")];
+}
+
+describe("issue card focus trap", () => {
+  afterEach(() => {
+    document.body.replaceChildren();
+  });
+
+  it("follows a re-rendered card without moving focus or losing the original focus owner", () => {
+    const pageButton = document.body.appendChild(document.createElement("button"));
+    pageButton.focus();
+
+    const firstRoot = mountCard();
+    const firstTrap = trapFocusInIssueCard(firstRoot);
+    expect(document.activeElement).toBe(firstRoot.querySelector(".hic-card"));
+
+    // What the pushed-config overlay does on every poll: throw the rendered card away and render a fresh one.
+    firstRoot.remove();
+    const secondRoot = mountCard();
+    firstTrap.release({ restoreFocus: false });
+    const secondTrap = trapFocusInIssueCard(secondRoot, {
+      moveFocusIntoCard: false,
+      previouslyFocused: firstTrap.previouslyFocused,
+    });
+    expect(document.activeElement).not.toBe(secondRoot.querySelector(".hic-card"));
+
+    // The trap now belongs to the visible card, so Tab lands inside it instead of inside the detached one.
+    pressTab();
+    expect(document.activeElement).toBe(cardButtons(secondRoot)[0]);
+
+    secondTrap.release();
+    expect(document.activeElement).toBe(pageButton);
+  });
+});