@microscope-js/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 microscope-js contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @microscope-js/core
+
+Framework-agnostic core of microscope-js. Defines the `Renderer` interface and the registry that picks the right renderer for a source.
+
+```ts
+import { createRegistry, mount } from '@microscope-js/core';
+import { pdfRenderer } from '@microscope-js/renderer-pdf';
+
+const registry = createRegistry([pdfRenderer]);
+const handle = await mount({
+  source: file,
+  container: document.getElementById('viewer')!,
+  registry,
+});
+// later...
+handle.destroy();
+```
+
+## Defining a renderer
+
+```ts
+import type { Renderer } from '@microscope-js/core';
+
+export const myRenderer: Renderer = {
+  id: 'myformat',
+  name: 'My Format',
+  mimes: ['application/x-myformat'],
+  extensions: ['myf'],
+  async render({ source, container, signal }) {
+    // ... mount into container, listen to signal for cancellation
+    return {
+      destroy() { /* clean up */ },
+    };
+  },
+};
+```
+
+Renderers are pure values — no class instantiation, no global state. The registry handles matching by MIME + extension, with custom `canRender` overrides for byte-sniffing renderers.

package/dist/index.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+var utils = require('@microscope-js/utils');
+
+// src/registry.ts
+function createRegistry(renderers) {
+  const entries = renderers.map(
+    (r, i) => "renderer" in r ? r : { renderer: r, priority: i }
+  );
+  const byId = /* @__PURE__ */ new Map();
+  for (const { renderer } of entries) {
+    byId.set(renderer.id, renderer);
+  }
+  return {
+    entries,
+    get(id) {
+      return byId.get(id) ?? null;
+    },
+    async match(source) {
+      const ext = utils.extOf(source.name);
+      const mime = source.mime;
+      const candidates = [];
+      for (const entry of entries) {
+        const r = entry.renderer;
+        if (r.canRender) {
+          const ok = await r.canRender(source);
+          if (ok) candidates.push(entry);
+          continue;
+        }
+        if (claimsByMeta(r, mime, ext)) candidates.push(entry);
+      }
+      if (candidates.length === 0) return null;
+      candidates.sort((a, b) => b.priority - a.priority);
+      return candidates[0]?.renderer ?? null;
+    }
+  };
+}
+function claimsByMeta(r, mime, ext) {
+  if (mime) {
+    for (const m of r.mimes) {
+      if (utils.mimeMatches(mime, m)) return true;
+    }
+  }
+  if (ext && r.extensions.includes(ext)) return true;
+  return false;
+}
+function composeRegistries(...regs) {
+  const merged = [];
+  for (const r of regs) merged.push(...r.entries);
+  return createRegistry(merged);
+}
+async function mount(opts) {
+  const { source, container, registry, options, signal, t, rendererId } = opts;
+  if (!container) {
+    throw new utils.MicroscopeError("mount() requires a container element", "INVALID_SOURCE");
+  }
+  if (signal?.aborted) {
+    throw new utils.MicroscopeError("aborted before start", "ABORTED");
+  }
+  const normalized = await utils.normalizeSource(source);
+  if (!normalized.mime) {
+    normalized.mime = await utils.sniffMime(normalized.blob);
+  }
+  const renderer = rendererId ? registry.get(rendererId) : await registry.match(normalized);
+  if (!renderer) {
+    throw new utils.MicroscopeError(
+      `No renderer registered for source (mime=${normalized.mime ?? "unknown"}, name=${normalized.name ?? "unknown"})`,
+      "UNSUPPORTED"
+    );
+  }
+  utils.clearContainer(container);
+  return renderer.render({ source: normalized, container, options, signal, t });
+}
+
+Object.defineProperty(exports, "MicroscopeError", {
+  enumerable: true,
+  get: function () { return utils.MicroscopeError; }
+});
+Object.defineProperty(exports, "extOf", {
+  enumerable: true,
+  get: function () { return utils.extOf; }
+});
+Object.defineProperty(exports, "normalizeSource", {
+  enumerable: true,
+  get: function () { return utils.normalizeSource; }
+});
+Object.defineProperty(exports, "sniffMime", {
+  enumerable: true,
+  get: function () { return utils.sniffMime; }
+});
+exports.composeRegistries = composeRegistries;
+exports.createRegistry = createRegistry;
+exports.mount = mount;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/registry.ts","../src/mount.ts"],"names":["extOf","mimeMatches","MicroscopeError","normalizeSource","sniffMime","clearContainer"],"mappings":"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","file":"index.cjs","sourcesContent":["import { extOf, mimeMatches } from '@microscope-js/utils';\nimport type { Registry, RegistryEntry, Renderer } from './types.js';\n\n/**\n * Build a registry from a list of renderers. Later renderers in the list win\n * unless an explicit priority is given via `{ renderer, priority }`.\n *\n * The registry is intentionally tiny — picking a renderer is just:\n *   1. Run `canRender` overrides first (custom byte-sniffing wins).\n *   2. Otherwise match by MIME, then by extension, then by sniffed MIME.\n *   3. Highest priority wins.\n */\nexport function createRegistry(renderers: ReadonlyArray<Renderer | RegistryEntry>): Registry {\n  const entries: RegistryEntry[] = renderers.map((r, i) =>\n    'renderer' in r ? r : { renderer: r, priority: i },\n  );\n\n  const byId = new Map<string, Renderer>();\n  for (const { renderer } of entries) {\n    byId.set(renderer.id, renderer);\n  }\n\n  return {\n    entries,\n    get(id) {\n      return byId.get(id) ?? null;\n    },\n    async match(source) {\n      const ext = extOf(source.name);\n      const mime = source.mime;\n\n      // First pass — let any renderer with a custom `canRender` claim the source.\n      // This is how byte-sniffing renderers (ZIP-based formats) override MIME.\n      const candidates: RegistryEntry[] = [];\n      for (const entry of entries) {\n        const r = entry.renderer;\n        if (r.canRender) {\n          const ok = await r.canRender(source);\n          if (ok) candidates.push(entry);\n          continue;\n        }\n        if (claimsByMeta(r, mime, ext)) candidates.push(entry);\n      }\n\n      if (candidates.length === 0) return null;\n      candidates.sort((a, b) => b.priority - a.priority);\n      return candidates[0]?.renderer ?? null;\n    },\n  };\n}\n\nfunction claimsByMeta(r: Renderer, mime: string | null, ext: string | null): boolean {\n  if (mime) {\n    for (const m of r.mimes) {\n      if (mimeMatches(mime, m)) return true;\n    }\n  }\n  if (ext && r.extensions.includes(ext)) return true;\n  return false;\n}\n\n/**\n * Compose two registries — useful when an app wants its own custom renderers\n * layered on top of the default ones without losing tree-shakability.\n */\nexport function composeRegistries(...regs: ReadonlyArray<Registry>): Registry {\n  const merged: RegistryEntry[] = [];\n  for (const r of regs) merged.push(...r.entries);\n  return createRegistry(merged);\n}\n","import { MicroscopeError, clearContainer, normalizeSource, sniffMime } from '@microscope-js/utils';\nimport type { MountOptions, RenderHandle } from './types.js';\n\n/**\n * The single entry point most callers will use. Normalizes the source,\n * sniffs MIME if unknown, picks a renderer from the registry, and renders.\n *\n * Returns a handle whose `destroy()` MUST be called by the caller.\n */\nexport async function mount(opts: MountOptions): Promise<RenderHandle> {\n  const { source, container, registry, options, signal, t, rendererId } = opts;\n\n  if (!container) {\n    throw new MicroscopeError('mount() requires a container element', 'INVALID_SOURCE');\n  }\n  if (signal?.aborted) {\n    throw new MicroscopeError('aborted before start', 'ABORTED');\n  }\n\n  const normalized = await normalizeSource(source);\n  if (!normalized.mime) {\n    normalized.mime = await sniffMime(normalized.blob);\n  }\n\n  const renderer = rendererId ? registry.get(rendererId) : await registry.match(normalized);\n\n  if (!renderer) {\n    throw new MicroscopeError(\n      `No renderer registered for source (mime=${normalized.mime ?? 'unknown'}, name=${normalized.name ?? 'unknown'})`,\n      'UNSUPPORTED',\n    );\n  }\n\n  clearContainer(container);\n  return renderer.render({ source: normalized, container, options, signal, t });\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { Source, NormalizedSource } from '@microscope-js/utils';
+export { MicroscopeError, NormalizedSource, Source, extOf, normalizeSource, sniffMime } from '@microscope-js/utils';
+
+/** Runtime context handed to a Renderer when it's asked to display a source. */
+interface RenderContext {
+    /** The normalized source. Renderers receive a Blob, not the original input. */
+    source: NormalizedSource;
+    /** DOM node the renderer must mount into. It will be cleared before render. */
+    container: HTMLElement;
+    /** Per-render options forwarded to the renderer. Shape is renderer-specific. */
+    options?: Record<string, unknown>;
+    /** Cancels in-flight rendering. The renderer should clean up partial state. */
+    signal?: AbortSignal;
+    /** Translation callback for any user-facing strings (toolbar labels, errors). */
+    t?: (key: string, fallback: string) => string;
+}
+/** Handle returned to callers — destroy() is the only required capability. */
+interface RenderHandle {
+    /** Tear down: revoke object URLs, abort workers, detach listeners. */
+    destroy(): void;
+    /** Renderer-specific capabilities (zoom, navigate, fullscreen, etc.). */
+    readonly capabilities?: Readonly<Record<string, unknown>>;
+}
+/** What a Renderer reports about itself before being asked to handle anything. */
+interface RendererMeta {
+    /** Unique id — e.g. `pdf`, `image`, `docx`. */
+    id: string;
+    /** Human-readable name for UI. */
+    name: string;
+    /** MIME types this renderer claims. Supports `*` wildcards (e.g. `image/*`). */
+    mimes: ReadonlyArray<string>;
+    /** Lowercase file extensions this renderer claims (no leading dot). */
+    extensions: ReadonlyArray<string>;
+}
+/**
+ * The single interface every format implementation must satisfy.
+ * Stateless — instances are reusable across renders.
+ */
+interface Renderer extends RendererMeta {
+    /**
+     * Cheap predicate run by the registry. Defaults check MIME + extension; renderers
+     * that need byte-sniffing override this to inspect `source.bytes()`.
+     */
+    canRender?(source: NormalizedSource): boolean | Promise<boolean>;
+    /** Perform the actual render. Must throw {@link MicroscopeError} on failure. */
+    render(ctx: RenderContext): Promise<RenderHandle>;
+}
+/** Entry the registry stores internally. */
+interface RegistryEntry {
+    renderer: Renderer;
+    priority: number;
+}
+/** Input to {@link mount} — what callers actually pass. */
+interface MountOptions {
+    source: Source;
+    container: HTMLElement;
+    registry: Registry;
+    options?: Record<string, unknown>;
+    signal?: AbortSignal;
+    t?: RenderContext['t'];
+    /** Force a specific renderer by id (skips matching). */
+    rendererId?: string;
+}
+interface Registry {
+    readonly entries: ReadonlyArray<RegistryEntry>;
+    /** Pick the highest-priority renderer that claims this source, or null. */
+    match(source: NormalizedSource): Promise<Renderer | null>;
+    /** Look up a renderer by id (used when callers force-select one). */
+    get(id: string): Renderer | null;
+}
+
+/**
+ * Build a registry from a list of renderers. Later renderers in the list win
+ * unless an explicit priority is given via `{ renderer, priority }`.
+ *
+ * The registry is intentionally tiny — picking a renderer is just:
+ *   1. Run `canRender` overrides first (custom byte-sniffing wins).
+ *   2. Otherwise match by MIME, then by extension, then by sniffed MIME.
+ *   3. Highest priority wins.
+ */
+declare function createRegistry(renderers: ReadonlyArray<Renderer | RegistryEntry>): Registry;
+/**
+ * Compose two registries — useful when an app wants its own custom renderers
+ * layered on top of the default ones without losing tree-shakability.
+ */
+declare function composeRegistries(...regs: ReadonlyArray<Registry>): Registry;
+
+/**
+ * The single entry point most callers will use. Normalizes the source,
+ * sniffs MIME if unknown, picks a renderer from the registry, and renders.
+ *
+ * Returns a handle whose `destroy()` MUST be called by the caller.
+ */
+declare function mount(opts: MountOptions): Promise<RenderHandle>;
+
+export { type MountOptions, type Registry, type RegistryEntry, type RenderContext, type RenderHandle, type Renderer, type RendererMeta, composeRegistries, createRegistry, mount };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Source, NormalizedSource } from '@microscope-js/utils';
+export { MicroscopeError, NormalizedSource, Source, extOf, normalizeSource, sniffMime } from '@microscope-js/utils';
+
+/** Runtime context handed to a Renderer when it's asked to display a source. */
+interface RenderContext {
+    /** The normalized source. Renderers receive a Blob, not the original input. */
+    source: NormalizedSource;
+    /** DOM node the renderer must mount into. It will be cleared before render. */
+    container: HTMLElement;
+    /** Per-render options forwarded to the renderer. Shape is renderer-specific. */
+    options?: Record<string, unknown>;
+    /** Cancels in-flight rendering. The renderer should clean up partial state. */
+    signal?: AbortSignal;
+    /** Translation callback for any user-facing strings (toolbar labels, errors). */
+    t?: (key: string, fallback: string) => string;
+}
+/** Handle returned to callers — destroy() is the only required capability. */
+interface RenderHandle {
+    /** Tear down: revoke object URLs, abort workers, detach listeners. */
+    destroy(): void;
+    /** Renderer-specific capabilities (zoom, navigate, fullscreen, etc.). */
+    readonly capabilities?: Readonly<Record<string, unknown>>;
+}
+/** What a Renderer reports about itself before being asked to handle anything. */
+interface RendererMeta {
+    /** Unique id — e.g. `pdf`, `image`, `docx`. */
+    id: string;
+    /** Human-readable name for UI. */
+    name: string;
+    /** MIME types this renderer claims. Supports `*` wildcards (e.g. `image/*`). */
+    mimes: ReadonlyArray<string>;
+    /** Lowercase file extensions this renderer claims (no leading dot). */
+    extensions: ReadonlyArray<string>;
+}
+/**
+ * The single interface every format implementation must satisfy.
+ * Stateless — instances are reusable across renders.
+ */
+interface Renderer extends RendererMeta {
+    /**
+     * Cheap predicate run by the registry. Defaults check MIME + extension; renderers
+     * that need byte-sniffing override this to inspect `source.bytes()`.
+     */
+    canRender?(source: NormalizedSource): boolean | Promise<boolean>;
+    /** Perform the actual render. Must throw {@link MicroscopeError} on failure. */
+    render(ctx: RenderContext): Promise<RenderHandle>;
+}
+/** Entry the registry stores internally. */
+interface RegistryEntry {
+    renderer: Renderer;
+    priority: number;
+}
+/** Input to {@link mount} — what callers actually pass. */
+interface MountOptions {
+    source: Source;
+    container: HTMLElement;
+    registry: Registry;
+    options?: Record<string, unknown>;
+    signal?: AbortSignal;
+    t?: RenderContext['t'];
+    /** Force a specific renderer by id (skips matching). */
+    rendererId?: string;
+}
+interface Registry {
+    readonly entries: ReadonlyArray<RegistryEntry>;
+    /** Pick the highest-priority renderer that claims this source, or null. */
+    match(source: NormalizedSource): Promise<Renderer | null>;
+    /** Look up a renderer by id (used when callers force-select one). */
+    get(id: string): Renderer | null;
+}
+
+/**
+ * Build a registry from a list of renderers. Later renderers in the list win
+ * unless an explicit priority is given via `{ renderer, priority }`.
+ *
+ * The registry is intentionally tiny — picking a renderer is just:
+ *   1. Run `canRender` overrides first (custom byte-sniffing wins).
+ *   2. Otherwise match by MIME, then by extension, then by sniffed MIME.
+ *   3. Highest priority wins.
+ */
+declare function createRegistry(renderers: ReadonlyArray<Renderer | RegistryEntry>): Registry;
+/**
+ * Compose two registries — useful when an app wants its own custom renderers
+ * layered on top of the default ones without losing tree-shakability.
+ */
+declare function composeRegistries(...regs: ReadonlyArray<Registry>): Registry;
+
+/**
+ * The single entry point most callers will use. Normalizes the source,
+ * sniffs MIME if unknown, picks a renderer from the registry, and renders.
+ *
+ * Returns a handle whose `destroy()` MUST be called by the caller.
+ */
+declare function mount(opts: MountOptions): Promise<RenderHandle>;
+
+export { type MountOptions, type Registry, type RegistryEntry, type RenderContext, type RenderHandle, type Renderer, type RendererMeta, composeRegistries, createRegistry, mount };

package/dist/index.js

@@ -0,0 +1,76 @@
+import { extOf, mimeMatches, MicroscopeError, normalizeSource, sniffMime, clearContainer } from '@microscope-js/utils';
+export { MicroscopeError, extOf, normalizeSource, sniffMime } from '@microscope-js/utils';
+
+// src/registry.ts
+function createRegistry(renderers) {
+  const entries = renderers.map(
+    (r, i) => "renderer" in r ? r : { renderer: r, priority: i }
+  );
+  const byId = /* @__PURE__ */ new Map();
+  for (const { renderer } of entries) {
+    byId.set(renderer.id, renderer);
+  }
+  return {
+    entries,
+    get(id) {
+      return byId.get(id) ?? null;
+    },
+    async match(source) {
+      const ext = extOf(source.name);
+      const mime = source.mime;
+      const candidates = [];
+      for (const entry of entries) {
+        const r = entry.renderer;
+        if (r.canRender) {
+          const ok = await r.canRender(source);
+          if (ok) candidates.push(entry);
+          continue;
+        }
+        if (claimsByMeta(r, mime, ext)) candidates.push(entry);
+      }
+      if (candidates.length === 0) return null;
+      candidates.sort((a, b) => b.priority - a.priority);
+      return candidates[0]?.renderer ?? null;
+    }
+  };
+}
+function claimsByMeta(r, mime, ext) {
+  if (mime) {
+    for (const m of r.mimes) {
+      if (mimeMatches(mime, m)) return true;
+    }
+  }
+  if (ext && r.extensions.includes(ext)) return true;
+  return false;
+}
+function composeRegistries(...regs) {
+  const merged = [];
+  for (const r of regs) merged.push(...r.entries);
+  return createRegistry(merged);
+}
+async function mount(opts) {
+  const { source, container, registry, options, signal, t, rendererId } = opts;
+  if (!container) {
+    throw new MicroscopeError("mount() requires a container element", "INVALID_SOURCE");
+  }
+  if (signal?.aborted) {
+    throw new MicroscopeError("aborted before start", "ABORTED");
+  }
+  const normalized = await normalizeSource(source);
+  if (!normalized.mime) {
+    normalized.mime = await sniffMime(normalized.blob);
+  }
+  const renderer = rendererId ? registry.get(rendererId) : await registry.match(normalized);
+  if (!renderer) {
+    throw new MicroscopeError(
+      `No renderer registered for source (mime=${normalized.mime ?? "unknown"}, name=${normalized.name ?? "unknown"})`,
+      "UNSUPPORTED"
+    );
+  }
+  clearContainer(container);
+  return renderer.render({ source: normalized, container, options, signal, t });
+}
+
+export { composeRegistries, createRegistry, mount };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/registry.ts","../src/mount.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { extOf, mimeMatches } from '@microscope-js/utils';\nimport type { Registry, RegistryEntry, Renderer } from './types.js';\n\n/**\n * Build a registry from a list of renderers. Later renderers in the list win\n * unless an explicit priority is given via `{ renderer, priority }`.\n *\n * The registry is intentionally tiny — picking a renderer is just:\n *   1. Run `canRender` overrides first (custom byte-sniffing wins).\n *   2. Otherwise match by MIME, then by extension, then by sniffed MIME.\n *   3. Highest priority wins.\n */\nexport function createRegistry(renderers: ReadonlyArray<Renderer | RegistryEntry>): Registry {\n  const entries: RegistryEntry[] = renderers.map((r, i) =>\n    'renderer' in r ? r : { renderer: r, priority: i },\n  );\n\n  const byId = new Map<string, Renderer>();\n  for (const { renderer } of entries) {\n    byId.set(renderer.id, renderer);\n  }\n\n  return {\n    entries,\n    get(id) {\n      return byId.get(id) ?? null;\n    },\n    async match(source) {\n      const ext = extOf(source.name);\n      const mime = source.mime;\n\n      // First pass — let any renderer with a custom `canRender` claim the source.\n      // This is how byte-sniffing renderers (ZIP-based formats) override MIME.\n      const candidates: RegistryEntry[] = [];\n      for (const entry of entries) {\n        const r = entry.renderer;\n        if (r.canRender) {\n          const ok = await r.canRender(source);\n          if (ok) candidates.push(entry);\n          continue;\n        }\n        if (claimsByMeta(r, mime, ext)) candidates.push(entry);\n      }\n\n      if (candidates.length === 0) return null;\n      candidates.sort((a, b) => b.priority - a.priority);\n      return candidates[0]?.renderer ?? null;\n    },\n  };\n}\n\nfunction claimsByMeta(r: Renderer, mime: string | null, ext: string | null): boolean {\n  if (mime) {\n    for (const m of r.mimes) {\n      if (mimeMatches(mime, m)) return true;\n    }\n  }\n  if (ext && r.extensions.includes(ext)) return true;\n  return false;\n}\n\n/**\n * Compose two registries — useful when an app wants its own custom renderers\n * layered on top of the default ones without losing tree-shakability.\n */\nexport function composeRegistries(...regs: ReadonlyArray<Registry>): Registry {\n  const merged: RegistryEntry[] = [];\n  for (const r of regs) merged.push(...r.entries);\n  return createRegistry(merged);\n}\n","import { MicroscopeError, clearContainer, normalizeSource, sniffMime } from '@microscope-js/utils';\nimport type { MountOptions, RenderHandle } from './types.js';\n\n/**\n * The single entry point most callers will use. Normalizes the source,\n * sniffs MIME if unknown, picks a renderer from the registry, and renders.\n *\n * Returns a handle whose `destroy()` MUST be called by the caller.\n */\nexport async function mount(opts: MountOptions): Promise<RenderHandle> {\n  const { source, container, registry, options, signal, t, rendererId } = opts;\n\n  if (!container) {\n    throw new MicroscopeError('mount() requires a container element', 'INVALID_SOURCE');\n  }\n  if (signal?.aborted) {\n    throw new MicroscopeError('aborted before start', 'ABORTED');\n  }\n\n  const normalized = await normalizeSource(source);\n  if (!normalized.mime) {\n    normalized.mime = await sniffMime(normalized.blob);\n  }\n\n  const renderer = rendererId ? registry.get(rendererId) : await registry.match(normalized);\n\n  if (!renderer) {\n    throw new MicroscopeError(\n      `No renderer registered for source (mime=${normalized.mime ?? 'unknown'}, name=${normalized.name ?? 'unknown'})`,\n      'UNSUPPORTED',\n    );\n  }\n\n  clearContainer(container);\n  return renderer.render({ source: normalized, container, options, signal, t });\n}\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@microscope-js/core",
+  "version": "0.1.0",
+  "description": "Framework-agnostic core for microscope-js: Renderer interface + registry + mount() entry point",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@microscope-js/utils": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}