@volter/dawproject 0.5.67

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Volter AI, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,32 @@
+# @volter/dawproject
+
+A piece of music as a React component. The elements are DAWproject's (the open
+interchange format Bitwig and PreSonus publish): `Project`, `Transport`, `Track`,
+`Channel`, `Send`, `Device`, `Clip`, `Note`, `Marker`, `Points`, `Point`. A
+reconciler (`render.ts`, the shape of `@pixi/react`) mounts the component into a
+plain graph, and `readPiece` (`piece.ts`) reads the graph as a piece. Nothing in
+a piece imports anything but this package and its own modules.
+
+```tsx
+<Track name="Flute">
+  <Channel volume={-3} pan={0.15}>
+    <Device plugin="soundfont" params={{ bank: BANK, program: 73 }} />
+    <Send to="Hall" level={-14} />
+  </Channel>
+  <Clip at="1" bars={8}>
+    <Note at="1:1" pitch="F#5" dur="h" vel={0.6} />
+    <Note at="1:3" pitch="E5" dur="q" artic="legato" />
+  </Clip>
+</Track>
+```
+
+Written units (`notation.ts`): `at` is an absolute `bar:beat`, `pitch` a note
+name, `dur` a note value (`w h q 8 16 32`, dots, `t` for triplets). A `<Clip>`
+takes `at` and `bars`; the transport takes `tempo` and `meter`.
+
+`perform(piece)` (`perform.ts`) is the one performance both the editor's
+preview and the export play: the tempo map (`<Points target="tempo">`, beats to
+seconds), articulations, controller lanes sampled into events, and the
+`humanize` device's seeded drift.
+
+Apache-2.0. A piece carries this package when it ships.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@volter/dawproject",
+  "author": "Volter AI, Inc.",
+  "license": "Apache-2.0",
+  "version": "0.5.67",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "A piece of music as React elements named for DAWproject's own model (Project, Transport, Track, Channel, Device, Clip, Note, Marker), and the renderer that mounts one into a plain graph.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/dawproject"
+  },
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "react-reconciler": "0.31.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+/**
+ * A PIECE OF MUSIC IS A REACT COMPONENT whose elements are DAWproject's own model
+ * (github.com/bitwig/dawproject, `Project.xsd`) — the same nouns — written in a composer's
+ * units (`./notation`): positions as `bar:beat`, pitches as note names, lengths as note values.
+ * A piece imports these and nothing of the editor:
+ *
+ * ```tsx
+ * import { Channel, Clip, Device, Note, Project, Track, Transport } from '@volter/dawproject';
+ *
+ * export default function Theme() {
+ *   return (
+ *     <Project>
+ *       <Transport tempo={96} meter="4/4" />
+ *       <Track name="Lead">
+ *         <Channel volume={-6} pan={0} />
+ *         <Clip at="1" bars={2}>
+ *           <Note at="1:1" pitch="E4" dur="q" vel={0.8} />
+ *           <Note at="1:2.5" pitch="F#4" dur="8" />
+ *         </Clip>
+ *       </Track>
+ *     </Project>
+ *   );
+ * }
+ * ```
+ *
+ * Positions are ABSOLUTE bars of the piece; a clip is a region of the arrangement, and every
+ * note inside it states the bar it sounds in.
+ *
+ * Each export is the element's TYPE NAME, a string, so the elements carry no identity of
+ * this module: the renderer (`./render`) recognizes them by name wherever the piece's copy
+ * of this package was resolved from. DAWproject's `Note` spells its key `key`, which React
+ * reserves, so the note name is `pitch`.
+ */
+
+import type { FC, ReactNode } from 'react';
+
+/** A position in the piece: `bar` or `bar:beat`, both counted from 1 (`9:2.5`). */
+export type Position = string;
+/** A note value: `w h q 8 16 32`, dots, `t` for a triplet; or a number of quarter-note beats. */
+export type Length = string | number;
+
+export interface ProjectProps {
+  readonly children?: ReactNode;
+}
+
+/** DAWproject `Transport`: `Tempo` in BPM and `TimeSignature` as `n/d` (default `4/4`). */
+export interface TransportProps {
+  readonly tempo: number;
+  readonly meter?: string;
+  /** A tempo lane: `<Points target="tempo">`. */
+  readonly children?: ReactNode;
+}
+
+/** DAWproject `Track`: a named lane that owns a channel and its clips. */
+export interface TrackProps {
+  readonly name: string;
+  readonly color?: string;
+  readonly children?: ReactNode;
+}
+
+/**
+ * DAWproject `Channel`: the mixer strip. `volume` is in decibels, `pan` in −1…1. `role` is the
+ * schema's: `regular` (a track's own strip, the default), `effect` (a bus other channels send to,
+ * such as a reverb), `submix` (a group track's strip: the tracks inside that `<Track>` sum into
+ * it), or `master` (the one strip everything ends in).
+ */
+export interface ChannelProps {
+  readonly role?: 'regular' | 'effect' | 'master' | 'submix';
+  readonly volume?: number;
+  readonly pan?: number;
+  readonly mute?: boolean;
+  readonly solo?: boolean;
+  readonly children?: ReactNode;
+}
+
+/** DAWproject `Send`: this channel feeds the `effect` channel of the track named `to`, at `level` dB. */
+export interface SendProps {
+  readonly to: string;
+  readonly level: number;
+  /** Taken before the fader (`pre`) rather than after it (the default). */
+  readonly pre?: boolean;
+}
+
+/** A device parameter: a number, a string, a switch, or a list of them (an equaliser's bands). */
+export type DeviceParam =
+  | number
+  | string
+  | boolean
+  | readonly Readonly<Record<string, number | string | boolean>>[]
+  | Readonly<Record<string, number>>;
+
+/**
+ * DAWproject `Device`: an instrument or effect on a channel, named by its plugin. The built-in
+ * effects take the schema's own device types: `equalizer` (`bands`: `{ type: 'highPass' | 'lowPass'
+ * | 'lowShelf' | 'highShelf' | 'bell', freq, gain?, q? }`), `compressor` (`threshold`, `ratio`,
+ * `attack`, `release`, `knee`, `makeup`), `limiter` (`ceiling`, `release`), and `convolution`
+ * (`ir`: a project path to an impulse response WAV, `predelay` ms, `wet` 0–1).
+ *
+ * The instrument is `soundfont` (`bank`: a project path to an .sf2/.sf3, `program`, `bankNumber`,
+ * `drums`). Its `articulations` maps a note's `artic` to the program in the same bank that plays
+ * it, where the bank records that articulation apart (`{ staccato: 101, pizzicato: 102 }`): a
+ * note with a mapped `artic` sounds on that patch, every other note on `program`.
+ */
+export interface DeviceProps {
+  readonly plugin: string;
+  readonly name?: string;
+  /** The plugin's own parameters, by the plugin's own names. */
+  readonly params?: Readonly<Record<string, DeviceParam>>;
+}
+
+/** DAWproject `Clip`: a region of a track's timeline, from bar `at` for `bars` bars. */
+export interface ClipProps {
+  readonly at: Position;
+  readonly bars: number;
+  readonly name?: string;
+  readonly children?: ReactNode;
+}
+
+/**
+ * DAWproject `Note`: a note name at a position for a length. `vel` and `rel` are 0…1. `artic` is
+ * how it is played: `staccato`, `staccatissimo`, `tenuto`, `accent`, `marcato` or `legato`, or a
+ * technique a sampled instrument records apart, `pizzicato` or `tremolo`. A soundfont device's
+ * `articulations` names the patch that plays each (see `DeviceProps`).
+ */
+export interface NoteProps {
+  readonly at: Position;
+  readonly pitch: string;
+  readonly dur: Length;
+  readonly vel?: number;
+  readonly rel?: number;
+  readonly artic?: 'staccato' | 'staccatissimo' | 'tenuto' | 'accent' | 'marcato' | 'legato' | 'pizzicato' | 'tremolo';
+}
+
+/**
+ * DAWproject `Points`: an automation lane. In a `<Clip>`, `target` is a MIDI controller
+ * (`cc1` modulation, `cc11` expression, `cc64` sustain, …) or `pitchbend`, with values 0–1
+ * (pitch bend −1…1). In `<Transport>`, `target="tempo"` and values are BPM.
+ */
+export interface PointsProps {
+  readonly target: string;
+  readonly children?: ReactNode;
+}
+
+/** A point on a lane. Values move linearly to the next point unless the point `hold`s. */
+export interface PointProps {
+  readonly at: Position;
+  readonly value: number;
+  readonly hold?: boolean;
+}
+
+/** DAWproject `Marker`: a named point on the arrangement's timeline. */
+export interface MarkerProps {
+  readonly at: Position;
+  readonly name: string;
+}
+
+function element<P>(name: string): FC<P> {
+  return name as unknown as FC<P>;
+}
+
+export const Project = element<ProjectProps>('dawproject.Project');
+export const Transport = element<TransportProps>('dawproject.Transport');
+export const Track = element<TrackProps>('dawproject.Track');
+export const Channel = element<ChannelProps>('dawproject.Channel');
+export const Send = element<SendProps>('dawproject.Send');
+export const Device = element<DeviceProps>('dawproject.Device');
+export const Clip = element<ClipProps>('dawproject.Clip');
+export const Note = element<NoteProps>('dawproject.Note');
+export const Marker = element<MarkerProps>('dawproject.Marker');
+export const Points = element<PointsProps>('dawproject.Points');
+export const Point = element<PointProps>('dawproject.Point');
+
+/** Every element this package names, keyed by its short name. */
+export const ELEMENT_TYPES = {
+  Project: 'dawproject.Project',
+  Transport: 'dawproject.Transport',
+  Track: 'dawproject.Track',
+  Channel: 'dawproject.Channel',
+  Send: 'dawproject.Send',
+  Device: 'dawproject.Device',
+  Clip: 'dawproject.Clip',
+  Note: 'dawproject.Note',
+  Marker: 'dawproject.Marker',
+  Points: 'dawproject.Points',
+  Point: 'dawproject.Point',
+} as const;
+
+export type ElementName = keyof typeof ELEMENT_TYPES;
+
+/** The written units' spellings, for code that generates notes (`at={formatAt(beat, 4)}`). */
+export { beatAt, beatsOf, formatAt, formatDuration, formatPitch, midiOf } from './notation';

package/src/notation.ts

@@ -0,0 +1,107 @@
+/**
+ * THE WRITTEN UNITS a piece is authored in: positions as `bar:beat`, pitches as note names,
+ * lengths as note values, meter as `n/d`. These are a composer's units and the ones a language
+ * model writes with the fewest slips (a format experiment on one brief: first drafts in these
+ * units carried about 17 voice-leading faults against 24–27 in beats and MIDI numbers). The
+ * reader (`piece.ts`) turns them into beats and MIDI keys; the editor writes them back with
+ * `formatAt`, `formatPitch` and `formatDuration`, so a gesture leaves the spelling a person reads.
+ *
+ * Positions are ABSOLUTE: `9:2.5` is the second half of beat 2 of bar 9 of the piece, wherever
+ * the note's clip starts. A clip is a region of the arrangement, not a second bar count.
+ */
+
+const LETTER: Record<string, number> = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 };
+const SHARP_NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
+const FLAT_NAMES = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'];
+
+/** `C4` = 60 (scientific pitch); accidentals `#`, `b`, `##`, `bb`. */
+export function midiOf(name: string): number {
+  const match = /^([A-Ga-g])(##|bb|#|b)?(-?\d)$/.exec(name.trim());
+  if (!match) throw new Error(`Not a note name: "${name}" (write it like F#5, Bb3, C4)`);
+  const [, letter = 'C', accidental = '', octave = '4'] = match;
+  const shift = accidental === '#' ? 1 : accidental === '##' ? 2 : accidental === 'b' ? -1 : accidental === 'bb' ? -2 : 0;
+  return (Number(octave) + 1) * 12 + (LETTER[letter.toUpperCase()] ?? 0) + shift;
+}
+
+/** A MIDI key as a note name, spelled with flats when `flats` (a key on the flat side). */
+export function formatPitch(midi: number, flats = false): string {
+  const names = flats ? FLAT_NAMES : SHARP_NAMES;
+  return `${names[((midi % 12) + 12) % 12]}${Math.floor(midi / 12) - 1}`;
+}
+
+/** Whether a written pitch uses a flat: a gesture keeps the spelling family it found. */
+export function spelledFlat(name: string): boolean {
+  return /^[A-Ga-g]b/.test(name.trim());
+}
+
+const VALUE: Record<string, number> = { w: 4, h: 2, q: 1, '8': 0.5, '16': 0.25, '32': 0.125 };
+
+/**
+ * A note value in quarter-note beats: `w h q 8 16 32`, a dot per `.` (`q.` = 1.5), `t` for a
+ * triplet (`8t` = 1/3). A plain positive number is beats (`2.5`, for a tie across values).
+ */
+export function beatsOf(value: string | number): number {
+  if (typeof value === 'number') {
+    if (value > 0 && Number.isFinite(value)) return value;
+    throw new Error(`Not a length: ${value}`);
+  }
+  const match = /^(w|h|q|8|16|32)(t?)(\.*)$/.exec(value.trim());
+  if (!match) {
+    const number = Number(value);
+    if (Number.isFinite(number) && number > 0) return number;
+    throw new Error(`Not a note value: "${value}" (w h q 8 16 32, a dot per ".", t for triplet, or beats)`);
+  }
+  const [, base = 'q', triplet = '', dots = ''] = match;
+  let beats = VALUE[base] ?? 1;
+  if (triplet) beats = (beats * 2) / 3;
+  let add = beats;
+  for (let i = 0; i < dots.length; i++) {
+    add /= 2;
+    beats += add;
+  }
+  return beats;
+}
+
+/** Beats as the plainest note value that spells them exactly, else the number of beats. */
+export function formatDuration(beats: number): string {
+  const candidates: [string, number][] = [];
+  for (const base of ['w', 'h', 'q', '8', '16', '32']) {
+    for (const dots of ['', '.', '..']) {
+      candidates.push([`${base}${dots}`, beatsOf(`${base}${dots}`)]);
+    }
+    candidates.push([`${base}t`, beatsOf(`${base}t`)]);
+  }
+  const exact = candidates.find(([, value]) => Math.abs(value - beats) < 1e-9);
+  return exact ? exact[0] : String(Math.round(beats * 1e6) / 1e6);
+}
+
+/** Quarter-note beats per bar: `4/4` → 4, `3/4` → 3, `6/8` → 3. */
+export function beatsPerBarOf(meter: string): number {
+  const match = /^(\d+)\/(\d+)$/.exec(meter.trim());
+  if (!match) throw new Error(`Not a meter: "${meter}" (write it like 3/4)`);
+  return (Number(match[1]) * 4) / Number(match[2]);
+}
+
+/** `bar` or `bar:beat` (1-based; the beat may be fractional) to beats from the piece's start. */
+export function beatAt(position: string | number, beatsPerBar: number): number {
+  const text = String(position).trim();
+  const match = /^(\d+)(?::(\d+(?:\.\d+)?))?$/.exec(text);
+  if (!match) throw new Error(`Not a position: "${text}" (write bar:beat, like 9:2.5)`);
+  const bar = Number(match[1]);
+  const beat = match[2] === undefined ? 1 : Number(match[2]);
+  if (bar < 1 || beat < 1 || beat >= beatsPerBar + 1 - 1e-9) {
+    throw new Error(`"${text}" is not in a ${beatsPerBar}-beat bar (bars and beats count from 1)`);
+  }
+  return (bar - 1) * beatsPerBar + (beat - 1);
+}
+
+/**
+ * Beats from the piece's start as `bar:beat`. A note always spells its beat (`9:1`); a clip or
+ * marker on a downbeat is just its bar (`bar: true` → `9`).
+ */
+export function formatAt(beats: number, beatsPerBar: number, options: { readonly bar?: boolean } = {}): string {
+  const rounded = Math.round(beats * 1e6) / 1e6;
+  const bar = Math.floor(rounded / beatsPerBar + 1e-9) + 1;
+  const beat = Math.round((rounded - (bar - 1) * beatsPerBar + 1) * 1e6) / 1e6;
+  return options.bar && beat === 1 ? String(bar) : `${bar}:${beat}`;
+}

package/src/perform.ts

@@ -0,0 +1,206 @@
+/**
+ * THE PERFORMANCE: what a piece's written notes become when played. One pure function, read by
+ * the editor's engine and by the export alike, so the two can never disagree about what sounds:
+ *
+ *   - the TEMPO MAP (`<Points target="tempo">` in `<Transport>`): beats to seconds, linear ramps
+ *     between points unless a point holds;
+ *   - ARTICULATIONS (`artic` on a note): staccato, staccatissimo, tenuto, accent, marcato and
+ *     legato shape length and velocity; every note keeps its `artic`, so an instrument that
+ *     records one apart (`articulations` on its device) plays it on that patch;
+ *   - CONTROLLER LANES (`<Points target="cc11">` in a clip): sampled into controller events;
+ *   - HUMANISING (`<Device plugin="humanize">` on a channel): seeded, so every render is the same,
+ *     and CORRELATED (a slow random walk, not independent jitter per note), because a player who is
+ *     late stays late for a while and listeners prefer that (Hennig et al., PLoS ONE 2011);
+ *   - the same pitch struck again while it still sounds cuts the earlier note just before, so the
+ *     second note is not choked by the first one's release (a sampler trap music-engine measured).
+ *
+ * Nothing here is invented for a piece: every value comes from its source.
+ */
+
+import type { Piece, PiecePoints } from './piece';
+
+export interface PerformedNote {
+  readonly track: string;
+  /** The written start, in beats: which section a note belongs to (`start` may drift across it). */
+  readonly beat: number;
+  readonly start: number;
+  readonly end: number;
+  readonly pitch: number;
+  readonly velocity: number;
+  /** How it is played (`staccato`, `pizzicato`, …), or `null`. */
+  readonly artic: string | null;
+}
+
+export interface PerformedControl {
+  readonly track: string;
+  /** MIDI controller number, or `pitchbend`. */
+  readonly controller: number | 'pitchbend';
+  readonly time: number;
+  /** 0–1 for a controller; −1…1 for pitch bend. */
+  readonly value: number;
+}
+
+export interface Performance {
+  readonly notes: readonly PerformedNote[];
+  readonly controls: readonly PerformedControl[];
+  /** Seconds at a beat (the tempo map). */
+  readonly secondsAt: (beat: number) => number;
+  /** Beat at a second (its inverse). */
+  readonly beatAt: (seconds: number) => number;
+  /** Seconds the piece lasts. */
+  readonly seconds: number;
+}
+
+interface TempoSegment {
+  readonly beat: number;
+  readonly bpm: number;
+  readonly nextBeat: number;
+  readonly nextBpm: number;
+  readonly startSeconds: number;
+}
+
+/** Seconds from `from` to `from + span` beats over a tempo that moves linearly from `a` to `b` BPM. */
+function segmentSeconds(span: number, a: number, b: number, length: number): number {
+  if (span <= 0) return 0;
+  if (Math.abs(b - a) < 1e-9 || length <= 0) return (span * 60) / a;
+  // bpm(x) = a + (b - a) x / length; seconds = ∫ 60 / bpm dx
+  const k = (b - a) / length;
+  return (60 / k) * Math.log((a + k * span) / a);
+}
+
+export function tempoMap(piece: Piece): { secondsAt(beat: number): number; beatAt(seconds: number): number } {
+  const lane = piece.transport.tempoPoints;
+  const points = [...(lane?.points ?? [])].sort((x, y) => x.time - y.time);
+  if (points.length === 0 || (points[0]?.time ?? 0) > 0) points.unshift({ id: 'tempo:0', oid: null, time: 0, value: piece.transport.tempo, hold: true });
+  const segments: TempoSegment[] = [];
+  let seconds = 0;
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i]!;
+    const next = points[i + 1];
+    const nextBeat = next ? next.time : Number.POSITIVE_INFINITY;
+    const nextBpm = next && !point.hold ? next.value : point.value;
+    segments.push({ beat: point.time, bpm: point.value, nextBeat, nextBpm, startSeconds: seconds });
+    if (next) seconds += segmentSeconds(next.time - point.time, point.value, nextBpm, next.time - point.time);
+  }
+  const secondsAt = (beat: number): number => {
+    let segment = segments[0]!;
+    for (const candidate of segments) if (candidate.beat <= beat) segment = candidate;
+    const length = Number.isFinite(segment.nextBeat) ? segment.nextBeat - segment.beat : 0;
+    return segment.startSeconds + segmentSeconds(beat - segment.beat, segment.bpm, segment.nextBpm, length);
+  };
+  const beatAt = (target: number): number => {
+    let low = 0;
+    let high = 1;
+    while (secondsAt(high) < target) high *= 2;
+    for (let i = 0; i < 60; i++) {
+      const middle = (low + high) / 2;
+      if (secondsAt(middle) < target) low = middle;
+      else high = middle;
+    }
+    return (low + high) / 2;
+  };
+  return { secondsAt, beatAt };
+}
+
+/** Deterministic PRNG (mulberry32): the same seed gives the same performance. */
+function random(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** A slow, bounded random walk sampled per note: correlated drift, not jitter. */
+function drift(seed: number, count: number, amount: number): number[] {
+  const next = random(seed);
+  const out: number[] = [];
+  let value = 0;
+  for (let i = 0; i < count; i++) {
+    value = value * 0.8 + (next() * 2 - 1) * 0.45;
+    out.push(Math.max(-1, Math.min(1, value)) * amount);
+  }
+  return out;
+}
+
+const ARTICULATION: Record<string, { length: number; velocity: number; overlap?: number }> = {
+  staccato: { length: 0.5, velocity: 0.05 },
+  staccatissimo: { length: 0.25, velocity: 0.08 },
+  tenuto: { length: 1, velocity: 0.03 },
+  accent: { length: 0.9, velocity: 0.15 },
+  marcato: { length: 0.75, velocity: 0.22 },
+  legato: { length: 1, velocity: 0, overlap: 0.06 },
+  // Techniques, not shapes: written length and velocity; the patch plays them.
+  pizzicato: { length: 1, velocity: 0 },
+  tremolo: { length: 1, velocity: 0 },
+};
+
+/** Where every written note and lane of the piece sounds, in seconds. */
+export function perform(piece: Piece): Performance {
+  const { secondsAt, beatAt } = tempoMap(piece);
+  const notes: PerformedNote[] = [];
+  const controls: PerformedControl[] = [];
+  for (const track of piece.tracks) {
+    const humanize = track.channel?.devices.find((device) => device.plugin === 'humanize');
+    const timingMs = typeof humanize?.params['timingMs'] === 'number' ? humanize.params['timingMs'] : 0;
+    const velocityAmount = typeof humanize?.params['velocity'] === 'number' ? humanize.params['velocity'] : 0;
+    const seed = typeof humanize?.params['seed'] === 'number' ? humanize.params['seed'] : 1;
+    const written = track.clips.flatMap((clip) => clip.notes).sort((a, b) => a.start - b.start || a.pitch - b.pitch);
+    const timeDrift = drift(seed, written.length, timingMs / 1000);
+    const velocityDrift = drift(seed + 7919, written.length, velocityAmount);
+    const performed = written.map((note, index) => {
+      const shape = note.artic ? ARTICULATION[note.artic] : undefined;
+      const start = secondsAt(note.start) + (timeDrift[index] ?? 0);
+      const writtenEnd = secondsAt(note.start + note.duration);
+      const length = (writtenEnd - secondsAt(note.start)) * (shape?.length ?? 1) + (shape?.overlap ?? 0);
+      return {
+        track: track.id,
+        beat: note.start,
+        start: Math.max(0, start),
+        end: Math.max(0, start) + Math.max(0.02, length),
+        pitch: note.pitch,
+        velocity: Math.max(0.01, Math.min(1, note.vel + (shape?.velocity ?? 0) + (velocityDrift[index] ?? 0))),
+        artic: note.artic,
+      };
+    });
+    // A pitch struck again while it sounds: end the earlier note 12 ms before the new one.
+    for (let i = 0; i < performed.length; i++) {
+      for (let j = i + 1; j < performed.length; j++) {
+        const earlier = performed[i]!;
+        const later = performed[j]!;
+        if (later.start >= earlier.end) break;
+        if (later.pitch === earlier.pitch && later.start > earlier.start) {
+          performed[i] = { ...earlier, end: Math.max(earlier.start + 0.02, later.start - 0.012) };
+        }
+      }
+    }
+    notes.push(...performed);
+    for (const clip of track.clips) {
+      for (const lane of clip.lanes) controls.push(...sampleLane(track.id, lane, secondsAt));
+    }
+  }
+  const seconds = secondsAt(piece.length);
+  return { notes, controls, secondsAt, beatAt, seconds };
+}
+
+/** A lane's points as controller events: every point, plus linear steps between them (1/16 beat). */
+function sampleLane(track: string, lane: PiecePoints, secondsAt: (beat: number) => number): PerformedControl[] {
+  const controller = lane.target === 'pitchbend' ? 'pitchbend' : Number(/^cc(\d+)$/.exec(lane.target)?.[1] ?? Number.NaN);
+  if (controller !== 'pitchbend' && !Number.isInteger(controller)) return [];
+  const points = [...lane.points].sort((a, b) => a.time - b.time);
+  const out: PerformedControl[] = [];
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i]!;
+    const next = points[i + 1];
+    out.push({ track, controller, time: secondsAt(point.time), value: point.value });
+    if (!next || point.hold) continue;
+    for (let beat = point.time + 0.25; beat < next.time - 1e-9; beat += 0.25) {
+      const t = (beat - point.time) / (next.time - point.time);
+      out.push({ track, controller, time: secondsAt(beat), value: point.value + (next.value - point.value) * t });
+    }
+  }
+  return out;
+}

package/src/piece.ts

@@ -0,0 +1,277 @@
+/**
+ * THE PIECE, READ: a mounted graph ({@link DawNode}) as the arrangement a DAW shows. Tracks
+ * with their channel, devices and clips; clips with their notes; transport and markers. Times
+ * stay in beats; a note's `start` is its clip's `time` plus its own.
+ *
+ * Nothing here decides what may be edited. A node carries the source element it came from
+ * (`oid`); whether a given prop of that element is a literal the editor may write is the
+ * source's answer, read at the element (the editor's source index), never guessed here. The one
+ * fact the graph itself knows is REPETITION: when one source element rendered several nodes
+ * (a `.map()`, a loop, a component used twice), those nodes share an oid, and no single one of
+ * them is that element's own.
+ */
+
+import type { DeviceParam } from './index';
+import { beatAt, beatsOf, beatsPerBarOf, midiOf } from './notation';
+import type { DawNode } from './render';
+
+export interface PieceTransport {
+  readonly tempo: number;
+  readonly numerator: number;
+  readonly denominator: number;
+  /** Quarter-note beats per bar (`6/8` → 3). */
+  readonly beatsPerBar: number;
+  readonly oid: string | null;
+  /** The tempo lane (`<Points target="tempo">`), or `null` for one tempo throughout. */
+  readonly tempoPoints: PiecePoints | null;
+}
+
+export interface PieceNote {
+  readonly id: string;
+  readonly oid: string | null;
+  /** Start in beats from the piece's start. */
+  readonly start: number;
+  /** Start in beats from its clip's start. */
+  readonly time: number;
+  readonly duration: number;
+  readonly pitch: number;
+  readonly vel: number;
+  /** How it is played (`staccato`, `legato`, …), or `null`. */
+  readonly artic: string | null;
+  /** As written: `at`, `pitch` and `dur` exactly as the source spells them. */
+  readonly written: { readonly at: string; readonly pitch: string; readonly dur: string };
+}
+
+export interface PiecePoint {
+  readonly id: string;
+  readonly oid: string | null;
+  /** Beats from the piece's start. */
+  readonly time: number;
+  readonly value: number;
+  readonly hold: boolean;
+}
+
+/**
+ * An automation lane: in a clip a controller (`cc11`) or `pitchbend`; on the transport `tempo`; on
+ * a track its mixer (`volume`, `pan`, `send:<bus>`).
+ */
+export interface PiecePoints {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly target: string;
+  readonly points: readonly PiecePoint[];
+}
+
+export interface PieceClip {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly name: string | null;
+  readonly time: number;
+  readonly duration: number;
+  readonly notes: readonly PieceNote[];
+  readonly lanes: readonly PiecePoints[];
+}
+
+export interface PieceDevice {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly plugin: string;
+  readonly name: string | null;
+  readonly params: Readonly<Record<string, DeviceParam>>;
+}
+
+export interface PieceSend {
+  readonly oid: string | null;
+  /** The name of the track whose `effect` channel this feeds. */
+  readonly to: string;
+  readonly level: number;
+  readonly pre: boolean;
+}
+
+export interface PieceChannel {
+  readonly oid: string | null;
+  /** `submix`: a group track's channel, summing the tracks it contains (DAWproject's role). */
+  readonly role: 'regular' | 'effect' | 'master' | 'submix';
+  readonly volume: number;
+  readonly pan: number;
+  readonly mute: boolean;
+  readonly solo: boolean;
+  readonly devices: readonly PieceDevice[];
+  readonly sends: readonly PieceSend[];
+}
+
+export interface PieceTrack {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly name: string;
+  readonly color: string | null;
+  readonly channel: PieceChannel | null;
+  readonly clips: readonly PieceClip[];
+  /**
+   * The track's own automation across the arrangement (`<Points>` children of `<Track>`, outside
+   * any clip): `volume` and `send:<bus>` in dB, `pan` −1…1. Points in piece time.
+   */
+  readonly lanes: readonly PiecePoints[];
+  /** The group track this one sits in (its `submix` channel sums this track), or `null`. */
+  readonly parent: string | null;
+}
+
+export interface PieceMarker {
+  readonly id: string;
+  readonly oid: string | null;
+  readonly time: number;
+  readonly name: string;
+}
+
+export interface Piece {
+  readonly transport: PieceTransport;
+  readonly tracks: readonly PieceTrack[];
+  readonly markers: readonly PieceMarker[];
+  /** The last beat any clip reaches. */
+  readonly length: number;
+  /** How many nodes each oid rendered; above 1 means the element repeats. */
+  readonly oidCounts: ReadonlyMap<string, number>;
+}
+
+function num(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+function str(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+function bool(value: unknown): boolean {
+  return value === true;
+}
+
+function countOids(node: DawNode, counts: Map<string, number>): void {
+  if (node.oid) counts.set(node.oid, (counts.get(node.oid) ?? 0) + 1);
+  for (const child of node.children) countOids(child, counts);
+}
+
+/** Read a mounted graph as a piece. Refuses a root that is not a `<Project>`. */
+export function readPiece(root: DawNode): Piece {
+  if (root.type !== 'Project') throw new Error(`A piece's root is <Project>; this one is <${root.type}>.`);
+  const oidCounts = new Map<string, number>();
+  countOids(root, oidCounts);
+  // The transport first: every position in the piece is read against its meter.
+  const transportNode = root.children.find((node) => node.type === 'Transport');
+  const meter = str(transportNode?.props['meter']) ?? '4/4';
+  const beatsPerBar = beatsPerBarOf(meter);
+  const [numerator = 4, denominator = 4] = meter.split('/').map(Number);
+  const transport: PieceTransport = {
+    tempo: num(transportNode?.props['tempo'], 120),
+    numerator,
+    denominator,
+    beatsPerBar,
+    oid: transportNode?.oid ?? null,
+    tempoPoints: null,
+  };
+  const position = (value: unknown, where: string): number => {
+    if (typeof value !== 'string' && typeof value !== 'number') throw new Error(`${where} has no \`at\` position.`);
+    return beatAt(value, beatsPerBar);
+  };
+  const readLane = (node: DawNode, id: string, where: string): PiecePoints => ({
+    id,
+    oid: node.oid,
+    target: str(node.props['target']) ?? '',
+    points: node.children
+      .filter((point) => point.type === 'Point')
+      .map((point, index) => ({
+        id: `${id}:point:${index}`,
+        oid: point.oid,
+        time: position(point.props['at'], `A <Point> in ${where}`),
+        value: num(point.props['value'], 0),
+        hold: bool(point.props['hold']),
+      })),
+  });
+  const tempoNode = transportNode?.children.find((node) => node.type === 'Points' && node.props['target'] === 'tempo');
+  const withTempo: PieceTransport = tempoNode ? { ...transport, tempoPoints: readLane(tempoNode, 'transport:tempo', '<Transport>') } : transport;
+  const tracks: PieceTrack[] = [];
+  const markers: PieceMarker[] = [];
+  let length = 0;
+  /**
+   * A track, and (after it) every track it contains: a group's children sum into its strip, the
+   * group's channel `role="submix"`. `parent` is the group track's id.
+   */
+  const readTrack = (node: DawNode, trackId: string, parent: string | null): void => {
+    const trackName = str(node.props['name']) ?? `Track ${tracks.length + 1}`;
+    let channel: PieceChannel | null = null;
+    const clips: PieceClip[] = [];
+    const trackLanes: PiecePoints[] = [];
+    node.children.forEach((child, childIndex) => {
+      if (child.type === 'Channel') {
+        const role = str(child.props['role']);
+        channel = {
+          oid: child.oid,
+          role: role === 'effect' || role === 'master' || role === 'submix' ? role : 'regular',
+          sends: child.children
+            .filter((send) => send.type === 'Send')
+            .map((send) => ({ oid: send.oid, to: str(send.props['to']) ?? '', level: num(send.props['level'], 0), pre: bool(send.props['pre']) })),
+          volume: num(child.props['volume'], 0),
+          pan: num(child.props['pan'], 0),
+          mute: bool(child.props['mute']),
+          solo: bool(child.props['solo']),
+          devices: child.children
+            .filter((device) => device.type === 'Device')
+            .map((device, deviceIndex) => ({
+              id: `${trackId}:device:${deviceIndex}`,
+              oid: device.oid,
+              plugin: str(device.props['plugin']) ?? '',
+              name: str(device.props['name']),
+              params: (device.props['params'] ?? {}) as Record<string, DeviceParam>,
+            })),
+        };
+      } else if (child.type === 'Clip') {
+        const clipId = `${trackId}:clip:${childIndex}`;
+        const clipName = str(child.props['name']);
+        const where = `<Clip${clipName ? ` "${clipName}"` : ''}> on ${trackName}`;
+        const time = position(child.props['at'], where);
+        const duration = num(child.props['bars'], 0) * beatsPerBar;
+        const notes: PieceNote[] = child.children
+          .filter((note) => note.type === 'Note')
+          .map((note, noteIndex) => {
+            const writtenPitch = String(note.props['pitch'] ?? '');
+            const writtenDur = note.props['dur'];
+            const start = position(note.props['at'], `A <Note> in ${where}`);
+            return {
+              id: `${clipId}:note:${noteIndex}`,
+              oid: note.oid,
+              start,
+              time: start - time,
+              duration: beatsOf(typeof writtenDur === 'number' ? writtenDur : String(writtenDur ?? '')),
+              pitch: midiOf(writtenPitch),
+              vel: num(note.props['vel'], 0.7),
+              artic: str(note.props['artic']),
+              written: { at: String(note.props['at'] ?? ''), pitch: writtenPitch, dur: String(writtenDur ?? '') },
+            };
+          });
+        const lanes = child.children
+          .filter((lane) => lane.type === 'Points')
+          .map((lane, laneIndex) => readLane(lane, `${clipId}:lane:${laneIndex}`, where));
+        length = Math.max(length, time + duration);
+        clips.push({ id: clipId, oid: child.oid, name: clipName, time, duration, notes, lanes });
+      } else if (child.type === 'Points') {
+        trackLanes.push(readLane(child, `${trackId}:lane:${childIndex}`, `<Track "${trackName}">`));
+      }
+    });
+    tracks.push({ id: trackId, oid: node.oid, name: trackName, color: str(node.props['color']), channel, clips, lanes: trackLanes, parent });
+    for (const [childIndex, child] of node.children.entries()) {
+      if (child.type === 'Track') readTrack(child, `${trackId}/track:${childIndex}`, trackId);
+    }
+  };
+  root.children.forEach((node, index) => {
+    if (node.type === 'Marker') {
+      markers.push({ id: `marker:${index}`, oid: node.oid, time: position(node.props['at'], 'A <Marker>'), name: str(node.props['name']) ?? '' });
+    } else if (node.type === 'Track') {
+      readTrack(node, `track:${index}`, null);
+    }
+  });
+  return { transport: withTempo, tracks, markers, length, oidCounts };
+}
+
+/** Seconds per beat at the piece's tempo (a constant tempo; tempo automation is not read yet). */
+export function secondsPerBeat(piece: Piece): number {
+  return 60 / piece.transport.tempo;
+}

package/src/render.ts

@@ -0,0 +1,240 @@
+/**
+ * THE RENDERER: mounts a piece (a React component of `@volter/dawproject` elements) into a
+ * plain graph of {@link DawNode}s, the way `@pixi/react` mounts a world into Pixi containers.
+ * The graph is plain data, so it crosses any realm and any worker unchanged.
+ *
+ * The editor stamps every JSX element of a project module with its source address (`data-oid`,
+ * `@volter/editor-react`'s transform, in the editor's served graph only). The stamp arrives here
+ * as an ordinary prop; each node keeps it as {@link DawNode.oid} and drops it from `props`, so a
+ * node knows the exact source element it came from. A standalone render has no stamps and every
+ * `oid` is `null`.
+ *
+ * The host config is `@pixi/react`'s shape (react-reconciler 0.31 on React 19): mutation mode,
+ * no text, no suspense, and every commit publishes a fresh snapshot to the root's listeners.
+ */
+
+import type { ComponentType, ReactNode } from 'react';
+import { createElement } from 'react';
+import Reconciler from 'react-reconciler';
+import { ConcurrentRoot, DefaultEventPriority } from 'react-reconciler/constants.js';
+
+export const OID_PROP = 'data-oid';
+const TYPE_PREFIX = 'dawproject.';
+
+export interface DawNode {
+  /** The element's short name: `Project`, `Track`, `Clip`, `Note`, … */
+  readonly type: string;
+  readonly props: Readonly<Record<string, unknown>>;
+  /** The source element this node was rendered from, or `null` outside the editor. */
+  readonly oid: string | null;
+  readonly children: readonly DawNode[];
+}
+
+interface Instance {
+  type: string;
+  props: Record<string, unknown>;
+  oid: string | null;
+  children: Instance[];
+}
+
+interface Container {
+  children: Instance[];
+  onCommit: () => void;
+}
+
+function ownProps(props: Record<string, unknown>): { props: Record<string, unknown>; oid: string | null } {
+  const out: Record<string, unknown> = {};
+  let oid: string | null = null;
+  for (const [key, value] of Object.entries(props)) {
+    if (key === 'children') continue;
+    if (key === OID_PROP) {
+      oid = typeof value === 'string' ? value : null;
+      continue;
+    }
+    out[key] = value;
+  }
+  return { props: out, oid };
+}
+
+function shortType(type: string): string {
+  if (!type.startsWith(TYPE_PREFIX)) {
+    throw new Error(
+      `<${type}> is not a DAWproject element. A piece renders only @volter/dawproject's elements (Project, Transport, Track, Channel, Device, Clip, Note, Marker) and components made of them.`,
+    );
+  }
+  return type.slice(TYPE_PREFIX.length);
+}
+
+function remove<T>(list: T[], item: T): void {
+  const index = list.indexOf(item);
+  if (index >= 0) list.splice(index, 1);
+}
+
+function insert<T>(list: T[], item: T, before: T): void {
+  remove(list, item);
+  const index = list.indexOf(before);
+  list.splice(index < 0 ? list.length : index, 0, item);
+}
+
+let currentUpdatePriority = 0;
+
+const reconciler = Reconciler({
+  isPrimaryRenderer: false,
+  noTimeout: -1,
+  NotPendingTransition: null,
+  supportsHydration: false,
+  supportsMutation: true,
+  supportsPersistence: false,
+  warnsIfNotActing: false,
+  createInstance(type: string, props: Record<string, unknown>): Instance {
+    const { props: own, oid } = ownProps(props);
+    return { type: shortType(type), props: own, oid, children: [] };
+  },
+  createTextInstance(text: string): never {
+    throw new Error(`A piece renders elements, not text ("${text}").`);
+  },
+  appendInitialChild(parent: Instance, child: Instance) {
+    parent.children.push(child);
+  },
+  appendChild(parent: Instance, child: Instance) {
+    remove(parent.children, child);
+    parent.children.push(child);
+  },
+  appendChildToContainer(container: Container, child: Instance) {
+    remove(container.children, child);
+    container.children.push(child);
+  },
+  insertBefore(parent: Instance, child: Instance, before: Instance) {
+    insert(parent.children, child, before);
+  },
+  insertInContainerBefore(container: Container, child: Instance, before: Instance) {
+    insert(container.children, child, before);
+  },
+  removeChild(parent: Instance, child: Instance) {
+    remove(parent.children, child);
+  },
+  removeChildFromContainer(container: Container, child: Instance) {
+    remove(container.children, child);
+  },
+  clearContainer(container: Container) {
+    container.children.length = 0;
+  },
+  commitUpdate(instance: Instance, _type: string, _old: Record<string, unknown>, next: Record<string, unknown>) {
+    const { props, oid } = ownProps(next);
+    instance.props = props;
+    instance.oid = oid;
+  },
+  finalizeInitialChildren: () => false,
+  shouldSetTextContent: () => false,
+  getRootHostContext: () => ({}),
+  getChildHostContext: (parent: object) => parent,
+  getPublicInstance: (instance: Instance) => instance,
+  prepareForCommit: () => null,
+  resetAfterCommit(container: Container) {
+    container.onCommit();
+  },
+  preparePortalMount() {},
+  scheduleTimeout: setTimeout,
+  cancelTimeout: clearTimeout,
+  getCurrentUpdatePriority: () => currentUpdatePriority,
+  setCurrentUpdatePriority(priority: number) {
+    currentUpdatePriority = priority;
+  },
+  resolveUpdatePriority: () => currentUpdatePriority || DefaultEventPriority,
+  getInstanceFromNode: () => null,
+  getInstanceFromScope: () => null,
+  beforeActiveInstanceBlur() {},
+  afterActiveInstanceBlur() {},
+  prepareScopeUpdate() {},
+  detachDeletedInstance() {},
+  hideInstance() {},
+  unhideInstance() {},
+  hideTextInstance() {},
+  unhideTextInstance() {},
+  maySuspendCommit: () => false,
+  preloadInstance: () => true,
+  startSuspendingCommit() {},
+  suspendInstance() {},
+  waitForCommitToBeReady: () => null,
+  resetFormInstance() {},
+  requestPostPaintCallback() {},
+  shouldAttemptEagerTransition: () => false,
+  trackSchedulerEvent() {},
+  resolveEventType: () => null,
+  resolveEventTimeStamp: () => -1.1,
+  rendererPackageName: '@volter/dawproject',
+  rendererVersion: '0.5.67',
+} as never);
+
+function snapshot(instance: Instance): DawNode {
+  return {
+    type: instance.type,
+    props: { ...instance.props },
+    oid: instance.oid,
+    children: instance.children.map(snapshot),
+  };
+}
+
+export interface PieceRoot {
+  /** The latest committed graph: the piece's single root element, or `null` before the first commit. */
+  readonly current: () => DawNode | null;
+  /** Re-render with a new component (the same module re-imported after an edit). */
+  readonly render: (piece: ComponentType) => Promise<DawNode>;
+  /** Called after every commit, including updates the piece makes itself (state, effects). */
+  readonly subscribe: (listener: (graph: DawNode | null) => void) => () => void;
+  readonly unmount: () => void;
+}
+
+/** Mount a piece. Resolves once the first commit has produced its graph. */
+export function createPieceRoot(onError: (error: unknown) => void = console.error): PieceRoot {
+  const listeners = new Set<(graph: DawNode | null) => void>();
+  let latest: DawNode | null = null;
+  const container: Container = {
+    children: [],
+    onCommit() {
+      const roots = container.children;
+      if (roots.length > 1) {
+        onError(new Error(`A piece renders one <Project>; this one rendered ${roots.length} root elements.`));
+      }
+      latest = roots[0] ? snapshot(roots[0]) : null;
+      for (const listener of listeners) listener(latest);
+    },
+  };
+  // react-reconciler 0.31's runtime takes ten arguments (the three error callbacks are new in
+  // React 19); the installed `@types/react-reconciler` still declares the older eight.
+  const createContainer = reconciler.createContainer as unknown as (
+    ...args: unknown[]
+  ) => ReturnType<typeof reconciler.createContainer>;
+  const fiberRoot = createContainer(
+    container,
+    ConcurrentRoot,
+    null,
+    false,
+    null,
+    '',
+    onError,
+    onError,
+    onError,
+    null,
+  );
+  const render = (piece: ComponentType): Promise<DawNode> =>
+    new Promise((resolve, reject) => {
+      const element: ReactNode = createElement(piece);
+      reconciler.updateContainer(element, fiberRoot, null, () => {
+        if (latest) resolve(latest);
+        else reject(new Error('The piece rendered nothing; its default export returns a <Project>.'));
+      });
+    });
+  return {
+    current: () => latest,
+    render,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    unmount() {
+      reconciler.updateContainer(null, fiberRoot, null, () => undefined);
+      listeners.clear();
+    },
+  };
+}