@motionscript/browser 0.0.0-stage → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -0,0 +1,192 @@
+# @motionscript/browser
+
+## 0.1.0-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [d2241c3]
+- Updated dependencies [2026625]
+  - @motionscript/renderer@0.1.0-alpha.10
+
+## 0.1.0-alpha.9
+
+### Patch Changes
+
+- @motionscript/renderer@0.1.0-alpha.9
+
+## 0.1.0-alpha.8
+
+### Patch Changes
+
+- @motionscript/renderer@0.1.0-alpha.8
+
+## 0.1.0-alpha.7
+
+### Patch Changes
+
+- @motionscript/skia-render@0.1.0-alpha.7
+
+## 0.1.0-alpha.6
+
+### Minor Changes
+
+- aa75a19: A source-string node default-exports a component, and is written with calls.
+
+  - `Registry.addNodeFromSource`, `engine.registerNode(source)` and a string in `nodes` (browser and headless) take a script whose default export is a component (`export default component2d({ key: "…", … })`), not a class decorated with `@node(...)`.
+  - `DynamicNodeConfig.jsxRuntime` is gone, and browser's default compiler reads TypeScript without JSX or decorators: a script with JSX fails to compile, and one that requires `@motionscript/sdk/jsx-runtime` fails to link. The CDN build no longer imports `@motionscript/core/jsx/jsx-runtime`, so an import map need not name it.
+
+### Patch Changes
+
+- @motionscript/skia-render@0.1.0-alpha.6
+
+## 0.1.0-alpha.5
+
+### Patch Changes
+
+- da6f97a: An export's audio mix asks the host's byte source before the network.
+
+  `mixAudio`, and so `exportVideo` and `mixTimelineAudio`, fetched every audio source from the network, while previews, stills and the rest of an export read bytes through `setAssetByteSource` first. A host holding a recording locally (one not yet uploaded, or with no network) exported silence or failed where the preview played. The source is now asked with the address the catalog resolves, as `WebStorageAdapter` does, and a `null` falls through to `fetch` as before.
+
+- The headless engine can export a video across several pages at once, and an export can render a range of frames.
+
+  - `@motionscript/headless`: `renderVideo({ concurrency })` cuts the timeline into that many contiguous runs of frames, renders and encodes each in a page of its own (one Chromium, one bundle), and joins them with `concatVideoSegments` without re-encoding. Every segment gets the same codec, bitrate and hardware acceleration and begins on a key frame; the audio is mixed once over the whole timeline with `mixTimelineAudio`. The default of 1 exports in one page as before. The added pages stay open for the next export. Segments that still cannot be joined fall back to a one-page export, with the reason on stderr.
+  - `@motionscript/headless`: `renderVideo` also takes `supersample`, `codec`, `bitrate`, `hardwareAcceleration` and `includeAudio`, which reach the browser exporter, and `parseConcurrency` is exported beside the other option parsers. The page bridge has `countFrames()` and `concatSegments()`, and a bundle without them is `BRIDGE_INCOMPATIBLE`.
+  - `@motionscript/headless`: `renderVideo` sends the document into the page as its JSON text (a caller may pass the text itself), because Playwright carries a 5000-node object in about 1.4 s and its text in about 0.2 s. The page exports through `exportVideo` without opening a session, whose controller discovered every track on frame 0 only for the exporter to discover them again.
+  - `@motionscript/core`: `ExportVideoRequest` (so `session.export`) takes `frames: { start, end }`, a `FrameRange` with `end` excluded.
+  - `@motionscript/skia-render` and `@motionscript/browser`: `renderTimeline` and `exportVideo` take `frames` too. A range renders those frames alone, timestamped from 0, discovers only the tracks they touch, and is always silent: it is one segment of a split export. A range that is empty or leaves the timeline throws a `RangeError` before anything is encoded.
+
+- da6f97a: Every package ships a `NOTICE`, and a browser build lists what it bundles.
+
+  - Each tarball carries the repository `NOTICE`: the copyright line and the MIT attributions for the noise functions in `skia-render`'s fractal-noise fill (David Hoskins' "Hash without Sine", Inigo Quilez's 2D simplex noise).
+  - `@motionscript/canvaskit` ships `THIRD_PARTY_NOTICES.txt` with the licences of the libraries compiled into the binary: FreeType, HarfBuzz, ICU 74, zlib, libpng, Brotli, WOFF2, Emscripten and musl.
+  - `dist/browser/manifest.json` gains `thirdParty`, the packages the browser build bundled (`name`, `version`, `license`), and their licence and NOTICE files are written to `dist/browser/THIRD_PARTY_LICENSES.txt`. `@motionscript/browser` bundles mediabunny (MPL-2.0, unmodified; source at https://github.com/Vanilagy/mediabunny), esbuild-wasm and three; `@motionscript/math` bundles MathJax.
+
+- Updated dependencies
+- Updated dependencies [da6f97a]
+- Updated dependencies [1778355]
+- Updated dependencies
+  - @motionscript/skia-render@0.1.0-alpha.5
+
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- 158723b: **Breaking:** the engine no longer has a "scene" in its document API. Its unit is a clip document on a project track, so the names that said "scene" now say what the thing is. This is a clean break: there are no aliases and no deprecated re-exports, so update the names below.
+
+  | Before                                                   | After                        |
+  | -------------------------------------------------------- | ---------------------------- |
+  | `SceneDocument` (`StillDocument \| CompositionDocument`) | `VisualDocument`             |
+  | `SceneTimeline`                                          | `ClipTimeline`               |
+  | `SceneEffect` (the union of effects a node can carry)    | `NodeEffect`                 |
+  | `integrateSpeedToSceneTime`                              | `integrateSpeedToClipTime`   |
+  | `sourceTimeAtSceneElapsed`                               | `sourceTimeAtClipElapsed`    |
+  | `Sound.sceneDurationFor`                                 | `Sound.clipDurationFor`      |
+  | `AudioSink.syncTo(sceneTime)` (parameter name)           | `AudioSink.syncTo(clipTime)` |
+
+  `ClipDocument` is now `VisualDocument | AudioDocument`, as before. The document types, the 3D `Scene3D` and its `scene3d` settings are unchanged: that is a 3D scene, not this.
+
+  Two messages changed with the names: `assertValidDocument` now throws `Invalid clip document:` (was `Invalid scene document:`), and the JSX runtime's error for a value that is not a node class reads `JSX element must be a Node class`.
+
+  The built-in `Canvas2D`, `Provider` and `ThemeProvider` moved from `nodes/scene/` to `nodes/root/` inside core. That directory was never an export path, so no import from the package changes.
+
+- 8e9afad: One frame/time conversion and one `FrameSpec`, and fixes to browser playback and export.
+
+  - Core exports `clipFrameToTime`, `clipTimeToFrame`, `frameSpecAtTime`, `FrameSpec` and `DEFAULT_OUTPUT`. The conversion is tolerant of float error: a time within a few ulps of a whole frame is that frame. The playback controller, `Session.seek`, track placement and the evaluator all use it. Before, `currentFrame` read one frame early for 2 to 6 percent of frames (frame 123 at 60 fps), so a document swap after `seek(123)` repainted frame 122, and `trackFrameCount` gained a frame when a length on a boundary landed an ulp high (4.15 s at 60 fps counted 250, not 249).
+  - `FrameSpec` is declared once, in core, and re-exported by `@motionscript/browser` and `@motionscript/headless`; the browser's `DEFAULT_OUTPUT` and the React hook's fallback are core's defaults. The React playhead reads the frame the clock reports through the same conversion.
+  - `WebTicker` no longer stalls a looping host: the end of a run is read again after listeners and tick callbacks have run, a final tick always fires, and a finished run pauses itself. `play` is synchronous, as `Ticker.play` is typed, so a `pause` or `seek` in the same turn works; a rejected `AudioContext.resume()` pauses and logs.
+  - A supersampled export draws into a canvas that is a whole multiple of the output, so an odd-sized viewport is no longer stretched by about 1 percent.
+  - `StillRenderer.toBytes`, `toBlob` and `toDataURL` throw before any frame has been drawn onto the surface, instead of encoding blank pixels.
+
+### Patch Changes
+
+- 997dd9e: A `Video` whose file holds no audio track is a silent video, not a failed load.
+
+  - A `Video` declares its own sound for the same `src` as its picture. For a file with no audio track (a screen recording, say) the decode fails, and the asset manager reported `audio "…" could not be loaded: Unable to decode audio data`, which a host shows as its preview having stopped, and `mixAudio` rejected, which fails an export.
+  - `AudioClip` and `AudioRequest` take `optional`, and `Video` declares its clips so. A source only optional requests want is silence when it cannot be fetched or decoded: the manager says nothing and `mixAudio` leaves those requests out and renders the rest.
+  - A `sound` that names such a file is still a failure, reported once and rejecting the mix, because there the sound is the whole of what was asked for. That includes a request that starts wanting a source that had already failed quietly.
+  - A source that failed quietly is kept across a document swap instead of being fetched whole again on every edit; one that was reported is still tried afresh.
+  - `optional` is not part of a request's id.
+
+- ada534c: Fixes across 3D, audio, asset loading, the session and the JSX runtime.
+
+  - A string shader or post-effect uniform is a texture only when it looks like an asset path. A colour uniform such as `uTint: 'tomato'` made declaring the scene's assets throw `Image asset not found`.
+  - `lookAt`, a camera's `target` and a light's `target` tween with `to()`. They had no tween, so a `to` moved the other props and left these where they started. An unset `target` tweens from the origin; an unset `lookAt` holds until the end, since "do not aim" has no midpoint.
+  - A `Canvas3D` with no 3D children records an empty scene instead of a default camera and rig, so a viewport holding only 2D children skips the 3D pass and no longer creates a WebGL context.
+  - A looping `Sound` repeats its trimmed region. `AudioRequest` carries the loop's `trimEnd`, a loop with a `trimEnd` and no cut runs open instead of playing once, and the live device and the offline mix set `loopStart` and `loopEnd` to the region (a seek into the middle of a loop is folded into it too), so the trim no longer wraps the whole buffer.
+  - An audio curve's ease is part of its key. Every engine easing is an anonymous closure, so editing only an ease left the request unchanged and the device kept playing the old sound. Easings record a description, and the same ease built twice keys the same.
+  - A failed audio fetch is caught, reported once, and not started again on every sync, instead of being an unhandled rejection. A layout-gated loader is no longer disposed and loaded again when the frame leaves its window.
+  - `AssetNotLoadedError` names `assets.video(...)` for a video, `assets.loader(...)` for a loader and `declareAudio()` for audio.
+  - `Engine.setManifest` reaches a live session's controller: a font or image added after open is known to clips already built, and tracks that failed for want of it are built again. `session.replace` keeps the `fps` and `viewport` the session was opened with instead of throwing on the document it is already playing.
+  - The JSX automatic runtime keeps `key`: `<Rect key="card" />` lowers to `jsx(Rect, {}, "card")`, and `jsx` now takes the third argument.
+
+- 55a3b69: A still, a screenshot or an export refuses a font family the manifest does not describe.
+
+  - A text node naming a family with no manifest entry was shaped against the fallback face, with a console warning, and the frame was returned as if it were the document's. Described later, the same document draws differently, so a frame stored or encoded in the meantime was the wrong one. `StorageAdapter` now throws `AssetNotLoadedError` (`assetType: "font"`, `src` the family) for it when its `DecodePolicy` is `"exact"`, which every still, screenshot and export sets while it draws. Nothing is remembered of the refusal, so a renderer handed a manifest that describes the family loads it on the next render.
+  - A preview is unchanged: an undescribed family draws in the fallback face, with the warning, until a manifest describes it. The warning is no longer printed for a still or an export, which now fail instead.
+  - A text node that names no family at all is refused by `requireFontFamily`, as before.
+  - `renderImage` and `renderVideo` in `@motionscript/headless` reject with the page's error for such a document, where they used to return a frame with no text in it.
+
+- Updated dependencies [cd1c774]
+- Updated dependencies [fb0ac65]
+- Updated dependencies [217ae88]
+- Updated dependencies [cd420db]
+- Updated dependencies [848c40c]
+- Updated dependencies [7f8b4d0]
+  - @motionscript/skia-render@0.1.0-alpha.4
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- 1f00320: 3D renders its settings from the first frame, and installs itself without relying on module side effects.
+
+  - The first 3D frame of a session, and the first after an `antialias` change, drew without the scene's tone mapping, shadows or `studio` environment, because they were written before the renderer existed. The renderer is now made before a scene syncs, so the same scene gives the same pixels on every frame. `Canvas3DRendererHost` gains `prepare(three, { antialias })`, which the backend calls first, and a scene's settings go to the host its backend was built with rather than whichever one is registered.
+  - After an `antialias` change, a `studio` environment kept a texture from the replaced renderer and metal drew dark on every later frame. The environment is now generated per renderer.
+  - `@motionscript/browser` registered 3D when its root module was evaluated, while declaring `sideEffects: false`. A bundler honouring the flag, such as rolldown under Vite 8, could drop both calls, and `Canvas3D` then drew its 2D parts only, with no error. Every `WebRenderContext` now installs the WebGL renderer and core's three loader when it is built, so each engine session, still renderer and export carries 3D with it, and importing the package registers nothing.
+
+- 47b6b7d: A curve on an `AudioBus` animates, over the bus's own span.
+
+  - A curve in a bus's `filters` was resolved against a length of 0, so it held its first value: `AudioFilters.gain(fadeOut(1))` never faded, and a fade or `ramp` up from 0 silenced everything on the bus. It now runs over the bus's presence span, from its row's `startAt` to its `endAt`, or to its clip's end when nothing removes it, the way a sound's curve runs over the sound's. Every clip on the bus hears the same fade, wherever its own span falls.
+  - A curve-valued bus `volume` was read as 1. It is now scheduled like a curve in `filters`.
+  - A bus chain was built once per bus id and kept, so a later change to the bus's level, mute or filters was not heard for the life of the device, and the offline mix played every clip through whichever version of a bus it met first. A chain is now reused only for a bus that sounds the same, and the live device builds its bus chains again after each pause, so a curve lines up with wherever playback resumes.
+  - The live device restarted a curve segment from its first value when it began playing partway through that segment. It now picks the segment up where it has got to, as the offline mix does.
+  - `AudioBusStop` carries the bus's span as `startAt` and `endAt`, in the same seconds as the request that carries it, and `busStopKey` keys a stop by everything that changes its sound. `busPathOf` and `busPathTo` take the declaring `AudioScope` as a second argument, and `AudioBusGraph.inputFor` takes the time its start time falls at, in the stops' seconds, as a third.
+
+- e2ce45c: A node compiled from source can use JSX and name its own variables freely.
+
+  - The default compiler for a source-string node emitted classic `React.createElement` calls, so a script with JSX registered and then threw `React is not defined` the first time its constructor ran. It now compiles JSX with the automatic runtime and `@motionscript/sdk` as the import source, which links to `DynamicNodeConfig.jsxRuntime`. A script needs no pragma, and a `@jsxRuntime` or `@jsxImportSource` pragma in it still takes precedence.
+  - A top-level `const`, `let` or `class` named like one of the globals a script is denied (`const frames = 30`, `let history = []`, `class Request {}`) failed with `SyntaxError: Identifier '…' has already been declared`. The script now runs in a scope of its own inside the one that denies those names, so its declaration shadows the denied global. Names it does not declare still read as `undefined`.
+
+- 42e9217: A failed asset fetch fails instead of loading empty bytes. `WebStorageAdapter` read a response's body whatever its status, so a 404 for a font file reached the font manager, which registered nothing, and the family still counted as loaded: its text drew nothing, on every frame, and nothing reported it. A missing image or audio file failed later, in a decoder, with a message that never named the address. A response that is not OK now rejects the load with `Fetching "<url>" failed: HTTP <status>`, which reaches the host the way any failed load does: a seek, a still or an export rejects, and a prefetch logs it. Nothing is cached, so the next load tries again.
+
+  - A font family registers once every one of its files has arrived, so a family missing a weight is not registered half-way and a retry does not register the rest a second time.
+  - `mixAudio`, which mixes every export's soundtrack, checks the status the same way.
+  - A render through `@motionscript/headless` of a document whose font is missing from `assetsDir` now fails naming the file, instead of drawing its text empty.
+
+- 1c48469: Stills and exports render the frame, theme and scale they were asked for.
+
+  - Overlapping `session.image()` calls each return their own frame. They shared one renderer, so every image held the last frame drawn; the engine's exporter now queues them.
+  - `exportVideo` applies the document's `theme`, and takes a `theme` option for a document that carries none, as `exportScreenshot` and `StillRenderer` do. A themed document exported on its own drew its tokens black, or in whatever theme was last set globally. `renderTimeline` and `drawFrameAt` take the same `theme` and apply it themselves.
+  - `RenderStillOptions.scale`, and so `session.image({ scale })`, applies to that call only. It used to become the renderer's scale, so the next call without one drew at it too.
+  - An export rejects with `NothingToDrawError` at the first frame whose every track failed to build, the same error a still of that frame throws. It used to encode a black video and log nothing. The error is exported from both packages and carries the `frame` and each track's failure. A track that built is drawable even when one of its nodes failed to declare its assets or audio; a still used to refuse it.
+
+- Updated dependencies [1f00320]
+- Updated dependencies [979a467]
+- Updated dependencies [1c48469]
+  - @motionscript/skia-render@0.1.0-alpha.3
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- @motionscript/skia-render@0.1.0-alpha.2
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- @motionscript/skia-render@0.1.0-alpha.1
+
+## 0.1.0-alpha.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,49 @@
+Motionscript
+Copyright 2026 Motionscript LLC
+
+This product includes the third-party code below, each part under the MIT
+License reproduced at the end of this file.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`fn_hash2`):
+  "Hash without Sine" by David Hoskins (https://www.shadertoy.com/view/4djSRW).
+  Copyright (c) 2014 David Hoskins.
+
+- packages/renderer/crates/renderer/src/shaders/prim.wgsl (`simplex_noise`): "Noise - simplex - 2D" by Inigo Quilez
+  (https://www.shadertoy.com/view/Msf3WH). Copyright (c) 2013 Inigo Quilez.
+
+- packages/renderer/crates/render3d (in @motionscript/renderer's WebAssembly):
+  its shaders (src/shaders/mesh.wgsl) port three.js r185's mesh programs and
+  src/geometry.rs its primitive generators (https://threejs.org).
+  Copyright (c) 2010-2026 three.js authors.
+
+@motionscript/renderer's WebAssembly (dist/ms_renderer_bg.wasm) compiles in
+Rust crates under MIT, Apache-2.0, Zlib and Unicode-3.0 terms (wgpu, naga,
+harfrust, read-fonts, kurbo, wasm-bindgen and others); their notices are in
+packages/renderer/THIRD_PARTY_NOTICES.txt.
+
+MP3 export loads @mediabunny/mp3-encoder (MPL-2.0), a WebAssembly build of
+the LAME MP3 encoder (LGPL, https://lame.sourceforge.io), on first use.
+
+The browser builds under dist/browser/ bundle each package's npm dependencies;
+dist/browser/THIRD_PARTY_LICENSES.txt in each package lists them with their
+licences.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,4 +1,141 @@
-# Temporary Holding Version
+# @motionscript/browser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+The browser platform for [Motion Script](https://motionscript.dev): it draws
+every frame with WebGPU through [`@motionscript/renderer`](https://github.com/motionscript-dev/motionscript/tree/main/packages/renderer), which it
+builds in. It implements the
+`platform`/`render` abstractions from [`@motionscript/core`](https://github.com/motionscript-dev/motionscript/tree/main/packages/core) so
+documents can be drawn to a canvas, played back with synchronized audio, and
+exported to video all in the browser.
+
+How a frame is drawn (shapes, fills, strokes, effects, text, 3D) lives in the
+renderer (Rust/wgpu compiled to WebAssembly). This package supplies the browser's
+half: the export frame loop, encoding, Web Audio, the clock and the entry points.
+A browser without WebGPU cannot draw: every entry that draws rejects with
+`WebGpuUnavailableError` (check `isWgpuSupported()` first to say so up front).
+
+## What's in here
+
+- **Engine**: `createBrowserEngine` wires every platform seam below into a
+  `@motionscript/core` `Engine`. Await it once at app start and share it.
+- **Exporter**: `exportVideo` renders a document offline and muxes video and
+  audio into an MP4 (H.264 + AAC, the default) or a WebM (VP9 + Opus) using
+  [mediabunny](https://github.com/Vanilagy/mediabunny). `exportAudio` writes the
+  timeline's mixed audio alone as WAV (the default), MP3 or M4A without rendering
+  a frame, and throws `NoAudioError` when nothing plays. `EXPORT_FORMATS` gives
+  each format's kind, extension and MIME type. MP3 loads a WASM build of LAME on
+  first use, in a worker started from a `blob:` URL, so a host's CSP needs
+  `worker-src blob:` for it.
+- **Stills**: `StillRenderer` (from `createStillRenderer`) is a long-lived
+  renderer that repaints single frames into a canvas the host owns, for
+  thumbnails and previews; `exportScreenshot` is the one-shot wrapper over it.
+- **Concat**: `concatVideoSegments` joins separately encoded MP4 (or WebM)
+  segments into one file of the same container without re-encoding, so an export can be split across workers. A segment is
+  `exportVideo({ frames: { start, end } })` (or `session.export({ frames })`):
+  that range alone, timestamped from 0 and silent.
+  `mixTimelineAudio` mixes the whole timeline's audio once for the joined file.
+  Every segment must share one encoder configuration; a mismatch throws
+  `ConcatMismatchError`.
+- **Parallel export**: `exportVideoParallel` takes `exportVideo`'s parameters
+  plus `lanes`, the renderers to spread the frames over: `localLane()` for
+  this page, and `messagePortLane(port)` for another realm (a second window or
+  process) that answers with `serveExportLane(port, resolve)`. It cuts the
+  timeline into key-frame-aligned frame ranges of the whole project, starts on
+  the first lane alone and admits the next only while that raises throughput
+  (every lane's encoder shares the browser's one GPU process, so light scenes
+  gain nothing from a second lane), mixes the audio once while the frames
+  render, joins each range as soon as the ones before it are done (into
+  `stream` when given) and reports progress by frames drawn.
+  `createSegmentJoiner` is the incremental join underneath.
+- **Audio**: `WebAudioPlayer` drives playback through the Web Audio API;
+  `mixAudio` and `encodeWav` (also on the `@motionscript/browser/audio`
+  subpath, which skips the renderer) mix down offline.
+- **Assets**: `setAssetByteSource` lets a host answer for an asset's bytes (a file
+  the user just chose, say) before the renderer's storage goes to the network; it
+  applies to previews, exports and stills alike. `loadAssetBytes` reads through it.
+- **Source-string nodes**: `createBrowserEngine({ nodes })` also accepts TS source
+  strings (array form only), each default-exporting a component (`component2d({ key })`),
+  compiled with `esbuild-wasm` on first use. A script is written with calls: JSX
+  neither compiles nor links. `dynamicNodes` overrides the SDK, extra importable
+  `modules` or the compiler, each field defaulting on its own.
+- **Clock**: `WebTicker` synchronizes scene playback to `requestAnimationFrame` while calculating dt from audio context to ensure audio and animation line up.
+- **Renderer**: `isWgpuSupported`, `onWgpuEvent` (device loss and recovery), and
+  the WGSL shader tools `ShaderPreview`, `validateShader` and `WGSL_PRELUDE`, from
+  `@motionscript/renderer`.
+
+## Usage
+
+```bash
+npm install @motionscript/browser @motionscript/core
+```
+
+```ts
+import { createBrowserEngine } from '@motionscript/browser';
+
+const engine = await createBrowserEngine({ nodes: [MyNode] });
+const session = engine.open({ document, target: canvasEl });
+session.playback!.play();
+
+const mp4 = await session.export();
+```
+
+The renderer's `ms_renderer_bg.wasm` resolves beside its module, which a bundler
+handles; elsewhere serve it and pass its URL as `rendererWasmUrl` (every entry
+that draws takes it). `session.export()` resolves to the MP4 bytes unless
+`encode: { download: true }` asks for a browser download; `encode: { format }`
+picks another format (`'webm'`, or `'wav'`, `'mp3'` or `'m4a'` for audio alone).
+
+## Render issues and GPU faults
+
+What the renderer drew but not as the document says (a feature it lacks, a shader
+that does not compile, a lost GPU device) is a typed `RenderIssue`: a session
+lists it in `buildErrors`, and `exportVideo`, `exportVideoParallel`,
+`session.export()`, `session.image()` and `StillRenderer.render` hand it to
+`onIssue`. A lost device or a crashed backend fails those instead with a
+`RenderBackendError` (from `@motionscript/core`; `retryable` when the backend
+recovered on a new device).
+
+A shader stored in the retired SkSL language (`language: "sksl"`, from documents
+written before WGSL was the only one) draws nothing and is reported as a `shader`
+issue asking for a WGSL port.
+
+## CDN build
+
+`pnpm build` ends by writing `dist/browser/` (generated, never edited): one minified
+ES module per `exports` entry (`index.js`, `audio.js`), shared and lazy chunks, `esbuild.wasm`, `ms_renderer_bg.wasm`, and a
+`manifest.json` mapping each export and binary asset to a package-relative path.
+The renderer is bundled in; the peers stay imports, so a host's import map names each
+of these bare specifiers once, to one copy:
+
+```
+@motionscript/core
+@motionscript/core/sdk
+```
+
+Against a CDN module URL the default `ms_renderer_bg.wasm` and `esbuild.wasm` URLs do
+not resolve, so a host passes `rendererWasmUrl` and, if it compiles source-string nodes,
+`compilerWasmUrl`. Both binaries are listed in the packages' manifests.
+
+See the [docs](https://motionscript.dev/docs) for the full feature set and API
+reference.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm --filter @motionscript/browser build   # eslint, tsc, tsc-alias, then the CDN build
+pnpm --filter @motionscript/browser test    # vitest: real Chromium, plus a Node project
+```
+
+The tests run in Chromium on SwiftShader's WebGPU adapter through
+`@vitest/browser-playwright` (headed with `HEADED=1`, which Linux needs, under
+`xvfb-run`: a headless page there reads a WebGPU canvas back empty), so install it
+once with `pnpm --filter @motionscript/browser exec playwright install --with-deps chromium`.
+They import the **built** `dist/` of core and the renderer: run `pnpm build:lib` (Rust
+needed) first on a fresh checkout. Files named `*.node.test.ts` run in Node and ask what a consumer's bundler
+keeps of this package (`tree-shaking`, `cdn-build`). Suites that need an H.264 or AAC
+encoder skip on a Chromium without one; `REQUIRE_ENCODERS=1` makes them fail instead.
+
+See [CLAUDE.md](https://github.com/motionscript-dev/motionscript/blob/main/packages/browser/CLAUDE.md) for the traps when editing here,
+[ARCHITECTURE.md](https://github.com/motionscript-dev/motionscript/blob/main/ARCHITECTURE.md) for the layering and
+[CONTRIBUTING.md](https://github.com/motionscript-dev/motionscript/blob/main/CONTRIBUTING.md) for the workflow.