canvas-recorder-lib 0.5.0 → 0.6.0

package/BREAKING-CHANGES.md

@@ -0,0 +1,18 @@
+# Breaking Changes
+
+Changes that can break a project using this library, newest first, and what to do about each.
+This is not a full list of changes:  new features and fixes aren't here.
+
+While the version is 0.x, every breaking change comes with a new minor version (0.5 → 0.6), and nothing else does.
+A project that depends on `"^0.5.0"` gets 0.5.x updates but never 0.6.0, so it only meets these changes when someone installs the new version on purpose.
+
+## 0.6.0 (2026-11-05)
+
+- **`CANVAS_WIDTH_UNITS`, `CANVAS_HEIGHT_UNITS` and `PIXELS_PER_UNIT` are gone** from `src/slide-components/video-info`.
+  The video's size can change now, from the GUI or from `canvasRecorder.size`, so a constant can't hold it.
+  Use `canvasWidthUnits()`, `canvasHeightUnits()` and `pixelsPerUnit()` instead, and call them while drawing, not when the module loads.
+  To keep the old fixed size, set it in your main program and call `canvasRecorder.lockSize()`.
+
+## 0.5.0 (2026-10-18)
+
+The first version on npm.

package/README.md

@@ -3,10 +3,20 @@
 Preview, edit, annotate and record HTML canvas animations.
 This is the tooling from [canvas-recorder](https://github.com/TradeIdeasPhilip/canvas-recorder), packaged as a library, so each video can be its own small project.
 
-**Status:** version 0.x, a first version. Expect breaking changes.
+**Status:** in use for published videos.
+It's still growing:  while the version is 0.x, a change that could break your project comes with a new minor version (0.5 → 0.6), and [BREAKING-CHANGES.md](BREAKING-CHANGES.md) says what changed and how to update.
+
+**Source:** https://github.com/TradeIdeasPhilip/canvas-recorder-lib
 
 **API docs:** https://tradeideasphilip.github.io/canvas-recorder-lib/
 
+**Try it:** the [Simple Video Editor](https://tradeideasphilip.github.io/canvas-recorder-lib/simple-video-editor/) is this library's player and Visual Editor with an empty project:  open video clips from your computer, add text and callouts, and save an MP4.
+Its source is in [simple-video-editor/](https://github.com/TradeIdeasPhilip/canvas-recorder-lib/tree/master/simple-video-editor).
+
+**Showcase:** the [showcase](https://tradeideasphilip.github.io/canvas-recorder-lib/tests/showcase.html) is a series of slides that show what the library can do, one topic per slide.
+Looking for code or ideas to copy?  Start there.
+Its source is in [test-project/src/showcase/](https://github.com/TradeIdeasPhilip/canvas-recorder-lib/tree/master/test-project/src/showcase), one file per slide.
+
 ## Use
 
 ```ts
@@ -17,9 +27,17 @@ import { myVideo } from "./my-video.ts"; // Any Showable.
 // canvasRecorder.pixelWidth = 1920;
 // canvasRecorder.pixelHeight = 1080;
 
+// Optional.  For a video drawn for one specific size.
+// canvasRecorder.lockSize();
+
 canvasRecorder.start(myVideo, { name: "my-video" });
 ```
 
+The player shows the video's size (pixels and units) in four fields.
+Unless the program calls `lockSize()`, the user can change them, and the player remembers the change for this video.
+So read `canvasRecorder.width` and the rest while drawing, not once at startup.
+The Save dialog can also save one file at a different size, without changing the video.
+
 `start()` replaces the page's `<body>` with the player and its Visual Editor.
 Leave your HTML's body empty, or put "Please wait…" in it.
 
@@ -37,15 +55,52 @@ The package includes the TypeScript source next to the compiled JavaScript, and
 
 Things the first project to use this library ([riemann-surfaces-3d](https://github.com/TradeIdeasPhilip/riemann-surfaces-3d)) ran into.
 
+### Installing
+
+```bash
+npm install canvas-recorder-lib
+npm install-scripts deny onnxruntime-node protobufjs
+npm install-scripts ls     # should say "No packages with unreviewed install scripts."
+```
+
+- **Depend on the published version,** not `"file:../canvas-recorder-lib"`.
+  A `file:` dependency works on your machine, but GitHub's build machine has no `../canvas-recorder-lib`, so your GitHub Pages deploy fails.
+  `npm ci` doesn't notice; `tsc` stops with "Cannot find module 'canvas-recorder-lib'."
+- **Deny those two install scripts.** npm 11 skips dependencies' install scripts until your project approves or denies them, and warns about each one.
+  Both come from `@huggingface/transformers`, which the library uses for transcription, and neither is needed in a browser.
+  `deny` records that in your `package.json`'s `allowScripts`.
+  - That field replaces any `allow-scripts` setting in your `~/.npmrc`.
+    If your `~/.npmrc` approves `fsevents` (Vite's file watcher on macOS), approve it again here:  `npm install-scripts approve fsevents --no-allow-scripts-pin`.
+    In a new project that fails with `ENOMATCH`, because the first `npm install` doesn't put `fsevents` in `node_modules`.
+    Run `npm install` again (it warns that `fsevents` isn't approved), then approve it.
+- **Expect a big `package-lock.json`.** The library's dependencies are installed in your project, including some that only Node.js uses.
+
+### Working on the library at the same time
+
+```bash
+npm link ../canvas-recorder-lib    # in your project
+npm run watch                      # in canvas-recorder-lib
+```
+
+- `npm link` replaces `node_modules/canvas-recorder-lib` with a symlink to your copy, without touching `package.json` or `package-lock.json`.
+  So your deploy keeps using the published version.
+- `npm ls canvas-recorder-lib` shows `-> ./../canvas-recorder-lib` while the link is active.
+- Any later `npm install` or `npm ci` quietly puts the published copy back.
+- Your project uses the library's compiled `dist/`, so keep `npm run watch` running in the library.
+- When the library change is ready, publish a new version, then `npm install canvas-recorder-lib@<version>` in your project and commit both package files.
+
 ### Vite setup
 
-While both projects are on your disk, link the library with `"canvas-recorder-lib": "file:../canvas-recorder-lib"` in package.json.
-Then add this to your `vite.config.js`:
+Add this to your `vite.config.js`:
 
 ```js
 import { defineConfig, searchForWorkspaceRoot } from "vite";
 
 export default defineConfig({
+  base: "./",
+  resolve: {
+    dedupe: ["phil-lib"],
+  },
   server: {
     port: 5174, // Pick one per project, and keep it.
     strictPort: true,
@@ -53,16 +108,28 @@ export default defineConfig({
       allow: [searchForWorkspaceRoot(process.cwd()), "../canvas-recorder-lib"],
     },
   },
+  optimizeDeps: {
+    include: ["canvas-recorder-lib > @huggingface/transformers"],
+  },
+  build: {
+    rolldownOptions: { output: { keepNames: true } }, // Vite 8.  Vite 7:  rollupOptions.
+  },
 });
 ```
 
-- **`fs.allow`:** without it, the server console says the transcription worker is "outside of Vite serving allow list", and transcripts fail.
+- **`base: "./"`:** relative paths, so the build works on GitHub Pages, or in any subdirectory.
+- **`dedupe`:** one copy of phil-lib.  With the library linked, Vite would otherwise load two:  yours, and the one in the library's `node_modules`.
+- **`fs.allow`:** needed while the library is linked.
+  Without it, the server console says the transcription worker is "outside of Vite serving allow list", and transcripts fail.
   A linked library lives outside your project. Vite serves files that are imported, but the worker is loaded by URL.
   Setting `allow` turns off Vite's default, so your own folder has to be listed too; that's what `searchForWorkspaceRoot()` is for.
+- **`optimizeDeps.include`:** without it, the first Import audio or transcript reloads the page, under `npm run dev` only.
+  Only the transcription worker imports that package, and Vite doesn't look inside workers when it starts, so it finds the package late and reloads to use it.
+- **`keepNames`:** the Visual Editor writes TypeScript that names each component's class (Sync diffs, and `properties/*.txt`).
+  In a minified production build, like your GitHub Pages copy, those names come out as `hi` and `Nr` without it.
 - **A fixed port:** the editor saves your work in the browser (IndexedDB), and the browser keeps a separate copy for each origin.
   If another project already has the port, Vite quietly moves to the next one (5173 → 5174), and the editor seems to forget everything.
   `strictPort` makes that an error instead.
-- **`npm run watch`:** your project uses the library's compiled `dist/`, so keep this running in the library while you change it.
 
 ### Ports
 
@@ -75,7 +142,9 @@ For a new project, take the next number and add it here.
 | 5173 | [canvas-recorder](https://github.com/TradeIdeasPhilip/canvas-recorder) (Vite's default; historical) |
 | 5174 | [riemann-surfaces-3d](https://github.com/TradeIdeasPhilip/riemann-surfaces-3d) |
 | 5175 | [affine-transforms](https://github.com/TradeIdeasPhilip/affine-transforms) |
-| 5176 | `test-project/` in this repo (planned; see [development-plans/test-project.md](development-plans/test-project.md)) |
+| 5176 | [`test-project/`](https://github.com/TradeIdeasPhilip/canvas-recorder-lib/tree/master/test-project) in this repo:  the showcase, tests and tools |
+| 5177 | [`simple-video-editor/`](https://github.com/TradeIdeasPhilip/canvas-recorder-lib/tree/master/simple-video-editor) in this repo |
+| 5178 | 7-pointed-star |
 
 ### Starting the editor
 
@@ -86,12 +155,26 @@ For a new project, take the next number and add it here.
   Disabling every sheet that has more than `@font-face` rules works (see `hideOurStyles()` in riemann-surfaces-3d's `src/video-editor.ts`).
 - **Stop your own animation loop and keyboard handlers.** Otherwise typing in the Visual Editor's text boxes drives your program.
 - **Put sound files in your `public/` folder** and refer to them as `"./name.m4a"`.
+- **Or use files on your computer.** The Video File and Image File panels have **📂 Open file…**, which stores a URL like `local:Screen Recording.mov`.
+  The browser remembers the file, but only in this browser on this computer.
+  After a reload it may want your OK again:  click **🔓 Allow local files**.
+  The Save dialog checks every local file before it starts, so a long recording can't stop halfway to ask.
+  In your own code, read media with `fetchMedia()`, which understands `local:` URLs.
 - **Save the editor's state into your project, so it's in git.** The editor always saves inside the browser (IndexedDB), which git can't see.
   Make a `properties/` folder, and point **💾 Save As**, the **Save defaults** checkbox, and **Save Diffs** at it.
   The browser remembers each choice, so after the first time they keep saving there.
   Add a `properties/README.md` explaining the three files; copy [riemann-surfaces-3d's](https://github.com/TradeIdeasPhilip/riemann-surfaces-3d/blob/master/properties/README.md).
 - **Register your own components** with `componentRegistry.set(key, { create })`.
   Then the Visual Editor can add, save and load them, and "TypeScript defaults" can rebuild them.
+- **A mistake in the Visual Editor is a state, not an error.** Your components should treat it that way:
+  - Show a warning, in the editor or on the canvas.  Never throw, and never a dialog box.
+  - Save it like any other state.  Editing between two good states often passes through bad ones.
+  - Draw as much as still makes sense.  Values in worse shape can come back from IndexedDB or a file, so fail gracefully and make them easy to fix.
+  - Throwing while saving a video is only for external failures, like an image or video that doesn't load.
+  - Assertions are still fine for the programmer's own mistakes, like a table of values checked when the program starts.
+- **Name a replaceable child with `userEditableDescription`,** not the constructor's `description`, when your code adds one with `replaceableComponents.push()`.
+  When the editor loads saved changes, it rebuilds those children from the registry, so a `description` from your constructor comes back as the registry's default.
+  `userEditableDescription` is saved with the rest, and the diff file uses it to match each child with its TypeScript.
 
 ### Recording a program that has its own state
 
@@ -115,27 +198,36 @@ It is only downloaded if someone uses transcription.
 
 ## How this library is made
 
-canvas-recorder is the source of truth.
-`npm run import` copies the player, and everything it imports, from `../canvas-recorder` into `dev/` and `src/`, verbatim.
-The library's own code lives in `lib/`.
-
-To pick up newer code from canvas-recorder:
-
-1. Make a branch from the previous "Verbatim import from canvas-recorder …" commit.
-2. Run `npm run import`, and commit: "Verbatim import from canvas-recorder <hash>".
-3. Merge that branch into master.
-   The library's hand edits stay as they are, and history only grows, so a plain `git push` works.
-4. `npm run build`, and bump the version in package.json.
-
-`imported-files.txt` lists what was copied, and from which commit.
+The code came from [canvas-recorder](https://github.com/TradeIdeasPhilip/canvas-recorder), which is now historical.
+Since 2026-10-14, this library is the master copy:  new features and fixes start here.
+`imported-files.txt` lists what was copied, and from which canvas-recorder commit.
 
 ## Build
 
 ```
 npm install
 npm run build    # or:  npm run watch
+npm run clean    # empty dist/
+npm run docs     # API docs, in docs/
 ```
 
 Output goes to `dist/`: `.js`, `.d.ts`, source maps, plus the CSS and JSON files the JavaScript imports.
 
-A project that depends on this library through `"canvas-recorder-lib": "file:../canvas-recorder-lib"` sees a change as soon as `npm run watch` recompiles it.
+Every relative import names its file, like `from "./utility.ts"`, and `npm run build` stops if one doesn't.
+tsc turns `.ts` into `.js` in `dist/`, which works everywhere; an import with no extension only works where a tool like Vite guesses it.
+
+`build` and `watch` only add and overwrite files in `dist/`, so a project's running dev server never sees it empty.
+A deleted or renamed source file leaves its old output behind until `npm run clean`.
+
+A project that has linked this library (see [Working on the library at the same time](#working-on-the-library-at-the-same-time)) sees a change as soon as `npm run watch` recompiles it.
+
+The Simple Video Editor is a separate npm project inside this repo.  [simple-video-editor/README.md](simple-video-editor/README.md) says how to run it.
+
+## Releasing
+
+1. Bump the version.  If [BREAKING-CHANGES.md](BREAKING-CHANGES.md) has an "Unreleased" section:  `npm version minor --no-git-tag-version`, and replace "Unreleased" with the new version and the date.
+   Otherwise:  `npm version patch --no-git-tag-version`.  Commit and push.
+2. `npm publish`.  `prepublishOnly` empties and rebuilds `dist/` first, so nothing stale is published.
+3. In each project:  `npm install canvas-recorder-lib@<version>`, `npx tsc --noEmit`, and commit `package.json` and `package-lock.json`.
+
+The API docs publish themselves on every push to master.

package/dev/audio-builder.ts

@@ -1,3 +1,5 @@
+import { fetchMedia } from "../src/local-files.ts";
+
 /**
  * This creates a complete audio clip by joining multiple clips.
  * It starts with all silence and you can add the clips wherever you need them.
@@ -45,7 +47,7 @@ export class AudioBuilder {
 
   async #createNewAudioBuffer(url: string) {
     const time1 = performance.now();
-    const response = await fetch(url);
+    const response = await fetchMedia(url);
     const time2 = performance.now();
     const encodedSource = await response.arrayBuffer();
     const time3 = performance.now();
@@ -103,7 +105,7 @@ export class AudioBuilder {
    * And the url will start with "./".
    *
    * CORS can be an issue depending on the server.
-   * Local files are forbidden.
+   * A `local:` URL reads a file on the user's computer.  See src/local-files.ts.
    * @param startMsInDestination 0 to play the new clip at the the beginning of the video.
    * 1000 to start this clip 1 second after the video starts.
    *

package/dev/canvas-recorder.css

@@ -367,3 +367,62 @@ body {
   outline: 2px solid #4a90d9;
   outline-offset: -2px;
 }
+
+/* ── Multi Text editor ───────────────────────────────────────────────── */
+
+/* The FormatEditor in dev/format-editor.ts:  plain text with a menu ("chip")
+   in front of each run of text, naming its Text Format.  From
+   format-editor-prototype's style.css. */
+.format-editor {
+  min-height: 6rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid #c7c7cc;
+  border-radius: 6px;
+  background: white;
+  /* Newlines are stored as plain "\n" characters, not <br> or <div>. */
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  line-height: 1.9;
+  font-size: 1.05rem;
+}
+
+.format-editor:focus-within {
+  outline: 2px solid #0a66d8;
+  outline-offset: 1px;
+}
+
+.format-chip {
+  display: inline-block;
+  margin: 0 1px;
+  vertical-align: baseline;
+}
+
+.format-chip select {
+  font: inherit;
+  font-size: 0.8rem;
+  line-height: 1.2;
+  padding: 0 0.15rem;
+  color: #1d1d1f;
+  background: #e3edfb;
+  border: 1px solid #9dbbe6;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+/* A name that isn't one of the formats this text can see. */
+.format-chip.invalid select {
+  color: #d70015;
+  background: #fde8ea;
+  border-color: #d70015;
+  font-weight: 600;
+}
+
+/* In the open menu, all options except the unknown one use the normal color. */
+.format-chip.invalid select option {
+  color: #1d1d1f;
+  font-weight: normal;
+}
+
+.format-chip select option.invalid {
+  color: #d70015;
+}