Module @microscope-js/core

@microscope-js/core

The framework-agnostic heart of microscope-js. One Renderer interface, one Registry, one mount(). Everything else is a plugin.

Install

pnpm add @microscope-js/core @microscope-js/renderer-pdf

You almost never use core alone — pair it with one or more @microscope-js/renderer-* packages.

Use

import { createRegistry, mount } from '@microscope-js/core';
import { pdfRenderer } from '@microscope-js/renderer-pdf';
import { imageRenderer } from '@microscope-js/renderer-image';

const registry = createRegistry([pdfRenderer, imageRenderer]);

const handle = await mount({
  source: fileInput.files[0],            // File | Blob | ArrayBuffer | Uint8Array | URL | string
  container: document.getElementById('viewer')!,
  registry,
});

// later, when navigating away
handle.destroy();

mount() normalizes the source, sniffs the MIME type if needed, picks the highest-priority renderer that claims it, clears the container, and renders.

API

`createRegistry(renderers)`

Build a Registry from a list of Renderers. Later entries win by default; pass { renderer, priority } to override.

`composeRegistries(...registries)`

Merge multiple registries — useful when an app layers custom renderers on top of defaults without losing tree-shakability.

`mount(opts): Promise<RenderHandle>`

Option	Type	Description
`source`	`Source`	What to render — `File`, `Blob`, `ArrayBuffer`, `Uint8Array`, `URL`, or `string` URL
`container`	`HTMLElement`	DOM node to mount into. Cleared before render.
`registry`	`Registry`	Where to look up the renderer
`options?`	`Record<string, unknown>`	Per-render options, forwarded to the matched renderer
`signal?`	`AbortSignal`	Cancels in-flight rendering
`rendererId?`	`string`	Force-pick a renderer by id (skips matching)
`t?`	`(key, fallback) => string`	Translation hook for user-facing strings

Returns a RenderHandle with a required destroy() and optional renderer-specific capabilities (e.g. pageCount / scrollToPage from PDF, sheetNames / showSheet from XLSX).

Define your own renderer

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 }) {
    // …draw `source.blob` into `container`, honor `signal` for cancellation
    return {
      destroy() { /* clean up */ },
    };
  },
};

Renderers are plain values — no class instantiation, no global state. The registry handles matching by MIME + extension, with an optional canRender() override for byte-sniffing.

Re-exports

For convenience the core barrel also exports MicroscopeError, Source, NormalizedSource, normalizeSource, sniffMime, and extOf from @microscope-js/utils — so simple consumers don't need a second install.