@celestia-island/hikari 0.55.92 → 0.55.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.92",
+  "version": "0.55.94",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAttachmentModal.tsx

@@ -286,7 +286,7 @@ export const HkAttachmentModal = defineComponent({
                 <p class="s-attachment-modal-text-empty">
                   {srcError.value
                     ? srcError.value
-                    : t("hikari::attachment.noPreview", "No preview available.")}
+                    : t("hikari::attachment.noPreview", "No preview available")}
                 </p>
               )}
               {textError.value && (

package/src/components/HkCaptchaModal.tsx

@@ -41,7 +41,7 @@ export const HkCaptchaModal = defineComponent({
         width={props.width}
       >
         <div class="s-captcha-modal">
-          <p class="s-captcha-modal-prompt">{t("hikari::captcha.prompt", "Complete the verification below to continue.")}</p>
+          <p class="s-captcha-modal-prompt">{t("hikari::captcha.prompt", "Complete the verification below to continue")}</p>
           {props.modelValue && (
             <HkCaptchaWidget
               siteKey={props.siteKey}

package/src/components/HkCaptchaWidget.tsx

@@ -166,7 +166,7 @@ export const HkCaptchaWidget = defineComponent({
         return (
           <div class="s-captcha-widget s-captcha-widget-placeholder">
             <ShieldAlert size={16} />
-            <span>{t("hikari::captcha.placeholder", "Verification is not configured for this deployment (no site key provided).")}</span>
+            <span>{t("hikari::captcha.placeholder", "Verification is not configured for this deployment (no site key provided)")}</span>
           </div>
         );
       }

package/src/components/HkCookieConsent.test.tsx

@@ -51,7 +51,7 @@ describe("HkCookieConsent", () => {
     await nextTick();
     const notice = container.querySelector<HTMLElement>(".s-cookie-consent");
     expect(notice, "notice span renders").toBeTruthy();
-    expect(notice!.textContent).toContain("This site uses cookies.");
+    expect(notice!.textContent).toContain("This site uses cookies");
     const ok = container.querySelector<HTMLButtonElement>(".s-cookie-consent-ok");
     expect(ok, "OK button renders").toBeTruthy();
     expect(ok!.textContent).toBe("OK");

package/src/components/HkCookieConsent.tsx

@@ -45,7 +45,7 @@ export const HkCookieConsent = defineComponent({
       if (accepted.value) return <Cookie size={12} class="s-cookie-consent-icon" />;
       return (
         <span class="s-cookie-consent">
-          {t("hikari::cookie.text", "This site uses cookies.")}
+          {t("hikari::cookie.text", "This site uses cookies")}
           <button type="button" class="s-cookie-consent-ok" onClick={accept}>
             {t("hikari::cookie.ok", "OK")}
           </button>

package/src/components/HkErrorBoundary.test.tsx

@@ -91,6 +91,17 @@ describe("HkErrorBoundary", () => {
     expect(el.querySelector(".hk-error-landing")).not.toBeNull();
   });
 
+  it("feeds the landing's built-in copy action with the captured error", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const el = mountWith(Boom, { copyErrorLabel: "Copy Error" });
+    await nextTick();
+
+    const buttons = Array.from(el.querySelectorAll<HTMLButtonElement>(".hk-error-landing__actions button"));
+    // Built-in copy seats first, the boundary's own retry follows.
+    expect(buttons[0]!.textContent).toBe("Copy Error");
+    expect(buttons.some((b) => b.textContent === "Retry")).toBe(true);
+  });
+
   it("keeps the custom fallback render prop contract", async () => {
     vi.spyOn(console, "error").mockImplementation(() => {});
     const el = mountWith(Boom, {

package/src/components/HkErrorBoundary.tsx

@@ -1,7 +1,6 @@
-import { Copy, RefreshCw } from "lucide-vue-next";
+import { RefreshCw } from "lucide-vue-next";
 import { computed, defineComponent, onErrorCaptured, ref, type PropType, type VNode } from "vue";
 
-import { useClipboard } from "../runtime/useClipboard";
 import { useI18n } from "../i18n/context";
 import HButton from "./HkButton";
 import { HkErrorLanding } from "./HkErrorLanding";
@@ -31,8 +30,9 @@ function formatError(err: CapturedError): string {
  * The built-in fallback is the same HkErrorLanding card the family's
  * full-page takeovers use (inline variant): tone icon, headline, the error
  * name as the tone-matched HkBadge chip, the message as the description,
- * the raw name/message/stack in the fixed-height JSON tree pane, plus
- * retry / copy actions.
+ * the raw name/message/stack in the fixed-height JSON tree pane, plus the
+ * retry action and the landing's built-in copy action (fed with the
+ * formatted error text).
  */
 export default defineComponent({
   name: "HkErrorBoundary",
@@ -44,7 +44,6 @@ export default defineComponent({
     retryLabel: { type: String, default: "" },
   },
   setup(props, { slots }) {
-    const clipboard = useClipboard();
     const { t } = useI18n();
     const error = ref<CapturedError | null>(null);
 
@@ -87,6 +86,11 @@ export default defineComponent({
           title={props.errorTitle || t("hikari::errors.defaultTitle", "Something went wrong")}
           description={err.message}
           code={err.name}
+          // The copy action is the landing's built-in now (seated left of
+          // the host actions, one design family-wide); this boundary only
+          // feeds it the formatted error and its legacy label override.
+          copyText={formatError(err)}
+          copyLabel={props.copyErrorLabel}
         >
           {{
             default: () => <HkJsonTree value={detailsValue.value} ariaLabel="stack trace" />,
@@ -95,10 +99,6 @@ export default defineComponent({
                 <RefreshCw size={12} />
                 {props.retryLabel || t("hikari::errorBoundary.retry", "Retry")}
               </HButton>,
-              <HButton variant="ghost" size="sm" onClick={() => clipboard.copy(formatError(err))}>
-                <Copy size={12} />
-                {props.copyErrorLabel || t("hikari::errorBoundary.copyError", "Copy Error")}
-              </HButton>,
             ],
           }}
         </HkErrorLanding>

package/src/components/HkErrorLanding.inline.contract.test.ts

@@ -51,3 +51,15 @@ describe("HkErrorLanding inline contract", () => {
     expect(card).not.toContain("2.25rem");
   });
 });
+
+describe("HkErrorLanding multiline headline contract", () => {
+  const css = readFileSync(join(here, "HkErrorLanding.scss"), "utf-8");
+  const title = ruleBody(css, ".hk-error-landing__title");
+
+  it("renders authored line breaks in the headline as breaks", () => {
+    // Catalogs ship per-line copy (a dash clause moved onto its own
+    // line); without pre-line the h1 collapses those breaks to spaces.
+    expect(title).toContain("white-space: pre-line");
+    expect(title).toContain("overflow-wrap: anywhere");
+  });
+});

package/src/components/HkErrorLanding.scss

@@ -173,6 +173,11 @@
   letter-spacing: -0.01em;
   line-height: 1.35;
   color: rgb(var(--hel-text));
+  // Headlines may carry their own line breaks (hosts ship per-line copy,
+  // e.g. a two-clause landing where the dash clause moved to its own
+  // line) — render them as breaks, not spaces.
+  white-space: pre-line;
+  overflow-wrap: anywhere;
 }
 
 .hk-error-landing__desc {

package/src/components/HkErrorLanding.test.tsx

@@ -1,5 +1,5 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { createApp, h } from "vue";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick } from "vue";
 
 import { HkErrorLanding } from "./HkErrorLanding";
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
@@ -11,6 +11,8 @@ interface MountOptions {
   status?: number;
   tone?: "error" | "warning" | "info";
   variant?: "page" | "inline";
+  copyText?: string;
+  copyLabel?: string;
   details?: () => ReturnType<typeof h>;
   actions?: () => ReturnType<typeof h>;
   brand?: () => ReturnType<typeof h>;
@@ -28,6 +30,8 @@ function mountLanding(opts: MountOptions = {}) {
         status: opts.status,
         tone: opts.tone ?? "error",
         variant: opts.variant ?? "page",
+        copyText: opts.copyText ?? "",
+        copyLabel: opts.copyLabel ?? "",
       }, {
         ...(opts.details ? { default: opts.details } : {}),
         ...(opts.actions ? { actions: opts.actions } : {}),
@@ -39,12 +43,29 @@ function mountLanding(opts: MountOptions = {}) {
   return container;
 }
 
+/** Stub the async clipboard (jsdom ships none) and restore afterwards. */
+function stubClipboard() {
+  const writeText = vi.fn().mockResolvedValue(undefined);
+  Object.defineProperty(navigator, "clipboard", {
+    value: { writeText },
+    configurable: true,
+    writable: true,
+  });
+  return writeText;
+}
+
+function actionButtons(el: HTMLElement): HTMLButtonElement[] {
+  return Array.from(el.querySelectorAll<HTMLButtonElement>(".hk-error-landing__actions button"));
+}
+
 afterEach(() => {
   for (const { app, container } of mounts) {
     app.unmount();
     container.remove();
   }
   mounts.length = 0;
+  Reflect.deleteProperty(navigator, "clipboard");
+  vi.restoreAllMocks();
 });
 
 describe("HkErrorLanding", () => {
@@ -142,4 +163,51 @@ describe("HkErrorLanding", () => {
     const root = el.querySelector(".hk-error-landing")!;
     expect(root.classList.contains("is-inline")).toBe(true);
   });
+
+  it("seats the built-in copy action FIRST, left of the host actions", () => {
+    const el = mountLanding({
+      copyText: "Boom: bad",
+      actions: () => h("button", { class: "fake-action" }, "Retry"),
+    });
+    const buttons = actionButtons(el);
+    expect(buttons).toHaveLength(2);
+    expect(buttons[0]!.textContent).toBe("Copy error details");
+    expect(buttons[1]!.classList.contains("fake-action")).toBe(true);
+  });
+
+  it("writes the copy payload and flips the label to Copied", async () => {
+    const writeText = stubClipboard();
+    const el = mountLanding({ copyText: "full error info" });
+    const copy = actionButtons(el)[0]!;
+    copy.click();
+    await vi.waitFor(() => expect(writeText).toHaveBeenCalledTimes(1));
+    expect(writeText).toHaveBeenCalledWith("full error info");
+    await nextTick();
+    await nextTick();
+    expect(actionButtons(el)[0]!.textContent).toBe("Copied");
+  });
+
+  it("renders the copy action alone when the host passes no actions", () => {
+    const el = mountLanding({ copyText: "raw" });
+    const buttons = actionButtons(el);
+    expect(buttons).toHaveLength(1);
+    expect(buttons[0]!.textContent).toBe("Copy error details");
+  });
+
+  it("renders no copy action and no actions row without copyText and slot", () => {
+    const el = mountLanding({ title: "Boom" });
+    expect(el.querySelector(".hk-error-landing__actions")).toBeNull();
+  });
+
+  it("keeps the actions row host-only when copyText is empty", () => {
+    const el = mountLanding({ actions: () => h("button", { class: "fake-action" }, "Retry") });
+    const buttons = actionButtons(el);
+    expect(buttons).toHaveLength(1);
+    expect(buttons[0]!.classList.contains("fake-action")).toBe(true);
+  });
+
+  it("honours a custom copy label override", () => {
+    const el = mountLanding({ copyText: "raw", copyLabel: "Copy Error" });
+    expect(actionButtons(el)[0]!.textContent).toBe("Copy Error");
+  });
 });

package/src/components/HkErrorLanding.tsx

@@ -1,4 +1,4 @@
-import { Braces, Info, TriangleAlert } from "lucide-vue-next";
+import { Braces, Check, Copy, Info, TriangleAlert } from "lucide-vue-next";
 import {
   computed,
   defineComponent,
@@ -7,11 +7,14 @@ import {
   onUpdated,
   ref,
   type PropType,
+  type VNode,
 } from "vue";
 
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useI18n } from "../i18n/context";
+import { useClipboard } from "../runtime/useClipboard";
 import HkBadge from "./HkBadge";
+import HkButton from "./HkButton";
 
 import "./HkErrorLanding.scss";
 
@@ -27,6 +30,13 @@ export type HErrorTone = "error" | "warning" | "info";
  */
 export type HErrorLandingVariant = "page" | "inline";
 
+/** Slot renderers may return a single vnode or an array — normalize to an
+ *  array so the built-in copy action and the host's actions share one row. */
+function normalizeSlotNodes(nodes: VNode | VNode[] | undefined): VNode[] {
+  if (!nodes) return [];
+  return Array.isArray(nodes) ? nodes : [nodes];
+}
+
 /**
  * HkErrorLanding — the shared full-page error landing.
  *
@@ -46,6 +56,15 @@ export type HErrorLandingVariant = "page" | "inline";
  * server-rendered error page alike. All host-facing copy (`title`,
  * `description`, action buttons) arrives pre-translated; the component only
  * translates its own labels via `hikari::errors.*`.
+ *
+ * The standard copy action: hosts pass `copyText` (the full error info they
+ * want on the clipboard — headline, technical context, raw payload, …) and
+ * the landing seats its built-in "copy error details" button as the FIRST
+ * action, left of whatever the actions slot renders — one design for the
+ * whole error-landing family instead of every consumer hand-rolling its
+ * own copy row (the boundary used to ship a private one; it now feeds this
+ * hook). `copyLabel` overrides the button wording when a host already
+ * ships its own.
  */
 export const HkErrorLanding = defineComponent({
   name: "HkErrorLanding",
@@ -58,15 +77,29 @@ export const HkErrorLanding = defineComponent({
     code: { type: String, default: "" },
     /** HTTP status chip, e.g. 400. */
     status: { type: Number, default: undefined },
+    /** Full error info the built-in copy action puts on the clipboard
+     *  (headline + technical context + raw payload, host-composed).
+     *  Empty disables the action. */
+    copyText: { type: String, default: "" },
+    /** Optional wording override for the built-in copy button; empty
+     *  falls back to `hikari::errors.copyDetails`. */
+    copyLabel: { type: String, default: "" },
     tone: { type: String as PropType<HErrorTone>, default: "error" },
     /** Layout variant: `page` (viewport backdrop) or `inline` (in-flow card). */
     variant: { type: String as PropType<HErrorLandingVariant>, default: "page" },
   },
   setup(props, { slots }) {
     const { t } = useI18n();
+    const clipboard = useClipboard();
 
     const titleText = computed(() => props.title || t("hikari::errors.defaultTitle", "Something went wrong"));
     const hasDetails = computed(() => slots.default != null);
+    // The actions row carries the built-in copy action whenever the host
+    // feeds it a payload — with or without slot actions beside it.
+    // Frozen like hasDetails: the slots object identity is not reactive,
+    // so a slot appearing mid-lifetime wouldn't flip this row — every
+    // family host mounts the landing with its slot set already settled.
+    const hasActions = computed(() => slots.actions != null || props.copyText !== "");
 
     // Badge variant follows the landing tone so the chip, the icon and the
     // card wash always speak the same severity language.
@@ -175,7 +208,31 @@ export const HkErrorLanding = defineComponent({
             </div>
           )}
 
-          {slots.actions && <div class="hk-error-landing__actions">{slots.actions()}</div>}
+          {hasActions.value && (
+            <div class="hk-error-landing__actions" aria-live="polite">
+              {[
+                // The standard copy action seats FIRST — left of every
+                // host-provided action — so the whole family reads
+                // [copy] [retry] [dismiss…] no matter who hosts the card.
+                ...(props.copyText
+                  ? [(
+                    <HkButton
+                      key="hk-error-copy"
+                      size="sm"
+                      variant="ghost"
+                      onClick={() => { void clipboard.copy(props.copyText); }}
+                    >
+                      {clipboard.copied.value ? <Check size={12} /> : <Copy size={12} />}
+                      {clipboard.copied.value
+                        ? t("hikari::errors.copied", "Copied")
+                        : props.copyLabel || t("hikari::errors.copyDetails", "Copy error details")}
+                    </HkButton>
+                  )]
+                  : []),
+                ...(normalizeSlotNodes(slots.actions?.())),
+              ]}
+            </div>
+          )}
         </div>
       </div>
     );

package/src/components/HkLogWindow.tsx

@@ -179,7 +179,7 @@ export const HkLogWindow = defineComponent({
             ref={scrollRef}
           >
             {currentLines.value.length === 0 ? (
-              <div class="s-log-empty">{t("hikari::log.empty", "No log lines yet.")}</div>
+              <div class="s-log-empty">{t("hikari::log.empty", "No log lines yet")}</div>
             ) : (
               currentLines.value.map((line, i) => (
                 <div key={i} class={["s-log-entry", `s-log-entry-${levelOf(line)}`]}>

package/src/components/HkNodeCanvas.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, isRef, nextTick, onUpdated, ref, type App } from "vue";
 
 import HkNodeCanvas, { NODE_CANVAS_DEFAULTS } from "./HkNodeCanvas";
+import { CANVAS_BOUNDS_MARGIN, clampCameraToBounds } from "./nodeCanvasTypes";
 
 /**
  * HkNodeCanvas tests — the camera protocol the three node surfaces share:
@@ -1050,4 +1051,142 @@ describe("HkNodeCanvas", () => {
     // Controlled: the internal camera did not move on its own.
     expect(instance.value!.camera).toEqual({ k: 1, x: 0, y: 0 });
   });
+
+  // ── Bounds clamp ─────────────────────────────────────────────────
+  // The camera may never push the content hull farther than half a
+  // viewport past the visible edge, per axis: at the limit the hull sits
+  // exactly CANVAS_BOUNDS_MARGIN of a viewport outside, and past it the
+  // outward drag is refused. Every camera write funnels through
+  // `setCamera`, so a drag, a wheel/pinch zoom, a tween and an imperative
+  // call all stop at the same edge.
+
+  describe("bounds clamp", () => {
+    // BOUNDS = 400×200 at (0,0), viewport 800×600, k = 1 ⇒
+    // x ∈ [-k·(x+w) - f·W, W - k·x + f·W] = [-800, 1200],
+    // y ∈ [-200 - 300, 600 + 300] = [-500, 900].
+    const X_LIMIT_LOW = -800;
+    const Y_LIMIT_LOW = -500;
+
+    it("clamps the pure camera to the expanded hull", () => {
+      const bounds = { x: 0, y: 0, width: 400, height: 200 };
+      const viewport = { width: 800, height: 600 };
+      // A camera already framing the content passes through untouched.
+      const inside = { k: 1, x: 100, y: 100 };
+      expect(clampCameraToBounds(inside, bounds, viewport)).toEqual(inside);
+      // Dragged far off-screen: stopped at the derived limit.
+      expect(clampCameraToBounds({ k: 1, x: -5000, y: -9000 }, bounds, viewport)).toEqual({
+        k: 1,
+        x: X_LIMIT_LOW,
+        y: Y_LIMIT_LOW,
+      });
+      // …and symmetrically for the far corners.
+      expect(clampCameraToBounds({ k: 1, x: 5000, y: 9000 }, bounds, viewport)).toEqual({
+        k: 1,
+        x: 1200,
+        y: 900,
+      });
+    });
+
+    it("holds the margin as a SCREEN distance at any zoom", () => {
+      // At k = 2 the world window halves, so the world-space margin halves
+      // with it — but the on-screen slack stays half a viewport.
+      const bounds = { x: 0, y: 0, width: 400, height: 200 };
+      const viewport = { width: 800, height: 600 };
+      const clamped = clampCameraToBounds({ k: 2, x: -99999, y: 0 }, bounds, viewport);
+      // xLow = -2·400 - 0.5·800 = -1200.
+      expect(clamped.x).toBe(-1200);
+      // At the limit the hull's right edge sits exactly half a viewport
+      // left of the screen's left edge.
+      const hullRightOnScreen = (bounds.width) * clamped.k + clamped.x;
+      expect(hullRightOnScreen).toBe(-viewport.width / 2);
+    });
+
+    it("passes degenerate inputs through unchanged", () => {
+      const cam = { k: 1, x: 123, y: 456 };
+      expect(clampCameraToBounds(cam, null, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 0, height: 100 }, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 100, height: 0 }, { width: 800, height: 600 })).toBe(cam);
+      expect(clampCameraToBounds(cam, { x: 0, y: 0, width: 100, height: 100 }, { width: 0, height: 0 })).toBe(cam);
+      expect(clampCameraToBounds({ k: 0, x: 1, y: 1 }, { x: 0, y: 0, width: 100, height: 100 }, { width: 800, height: 600 })).toEqual({ k: 0, x: 1, y: 1 });
+      // An astronomically placed hull overflows the clamp range (k·coord
+      // passes the double ceiling): refuse to clamp rather than write a
+      // non-finite translation (the browser would drop the transform).
+      const far = { x: 1e308, y: 1e308, width: 100, height: 100 };
+      expect(clampCameraToBounds({ k: 2, x: 123, y: 456 }, far, { width: 800, height: 600 })).toEqual({ k: 2, x: 123, y: 456 });
+      expect(clampCameraToBounds({ k: 1, x: NaN, y: 0 }, { x: 0, y: 0, width: 100, height: 100 }, { width: 800, height: 600 })).toEqual({ k: 1, x: NaN, y: 0 });
+    });
+
+    it("stops a pan that would drag the hull off-screen", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.camera).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+      // The far direction clamps at its own wall.
+      instance.value?.panBy(99999, 99999);
+      expect(instance.value!.camera).toEqual({ k: 1, x: 1200, y: 900 });
+      // Small moves apply on the free axis; the wall axis stays pinned.
+      instance.value?.panBy(-10, 5);
+      expect(instance.value!.camera).toEqual({ k: 1, x: 1190, y: 900 });
+    });
+
+    it("stops a pointer drag at the same edge", async () => {
+      const { instance, root } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      root.setPointerCapture = () => {};
+      root.dispatchEvent(pointerEvent("pointerdown", { pointerId: 21, clientX: 400, clientY: 300 }));
+      // 400 px of drag left/up, in two moves, is nowhere near the limit —
+      // then one enormous move rides into the wall.
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: 300, clientY: 250 }));
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: 200, clientY: 200 }));
+      root.dispatchEvent(pointerEvent("pointermove", { pointerId: 21, clientX: -100000, clientY: -100000 }));
+      document.body.dispatchEvent(pointerEvent("pointerup", { pointerId: 21, clientX: -100000, clientY: -100000, buttons: 0 }));
+      expect(instance.value!.camera).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+    });
+
+    it("keeps a wheel zoom anchored without escaping the walls", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      // Ride to the low-x wall first, then zoom out hard: the anchor keeps
+      // the world point under the cursor, but the translation must stay
+      // inside the clamp interval for the new k.
+      instance.value?.panBy(-5000, 0);
+      for (let step = 0; step < 12; step++) instance.value?.zoomBy(-1);
+      const cam = instance.value!.camera;
+      const xLow = -cam.k * (BOUNDS.x + BOUNDS.width) - CANVAS_BOUNDS_MARGIN * VIEWPORT.width;
+      const xHigh = VIEWPORT.width - cam.k * BOUNDS.x + CANVAS_BOUNDS_MARGIN * VIEWPORT.width;
+      expect(cam.x).toBeGreaterThanOrEqual(xLow - 1e-6);
+      expect(cam.x).toBeLessThanOrEqual(xHigh + 1e-6);
+    });
+
+    it("lets a controlled host's gestures clamp before the emit", async () => {
+      const onUpdate = vi.fn();
+      const { instance } = mount({
+        contentBounds: BOUNDS,
+        camera: { k: 1, x: 0, y: 0 },
+        "onUpdate:camera": onUpdate,
+        fitOnLoad: false,
+      });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      const last = onUpdate.mock.calls.at(-1)?.[0] as { k: number; x: number; y: number };
+      expect(last).toEqual({ k: 1, x: X_LIMIT_LOW, y: Y_LIMIT_LOW });
+    });
+
+    it("does nothing the host did not ask for when the clamp is off", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false, clampToBounds: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.camera).toEqual({ k: 1, x: -5000, y: -5000 });
+    });
+
+    it("never fights a fit: framing still centres the hull", async () => {
+      const { instance } = mount({ contentBounds: BOUNDS, fitOnLoad: false });
+      await nextTick();
+      instance.value?.panBy(-5000, -5000);
+      expect(instance.value!.fit()).toBe(true);
+      // 400×200 in 800×600 with 40 px padding → k = min(1.8, 2.6) capped at
+      // fitCap 1.25, centred: x = (800-500)/2, y = (600-250)/2.
+      expect(instance.value!.camera).toEqual({ k: 1.25, x: 150, y: 175 });
+    });
+  });
 });

package/src/components/HkNodeCanvas.tsx

@@ -13,6 +13,7 @@ import "./HkNodeCanvas.scss";
 
 import {
   computeLod,
+  clampCameraToBounds,
   edgeHitWidth,
   edgeMidpoint,
   edgePath,
@@ -39,7 +40,7 @@ export type {
   NodeCanvasPainter,
   PrintPaper,
 } from "./nodeCanvasTypes";
-export { computeLod, edgePath, edgeMidpoint, edgeHitWidth, sideOffset, oppositeSide, LOD_DEFAULTS, PAPER_SIZES } from "./nodeCanvasTypes";
+export { computeLod, edgePath, edgeMidpoint, edgeHitWidth, sideOffset, oppositeSide, LOD_DEFAULTS, PAPER_SIZES, clampCameraToBounds, CANVAS_BOUNDS_MARGIN } from "./nodeCanvasTypes";
 
 /** The pointer payload the edge events carry: a real MouseEvent for
  * hover/click/contextmenu, or a synthesized stand-in when a touch
@@ -143,6 +144,13 @@ interface PendingRequest {
  *     read to simplify their nodes at low zoom.
  *   - a **print mode**: disables gestures, fixes the camera, and exposes
  *     `exportSVG()` for vector output.
+ *   - a **bounds clamp** (default on): every camera write stops where the
+ *     content hull would leave half a viewport of itself past the visible
+ *     edge — a drag, a wheel or pinch zoom, a tween, an imperative call.
+ *     A graph can still be stranded only through the host's own channels:
+ *     opting out (`clampToBounds: false`), never supplying
+ *     `contentBounds`, or a controlled `camera` prop the host writes
+ *     verbatim (emitted gesture results are always pre-clamped).
  *
  * What it still does NOT own: what nodes look like, what data drives
  * them, or how they are laid out. The host draws node content through
@@ -165,7 +173,10 @@ export default defineComponent({
     /** Controlled camera (`v-model:camera`). Without it the component keeps
      *  its own, seeded by `fitOnLoad`. */
     camera: { type: Object as PropType<NodeCanvasCamera | undefined>, default: undefined },
-    /** Content rectangle, in world units, used for fit and clamping. */
+    /** Content rectangle, in world units — the hull every node on the
+     *  canvas forms. `fit` frames it, and the bounds clamp (`clampToBounds`,
+     *  on by default) refuses camera moves that would push it out of
+     *  reach. */
     contentBounds: { type: Object as PropType<NodeCanvasBounds | null>, default: null },
     /** Smallest zoom the camera will settle on. */
     minZoom: { type: Number, default: NODE_CANVAS_DEFAULTS.minZoom },
@@ -197,6 +208,15 @@ export default defineComponent({
     pannable: { type: Boolean, default: true },
     /** Whether the wheel zooms. */
     zoomable: { type: Boolean, default: true },
+    /** Keep the content within reach: the camera may never push the
+     *  content hull (the `contentBounds` envelope every node on the canvas
+     *  forms) farther than half a viewport past the visible edge, per
+     *  axis — the outward drag stops there instead of stranding the graph
+     *  off-screen. On by default; a canvas with a genuinely unbounded
+     *  surface (or one whose content the host moves independently) opts
+     *  out with `false`. Needs `contentBounds` to know the hull — without
+     *  it there is nothing to clamp against and this is a no-op. */
+    clampToBounds: { type: Boolean, default: true },
     /** Mount the minimap in the corner. */
     minimap: { type: Boolean, default: true },
     /** Which corner the minimap takes. */
@@ -558,12 +578,21 @@ export default defineComponent({
       // the surface freezes with no way back. Refuse to propagate it.
       if (!Number.isFinite(k) || k <= 0) return;
       if (!Number.isFinite(next.x) || !Number.isFinite(next.y)) return;
+      // Bounds clamp (default on): every write funnels through here, so a
+      // drag, a wheel/pinch zoom, a tween and an imperative `setCamera` all
+      // stop at the same edge — the content hull never leaves half a
+      // viewport of reach. `fit()` frames the hull inside the viewport and
+      // therefore always satisfies the clamp; it writes through
+      // `writeCamera` directly, so a host framing is never fought.
+      const bounded = props.clampToBounds
+        ? clampCameraToBounds({ k, x: next.x, y: next.y }, props.contentBounds, viewport.value)
+        : { k, x: next.x, y: next.y };
       // Any non-automatic camera move is the user's: a late `contentBounds`
       // must not throw that work away. It also means the host is somewhere
       // else, so a later `fit()` may ask for the same camera again.
       movedByHand = true;
       lastRequested = null;
-      writeCamera({ k, x: next.x, y: next.y });
+      writeCamera(bounded);
     }
 
     /** The camera that frames `contentBounds` inside the viewport. */

package/src/components/HkTokenUsagePanel.tsx

@@ -79,7 +79,7 @@ export const HkTokenUsagePanel = defineComponent({
         <div class="s-token-panel">
           {props.entries.length === 0 ? (
             <div class="s-token-panel-empty">
-              {t("hikari::tokenUsage.noData", "No token usage data available.")}
+              {t("hikari::tokenUsage.noData", "No token usage data available")}
             </div>
           ) : (
             <>

package/src/components/HkVoiceInputPopup.tsx

@@ -63,7 +63,7 @@ export const HkVoiceInputPopup = defineComponent({
         {props.mode === "notConfigured" ? (
           <div class="s-voice-popup-body" data-phase="install">
             <p class="s-voice-popup-text">
-              {t("hikari::chat.voice_not_configured", "Voice input requires the Whisper service.")}
+              {t("hikari::chat.voice_not_configured", "Voice input requires the Whisper service")}
             </p>
             <button class="s-voice-popup-link" type="button" onClick={openSettings}>
               {t("hikari::chat.voice_go_settings", "Open Voice Settings →")}