nuxt-cornerstone 1.0.0

package/dist/runtime/composables/useViewerShortcuts.js

@@ -0,0 +1,115 @@
+import { onMounted, onUnmounted } from "vue";
+export const DEFAULT_TOOL_SHORTCUTS = [
+  { className: "WindowLevelTool", shortcut: "w" },
+  { className: "PanTool", shortcut: "p" },
+  { className: "ZoomTool", shortcut: "z" },
+  { className: "LengthTool", shortcut: "m" },
+  { className: "RectangleROITool", shortcut: "b" },
+  { className: "EllipticalROITool", shortcut: "e" },
+  { className: "ProbeTool", shortcut: "t" }
+];
+const OWNS_KEYBOARD = [
+  "input",
+  "textarea",
+  "select",
+  '[role="combobox"]',
+  '[role="listbox"]',
+  '[role="option"]',
+  '[role="searchbox"]',
+  '[role="spinbutton"]',
+  '[role="textbox"]',
+  '[role="menu"]',
+  '[role="menuitem"]'
+].join(", ");
+function ownsKeyboard(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  return target.closest(OWNS_KEYBOARD) !== null;
+}
+const CORNERSTONE_VIEWPORT = "[data-viewport-uid][data-rendering-engine-uid]";
+function isCornerstoneViewport(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.closest(CORNERSTONE_VIEWPORT) !== null;
+}
+function isInDialog(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.closest('[role="dialog"], [role="alertdialog"]') !== null;
+}
+function isActivatable(target) {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.closest('button, a, [role="button"], [role="option"]') !== null;
+}
+function codeForLetter(letter) {
+  return `Key${letter.toUpperCase()}`;
+}
+export function useViewerShortcuts(handlers, options = {}) {
+  const tools = options.tools ?? DEFAULT_TOOL_SHORTCUTS;
+  function onKeydown(event) {
+    if (event.defaultPrevented && !isCornerstoneViewport(event.target)) return;
+    if (event.ctrlKey || event.metaKey || event.altKey) return;
+    if (ownsKeyboard(event.target)) return;
+    if (event.key === "?" || event.shiftKey && event.code === "Slash") {
+      handlers.toggleHelp();
+      event.preventDefault();
+      return;
+    }
+    if (isInDialog(event.target)) return;
+    if (!handlers.isEnabled()) return;
+    switch (event.code) {
+      case "ArrowDown":
+        handlers.step(1);
+        break;
+      case "ArrowUp":
+        handlers.step(-1);
+        break;
+      case "PageDown":
+        handlers.stepSeries(1);
+        break;
+      case "PageUp":
+        handlers.stepSeries(-1);
+        break;
+      case "Home":
+        handlers.first();
+        break;
+      case "End":
+        handlers.last();
+        break;
+      case "Space":
+        if (isActivatable(event.target)) return;
+        handlers.togglePlay();
+        break;
+      // `C` for cine, kept alongside Space for the same reason a media player
+      // has both a spacebar and a labelled button.
+      case "KeyC":
+        handlers.togglePlay();
+        break;
+      case "KeyR":
+        handlers.resetViewport();
+        break;
+      // Delete is the key for this everywhere, and Backspace is the one a Mac
+      // keyboard without a Delete key actually has. Backspace is only "go
+      // back" outside a text field in old browsers, and nothing here runs
+      // inside one — the widgets that own the keyboard have already been let
+      // through above — so taking it and marking it handled is safe.
+      case "Delete":
+      case "Backspace":
+        if (!handlers.deleteMeasurement) return;
+        handlers.deleteMeasurement();
+        break;
+      default: {
+        const tool = tools.find((entry) => codeForLetter(entry.shortcut) === event.code);
+        if (!tool) return;
+        handlers.setTool(tool.className);
+      }
+    }
+    event.preventDefault();
+  }
+  onMounted(() => window.addEventListener("keydown", onKeydown));
+  onUnmounted(() => window.removeEventListener("keydown", onKeydown));
+}
+export function releaseFocus(event) {
+  if (event.detail === 0) return;
+  const target = event.target;
+  if (!(target instanceof HTMLElement)) return;
+  target.closest("button")?.blur();
+}

package/dist/runtime/cornerstone.d.ts

@@ -0,0 +1,21 @@
+import type { CornerstoneLibs, CornerstoneModuleOptions, ResolvedCornerstoneOptions } from './types.js';
+/**
+ * Install the options resolved at build time. Called by the client plugin
+ * before any component can mount, so `ensureCornerstone()` never has to reach
+ * for a Nuxt context of its own.
+ */
+export declare function configureCornerstone(options: CornerstoneModuleOptions | undefined): void;
+/** Merge extra options in before init. Throws once init has started. */
+export declare function setCornerstoneOptions(options: CornerstoneModuleOptions): void;
+export declare function getCornerstoneOptions(): ResolvedCornerstoneOptions;
+/**
+ * Initialise Cornerstone3D once, and hand back the three entry points.
+ *
+ * Init order is not a style choice: `dicomImageLoaderInit()` calls
+ * `getWebWorkerManager()` from core, and core's `init()` is what creates that
+ * manager. Core first, loader second, tools last.
+ */
+export declare function ensureCornerstone(options?: CornerstoneModuleOptions): Promise<CornerstoneLibs>;
+/** The libraries if init has completed, else `null`. Never triggers a load. */
+export declare function getLoadedCornerstone(): CornerstoneLibs | null;
+export declare function isCornerstoneInitialised(): boolean;

package/dist/runtime/cornerstone.js

@@ -0,0 +1,100 @@
+import { configureI18n, t } from "./i18n/index.js";
+import { DEFAULT_TOOLS } from "./types.js";
+const hot = import.meta.hot;
+const state = hot ? hot.data.cornerstone ??= {} : {};
+state.registeredTools ??= /* @__PURE__ */ new Set();
+const DEFAULT_OPTIONS = {
+  autoInit: true,
+  core: {},
+  dicomImageLoader: {},
+  tools: { enabled: true, register: [...DEFAULT_TOOLS] },
+  i18n: {
+    locale: "en",
+    fallbackLocale: "en",
+    messages: {},
+    numberingSystem: "auto",
+    detect: false
+  },
+  viteCommonjs: true,
+  prefix: "Cornerstone",
+  renderingEngineId: "nuxt-cornerstone",
+  toolGroupId: "nuxt-cornerstone-tools"
+};
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function merge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === void 0 ? base : override;
+  }
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (value === void 0) continue;
+    out[key] = isPlainObject(out[key]) && isPlainObject(value) ? merge(out[key], value) : value;
+  }
+  return out;
+}
+export function configureCornerstone(options) {
+  state.options = merge(state.options ?? DEFAULT_OPTIONS, options);
+  configureI18n(state.options.i18n);
+}
+export function setCornerstoneOptions(options) {
+  if (state.libsPromise) {
+    throw new Error(`[nuxt-cornerstone] ${t("error.optionsLocked")}`);
+  }
+  configureCornerstone(options);
+}
+export function getCornerstoneOptions() {
+  return state.options ?? DEFAULT_OPTIONS;
+}
+export function ensureCornerstone(options) {
+  if (import.meta.server) {
+    return Promise.reject(
+      new Error(`[nuxt-cornerstone] ${t("error.ssr")}`)
+    );
+  }
+  if (options) setCornerstoneOptions(options);
+  state.libsPromise ??= load();
+  return state.libsPromise;
+}
+async function load() {
+  const options = getCornerstoneOptions();
+  const [core, dicomImageLoader, tools] = await Promise.all([
+    import("@cornerstonejs/core"),
+    import("@cornerstonejs/dicom-image-loader"),
+    import("@cornerstonejs/tools")
+  ]);
+  core.init(options.core);
+  dicomImageLoader.init(options.dicomImageLoader);
+  if (options.tools.enabled) {
+    tools.init();
+    if (options.tools.register !== false) {
+      registerTools(tools, options.tools.register);
+    }
+  }
+  const libs = { core, tools, dicomImageLoader };
+  state.libs = libs;
+  return libs;
+}
+function registerTools(tools, names) {
+  const registered = state.registeredTools;
+  for (const name of names) {
+    if (registered.has(name)) continue;
+    const ToolClass = tools[name];
+    if (typeof ToolClass !== "function") {
+      console.warn(`[nuxt-cornerstone] ${t("warn.unknownTool", { tool: name })}`);
+      continue;
+    }
+    try {
+      tools.addTool(ToolClass);
+    } catch {
+    }
+    registered.add(name);
+  }
+}
+export function getLoadedCornerstone() {
+  return state.libs ?? null;
+}
+export function isCornerstoneInitialised() {
+  return Boolean(state.libs);
+}

package/dist/runtime/dicom-instances.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Where a SOPInstanceUID can be found in this session.
+ *
+ * Annotations produced somewhere else — by a reporting system, or by a model
+ * running server-side — identify the slice they belong to by its
+ * SOPInstanceUID (0008,0018), because that is the only identifier that
+ * survives leaving the viewer. An imageId does not: `dicomfile:` ids are
+ * handed out by the loader as files are registered, so the same study opened
+ * twice has a different set of them.
+ *
+ * `useDicomFiles()` fills this in as it reads headers, and
+ * `useDicomAnnotations()` reads it to place incoming boxes. It lives here
+ * rather than inside either composable so that neither has to import the
+ * other.
+ *
+ * Nothing writes to it on the server: both writers go through
+ * `ensureCornerstone()`, which rejects during SSR. So the module-scoped map
+ * that would otherwise be shared between in-flight requests only ever holds
+ * one browser session's files.
+ */
+/**
+ * Remember where a slice lives.
+ *
+ * A later registration wins. Reopening a study registers the same UIDs against
+ * fresh imageIds, and the fresh ones are the ones that still resolve.
+ */
+export declare function registerInstance(sopInstanceUid: string, imageId: string): void;
+/** The imageId for a SOPInstanceUID, or `null` if that slice is not loaded. */
+export declare function imageIdForSopInstanceUid(sopInstanceUid: string): string | null;
+export declare function clearInstanceIndex(): void;
+/** How many slices can currently be found by UID. */
+export declare function instanceIndexSize(): number;

package/dist/runtime/dicom-instances.js

@@ -0,0 +1,15 @@
+const hot = import.meta.hot;
+const state = hot ? hot.data.cornerstoneInstances ??= {} : {};
+state.imageIds ??= /* @__PURE__ */ new Map();
+export function registerInstance(sopInstanceUid, imageId) {
+  state.imageIds.set(sopInstanceUid, imageId);
+}
+export function imageIdForSopInstanceUid(sopInstanceUid) {
+  return state.imageIds.get(sopInstanceUid) ?? null;
+}
+export function clearInstanceIndex() {
+  state.imageIds.clear();
+}
+export function instanceIndexSize() {
+  return state.imageIds.size;
+}

package/dist/runtime/dicom-zip.d.ts

@@ -0,0 +1,95 @@
+export { formatBytes } from './i18n/index.js';
+/**
+ * ZIP extraction for DICOM archives.
+ *
+ * `fflate` is imported dynamically: an app that never opens a ZIP should not
+ * pay for a decompressor, and its async `unzip` inflates on a worker pool so a
+ * 500-slice study does not block the frame the user is scrolling.
+ */
+/** A file pulled out of the archive, kept with the path it had inside it. */
+export interface ZipEntry {
+    /** Full path inside the archive, e.g. `STUDY/SER00002/IM000001`. */
+    path: string;
+    /**
+     * The backing buffer is pinned to `ArrayBuffer` rather than left as
+     * `ArrayBufferLike`, because `BlobPart` rejects a possibly-shared buffer and
+     * these bytes go straight into a `File`. fflate never allocates on a
+     * `SharedArrayBuffer`, so narrowing it here is sound.
+     */
+    bytes: Uint8Array<ArrayBuffer>;
+}
+export type SkipReason = 
+/** Archive metadata: `__MACOSX/`, dotfiles, `DICOMDIR`. */
+'metadata'
+/** Ruled out by extension before inflating — .pdf, .jpg, .txt and friends. */
+ | 'not-dicom-extension'
+/** Inflated, but neither the `DICM` magic nor a parseable dataset. */
+ | 'not-dicom'
+/** Zero bytes. */
+ | 'empty';
+export interface SkippedEntry {
+    path: string;
+    reason: SkipReason;
+}
+export interface UnzipDicomResult {
+    entries: ZipEntry[];
+    skipped: SkippedEntry[];
+}
+/**
+ * Default ceiling on total *uncompressed* bytes. A ZIP advertises the
+ * uncompressed size of every member in its central directory, so this is
+ * checked before anything is inflated — a 100 KB archive claiming 40 GB is
+ * rejected without allocating for it.
+ */
+export declare const DEFAULT_MAX_BYTES: number;
+export interface UnzipDicomOptions {
+    /** Ceiling on total uncompressed bytes. Default: 2 GiB. */
+    maxBytes?: number;
+}
+/**
+ * Rule a file out by its name alone, and say why, or `null` to keep it.
+ *
+ * Exported because the same question is asked of files that never came from an
+ * archive — a folder picked in a file dialog carries the same `.DS_Store` and
+ * report PDFs a burned CD does — and one definition of "not DICOM" is better
+ * than two that drift apart.
+ */
+export declare function nonDicomNameReason(path: string): 'metadata' | 'not-dicom-extension' | null;
+/** Bytes needed before {@link hasDicmMagic} can answer. */
+export declare const DICM_MAGIC_BYTES: number;
+/** Part 10 files carry `DICM` at byte 128, right after the preamble. */
+export declare function hasDicmMagic(bytes: Uint8Array): boolean;
+/**
+ * Enough bytes for {@link isDicomContent} to decide: the Part 10 preamble plus
+ * room for the first few elements of a dataset that has no preamble.
+ */
+export declare const CONTENT_PROBE_BYTES: number;
+/**
+ * Does this look like DICOM from its content alone?
+ *
+ * An extension proves nothing in either direction — plenty of DICOM files are
+ * named `IM000001`, and anything at all can be renamed to `.dcm` — so the
+ * answer has to come from the bytes.
+ *
+ * Part 10 files say so outright with their magic. A dataset stored without a
+ * preamble has nothing to declare, so its structure is read instead: the first
+ * element must open a group a dataset may legitimately open with, and the
+ * elements after it must parse and ascend. A PNG fails at the first tag, whose
+ * group reads as 0x5089.
+ *
+ * This is a positive test. Anything that cannot show one of those two things
+ * is rejected, which is the opposite of assuming a file is DICOM because
+ * nothing proved otherwise.
+ */
+export declare function isDicomContent(bytes: Uint8Array): Promise<boolean>;
+export type DicomParser = typeof import('dicom-parser');
+/**
+ * Inflate a ZIP and hand back the members that look like DICOM.
+ *
+ * Filtering happens in two passes. The cheap one runs inside fflate's `filter`
+ * hook, which sees each member's name and uncompressed size *before* it is
+ * inflated, so housekeeping files and obvious non-DICOM never cost anything.
+ * The second pass looks at the actual bytes, because a file's name tells you
+ * very little about whether it is DICOM.
+ */
+export declare function unzipDicom(data: Uint8Array, options?: UnzipDicomOptions): Promise<UnzipDicomResult>;

package/dist/runtime/dicom-zip.js

@@ -0,0 +1,149 @@
+import { formatBytes, t } from "./i18n/index.js";
+export { formatBytes } from "./i18n/index.js";
+export const DEFAULT_MAX_BYTES = 2 * 1024 ** 3;
+function isMetadataPath(path) {
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  return path.startsWith("__MACOSX/") || path.includes("/__MACOSX/") || name.startsWith(".") || name === "DICOMDIR" || name === "Thumbs.db";
+}
+const NON_DICOM_EXTENSION = /\.(?:txt|pdf|jpe?g|png|gif|bmp|tiff?|svg|xml|html?|json|csv|tsv|md|rtf|docx?|xlsx?|pptx?|zip|gz|tgz|bz2|xz|rar|7z|exe|dll|so|dylib|bat|sh|ini|cfg|log|db|sqlite|mp4|avi|mov|wav|mp3)$/i;
+export function nonDicomNameReason(path) {
+  if (isMetadataPath(path)) return "metadata";
+  if (NON_DICOM_EXTENSION.test(path)) return "not-dicom-extension";
+  return null;
+}
+const DICM_MAGIC = [68, 73, 67, 77];
+const DICM_MAGIC_OFFSET = 128;
+export const DICM_MAGIC_BYTES = DICM_MAGIC_OFFSET + DICM_MAGIC.length;
+export function hasDicmMagic(bytes) {
+  if (bytes.length < DICM_MAGIC_OFFSET + DICM_MAGIC.length) return false;
+  return DICM_MAGIC.every((byte, i) => bytes[DICM_MAGIC_OFFSET + i] === byte);
+}
+export const CONTENT_PROBE_BYTES = 16 * 1024;
+const FOREIGN_SIGNATURES = [
+  [137, 80, 78, 71],
+  // PNG
+  [255, 216, 255],
+  //       JPEG
+  [71, 73, 70, 56],
+  // GIF8
+  [66, 77],
+  //             BMP
+  [37, 80, 68, 70],
+  // %PDF
+  [80, 75, 3, 4],
+  // ZIP
+  [31, 139],
+  //             gzip
+  [82, 97, 114, 33],
+  // Rar!
+  [55, 122, 188, 175],
+  // 7z
+  [73, 73, 42, 0],
+  // TIFF little-endian
+  [77, 77, 0, 42],
+  // TIFF big-endian
+  [82, 73, 70, 70],
+  // RIFF (wav, avi, webp)
+  [79, 103, 103, 83],
+  // OggS
+  [127, 69, 76, 70],
+  // ELF
+  [77, 90],
+  //             DOS/PE executable
+  [73, 68, 51],
+  //       ID3 (mp3)
+  [60, 63, 120, 109],
+  // <?xm
+  [60, 33, 68, 79]
+  // <!DO
+];
+function hasForeignSignature(bytes) {
+  return FOREIGN_SIGNATURES.some(
+    (signature) => signature.every((byte, i) => bytes[i] === byte)
+  );
+}
+const OPENING_GROUPS = /* @__PURE__ */ new Set([2, 8]);
+const PROBE_ELEMENTS = 4;
+const readU16 = (bytes, at, littleEndian) => littleEndian ? bytes[at] | bytes[at + 1] << 8 : bytes[at] << 8 | bytes[at + 1];
+export async function isDicomContent(bytes) {
+  if (hasDicmMagic(bytes)) return true;
+  if (bytes.length < 8) return false;
+  if (hasForeignSignature(bytes)) return false;
+  if (OPENING_GROUPS.has(readU16(bytes, 0, false))) return true;
+  if (!OPENING_GROUPS.has(readU16(bytes, 0, true))) return false;
+  const dicomParser = await loadDicomParser();
+  return walksAsDataset(dicomParser, bytes, false) || walksAsDataset(dicomParser, bytes, true);
+}
+function walksAsDataset(dicomParser, bytes, explicitVr) {
+  try {
+    const stream = new dicomParser.ByteStream(dicomParser.littleEndianByteArrayParser, bytes, 0);
+    let previousTag = "";
+    for (let read = 0; read < PROBE_ELEMENTS; read++) {
+      if (stream.position + 8 > bytes.length) return read > 0;
+      const element = explicitVr ? dicomParser.readDicomElementExplicit(stream) : dicomParser.readDicomElementImplicit(stream);
+      if (!/^x[0-9a-f]{8}$/.test(element.tag)) return false;
+      if (element.tag <= previousTag) return false;
+      previousTag = element.tag;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+let dicomParserPromise = null;
+function loadDicomParser() {
+  dicomParserPromise ??= import("dicom-parser").then((mod) => {
+    const candidate = mod;
+    return candidate.default ?? mod;
+  });
+  return dicomParserPromise;
+}
+export async function unzipDicom(data, options = {}) {
+  const { maxBytes = DEFAULT_MAX_BYTES } = options;
+  const { unzip } = await import("fflate");
+  const skipped = [];
+  let claimedBytes = 0;
+  const filter = (file) => {
+    if (file.name.endsWith("/")) return false;
+    const nameReason = nonDicomNameReason(file.name);
+    if (nameReason) {
+      skipped.push({ path: file.name, reason: nameReason });
+      return false;
+    }
+    if (file.originalSize === 0) {
+      skipped.push({ path: file.name, reason: "empty" });
+      return false;
+    }
+    claimedBytes += file.originalSize;
+    if (claimedBytes > maxBytes) {
+      throw new Error(t("zip.tooLarge", { limit: formatBytes(maxBytes) }));
+    }
+    return true;
+  };
+  const unzipped = await new Promise((resolve, reject) => {
+    unzip(data, { filter }, (err, result) => {
+      if (err) reject(asZipError(err));
+      else resolve(result);
+    });
+  });
+  const entries = [];
+  for (const [path, bytes] of Object.entries(unzipped)) {
+    if (bytes.length === 0) {
+      skipped.push({ path, reason: "empty" });
+      continue;
+    }
+    if (!await isDicomContent(bytes)) {
+      skipped.push({ path, reason: "not-dicom" });
+      continue;
+    }
+    entries.push({ path, bytes });
+  }
+  return { entries, skipped };
+}
+function asZipError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (/invalid zip|no central directory|end of central/i.test(message)) {
+    return new Error(t("zip.notReadable"));
+  }
+  return new Error(t("zip.readFailed", { message }));
+}

package/dist/runtime/i18n/detect.d.ts

@@ -0,0 +1,37 @@
+import type { CornerstoneI18nOptions, LocaleSource } from '../types.js';
+/**
+ * Reading the locale from the application that installed the module.
+ *
+ * Kept out of the plugin so it depends on nothing Nuxt-specific — the plugin
+ * hands it `nuxtApp` and it duck-types its way from there.
+ */
+export declare const ALL_SOURCES: LocaleSource[];
+export declare function sourcesOf(detect: NonNullable<CornerstoneI18nOptions['detect']>): LocaleSource[];
+/**
+ * Adopt a locale only if there is a catalogue for it.
+ *
+ * An app running in a language nobody has translated keeps the configured
+ * locale, rather than flipping text direction under the viewer to go on showing
+ * English anyway.
+ */
+export declare function adoptLocale(candidate: unknown): boolean;
+/** Try each source in order; returns the one that answered, or `null`. */
+export declare function followHostLocale(nuxtApp: unknown, sources: LocaleSource[]): LocaleSource | null;
+/**
+ * `@nuxtjs/i18n` and vue-i18n both put the active locale on `nuxtApp.$i18n`.
+ * It is duck-typed rather than imported, so the module gains no dependency and
+ * simply declines when neither is installed.
+ *
+ * `toValue` inside the getter covers both shapes: a `Ref` in Composition mode,
+ * a reactive string property in legacy mode.
+ */
+export declare function followHostI18n(nuxtApp: unknown): boolean;
+/**
+ * The `lang` attribute, watched so a switch at runtime is picked up. Nearly
+ * every i18n library sets it, which makes this the generic path.
+ *
+ * Do not pair this source with setting `<html lang>` *from* this module's
+ * locale — that is a cycle. It settles, because adopting the locale that is
+ * already active changes nothing, but the app then has no source of truth.
+ */
+export declare function followHtmlLang(): boolean;

package/dist/runtime/i18n/detect.js

@@ -0,0 +1,37 @@
+import { toValue, watch } from "vue";
+import { hasCornerstoneCatalog, setCornerstoneLocale } from "./index.js";
+export const ALL_SOURCES = ["i18n", "html", "navigator"];
+export function sourcesOf(detect) {
+  return Array.isArray(detect) ? detect : detect ? ALL_SOURCES : [];
+}
+export function adoptLocale(candidate) {
+  if (typeof candidate !== "string" || !candidate) return false;
+  if (!hasCornerstoneCatalog(candidate)) return false;
+  setCornerstoneLocale(candidate);
+  return true;
+}
+export function followHostLocale(nuxtApp, sources) {
+  for (const source of sources) {
+    if (source === "i18n" && followHostI18n(nuxtApp)) return source;
+    if (source === "html" && followHtmlLang()) return source;
+    if (source === "navigator" && adoptLocale(navigator.language)) return source;
+  }
+  return null;
+}
+export function followHostI18n(nuxtApp) {
+  const host = nuxtApp?.$i18n;
+  if (!host || host.locale === void 0) return false;
+  const read = () => toValue(host.locale);
+  if (!adoptLocale(read())) return false;
+  watch(read, adoptLocale);
+  return true;
+}
+export function followHtmlLang() {
+  const root = document.documentElement;
+  if (!adoptLocale(root.lang)) return false;
+  new MutationObserver(() => adoptLocale(root.lang)).observe(root, {
+    attributes: true,
+    attributeFilter: ["lang"]
+  });
+  return true;
+}

package/dist/runtime/i18n/index.d.ts

@@ -0,0 +1,61 @@
+import type { MessageCatalog, MessageKey, MessageParams } from './messages.js';
+import type { CornerstoneI18nOptions } from '../types.js';
+export type { CornerstoneMessageKey, MessageCatalog, MessageKey, MessageParams, MessageValue, PluralCategory, } from './messages.js';
+export { BUILTIN_MESSAGES, en, fa } from './messages.js';
+/**
+ * A translator supplied by the host app, to route this module's strings
+ * through whatever i18n it already runs. Return `undefined` for any key it does
+ * not know and the built-in catalogue answers instead, so an app can override
+ * three strings without adopting the whole set.
+ */
+export type CornerstoneTranslator = (key: MessageKey, params: MessageParams | undefined, locale: string) => string | undefined;
+export declare const DEFAULT_LOCALE = "en";
+/**
+ * Apply the build-time `cornerstone.i18n` options.
+ *
+ * Called from `configureCornerstone()`, so it runs both for options that came
+ * through `runtimeConfig` and for options handed to `ensureCornerstone()` by an
+ * app's own plugin.
+ */
+export declare function configureI18n(options: CornerstoneI18nOptions | false | undefined): void;
+export declare function getCornerstoneLocale(): string;
+/**
+ * Switch locale at runtime. A no-op when `cornerstone.i18n` is `false` — an app
+ * that turned the catalogue off is driving the strings from its own i18n, and
+ * silently tracking a second locale here would only be confusing.
+ */
+export declare function setCornerstoneLocale(locale: string): void;
+/** Every locale with a catalogue, built-in or registered through options. */
+export declare function getCornerstoneLocales(): string[];
+/**
+ * Whether there is a catalogue for a locale, matching `fa-IR` against `fa`.
+ * Locale detection uses this to ignore languages nobody has translated.
+ */
+export declare function hasCornerstoneCatalog(locale: string): boolean;
+/** Route this module's strings through the host app's i18n. `null` unsets it. */
+export declare function setCornerstoneTranslator(translator: CornerstoneTranslator | null): void;
+/** Register or extend a catalogue at runtime, for locales not in the config. */
+export declare function addCornerstoneMessages(locale: string, catalog: MessageCatalog): void;
+/** Whether a locale is written right-to-left. */
+export declare function isRtlLocale(locale?: string): boolean;
+/** `'rtl'` or `'ltr'`, ready for a `dir` attribute. */
+export declare function dirForLocale(locale?: string): 'ltr' | 'rtl';
+/**
+ * Translate a key.
+ *
+ * Resolution order is translator, active locale, fallback locale, English, and
+ * finally the key itself — a missing string shows up as `series.unnamed`
+ * rather than as an empty label.
+ */
+export declare function t(key: MessageKey, params?: MessageParams): string;
+/** Format a number in the active locale. */
+export declare function n(value: number, options?: Intl.NumberFormatOptions): string;
+/**
+ * Human-readable byte size in the active locale — `2 GB`, or «۲ گیگابایت».
+ *
+ * The number is formatted by `Intl` (Persian-Indic digits, Persian decimal
+ * separator) but the unit comes from the catalogue. `Intl`'s own `style: 'unit'`
+ * is not usable here: CLDR's short English name for `byte` is "byte", so a
+ * 900-byte archive would read "900 byte".
+ */
+export declare function formatBytes(bytes: number): string;