@viritura/score-engine 0.0.0 → 0.1.0-next.1

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@viritura/score-engine` are documented here.
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking
+
+- `Engine` is now a type-only interface; `DisplayList` is an opaque handle.
+  Renderer types (`RenderCommand`, `PageLayout`, `MeasureBounds`, …) and the
+  `./errors`, `./timeline`, `./types` subpath exports are removed.
+- `paint()` draws ink only under the caller's transform: no clearing, no white
+  fill, no `zoom`/`scroll` options. Pass `background` for a fill.
+- `measure()` returns `pages[]` and `parts[]` (was `pageSizes`, `partIds`).
+- `beatToCanvas(dl, beat, partId)` is replaced by `positionToCanvas(dl, pos)`
+  and `playhead(dl, pos)`; geometry is page-local.
+- Part IDs are the source MNX part ID or `#<n>` (was a mismatched `p0`/`p1`).
+- `info()` returns `{ parts, measureCount, scores }`.
+
+### Added
+
+- `version`, `systems()`, `measures()`, `horizonPaper()`, `toSvg()`,
+  `createLayoutWorker()`, `createTileRenderer()`, `ink` colour.
+- `loadEngine({ textFont: false })`; default asset base next to the prebuilt bundle.
+  The default layout worker follows `assetBaseUrl`.
+- Published to npm with provenance, versioned independently of
+  `@viritura/score-viewer` and `@viritura/score-viewer-react`. Every engine
+  change on `main` also publishes a `-next.<n>` prerelease under the `next`
+  dist-tag. The
+  package ships `dist/` only: an ES module with Viritura's internal packages
+  inlined (no runtime dependencies), declarations, the layout worker, `wasm/`
+  and `fonts/`.
+- Prebuilt release archive (`pnpm build:score-engine-dist`) and CI workflow.
+
+### Fixed
+
+- Load failures reject with the underlying cause and can be retried.
+- Timeline uses real meters and honours `repeatExpansion`; no longer runs
+  schema validation (drops ~1.8 MB from bundles).
+- Text font no longer overrides the host page's generic `serif` family.
+
+## [0.0.1] — Phase 3 internal release
+
+### Added
+
+- `loadEngine(opts?)` singleton factory.
+- `Engine.layout(mnx, opts)`, `Engine.paint(ctx, dl, opts?)`,
+  `Engine.measure(dl)`, `Engine.info(mnx)`.
+- `EngineLoadError`, `ParseError`, `LayoutError` typed error classes.

package/README.md

@@ -1,3 +1,127 @@
 # @viritura/score-engine
 
-Reserved. The first real release will be published from GitHub Actions: https://github.com/Viritura/Viritura
+Framework-free music notation rendering kernel. MNX in; layout (Rust/WASM),
+ink-only Canvas painting, SVG, geometry queries and a playback timeline out.
+
+Page presentation — paper, shadows, zoom, scrolling, view modes, playhead
+chrome — belongs to [`@viritura/score-viewer`](../score-viewer) (framework-free)
+or [`@viritura/score-viewer-react`](../score-viewer-react).
+
+> **Status:** `0.x`. Breaking changes are possible before `1.0.0`; pin an
+> exact version. Public documentation:
+> [viritura.com/developers](https://viritura.com/developers).
+
+## Quick start
+
+```sh
+npm install @viritura/score-engine
+```
+
+```ts
+import { loadEngine } from "@viritura/score-engine";
+
+const engine = await loadEngine({ assetBaseUrl: "/score-engine/" });
+const dl = engine.layout(mnx, { pageWidth: 800 });
+
+const ctx = canvas.getContext("2d")!;
+ctx.fillStyle = "#fff"; // paper is yours
+ctx.fillRect(0, 0, canvas.width, canvas.height);
+engine.paint(ctx, dl, { page: 0 });
+```
+
+`pageWidth: 0` selects unpaged (horizon) layout. `pageSetup` gives explicit
+page height and margins in display-list units (CSS pixels at zoom 1).
+
+## Serving the runtime files
+
+The engine loads `wasm/`, `fonts/` and `score-engine.worker.js` at runtime
+from one base URL, which defaults to the directory of the engine module. A
+bundler moves the engine's code away from those files, so copy them from
+`node_modules/@viritura/score-engine/dist/` into your static assets and pass
+their URL as `assetBaseUrl`:
+
+```sh
+cp -r node_modules/@viritura/score-engine/dist/{wasm,fonts,score-engine.worker.js} public/score-engine/
+```
+
+See [Serving the files](https://viritura.com/developers#serving-the-files) for
+the Content Security Policy and font requirements.
+
+## Contract
+
+- **Loading.** `loadEngine({ assetBaseUrl?, textFont? })` loads WASM and fonts
+  once. Failures reject with `EngineLoadError` (`wasm` / `font`) carrying the
+  real cause, and a later call retries. Bravura is always loaded: layout uses
+  its metrics, so other music fonts are unsupported. The text face is
+  registered under the private family `Viritura Serif`, so the host page's
+  generic `serif` is untouched; `textFont: false` skips it and text falls back
+  to the page's `serif`.
+- **Opaque layouts.** `layout()` returns a `DisplayList` handle
+  (`width`, `height`, `pageCount`, `paged`). Its internals are not API.
+  `createLayoutWorker()` produces the same handles off the main thread.
+- **Ink only.** `paint(ctx, dl, { page, region, ink, background })` draws under
+  the caller's current transform (DPR, zoom, scroll) and never clears.
+  `ink` recolours default black ink (dark themes) and keeps explicit colours.
+- **Page-local geometry.** `measure`, `systems`, `measures`, `positionToCanvas`,
+  `playhead` and `canvasToBeat` use page-local coordinates (`y = 0` is the top
+  of that page). `horizonPaper` gives the paper rectangle for unpaged layouts.
+- **Stable part IDs.** Parts are identified by the source MNX `parts[n].id`, or
+  `#<n>` (0-based) when absent — the same in `info`, `measure`, geometry and
+  `timeline`.
+- **Timeline.** `timeline(mnx, { repeatExpansion })` is layout-independent and
+  deterministic, uses real meters, and expands repeats by default.
+- **SVG.** `toSvg(dl, { page, ink })` returns a standalone SVG with text and
+  glyphs as outlines.
+- **Large unpaged scores.** `createTileRenderer()` paints a viewport from
+  cached tiles.
+
+## Distribution
+
+The engine is published to npm alongside `@viritura/score-viewer` and
+`@viritura/score-viewer-react`, each versioned independently, and as a
+standalone release archive for pages without a build step.
+
+### npm
+
+`pnpm build:npm-packages` (after `pnpm wasm:build`) writes each package's
+`dist/`: an ES module with Viritura's internal workspace packages inlined,
+declarations, and (for this package) the worker, `wasm/`, `fonts/` and
+licences. `publishConfig` points the packed manifest at `dist/`, while the
+workspace keeps importing `src/`. `pnpm verify:npm-packages --render` packs
+all three, installs the tarballs into a fresh npm + Vite project and renders
+with them in headless Chromium.
+
+npm holds the released versions: the workspace manifests carry `0.0.0-dev`,
+and the viewers depend on siblings through `workspace:^`, which packs as a
+caret range.
+
+Every push to `main` that changes this package or its inputs publishes a
+prerelease `<next patch>-next.<run>` under the `next` dist-tag
+(`npm install @viritura/score-engine@next`), with provenance but no git tag
+or GitHub Release. Pin one exactly to track the engine closely; plain
+`npm install` and the viewers' caret ranges ignore prereleases.
+
+For a stable release, run **Publish npm packages**
+(`.github/workflows/npm-publish.yml`) from `main` and pick `patch`, `minor` or
+`major` for each package to release. The run bumps each selected package from
+its latest npm version (`pnpm score-release plan` shows the result locally),
+verifies them together, and publishes in dependency order with npm trusted
+publishing (no token) and provenance. Each release gets a
+`<package>-v<version>` tag and GitHub Release; the engine's carries the zip
+archive. A viewer released on its own is verified against the engine from npm,
+and the run refuses releases whose ranges would not resolve. The default
+`dry_run` does everything except upload. Keep changelog entries under
+`Unreleased` and move them under the version after a release.
+
+### Release archive
+
+`pnpm build:score-engine-dist` (after `pnpm wasm:build`) writes
+`dist/score-engine/`: ESM bundles `score-engine.js`, `score-engine.worker.js`
+and `score-viewer.js` with all workspace code inlined, declarations, `wasm/`,
+`fonts/`, licences and a `manifest.json` with the commit and SHA-256 of every
+file. The bundles find `wasm/`, `fonts/` and the worker next to themselves.
+
+CI (`.github/workflows/score-engine-dist.yml`) uploads this as a workflow
+artifact on pushes to `main` that change the bundle's inputs (the Rust engine,
+fonts, or the core/format/midi/renderer/score-engine/score-viewer packages).
+Release archives are attached to engine releases by the publish workflow.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viritura 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/dist/LICENSES/OFL-1.1.txt

@@ -0,0 +1,80 @@
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The fonts,
+including any derivative works, can be bundled, embedded, redistributed
+and/or sold with any software provided that any reserved names are not used
+by derivative works. The fonts and derivatives, however, cannot be released
+under any other type of license. The requirement for fonts to remain under
+this license does not apply to any document created using the fonts or their
+derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may include
+source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer or
+other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of the Font Software, to use, study, copy, merge, embed, modify, redistribute,
+and sell modified and unmodified copies of the Font Software, subject to the
+following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy contains
+the above copyright notice and this license. These can be included either as
+stand-alone text files, human-readable headers or in the appropriate
+machine-readable metadata fields within text or binary files as long as those
+fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font Name(s)
+unless explicit written permission is granted by the corresponding Copyright
+Holder. This restriction only applies to the primary font name as presented
+to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any Modified
+Version, except to acknowledge the contribution(s) of the Copyright Holder(s)
+and the Author(s) or with their explicit written permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must be
+distributed entirely under this license, and must not be distributed under
+any other license. The requirement for fonts to remain under this license
+does not apply to any document created using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
+INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE
+THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,95 @@
+# Third-Party Notices
+
+Viritura's MIT license applies to the original source code in this repository.
+The assets and generated components below remain under their respective terms.
+
+## Music and text fonts
+
+The following unmodified font binaries are distributed under the
+[SIL Open Font License 1.1](LICENSES/OFL-1.1.txt):
+
+| Font files                       | Copyright and source                                                                                                                                   | Reserved font name                 |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
+| `Bravura.otf`, `BravuraText.otf` | Copyright 2021 Steinberg Media Technologies GmbH. Designed by Daniel Spreadbury and contributors. [Bravura](https://github.com/steinbergmedia/bravura) | Bravura                            |
+| `LibertinusSerif-*.otf`          | Copyright 2012-2021 The Libertinus Project Authors. [Libertinus](https://github.com/alerque/libertinus)                                                | None recorded in the bundled files |
+| `Anybody-700.ttf`                | Copyright 2020 The Anybody Project Authors. [Anybody](https://github.com/Etcetera-Type-Co/Anybody)                                                     | None recorded in the bundled file  |
+| `BodoniModa-600.ttf`             | Copyright 2020 The Bodoni Moda Project Authors. [Bodoni Moda](https://github.com/indestructible-type/Bodoni)                                           | None recorded in the bundled file  |
+
+The font binaries have not been modified. Their embedded license metadata and
+copyright notices are retained. The OFL does not apply to documents or images
+created with these fonts.
+
+## SpessaSynth
+
+The browser audio worklet is generated during application development/build from the
+package-manager dependency rather than stored as a vendored bundle:
+
+- `spessasynth_lib` 4.3.1, copyright its contributors,
+  [Apache License 2.0](LICENSES/Apache-2.0.txt),
+  <https://github.com/spessasus/spessasynth_lib>
+- `spessasynth_core` 4.3.22, copyright its contributors,
+  [Apache License 2.0](LICENSES/Apache-2.0.txt),
+  <https://github.com/spessasus/spessasynth_core>
+
+`packages/audio/src/assetStaging.ts` copies the unmodified processor and source map
+from the installed `spessasynth_lib` package into Git-ignored application
+public-assets directories. The package distributions include the Apache 2.0
+license and no separate `NOTICE` file.
+
+## Denigma
+
+The Finale MUSX importer bundles a WebAssembly build of
+[Denigma](https://github.com/openmusx/denigma), distributed under the MIT
+License. Exact source revisions and artifact hashes are recorded in
+`packages/musx-import/assets/manifest.json`; the Denigma license is retained
+beside the generated assets. The package also retains the license files for the
+linked musxdom, mnxdom, smufl-mapping, pugixml, nlohmann/json,
+json-schema-validator, zlib, Emscripten, musl, and libc++ runtime dependencies,
+plus the smufl-mapping notice and Bravura-derived mapping data's SIL Open Font
+License.
+
+## SoundFont
+
+`packages/audio/assets/sounds/Shan-SGM-Pro-15.sf2` is the **Shan SGM Pro 15**
+SoundFont by Shan.
+
+- Creator reference: <https://www.youtube.com/@ShanAudioChannel>
+- SHA-256: `01ab03ff5156724c7c922fcabdb653d053ba50bd38a814756365b49e6a8c8d57`
+
+The bundled file does not contain a standard license identifier. Before a
+public release, retain the creator's explicit redistribution permission with
+the project's release records. A channel or download-page reference alone is
+not a redistribution license.
+
+## Impulse responses
+
+The five WAV files in `packages/audio/assets/sounds/ir/` come from
+[Voxengo Free Reverb Impulse Responses](https://www.voxengo.com/impulses/)
+and are distributed under the bundled
+[Voxengo impulse-response conditions](LICENSES/Voxengo-Impulse-Responses.txt):
+
+- `french-salon.wav`
+- `masonic-lodge.wav`
+- `musikvereinsaal.wav`
+- `scala-milan-opera.wav`
+- `st-nicolaes-church.wav`
+
+These files are complete and byte-identical to their entries in Voxengo's
+official `IMreverbs.zip`. Aleksey Vaneev retains exclusive ownership of the
+impulse files and all intellectual property rights in them.
+
+The Voxengo files must be removed before any paid version or paid distribution
+of Viritura. Non-paid distributions that include them must remain free of
+charge and include the copyright notice and complete conditions linked above.
+
+## Demo video
+
+Viritura can stream **Caminandes 3: Llamigos**, copyright Blender Foundation,
+from Wikimedia Commons. The video is not stored in this repository. It is used
+under [Creative Commons Attribution 3.0](https://creativecommons.org/licenses/by/3.0/).
+
+- Work page: <https://studio.blender.org/films/caminandes-3/>
+- Credit: Caminandes 3: Llamigos, Blender Foundation
+
+The source URL, license, and required attribution are also carried in
+`packages/video-sync/src/demoSources.ts` and shown with the clip.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./types/index.js";