@barmark/score 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/element.js CHANGED
@@ -3,12 +3,15 @@
3
3
  * Grid / Score switch. Its chart comes from the `text` property, a `src` URL or
4
4
  * a child `<script type="text/barmark">`, as `<barmark-chart>`'s does. A shadow
5
5
  * root drawn by `renderScoreHtml` is reused. The score engine (Verovio, in a
6
- * worker) loads on the first switch to the score, never before. Importing
6
+ * worker) loads on the first switch to the score, or earlier as `preload`
7
+ * asks, showing its progress while it loads. Importing
7
8
  * this module registers the element (once) and the font (once per document).
8
9
  */
9
10
  import { FONT_FAMILY, fontFaceCss, renderChartUnwrapped, } from "@barmark/render";
10
11
  import { chartSource, inlineChartText, optionsFromAttributes, } from "@barmark/render/element";
11
12
  import { parseChart } from "barmark";
13
+ import { isIntegrity } from "./download.js";
14
+ import { showStatus, UNMEASURED } from "./loading.js";
12
15
  import { isLeipzigFace, scorePane } from "./markup.js";
13
16
  import { decodeCarried, gridError, scoreShell } from "./shell.js";
14
17
  import { viewOf } from "./switch.js";
@@ -18,18 +21,22 @@ export function setEngineForTests(factory) {
18
21
  testEngine = factory;
19
22
  }
20
23
  let loading = null;
24
+ /** The page's engine once imported. */
25
+ let loaded = null;
21
26
  /** The page's engine, imported on first use; a failed import is tried again next time. */
22
27
  function loadEngine() {
23
28
  const factory = testEngine;
24
29
  if (factory)
25
30
  return Promise.resolve().then(factory);
26
- loading ??= import("./engine.js").then((m) => m.engine(), (e) => {
31
+ loading ??= import("./engine.js").then((m) => {
32
+ loaded = m.engine();
33
+ return loaded;
34
+ }, (e) => {
27
35
  loading = null;
28
36
  throw e;
29
37
  });
30
38
  return loading;
31
39
  }
32
- const LOADING = "Loading score…";
33
40
  /** The score's accessible name when the chart has no title. */
34
41
  const UNTITLED = "Score";
35
42
  const NOTE = "The score couldn't be drawn";
@@ -77,13 +84,23 @@ function takeEarlyText(el) {
77
84
  /** The grid's attributes, as `<barmark-chart>` observes them, then the score's own. */
78
85
  const OBSERVED = [
79
86
  ...["src", "theme", "bar-numbers", "rehearsal-letters", "numerals", "wrap", "show-part"],
80
- ...["view", "verovio-url"],
87
+ ...["view", "verovio-url", "verovio-integrity", "preload"],
81
88
  ];
89
+ /** With no `requestIdleCallback`, how long after connecting `preload="idle"` starts the load. */
90
+ const IDLE_FALLBACK_MS = 500;
91
+ /** Whether the reader asked to save data, or is on a 2G line: `preload="idle"` waits for intent there. */
92
+ function sparing() {
93
+ const c = globalThis.navigator?.connection;
94
+ return c?.saveData === true || c?.effectiveType === "2g" || c?.effectiveType === "slow-2g";
95
+ }
96
+ /** The pointer, focus or touch on the Score radio that says a reader may want the score. */
97
+ const INTENT = ["pointerenter", "focus", "touchstart"];
82
98
  const messageOf = (e) => (e instanceof Error ? e.message : String(e));
83
99
  /** The radio a click or key landed on. */
84
100
  const radioOf = (target) => target?.closest?.("[data-view]") ?? null;
85
101
  const same = (a, b) => a !== null && a.text === b.text && Math.abs(a.width - b.width) <= SLACK;
86
102
  const URL_REASON = "verovio-url must be an http(s) URL";
103
+ const INTEGRITY_REASON = "verovio-integrity must be one sha256-, sha384- or sha512- digest";
87
104
  /** `verovio-url` resolved against the page: undefined when absent, null unless http(s). */
88
105
  function verovioHref(value, base) {
89
106
  if (value === null)
@@ -122,6 +139,12 @@ function defineElement() {
122
139
  /** The engraving and theme the pane holds, so an unchanged one is not written again. */
123
140
  #revealed = null;
124
141
  #asked = null;
142
+ /** What the engine last said about the request being waited on. */
143
+ #status = UNMEASURED;
144
+ /** Whether this element has asked the engine to preload. */
145
+ #preloaded = false;
146
+ /** The pending idle preload's cancel, if one is armed. */
147
+ #idle = null;
125
148
  connectedCallback() {
126
149
  const early = takeEarlyText(this);
127
150
  if (early)
@@ -133,8 +156,11 @@ function defineElement() {
133
156
  this.#resize.observe(this);
134
157
  }
135
158
  this.#schedule();
159
+ this.#armIdle();
136
160
  }
137
161
  disconnectedCallback() {
162
+ this.#idle?.();
163
+ this.#idle = null;
138
164
  this.#observer.disconnect();
139
165
  this.#resize?.disconnect();
140
166
  this.#resize = null;
@@ -144,8 +170,10 @@ function defineElement() {
144
170
  if (!this.isConnected || old === value)
145
171
  return;
146
172
  // A new URL may be the fix: the Score radio works again, as after a new chart.
147
- if (name === "verovio-url")
173
+ if (name === "verovio-url" || name === "verovio-integrity")
148
174
  this.#clearFailure();
175
+ else if (name === "preload")
176
+ this.#preloadChanged();
149
177
  else if (name === "view")
150
178
  this.#applyView();
151
179
  else if (name === "src")
@@ -260,6 +288,73 @@ function defineElement() {
260
288
  this.#wired = switcher;
261
289
  switcher.addEventListener("click", (e) => this.#pick(radioOf(e.target)));
262
290
  switcher.addEventListener("keydown", (e) => this.#key(e));
291
+ const score = switcher.querySelector('[data-view="score"]');
292
+ for (const type of INTENT)
293
+ score?.addEventListener(type, () => this.#intent(), { passive: true });
294
+ }
295
+ /** `preload`: "none" unless "intent" or "idle"; "idle" is "intent" on a sparing connection. */
296
+ #preloadMode() {
297
+ const v = this.getAttribute("preload");
298
+ if (v === "idle")
299
+ return sparing() ? "intent" : "idle";
300
+ return v === "intent" ? "intent" : "none";
301
+ }
302
+ /** A reader reaching for Score: any preload but "none" starts now. */
303
+ #intent() {
304
+ if (this.#preloadMode() !== "none")
305
+ this.#preload();
306
+ }
307
+ /** A new `preload`: an idle load armed for "idle" is cancelled unless it is still "idle". */
308
+ #preloadChanged() {
309
+ if (this.#preloadMode() !== "idle") {
310
+ this.#idle?.();
311
+ this.#idle = null;
312
+ }
313
+ this.#armIdle();
314
+ }
315
+ /** `preload="idle"`: start the load when the page is idle (or shortly, without requestIdleCallback). */
316
+ #armIdle() {
317
+ if (this.#idle || this.#preloaded || this.#preloadMode() !== "idle")
318
+ return;
319
+ const run = () => {
320
+ this.#idle = null;
321
+ this.#preload();
322
+ };
323
+ const g = globalThis;
324
+ if (g.requestIdleCallback) {
325
+ const id = g.requestIdleCallback(run);
326
+ this.#idle = () => g.cancelIdleCallback?.(id);
327
+ }
328
+ else {
329
+ const t = setTimeout(run, IDLE_FALLBACK_MS);
330
+ this.#idle = () => clearTimeout(t);
331
+ }
332
+ }
333
+ /** Loads the engine with no job, once per element; the engine shares the one load. */
334
+ #preload() {
335
+ if (this.#preloaded)
336
+ return;
337
+ const source = this.#source();
338
+ if (source === null)
339
+ return;
340
+ this.#preloaded = true;
341
+ loadEngine().then((e) => e.preload(source.url, source.integrity), () => { });
342
+ }
343
+ /** Where Verovio comes from, or null (and why) when `verovio-url` or `verovio-integrity` is refused. */
344
+ #verovio() {
345
+ const url = verovioHref(this.getAttribute("verovio-url"), this.ownerDocument.baseURI);
346
+ if (url === null)
347
+ return { refused: URL_REASON };
348
+ const integrity = url === undefined ? null : this.getAttribute("verovio-integrity");
349
+ if (integrity === null)
350
+ return { url, integrity: undefined };
351
+ return isIntegrity(integrity)
352
+ ? { url, integrity: integrity.trim() }
353
+ : { refused: INTEGRITY_REASON };
354
+ }
355
+ #source() {
356
+ const v = this.#verovio();
357
+ return "refused" in v ? null : v;
263
358
  }
264
359
  #pick(radio) {
265
360
  if (!radio || radio.getAttribute("aria-disabled") === "true")
@@ -330,19 +425,32 @@ function defineElement() {
330
425
  return this.#reveal(this.#engraved);
331
426
  if (same(this.#asked, want))
332
427
  return this.#busy();
333
- const url = verovioHref(this.getAttribute("verovio-url"), this.ownerDocument.baseURI);
334
- if (url === null)
335
- return this.#fail(URL_REASON);
336
- void this.#engrave(want, url);
428
+ const verovio = this.#verovio();
429
+ if ("refused" in verovio)
430
+ return this.#fail(verovio.refused);
431
+ void this.#engrave(want, verovio);
337
432
  }
338
- /** Engraves `want`; only the newest request this element made is shown. */
339
- async #engrave(want, url) {
340
- this.#busy();
433
+ /** Engraves `want`; only the newest request this element made is shown, with its status while it waits. */
434
+ async #engrave(want, verovio) {
341
435
  this.#asked = want;
342
436
  const ask = ++this.#engraves;
437
+ this.#status = UNMEASURED;
438
+ const onStatus = (s) => {
439
+ if (ask !== this.#engraves)
440
+ return;
441
+ this.#status = s;
442
+ const { pane } = this.#parts();
443
+ if (pane && this.#revealed === null)
444
+ showStatus(pane, s);
445
+ };
446
+ const call = verovio.integrity === undefined ? { onStatus } : { onStatus, integrity: verovio.integrity };
447
+ const run = (e) => e.engrave(this, want.text, want.width, verovio.url, call);
448
+ // A loaded engine is asked at once, so its status (not a provisional one) is the first drawn.
449
+ const request = loaded ? run(loaded) : loadEngine().then(run);
450
+ this.#busy();
343
451
  let reply;
344
452
  try {
345
- reply = await (await loadEngine()).engrave(this, want.text, want.width, url);
453
+ reply = await request;
346
454
  }
347
455
  catch (e) {
348
456
  reply = { id: 0, ok: false, reason: messageOf(e) };
@@ -357,13 +465,13 @@ function defineElement() {
357
465
  if (this.view === "score")
358
466
  this.#reveal(this.#engraved);
359
467
  }
360
- /** A score on its way: a shown one stays (busy) until the new one lands, else "Loading score…". */
468
+ /** A score on its way: a shown one stays (busy) until the new one lands, else its loading status. */
361
469
  #busy() {
362
470
  const { grid, pane } = this.#parts();
363
471
  if (!pane)
364
472
  return;
365
473
  if (this.#revealed === null)
366
- pane.textContent = LOADING;
474
+ showStatus(pane, this.#status);
367
475
  pane.setAttribute("aria-busy", "true");
368
476
  pane.toggleAttribute("hidden", false);
369
477
  grid?.toggleAttribute("hidden", true);
package/dist/engine.d.ts CHANGED
@@ -1,9 +1,22 @@
1
- /** What a page asks the worker for: one chart, laid out for a width. */
2
- export type Request = {
1
+ import type { Download } from "./download.js";
2
+ /**
3
+ * Where a worker loads Verovio from: no `verovioUrl`, the package's own;
4
+ * with `verovioIntegrity`, a copy that must have that digest (or the
5
+ * package's own is loaded in its place).
6
+ */
7
+ export type VerovioSource = {
8
+ verovioUrl?: string;
9
+ verovioIntegrity?: string;
10
+ };
11
+ /**
12
+ * What a page asks the worker for: one chart, laid out for a width; or,
13
+ * with `preload`, only to load Verovio (`text` and `width` unused).
14
+ */
15
+ export type Request = VerovioSource & {
3
16
  id: number;
4
17
  text: string;
5
18
  width: number;
6
- verovioUrl?: string;
19
+ preload?: true;
7
20
  };
8
21
  /** What the worker answers. No `xml` or `diagnostics` cross the boundary. */
9
22
  export type Reply = {
@@ -18,6 +31,36 @@ export type Reply = {
18
31
  };
19
32
  /** An `EngraveReply` is a reply a page may show. */
20
33
  export type EngraveReply = Reply;
34
+ /**
35
+ * What the worker says before it engraves job `id`: its Verovio is loaded,
36
+ * and from where (no `verovioUrl`: the package's own), so the engine can
37
+ * start the job's deadline and give a replacement worker the same Verovio.
38
+ */
39
+ export type Ready = {
40
+ id: number;
41
+ loaded: VerovioSource;
42
+ };
43
+ /** How a worker's Verovio load is going: downloading (as far as it can be measured), then preparing. */
44
+ export type LoadStatus = Download | {
45
+ phase: "prepare";
46
+ };
47
+ /** What the worker says while it loads Verovio for job `id`. */
48
+ export type Progress = {
49
+ id: number;
50
+ status: LoadStatus;
51
+ };
52
+ /** Every message a worker sends: a job's `Progress` while it loads, its `Ready`, then its `Reply`. */
53
+ export type WorkerMessage = Reply | Ready | Progress;
54
+ /** What a caller hears while it waits: the engine's load, then its engraving. */
55
+ export type EngineStatus = LoadStatus | {
56
+ phase: "engrave";
57
+ };
58
+ export type EngraveCall = {
59
+ /** The SRI digest (`sha384-…`) the `verovioUrl` copy must have; on a mismatch the package's own loads. */
60
+ integrity?: string;
61
+ /** Hears the engine's status now, and as it changes, until the request settles. */
62
+ onStatus?: (status: EngineStatus) => void;
63
+ };
21
64
  /**
22
65
  * The part of a `Worker` the engine uses, so a test can pass a fake. It is
23
66
  * driven by the `onmessage` and `onerror` properties (a real `Worker`
@@ -26,18 +69,48 @@ export type EngraveReply = Reply;
26
69
  export interface WorkerLike {
27
70
  postMessage(request: Request): void;
28
71
  terminate(): void;
29
- onmessage: ((e: MessageEvent<Reply>) => void) | null;
72
+ onmessage: ((e: MessageEvent<WorkerMessage>) => void) | null;
30
73
  onerror: ((e: ErrorEvent) => void) | null;
31
74
  }
32
75
  export type Engine = {
33
76
  /**
34
77
  * Engrave `text` for `width`. Per `key` (the element) only the newest
35
78
  * request resolves with a reply; an older one resolves `null`. Rejects
36
- * with "The score engine failed" if the worker crashes.
79
+ * with "The score engine failed" if the worker crashes on it, or its
80
+ * Verovio load or its engraving runs past its deadline.
81
+ */
82
+ engrave(key: object, text: string, width: number, verovioUrl?: string, call?: EngraveCall): Promise<EngraveReply | null>;
83
+ /**
84
+ * Starts loading Verovio (from `verovioUrl`, checked against `integrity`
85
+ * when given) with no job, so a first score is quicker. Does nothing if
86
+ * a worker has Verovio loaded or is busy: there is one load to share.
37
87
  */
38
- engrave(key: object, text: string, width: number, verovioUrl?: string): Promise<EngraveReply | null>;
88
+ preload(verovioUrl?: string, integrity?: string): void;
39
89
  };
40
- /** An engine over one worker made on first use; a crashed worker is replaced on the next call. */
41
- export declare function createEngine(makeWorker: () => WorkerLike): Engine;
90
+ /** How long one job may engrave, from its worker's Verovio being ready, before the worker is cut off and the request rejects. */
91
+ export declare const JOB_DEADLINE_MS = 20000;
92
+ /** How long a worker may take to load Verovio for a job (a 7 MB download and compile on a slow line) before it is cut off. */
93
+ export declare const LOAD_DEADLINE_MS = 60000;
94
+ /**
95
+ * How long a job no one waits for any more (a newer request from its
96
+ * element superseded it) may engrave before its worker is cut off. Most
97
+ * jobs finish well within it, even on a slow device, and keeping the
98
+ * worker keeps its loaded Verovio. A job still loading Verovio is never
99
+ * cut for this: the load serves the next job.
100
+ */
101
+ export declare const SUPERSEDED_GRACE_MS = 3000;
102
+ export type EngineOptions = {
103
+ deadline?: number;
104
+ loadDeadline?: number;
105
+ grace?: number;
106
+ };
107
+ /**
108
+ * An engine over one worker made on first use, given one job at a time. A
109
+ * job whose worker crashes, or whose Verovio load or engraving runs past
110
+ * its deadline, rejects; one superseded and past its grace is dropped.
111
+ * Either way the worker is terminated and a fresh one (loading the
112
+ * Verovio the first one loaded) takes the requests still waiting.
113
+ */
114
+ export declare function createEngine(makeWorker: () => WorkerLike, options?: EngineOptions): Engine;
42
115
  /** The page's single shared engine, over one real module `Worker` made on first use. */
43
116
  export declare function engine(): Engine;
package/dist/engine.js CHANGED
@@ -1,48 +1,191 @@
1
- /** An engine over one worker made on first use; a crashed worker is replaced on the next call. */
2
- export function createEngine(makeWorker) {
1
+ /** How long one job may engrave, from its worker's Verovio being ready, before the worker is cut off and the request rejects. */
2
+ export const JOB_DEADLINE_MS = 20_000;
3
+ /** How long a worker may take to load Verovio for a job (a 7 MB download and compile on a slow line) before it is cut off. */
4
+ export const LOAD_DEADLINE_MS = 60_000;
5
+ /**
6
+ * How long a job no one waits for any more (a newer request from its
7
+ * element superseded it) may engrave before its worker is cut off. Most
8
+ * jobs finish well within it, even on a slow device, and keeping the
9
+ * worker keeps its loaded Verovio. A job still loading Verovio is never
10
+ * cut for this: the load serves the next job.
11
+ */
12
+ export const SUPERSEDED_GRACE_MS = 3_000;
13
+ const FAILED = "The score engine failed";
14
+ const isReady = (m) => "loaded" in m;
15
+ const isProgress = (m) => "status" in m;
16
+ const UNMEASURED = { phase: "download", fraction: null, bytes: null };
17
+ const ENGRAVING = { phase: "engrave" };
18
+ /** `source` without its absent fields (so a request carries no `verovioUrl: undefined`). */
19
+ const present = ({ verovioUrl, verovioIntegrity, }) => ({
20
+ ...(verovioUrl === undefined ? {} : { verovioUrl }),
21
+ ...(verovioUrl === undefined || verovioIntegrity === undefined ? {} : { verovioIntegrity }),
22
+ });
23
+ const clear = (job) => {
24
+ for (const t of job.timers)
25
+ clearTimeout(t);
26
+ job.timers = [];
27
+ };
28
+ /**
29
+ * An engine over one worker made on first use, given one job at a time. A
30
+ * job whose worker crashes, or whose Verovio load or engraving runs past
31
+ * its deadline, rejects; one superseded and past its grace is dropped.
32
+ * Either way the worker is terminated and a fresh one (loading the
33
+ * Verovio the first one loaded) takes the requests still waiting.
34
+ */
35
+ export function createEngine(makeWorker, options = {}) {
36
+ const deadline = options.deadline ?? JOB_DEADLINE_MS;
37
+ const loadDeadline = options.loadDeadline ?? LOAD_DEADLINE_MS;
38
+ const grace = options.grace ?? SUPERSEDED_GRACE_MS;
3
39
  let worker = null;
40
+ let running = null;
41
+ let loaded;
42
+ /** Whether the current worker has its Verovio loaded. */
43
+ let warm = false;
44
+ /** The engine's status, as a new caller first hears it. */
45
+ let status = UNMEASURED;
4
46
  let nextId = 0;
47
+ const waiting = [];
5
48
  const pending = new Map();
6
49
  const newest = new WeakMap();
7
- const fail = (w) => {
8
- if (worker !== w)
50
+ /** Preload jobs: no one waits on them, and they end at `Ready`. */
51
+ const preloads = new Set();
52
+ const settle = (id) => {
53
+ const p = pending.get(id);
54
+ pending.delete(id);
55
+ return p;
56
+ };
57
+ /** Cuts off the job `id` if the worker is still on it (rejecting it for `reason`, if given), and moves on to the next. */
58
+ const cut = (id, reason) => {
59
+ if (running?.id !== id)
9
60
  return;
61
+ clear(running);
62
+ running = null;
63
+ const w = worker;
10
64
  worker = null;
11
- w.terminate();
12
- const all = [...pending.values()];
13
- pending.clear();
14
- for (const p of all)
15
- p.reject(new Error("The score engine failed"));
65
+ warm = false;
66
+ preloads.delete(id);
67
+ w?.terminate();
68
+ if (reason !== null)
69
+ settle(id)?.reject(new Error(reason));
70
+ // A fresh worker loads Verovio again: the callers still waiting hear it from the start.
71
+ tell(UNMEASURED);
72
+ next();
73
+ };
74
+ const overdue = (id, what) => () => cut(id, `${FAILED}: ${what} took too long`);
75
+ /** Tells every waiting caller the engine's new status. */
76
+ const tell = (now) => {
77
+ status = now;
78
+ for (const p of pending.values())
79
+ p.onStatus?.(now);
80
+ };
81
+ /** Verovio is ready: the job's engraving deadline and its grace start now; a preload is done. */
82
+ const onReady = (job, ready) => {
83
+ loaded ??= ready.loaded;
84
+ warm = true;
85
+ // A preload's Ready engraves nothing: the job behind it hears "engrave" at its own Ready.
86
+ if (preloads.has(job.id)) {
87
+ finish(job);
88
+ return next();
89
+ }
90
+ tell(ENGRAVING);
91
+ clear(job);
92
+ job.timers = [
93
+ setTimeout(overdue(job.id, "engraving"), deadline),
94
+ setTimeout(() => {
95
+ job.graceOver = true;
96
+ if (job.superseded)
97
+ cut(job.id, null);
98
+ }, grace),
99
+ ];
100
+ };
101
+ /** The worker is done with `job`. */
102
+ const finish = (job) => {
103
+ clear(job);
104
+ running = null;
105
+ preloads.delete(job.id);
106
+ };
107
+ const onReply = (job, reply) => {
108
+ finish(job);
109
+ settle(reply.id)?.resolve(reply);
110
+ next();
16
111
  };
17
112
  const start = () => {
18
113
  if (worker)
19
114
  return worker;
20
115
  const w = makeWorker();
21
- w.onmessage = (e) => {
22
- const p = pending.get(e.data.id);
23
- if (!p)
116
+ w.onmessage = ({ data }) => {
117
+ const job = running;
118
+ if (worker !== w || job?.id !== data.id)
24
119
  return;
25
- pending.delete(e.data.id);
26
- p.resolve(newest.get(p.key) === e.data.id ? e.data : null);
120
+ if (isProgress(data))
121
+ tell(data.status);
122
+ else if (isReady(data))
123
+ onReady(job, data);
124
+ else
125
+ onReply(job, data);
126
+ };
127
+ w.onerror = () => {
128
+ if (worker === w && running)
129
+ cut(running.id, FAILED);
27
130
  };
28
- w.onerror = () => fail(w);
29
131
  worker = w;
30
132
  return w;
31
133
  };
134
+ /** Gives the worker the next job, if it is free: the Verovio it loaded first, whatever the request asks. */
135
+ const next = () => {
136
+ const request = running ? undefined : waiting.shift();
137
+ if (!request)
138
+ return;
139
+ const { verovioUrl, verovioIntegrity, ...rest } = request;
140
+ const id = rest.id;
141
+ running = { id, superseded: false, graceOver: false, timers: [] };
142
+ running.timers = [setTimeout(overdue(id, "loading Verovio"), loadDeadline)];
143
+ start().postMessage({ ...rest, ...present(loaded ?? { verovioUrl, verovioIntegrity }) });
144
+ };
145
+ /** No one waits for `id` any more: drop it if it waits its turn, cut it off past its grace if it runs. */
146
+ const supersede = (id) => {
147
+ settle(id)?.resolve(null);
148
+ const at = waiting.findIndex((r) => r.id === id);
149
+ if (at >= 0)
150
+ waiting.splice(at, 1);
151
+ if (running?.id !== id)
152
+ return;
153
+ running.superseded = true;
154
+ if (running.graceOver)
155
+ cut(id, null);
156
+ };
32
157
  return {
33
- engrave(key, text, width, verovioUrl) {
34
- const w = start();
158
+ engrave(key, text, width, verovioUrl, call = {}) {
35
159
  const id = ++nextId;
36
160
  const before = newest.get(key);
37
- if (before !== undefined) {
38
- pending.get(before)?.resolve(null);
39
- pending.delete(before);
40
- }
41
161
  newest.set(key, id);
42
162
  return new Promise((resolve, reject) => {
43
- pending.set(id, { key, resolve, reject });
44
- w.postMessage(verovioUrl === undefined ? { id, text, width } : { id, text, width, verovioUrl });
163
+ pending.set(id, { resolve, reject, onStatus: call.onStatus });
164
+ call.onStatus?.(warm ? ENGRAVING : status);
165
+ if (before !== undefined)
166
+ supersede(before);
167
+ waiting.push({
168
+ id,
169
+ text,
170
+ width,
171
+ ...present({ verovioUrl, verovioIntegrity: call.integrity }),
172
+ });
173
+ next();
174
+ });
175
+ },
176
+ preload(verovioUrl, integrity) {
177
+ if (warm || running || waiting.length > 0)
178
+ return;
179
+ const id = ++nextId;
180
+ preloads.add(id);
181
+ waiting.push({
182
+ id,
183
+ text: "",
184
+ width: 0,
185
+ preload: true,
186
+ ...present({ verovioUrl, verovioIntegrity: integrity }),
45
187
  });
188
+ next();
46
189
  },
47
190
  };
48
191
  }
package/dist/engrave.d.ts CHANGED
@@ -1,11 +1,35 @@
1
- import type { ChartDiagnostic } from "barmark";
1
+ import { type ChartDiagnostic, type ChartParse } from "barmark";
2
2
  import type { VerovioToolkit } from "verovio/esm";
3
3
  export type EngraveOptions = {
4
4
  /** The width available, in CSS pixels; below 320 it is 320. */
5
5
  width: number;
6
6
  /** Verovio's scale (default 40). */
7
7
  scale?: number;
8
+ /** The most the score may cost (`scoreCost`, about the bytes of MusicXML it writes); default `MAX_SCORE_COST`. */
9
+ maxCost?: number;
10
+ /** The longest MusicXML engraved, in characters: the export stops writing past it; default `MAX_XML_LENGTH`. */
11
+ maxXmlLength?: number;
8
12
  };
13
+ /**
14
+ * The most a score may cost (`scoreCost`, about the bytes of MusicXML it
15
+ * writes) before it is refused, unexported: a short chart with repeats can
16
+ * play thousands of bars, and writing each out could take gigabytes. A
17
+ * long lead sheet costs about half a megabyte.
18
+ */
19
+ export declare const MAX_SCORE_COST = 50000000;
20
+ /** The longest MusicXML handed to Verovio, in characters: the export stops writing past it (`maxLength`). */
21
+ export declare const MAX_XML_LENGTH = 50000000;
22
+ /**
23
+ * About how many bytes of MusicXML a score of the chart writes: every
24
+ * played bar's measure in every declared part (tacet ones too), each
25
+ * slot, pitch, degree, syllable and words, with the length of its text,
26
+ * and its heading. One pass over the play order, cheap enough to refuse a
27
+ * chart before exporting it. It is an early gate, not the bound: it
28
+ * leaves out what is rarely large (a part's silent lines, text lines), and
29
+ * the export's own `maxLength` budget, which `engraveChart` sets, is what
30
+ * keeps the MusicXML within `MAX_XML_LENGTH`.
31
+ */
32
+ export declare function scoreCost(parse: ChartParse): number;
9
33
  export type Engraved = {
10
34
  ok: true;
11
35
  svg: string;
@@ -37,5 +61,9 @@ export declare function engraveXml(vrv: VerovioToolkit, xml: string, options: En
37
61
  svg: string;
38
62
  pages: number;
39
63
  };
40
- /** A chart as a full score, or why it cannot be one. */
64
+ /**
65
+ * A chart as a full score, or why it cannot be one. A chart that would
66
+ * cost more than `maxCost` is refused before it is exported, and the
67
+ * export stops writing MusicXML longer than `maxXmlLength`.
68
+ */
41
69
  export declare function engraveChart(vrv: VerovioToolkit, text: string, options: EngraveOptions): Engraved;