omni-viewer-core 0.22.0 → 0.24.0

package/README.md

@@ -12,20 +12,25 @@ models, viewers mount into a DOM element, and everything host-specific
 
 ## Supported formats
 
-- **Documents** — PDF, Word (DOCX and legacy DOC), HWP, PowerPoint (PPTX and
+- **Documents** — Plain text (.txt), PDF, Word (DOCX and legacy DOC), HWP, PowerPoint (PPTX and
   legacy PPT), HTML, Markdown, Jupyter Notebook (.ipynb), EPUB e-books (2 and 3),
-  LaTeX (structure and math preview, not typesetting)
+  LaTeX (structure and math preview, not typesetting), OpenDocument (ODT/ODP)
 - **Data & spreadsheets** — Excel, CSV/TSV, JSON, JSONL/NDJSON, YAML, TOML, XML,
   Parquet, Arrow IPC / Feather V2 (.arrow/.feather), Avro, HDF5, MATLAB MAT, NumPy (NPY/NPZ), Safetensors, GGUF, ONNX, TFLite/LiteRT,
   Keras (.keras and legacy .h5), Core ML (.mlmodel and .mlpackage),
   OpenVINO IR (.xml + .bin), PyTorch Export (.pt2), ExecuTorch (.pte), Protocol
   Buffers, ReqIF, SQLite
-- **Web & network** — HAR (HTTP Archive) request logs
+- **Email, web & network** — EML and Outlook MSG email messages, HAR (HTTP Archive) request logs,
+  OpenAPI / Swagger API documents (JSON/YAML)
+- **Developer tooling** — JUnit XML test reports, SARIF 2.1.0, CycloneDX JSON
+  SBOMs, Chrome Trace Event JSON
+- **Medical imaging** — DICOM (.dcm/.dicom), native grayscale/RGB image preview,
+  multi-frame navigation, windowing and metadata inspection
 - **Media & graphics** — audio (waveform/spectrogram), video, images,
-  Photoshop PSD, fonts (TTF/OTF/WOFF)
+  Photoshop PSD, fonts (TTF/OTF/WOFF), 3D meshes (GLB/glTF/STL/OBJ)
 - **Engineering & automotive** — CAN DBC, AUTOSAR ARXML, ASAM A2L, Vector
-  ASC/BLF logs, ASAM MDF 4 (MF4), PCAP/PCAPNG, ROS bag, STEP (STP)
-- **Diagrams & GIS** — Mermaid, PlantUML, ESRI Shapefile, GeoJSON
+  ASC/BLF logs, ASAM MDF 4 (MF4), PCAP/PCAPNG, ROS bag, MCAP (.mcap), STEP (STP)
+- **Diagrams & GIS** — Mermaid, PlantUML, draw.io, ESRI Shapefile, GeoJSON, GPX, KML and KMZ
 - **Archives** — ZIP-family listing and safe entry preview
 
 The HTML viewer handles `.html` and `.htm` files with preview and source tabs.
@@ -34,6 +39,50 @@ navigation removed or blocked; inline styles and embedded data images remain.
 Files over 8 MiB show a bounded source preview. Very dense markup opens in
 source view to keep parsing responsive.
 
+### Plain text (.txt)
+
+`omni-viewer-core/viewers/text` provides a dependency-free, read-only text
+viewer. Whitespace, tabs and line endings are preserved; HTML and Markdown
+remain literal text. Soft line wrapping can be toggled without changing the
+content. UTF-8 is the default; UTF-8 and UTF-16 LE/BE BOMs are recognized.
+For BOM-less UTF-16, pass `parse: { encoding: 'utf-16le' }` (or `'utf-16be'`).
+Legacy encodings such as CP949 are not automatically detected. Malformed
+Unicode bytes are displayed as replacement characters with a visible warning;
+UTF-32 BOMs are rejected.
+
+```ts
+import { mountTextViewer } from 'omni-viewer-core/viewers/text';
+
+const handle = await mountTextViewer(
+  { fileName: 'notes.txt', data: bytes }, container, hostContext
+);
+// On file switch or tab close:
+handle.dispose();
+```
+
+The DOM-free parser is available at `omni-viewer-core/parsers/text` as
+`parseText(bytes, options)`. The default input limit is 256 MiB and the decoded
+preview budget is 8 MiB (excluding the BOM); larger previews are visibly marked
+as partial. Override them through `limits.maxInputBytes` / `maxPreviewBytes`
+(under `parse.limits` for the viewer). Incomplete characters at a preview
+boundary are omitted without an encoding warning. Decoding limits are
+cooperative; hosts still own file loading and hard CPU/memory bounds.
+Scoped hosts load `omni-viewer-core/styles/text.css`; shadow mode injects it.
+
+The registry returns `viewerId: 'text'` for `.txt` (including uppercase `.TXT`).
+Hosts must register that extension and explicitly map `text` to
+`mountTextViewer`; the registry does not load viewers. Other extensions and
+extensionless text retain their existing detection behavior.
+
+### DICOM (.dcm/.dicom)
+
+`omni-viewer-core/viewers/dicom` provides a dependency-free native 8/16-bit DICOM
+preview with frame navigation, window center/width, inversion, zoom, and a
+searchable metadata table. Implicit/explicit VR little endian and explicit VR
+big endian are supported. Compressed images keep metadata available and report
+that preview is unavailable. See [DICOM support and limits](examples/dicom/SUPPORT.md)
+and the [offline synthetic example](examples/dicom/README.md).
+
 ## Install
 
 ```sh
@@ -74,6 +123,156 @@ Viewers follow the same pattern — a `mount*Viewer(input, container, ctx,
 deps)` entry per format, plus `self-loading` variants that dynamically import
 their own dependencies for hosts that don't want to wire them manually.
 
+### Read-only file previews
+
+| Viewer ID | Parser / mount | Preview |
+| --- | --- | --- |
+| `sarif` | `parseSarif` / `mountSarifViewer` | Result severity, rule, tool and source locations |
+| `gps` | `parseGps` / `mountGpsViewer` | Offline GPX/KML/KMZ map and GPX track statistics |
+| `trace` | `parseTrace` / `mountTraceViewer` | Chrome Trace Event JSON timeline with search and zoom |
+| `sbom` | `parseSbom` / `mountSbomViewer` | CycloneDX components, licenses and direct dependencies |
+| `msg` | `parseMsg` / `mountMsgViewer` | Outlook message headers, text/HTML and file attachments |
+| `drawio` | `parseDrawio` / `mountDrawioViewer` | Compressed or plain diagrams, basic shapes, connectors and layers |
+| `opendocument` | `parseOpenDocument` / `mountOpenDocumentViewer` | ODT structure and basic ODP slide layout |
+
+Import each from `omni-viewer-core/parsers/<id>` or
+`omni-viewer-core/viewers/<id>`. Register the extensions and map the viewer IDs
+to their mount functions in the host. Scoped mounts use
+`omni-viewer-core/styles/file-preview.css`; the GPS map also uses
+`omni-viewer-core/styles/geojson.css`. Deflated KMZ, OpenDocument and draw.io
+content uses the runtime’s raw deflate `DecompressionStream` or a bounded
+`inflate` function supplied by the host.
+
+When `detectViewer` receives a text sample, it also routes `.json` and
+extensionless SARIF 2.1.0, CycloneDX and Trace Event JSON to `sarif`, `sbom`
+and `trace`, and `.xml` and extensionless namespaced GPX/KML and draw.io XML to
+`gps` and `drawio`. Extensionless KMZ, ODT/ODP and Outlook MSG are recognized by
+`probeContainer`. A `.msg` file must be an OLE compound file, so plain-text
+`.msg` files (ROS messages, Tcl catalogs) keep their previous routing.
+
+The GPS map draws geometry without basemap tiles and skips KML network links
+and overlays. The trace preview supports complete, begin/end and instant events.
+The MSG preview reads ordinary attachments and displays a diagnostic for
+embedded messages or RTF-only bodies. draw.io approximates advanced styles
+with basic shapes. OpenDocument previews text structure and basic slide layout.
+Each preview reports records omitted because of resource limits.
+
+### OpenAPI / Swagger (JSON / YAML)
+
+Open Swagger 2.0 and OpenAPI 3.0–3.2 specifications with searchable API
+documentation, HTTP method/tag filters, parameter and request/response schemas,
+examples, authentication definitions and an original-source tab.
+
+```ts
+import { mountSelfLoadingOpenApiViewer } from 'omni-viewer-core/viewers/openapi/self-loading';
+
+const handle = await mountSelfLoadingOpenApiViewer(
+  { fileName: 'openapi.yaml', data: bytes }, container, hostContext
+);
+handle.dispose();
+```
+
+JSON needs no external library. YAML uses the optional `yaml` 2.8.3 peer;
+base parser/viewer entries accept injected `yamlDeps`, and the opt-in
+`/self-loading` entries load it for YAML. The registry refines generic
+JSON/YAML to OpenAPI when file content matches; ordinary files retain their
+existing viewers. Pass complete text plus `{ yamlDeps }` as `detectViewer`'s
+sixth argument for strict YAML detection. Without it, conservative block YAML
+signatures are recognized and validated when mounted.
+
+Local references, Swagger definitions and parameter inheritance are supported.
+The viewer runs offline and renders descriptions as text. Exports include
+`parsers/openapi`, `viewers/openapi`, their `/self-loading` entries and
+`styles/openapi.css`. See the [viewer contract](docs/viewers/openapi.md) and
+[runnable examples](examples/openapi/README.md) for integration and limits.
+
+### 3D meshes (GLB / glTF / STL / OBJ)
+
+Install `three` (`^0.180.0`) and, for TypeScript projects, `@types/three`
+(`^0.180.0`). The viewer provides orbit/pan/zoom, fit to view, wireframe,
+grid/axes, mesh statistics, glTF materials and animation playback.
+
+```ts
+import { mountSelfLoadingMeshViewer } from 'omni-viewer-core/viewers/mesh/self-loading';
+
+const handle = await mountSelfLoadingMeshViewer(
+    { fileName: 'model.glb', data: bytes }, container, hostContext
+);
+// On file switch or tab close:
+handle.dispose();
+```
+
+For injected runtimes, use `mountMeshViewer(input, container, ctx, deps, options)`
+from `viewers/mesh`; `loadMeshViewerDeps()` supplies the standard Three.js deps.
+`parsers/mesh` offers DOM-free `parseMesh(bytes, { fileName, limits })`
+preflight without loading Three.js. It validates structure, coordinates, resource
+paths and budgets; scene decoding happens when mounted.
+
+Self-contained GLB and embedded glTF need no asset service. For `.gltf` with
+external `.bin` or textures, provide `ctx.documentAssets.resolve(relativePath)`;
+each returned asset's `dispose()` is called when the viewer closes. Input URLs,
+absolute paths and parent traversal are rejected; the core never resolves them
+against the page URL. Hosts must cap external asset sizes as well as the main
+input. OBJ geometry, UVs and normals are supported; MTL libraries use default
+materials with a warning. OBJ line and point primitives are omitted with a
+warning. Compressed glTF requires host-provided decoders via
+`deps.configureGltfLoader`; the core never downloads them. Rendering requires
+WebGL 2. Scoped hosts should load `styles/mesh.css`; shadow mode injects it.
+
+glTF preflight also budgets generated accessors, animation arrays, skeletons,
+instancing and morph storage. Generated GPU storage uses conservative estimates
+to cover device-dependent padding before rendering.
+
+Run `npm run build`, serve the repo root, and open `examples/mesh/` for a
+standalone example with sample files in all four formats and local file loading.
+
+### MCAP (.mcap)
+
+Inspect topics/channels, schemas, sampled messages, metadata, attachments and
+chunks in MCAP v0 recordings. The viewer includes topic filtering, search,
+pagination, text/hex payload inspection and JSON copy. JSON payloads are
+formatted when complete; CDR, Protobuf and other binary payloads are shown as
+raw bytes. Attachments are listed without extracting or executing their data.
+
+```ts
+import { mountSelfLoadingMcapViewer } from 'omni-viewer-core/viewers/mcap/self-loading';
+
+const handle = await mountSelfLoadingMcapViewer(
+    { fileName: 'robot.mcap', data: bytes }, container, ctx,
+    { parse: { previewMessages: 5_000 } }
+);
+// On close: handle.dispose();
+```
+
+Install the existing optional peers `lz4js` and `fzstd` to read compressed
+chunks with the self-loading entry. Uncompressed recordings need no peers.
+The base `parsers/mcap` and `viewers/mcap` entries import no runtime peers:
+`parseMcap(bytes, { decompressLz4?, decompressZstd? }, parseOptions)` and
+`mountMcapViewer(input, container, ctx, deps?, mountOptions?)` accept injected
+bounded decoders (the optional third argument limits decoder history bytes).
+Injected decoders may throw `McapDecompressionLimitError` to report resource
+limits separately from malformed input.
+`parsers/mcap/self-loading` exports `parseSelfLoadingMcap`
+and `loadMcapDeps`. Missing/unknown codecs leave a partial document with any
+available summary statistics and schemas. Incomplete scans display lower-bound
+counts when exact summary counts are unavailable.
+
+Defaults: 256 MiB input and cumulative chunk bytes, 1,000,000 records/map entries,
+5,000 retained messages, 4 KiB per payload/schema preview and an 8 MiB cumulative
+preview budget. Structural encoding identifiers are read independently of the
+preview budget (up to 16 KiB). Zstd frame content sizes and history windows are
+checked before decoding; history uses the configured chunk byte limit.
+Search/copy operate on retained samples; totals include every
+scanned message. Uint64 values remain decimal strings and timestamps display
+exact seconds relative to the recording's epoch. Chunk, data-section and summary
+CRCs are checked when present; attachment payload CRCs are not checked. Limits
+are cooperative; hosts can use a Worker for hard CPU/memory bounds. The viewer
+supports shadow/scoped isolation and `styles/mcap.css`. Detection recognizes
+the `.mcap` extension and binary magic, including extensionless recordings.
+Host adapters must add `mcap` to their explicit viewer import maps.
+
+The binary reader follows the [MCAP format specification](https://mcap.dev/spec).
+
 ### Fonts (TTF / OTF / WOFF)
 
 Preview local fonts with editable sample text, size and variable axis controls,
@@ -489,6 +688,46 @@ returns `partial` with diagnostics. Invalid JSON and unsupported major versions
 return typed failures. See [viewer details](examples/notebook/README.md) and the
 [sample notebook](examples/notebook/analysis.ipynb).
 
+### EML email (.eml)
+
+The EML viewer displays decoded subjects, sender/recipient fields, dates,
+plain-text and HTML bodies, all message headers, a bounded raw-source preview,
+and attachments. It handles nested MIME messages, Base64/quoted-printable,
+encoded header words, legacy body charsets, and extended attachment filenames.
+Attached messages remain downloadable `.eml` files rather than becoming the
+parent message's body. Extensionless messages are detected conservatively.
+
+```ts
+import { mountEmlViewer } from 'omni-viewer-core/viewers/eml';
+import { createCatalogI18n } from 'omni-viewer-core/i18n';
+
+const handle = await mountEmlViewer(
+  { fileName: file.name, data: new Uint8Array(await file.arrayBuffer()) },
+  container,
+  {
+    assets: { resolveAssetUrl: async path => path },
+    i18n: createCatalogI18n('ko'),
+    logger: { log: (level, message) => console.log(level, message) },
+    // Optional: save: { saveFile: async (name, bytes, mimeType) => … },
+    // Optional: clipboard: { writeText: text => navigator.clipboard.writeText(text) }
+  }
+);
+// On file change / unmount:
+handle.dispose();
+```
+
+HTML runs in an opaque sandbox with scripts, navigation, forms, and remote
+resources blocked. Embedded `cid:` raster images render locally. Attachment
+filenames are sanitized; saving goes through the optional host `save` service.
+Copy/save controls are disabled when their host service is absent. No MIME
+dependency is required. Default parsing limits are 32 MiB input/decoded data,
+1,000 MIME parts, 32 nesting levels, and 4 MiB per body preview. Limits can be
+configured through `parseEml(bytes, options)` from `parsers/eml`.
+
+The default mount uses Shadow DOM. Scoped mounting requires
+`omni-viewer-core/styles/eml.css`. Run `npm run build`, serve the repository
+root, and open `examples/eml/` for sample messages and a local file picker.
+
 ### HAR network logs (.har)
 
 A `.har` file is the HTTP Archive a browser's network panel (or curl, Charles,
@@ -535,6 +774,46 @@ metadata get their own tabs. Routing is by the `.har` extension; an
 extensionless archive is recognized by content — a `log` object holding an
 `entries` array — and claimed before the generic JSON viewer.
 
+### JUnit XML test reports
+
+A JUnit XML report is what nearly every test runner writes for CI: Gradle's
+`build/test-results/**/TEST-*.xml`, Maven Surefire, `pytest --junitxml`,
+vitest/Jest JUnit reporters, Go and Android tooling. It is an ordinary `.xml`,
+so the generic XML viewer keeps the extension and `detectViewer` routes a file
+to `junit` only when the supplied text sample has a `<testsuites>` root, or a
+`<testsuite>` root carrying counts or a JUnit child element:
+
+```ts
+import { detectViewer } from 'omni-viewer-core/registry';
+import { mountJUnitViewer } from 'omni-viewer-core/viewers/junit';
+
+const { viewerId } = detectViewer(file.name, undefined, undefined, undefined, text);
+if (viewerId === 'junit') await mountJUnitViewer({ fileName: file.name, data: bytes }, container, { ...ctx, clipboard });
+```
+
+`parseJUnit` is a contract parser (`ParseOutcome<JUnitDocument>`) built on the
+core XML scanner, so it has no DOM dependency, never loads external entities,
+and recovers a truncated report as `partial`. It reads nested suites, test cases
+with their `failure`/`error`/`skipped` results (and Surefire's flaky/rerun
+attempts), properties, and suite or case `system-out`/`system-err`. Writers
+disagree about the declared totals, so every count is recomputed from the
+cases; declared totals that differ are reported, not trusted. A `failure` or
+`error` placed directly in a suite becomes a synthetic case so a setup error
+shows in the list.
+
+The viewer opens on the first failing test with a pass/fail verdict, an
+outcome bar and summary figures (tests, passed, failed, errors, skipped, pass
+rate, duration). The test list is filterable by status, suite subtree, and free
+text over names, classes, and messages, with an opt-in toggle that extends the
+search to stack traces and captured output. It is sortable by status severity,
+name, suite, and time. The detail pane shows each result's message, type, and
+trace, the captured output, and properties, and **Copy failure details** puts a
+plain-text report on the clipboard. A suites tab lists nested suites with
+rolled-up counts, and the source tab shows the report text. Defaults are 64 MiB
+input, 100,000 cases, 64 KiB per trace or output block, and 16 MiB of captured
+output in total. See the [viewer contract](docs/viewers/junit.md) and
+[examples](examples/junit/README.md).
+
 ### EPUB e-books (.epub)
 
 EPUB 2.0.1 and EPUB 3.x books open in a reflowable reading pane with the
@@ -582,7 +861,7 @@ stored `mimetype` member.
 ### XML (.xml and XML dialects)
 
 Configuration and integration documents (`pom.xml`, Android manifests,
-MSBuild projects, SOAP/WSDL, RSS/Atom, XLIFF, KML/GPX…) open as an
+MSBuild projects, SOAP/WSDL, RSS/Atom, XLIFF…) open as an
 element/attribute tree with a node inspector and the original source side by
 side:
 
@@ -606,8 +885,11 @@ comments and PIs, with next/previous and a matches-only filter. Copy gives the
 XPath (positions appear only where names repeat), the value, or the node's XML.
 Both panes are virtualized, and long single-line sources are split into
 display segments. Defaults are 64 MiB input, 500,000 nodes, and depth 1,000.
-ARXML and ReqIF keep their dedicated viewers by extension. An `.xml` whose root
-is an OpenVINO IR goes to the OpenVINO viewer when a text sample is provided.
+ARXML and ReqIF keep their dedicated viewers by extension, and `.gpx`/`.kml`
+open in the GPS map. When a text sample is provided, an `.xml` whose root is an
+OpenVINO IR, a JUnit test report, a namespaced GPX/KML document or a draw.io
+`<mxfile>`/`<mxGraphModel>` goes to the OpenVINO, JUnit, GPS or draw.io viewer;
+a GPX/KML root without its namespace stays on this viewer.
 
 ### Archive host integration
 

package/THIRD_PARTY_NOTICES.md

@@ -2,6 +2,17 @@
 
 This distribution includes the following third-party software.
 
+## Three.js (optional peer)
+
+- Project: Three.js (`three`)
+- Copyright: 2010-2025 three.js authors
+- License: MIT
+- Use: 3D mesh rendering, GLB/glTF/STL/OBJ loaders and orbit controls
+- Source: https://github.com/mrdoob/three.js
+
+Three.js is supplied by the consuming host; the core does not redistribute its
+runtime. Retain the upstream MIT license when bundling it in an application.
+
 ## Hugging Face GGUF parser
 
 - Project: `@huggingface/gguf` and `@huggingface/tasks`
@@ -55,3 +66,15 @@ rhwp project, used only for tests and never published to the npm package.
 - License: MIT
 - Source: https://github.com/edwardkim/rhwp (`rhwp-studio/public/samples/`,
   `samples/valign_fixtures/`)
+
+## JUnit example reports
+
+`examples/junit/jenkins-nested-testsuites.xml` and
+`examples/junit/jenkins-suite-error.xml` are unmodified test fixtures from the
+Jenkins JUnit plugin, used for examples and tests and never published to the
+npm package.
+
+- Project: jenkinsci/junit-plugin (commit `04461ad56caf19b05bc16015f23675883df83d43`)
+- Copyright: (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
+- License: MIT
+- Source: https://github.com/jenkinsci/junit-plugin/tree/04461ad56caf19b05bc16015f23675883df83d43/src/test/resources/hudson/tasks/junit

package/dist/assets/audio-engine/spectrogram_kernel.mjs

@@ -0,0 +1,256 @@
+// Spectrogram computation, DOM-free and decoder-free.
+//
+// Ported from `native/audio-engine/audio_engine.c` (`generate_spectrogram`),
+// which in turn replicates the WaveSurfer plugin's pipeline: Hann window →
+// FFT → frequency-scale filter bank → dB → 8-bit colour index. Keeping the
+// same pipeline means the windowed renderer looks like the whole-file one it
+// replaces.
+//
+// The point of doing it here rather than in the plugin is the input: this takes
+// *a window of samples*, so cost follows the viewport instead of the file. A
+// two-hour track costs the same as a ten-second one.
+const sinc = (x) => (x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x));
+/** Window coefficients. `alpha` is only consulted by blackman and gauss. */
+export function windowCoefficients(size, kind = 'hann', alpha) {
+    const out = new Float32Array(size);
+    const last = size - 1;
+    for (let i = 0; i < size; i++) {
+        switch (kind) {
+            case 'rectangular':
+                out[i] = 1;
+                break;
+            case 'hann':
+                out[i] = 0.5 * (1 - Math.cos((2 * Math.PI * i) / last));
+                break;
+            case 'hamming':
+                out[i] = 0.54 - 0.46 * Math.cos((2 * Math.PI * i) / last);
+                break;
+            case 'bartlett':
+                out[i] = (2 / last) * (last / 2 - Math.abs(i - last / 2));
+                break;
+            case 'triangular':
+                out[i] = (2 / size) * (size / 2 - Math.abs(i - last / 2));
+                break;
+            case 'bartlettHann':
+                out[i] = 0.62 - 0.48 * Math.abs(i / last - 0.5) - 0.38 * Math.cos((2 * Math.PI * i) / last);
+                break;
+            case 'blackman': {
+                const a = alpha ?? 0.16;
+                out[i] = (1 - a) / 2
+                    - 0.5 * Math.cos((2 * Math.PI * i) / last)
+                    + (a / 2) * Math.cos((4 * Math.PI * i) / last);
+                break;
+            }
+            case 'cosine':
+                out[i] = Math.cos((i * Math.PI) / last - Math.PI / 2);
+                break;
+            case 'gauss': {
+                const a = alpha ?? 0.25;
+                out[i] = Math.exp(-0.5 * ((i - last / 2) / ((a * last) / 2)) ** 2);
+                break;
+            }
+            case 'lanczoz':
+                out[i] = sinc((2 * i) / last - 1);
+                break;
+        }
+    }
+    return out;
+}
+const DEFAULT_FFT_SIZE = 1024;
+const DEFAULT_GAIN_DB = 20;
+const DEFAULT_RANGE_DB = 80;
+/** Floor for the log: silence would otherwise be -Infinity dB. */
+const MIN_MAGNITUDE = 1e-12;
+// Scale conversions, matching the plugin's own set.
+const toMel = (hz) => 2595 * Math.log10(1 + hz / 700);
+const fromMel = (mel) => 700 * (10 ** (mel / 2595) - 1);
+const toBark = (hz) => {
+    let bark = (26.81 * hz) / (1960 + hz) - 0.53;
+    if (bark < 2)
+        bark += 0.15 * (2 - bark);
+    if (bark > 20.1)
+        bark += 0.22 * (bark - 20.1);
+    return bark;
+};
+const fromBark = (bark) => {
+    let value = bark;
+    if (value < 2)
+        value = (value - 0.3) / 0.85;
+    if (value > 20.1)
+        value = (value + 4.422) / 1.22;
+    return ((value + 0.53) / (26.28 - value)) * 1960;
+};
+const toLog = (hz) => Math.log10(Math.max(1, hz));
+const fromLog = (value) => 10 ** value;
+const ERB_SCALE = (1000 * Math.LN10) / 107.939;
+const toErb = (hz) => ERB_SCALE * Math.log10(1 + 0.00437 * hz);
+const fromErb = (erb) => (10 ** (erb / ERB_SCALE) - 1) / 0.00437;
+const forward = (scale) => scale === 'mel' ? toMel : scale === 'bark' ? toBark : scale === 'erb' ? toErb
+    : scale === 'logarithmic' ? toLog : (hz) => hz;
+const inverse = (scale) => scale === 'mel' ? fromMel : scale === 'bark' ? fromBark : scale === 'erb' ? fromErb
+    : scale === 'logarithmic' ? fromLog : (value) => value;
+/**
+ * Frequency at a fraction of the height, 0 at the bottom.
+ *
+ * The axis is only readable with labels on it, and the labels have to follow
+ * whichever scale drew the picture — evenly spaced rows are far from evenly
+ * spaced hertz on mel or log.
+ */
+export function frequencyAtFraction(fraction, scale, minHz, maxHz) {
+    const toScale = forward(scale);
+    const fromScale = inverse(scale);
+    const low = toScale(Math.max(0, minHz));
+    const high = toScale(Math.max(minHz, maxHz));
+    return fromScale(low + Math.min(1, Math.max(0, fraction)) * (high - low));
+}
+/** In-place radix-2 FFT. Tables are precomputed per size and reused. */
+function createFft(size) {
+    if (size < 2 || (size & (size - 1)) !== 0)
+        throw new Error(`spectrogram: fftSize must be a power of two, got ${size}`);
+    const levels = Math.log2(size);
+    const cos = new Float32Array(size / 2);
+    const sin = new Float32Array(size / 2);
+    for (let i = 0; i < size / 2; i++) {
+        cos[i] = Math.cos((2 * Math.PI * i) / size);
+        sin[i] = Math.sin((2 * Math.PI * i) / size);
+    }
+    // Bit-reversal permutation, precomputed so the hot loop stays arithmetic.
+    const reversed = new Uint32Array(size);
+    for (let i = 0; i < size; i++) {
+        let bits = 0;
+        for (let bit = 0; bit < levels; bit++)
+            bits = (bits << 1) | ((i >>> bit) & 1);
+        reversed[i] = bits;
+    }
+    return (real, imag) => {
+        for (let i = 0; i < size; i++) {
+            const j = reversed[i];
+            if (j > i) {
+                let swap = real[i];
+                real[i] = real[j];
+                real[j] = swap;
+                swap = imag[i];
+                imag[i] = imag[j];
+                imag[j] = swap;
+            }
+        }
+        for (let span = 2; span <= size; span *= 2) {
+            const half = span / 2;
+            const step = size / span;
+            for (let start = 0; start < size; start += span) {
+                for (let i = start, k = 0; i < start + half; i++, k += step) {
+                    const pair = i + half;
+                    const tre = real[pair] * cos[k] + imag[pair] * sin[k];
+                    const tim = -real[pair] * sin[k] + imag[pair] * cos[k];
+                    real[pair] = real[i] - tre;
+                    imag[pair] = imag[i] - tim;
+                    real[i] = real[i] + tre;
+                    imag[i] = imag[i] + tim;
+                }
+            }
+        }
+    };
+}
+/** FFT tables per size. A viewport is transformed as many small batches, and
+ *  rebuilding the trig and bit-reversal tables for each one is pure overhead. */
+const fftCache = new Map();
+function fftFor(size) {
+    let fft = fftCache.get(size);
+    if (!fft) {
+        fft = createFft(size);
+        fftCache.set(size, fft);
+    }
+    return fft;
+}
+/** Where each output row samples the linear FFT bins, with the interpolation
+ *  weights between the two neighbours. */
+function filterBank(bins, fftSize, sampleRate, scale, minHz, maxHz) {
+    const toScale = forward(scale);
+    const fromScale = inverse(scale);
+    const nyquist = sampleRate / 2;
+    const low = toScale(Math.max(0, Math.min(minHz, nyquist)));
+    const high = toScale(Math.max(low, Math.min(maxHz, nyquist)));
+    const hzPerBin = sampleRate / fftSize;
+    const bank = new Array(bins);
+    for (let row = 0; row < bins; row++) {
+        const centerHz = fromScale(low + (row / bins) * (high - low));
+        const exact = centerHz / hzPerBin;
+        const lo = Math.floor(exact);
+        const frac = exact - lo;
+        bank[row] = { lo, weightLo: 1 - frac, weightHi: frac };
+    }
+    return bank;
+}
+/**
+ * Intensities for one window of interleaved-free mono samples.
+ *
+ * Channels are the caller's business: pass a single channel, or a downmix.
+ * Columns run left to right in time, rows low to high in frequency.
+ */
+export function computeSpectrogram(samples, sampleRate, options = {}) {
+    const fftSize = options.fftSize ?? DEFAULT_FFT_SIZE;
+    const hopSize = options.hopSize ?? Math.max(1, Math.floor(fftSize / 4));
+    const bins = options.bins ?? fftSize / 2;
+    const scale = options.scale ?? 'mel';
+    const gainDb = options.gainDb ?? DEFAULT_GAIN_DB;
+    const rangeDb = options.rangeDb ?? DEFAULT_RANGE_DB;
+    if (hopSize < 1)
+        throw new Error('spectrogram: hopSize must be >= 1');
+    if (bins < 1)
+        throw new Error('spectrogram: bins must be >= 1');
+    if (rangeDb <= 0)
+        throw new Error('spectrogram: rangeDb must be > 0');
+    const fft = fftFor(fftSize);
+    const columns = samples.length >= fftSize
+        ? Math.floor((samples.length - fftSize) / hopSize) + 1
+        : 0;
+    const data = new Uint8Array(Math.max(0, columns) * bins);
+    if (columns <= 0)
+        return { columns: 0, bins, data };
+    const window = windowCoefficients(fftSize, options.windowFunc ?? 'hann', options.alpha);
+    const real = new Float32Array(fftSize);
+    const imag = new Float32Array(fftSize);
+    const halfBins = fftSize / 2;
+    const magnitudes = new Float32Array(halfBins);
+    const bank = filterBank(bins, fftSize, sampleRate, scale, options.frequencyMin ?? 0, options.frequencyMax ?? sampleRate / 2);
+    const norm = 2 / fftSize;
+    // White point sits `gainDb` below full scale and `rangeDb` more reaches
+    // black. This is the WaveSurfer plugin's convention (it maps with a white
+    // point of `-gainDB`); taking `gainDb` as an absolute ceiling instead put
+    // the floor 40 dB higher and rendered ordinary material almost entirely
+    // black.
+    const whiteDb = -gainDb;
+    const floorDb = whiteDb - rangeDb;
+    for (let column = 0; column < columns; column++) {
+        const offset = column * hopSize;
+        for (let i = 0; i < fftSize; i++) {
+            real[i] = samples[offset + i] * window[i];
+            imag[i] = 0;
+        }
+        fft(real, imag);
+        for (let bin = 0; bin < halfBins; bin++) {
+            const re = real[bin];
+            const im = imag[bin];
+            magnitudes[bin] = norm * Math.sqrt(re * re + im * im);
+        }
+        const base = column * bins;
+        for (let row = 0; row < bins; row++) {
+            const { lo, weightLo, weightHi } = bank[row];
+            const hi = lo + 1;
+            let magnitude;
+            if (lo >= halfBins)
+                magnitude = MIN_MAGNITUDE;
+            else if (hi >= halfBins)
+                magnitude = magnitudes[lo] * weightLo;
+            else
+                magnitude = magnitudes[lo] * weightLo + magnitudes[hi] * weightHi;
+            if (magnitude < MIN_MAGNITUDE)
+                magnitude = MIN_MAGNITUDE;
+            const db = 20 * Math.log10(magnitude);
+            data[base + row] = db <= floorDb ? 0
+                : db >= whiteDb ? 255
+                    : Math.round(((db - floorDb) / rangeDb) * 255);
+        }
+    }
+    return { columns, bins, data };
+}

package/dist/assets/audio-engine/spectrogram_worker.mjs

@@ -0,0 +1,24 @@
+// Worker shell for the spectrogram transform. Deliberately dumb, like
+// audio_engine_worker.mjs: it owns no analysis logic, only the message
+// plumbing, because everything here is outside the TypeScript build and
+// therefore untypechecked and untested.
+//
+// The transform is the compiled `viewers/audio/spectrogram.ts`, shipped beside
+// this file as `spectrogram_kernel.mjs` (see scripts/build-styles.mjs). Its URL
+// arrives with each message rather than being resolved relative to this file:
+// adapters that serve the core from blob URLs (obsidian) have no usable
+// sibling paths.
+
+let kernelPromise;
+
+self.onmessage = async (event) => {
+    const { id, kernelUrl, samples, sampleRate, options } = event.data;
+    try {
+        kernelPromise ??= import(kernelUrl);
+        const { computeSpectrogram } = await kernelPromise;
+        const result = computeSpectrogram(samples, sampleRate, options);
+        self.postMessage({ id, ok: true, result }, [result.data.buffer]);
+    } catch (error) {
+        self.postMessage({ id, ok: false, error: String(error?.message ?? error) });
+    }
+};