millirec 0.1.0 → 0.1.1

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/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1
4
+
5
+ - **Bundlers**: the package found its own folder with `new URL('./', import.meta.url)`, which Vite
6
+ and webpack 5 rewrite into a reference to the module FILE, so `loadSet()` fetched
7
+ `…/index.js/sets/digits.json`. The folder is now sliced from `import.meta.url`. With a bundler,
8
+ copy `dist/char-lite/` / `dist/char-cnn/` to your site and pass `assetBase` (README "Serving the
9
+ files", with Vite and webpack recipes; the old `optimizeDeps` advice did not work in 0.1.0; with this fix `optimizeDeps: { exclude: ['millirec'] }` works in Vite dev only, and builds still need the copy).
10
+ - **Clear errors when the files are not served**: `loadSet`, `loadOption`, the CNN model/kernel
11
+ loader and char-lite's worker/wasm boot now say which URL failed, what came back (a 404, an HTML
12
+ page from an SPA fallback, unparseable JSON) and what to do, instead of failing in `JSON.parse` or
13
+ the matcher.
14
+ - `"sideEffects"` lists the script-tag files (`dist/**/*.min.js`, `sets/*.js`, `options/*.js`) so a
15
+ bundler keeps `import 'millirec/overlap/millirec-overlap.min.js'`.
16
+ - `destroy()`: char-lite resolves pending and later `recognize()`/`rawScores()` with `null`;
17
+ char-cnn's `personalize()` returns `null`, `embedding()` throws `millirec: recognizer destroyed`,
18
+ `depersonalize()` is a no-op (they used to read past an empty stage list).
19
+ - char-cnn runs in a Web Worker (draws on `OffscreenCanvas`); webpack no longer tries to bundle the
20
+ kernel's dynamic import (`webpackIgnore`).
21
+ - Node / SSR: `create()` outside a browser throws a message saying so; `loadSet`/`loadOption` in
22
+ Node say to import the JSON instead.
23
+ - `MillirecCharCnn.create('fast')` = `create({ option: 'fast' })`.
24
+ - char-lite's result cache is an LRU of 256 (it grew without bound).
25
+ - Types: `Training.version` is `number` (and `mode` a string) so an imported set JSON type-checks;
26
+ `millirec:result` / `millirec:clear` are typed on `HTMLElementEventMap`; declarations for the
27
+ overlap widget's global (`import type {} from 'millirec/overlap'`); `typesVersions` for
28
+ `moduleResolution: node10`.
29
+ - package.json: `bugs`, `engines` (node ≥ 18, for tooling that imports the JSON).
30
+ - README: browser-only note, `destroy()`, the pad's options and events, overlap gzip sizes,
31
+ stable paths.
32
+
33
+ ## 0.1.0
34
+
35
+ First release.
package/README.md CHANGED
@@ -10,7 +10,7 @@ Three pieces, pick by what you need to read:
10
10
  |---|---|---|---|
11
11
  | `millirec/char-lite` | anything you have samples for: digits, letters, punctuation, emoji, made-up symbols | 26 KB + the training set (digits 4 KB, all 27 KB) | **yes** — add samples, add whole new classes |
12
12
  | `millirec/char-cnn` | capital letters A–Z | 15 KB (`small`) to 47 KB (`fast`); `accurate` 42 KB | refit on a writer's own letters (`personalize`) |
13
- | overlap (script tag) | whole words written letter over letter in one box | 52 KB + training | — |
13
+ | overlap (script tag) | whole words written letter over letter in one box | 34 KB (script 20 + wasm 14) + training (capitals 19 KB, all 42 KB) + the default word list (38 KB, skipped when you pass `words`) | — |
14
14
 
15
15
  ## Install
16
16
 
@@ -21,6 +21,12 @@ npm install millirec
21
21
  `import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
22
22
  (use `import`, not `require`), or the script-tag builds below.
23
23
 
24
+ **Browser only.** Recognition needs a browser: char-lite runs its matcher in a Web Worker, char-cnn
25
+ draws strokes on a canvas (an `OffscreenCanvas` inside a worker works too). Importing the package
26
+ is safe during server-side rendering; call `create()` on the client. In Node, `create()` throws a
27
+ message saying so, and the training sets can be imported as JSON
28
+ (`import digits from 'millirec/char-lite/sets/digits.json' with { type: 'json' }`) for tooling.
29
+
24
30
  ## char-lite
25
31
 
26
32
  ```js
@@ -37,8 +43,41 @@ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
37
43
 
38
44
  // or your own strokes: arrays of {x, y} points
39
45
  await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
46
+
47
+ rec.destroy() // when you are done with it
40
48
  ```
41
49
 
50
+ Each char-lite instance holds a Web Worker and its own copy of the wasm matcher, so call
51
+ `destroy()` when a recognizer is no longer needed (and share one recognizer between several pads
52
+ rather than creating one per pad). After `destroy()`, `recognize()` and `rawScores()` resolve
53
+ `null`, including calls that were still waiting.
54
+
55
+ ### The drawing pad
56
+
57
+ `attach(el, options)` mounts a canvas in `el` and returns a `Pad` (`clear()`, `undoClear()`,
58
+ `getStrokes()`, `isStale()`, `configure()`, `setInk()`, `repaint()`, `canvas`). Options:
59
+
60
+ | option | default | |
61
+ |---|---|---|
62
+ | `width`, `height` | 240, 240 | pad size in CSS px |
63
+ | `ink` | `'#1e293b'` | ink colour |
64
+ | `idleOverwrite` | 2 | seconds of pen-up after which the next stroke starts a new character (0 = off) |
65
+ | `scribbleClear` | true | scribbling over the character throws it away |
66
+ | `scribble` | null | overrides for the scribble detector's bars (`turns`, `retrace`, `winding`, `cover`) |
67
+ | `staleAlpha` | 0.3 | opacity of ink once the character has settled (1 keeps it solid) |
68
+ | `onStale` | — | `(stale) => void`, called on every change of the settled state |
69
+
70
+ `el` fires two events:
71
+
72
+ - `millirec:result` — after every stroke, `detail = { results, strokes }` (`results` is the top
73
+ three `{ char, prob }`; an empty pad reports `results: []`, so a reading of ink that is gone can be
74
+ cleared);
75
+ - `millirec:clear` — the pad dropped its own ink, `detail = { reason: 'idle' | 'scribble', undo }`;
76
+ `undo()` puts it back.
77
+
78
+ Both are typed on `HTMLElementEventMap`, so `el.addEventListener('millirec:result', (e) => e.detail.results)`
79
+ type-checks. char-cnn's `attach()` takes the same options and fires the same events.
80
+
42
81
  ### Training on your users' strokes
43
82
 
44
83
  A class name is any string, so a recognizer can learn one person's hand, or
@@ -65,13 +104,18 @@ training set can also be built offline and loaded with `fetch`.
65
104
  ```js
66
105
  import { MillirecCharCnn } from 'millirec/char-cnn'
67
106
 
68
- const rec = await MillirecCharCnn.create() // 'accurate' (default), 'fast' or 'small'
107
+ const rec = await MillirecCharCnn.create() // the 'accurate' option
108
+ // or: await MillirecCharCnn.create({ option: 'fast' }) // 'accurate' | 'fast' | 'small'
109
+ // (a bare name works too: create('fast'))
69
110
  rec.attach(document.querySelector('#pad'))
70
111
  await rec.recognize(strokes, { only: 'AEIOU' }) // restrict the answer to some letters
71
112
  await rec.personalize({ A: [a1, a2, a3], R: [r1, r2] }) // lean toward this writer's hand
113
+ rec.destroy() // let go of the models
72
114
  ```
73
115
 
74
- `millirec/char-cnn/core` is the same recognizer without the drawing pad.
116
+ `millirec/char-cnn/core` is the same recognizer without the drawing pad; it also runs inside a
117
+ Web Worker (it draws on an `OffscreenCanvas` there). After `destroy()`, `recognize()` and
118
+ `personalize()` return `null` and `embedding()` throws.
75
119
 
76
120
  ## overlap: words written in one box
77
121
 
@@ -88,23 +132,59 @@ for now:
88
132
 
89
133
  Copy `dist/overlap/` to your site (or load it from a CDN); the script finds its wasm, training and
90
134
  default word list beside itself. `set` is `capitals`, `lowercase`, `digits`, `punctuation` or `all`.
135
+ TypeScript declarations for the `MillirecOverlap` global and its `millirec-overlap:*` events come
136
+ with `import type {} from 'millirec/overlap'` (types only — the widget itself is the script tag).
91
137
 
92
138
  ## Serving the files
93
139
 
94
- The recognizers load a worker, a wasm file and model files at run time, from
95
- the folder the module itself is in. That works as-is when the browser loads the
96
- package files directly (no bundler, or a bundler that copies them). If your
97
- bundler moves the JavaScript somewhere else, copy the folder and say where it
98
- is:
140
+ The recognizers load a worker, a wasm file, training sets and model files at run time, by default
141
+ from the folder the module itself is in. That works as-is when the browser loads the package's
142
+ files where they are — no bundler, an import map, or a dev server that serves `node_modules`.
143
+
144
+ **With a bundler** (Vite, webpack, Rollup, esbuild, Parcel …) the JavaScript is moved into your
145
+ bundle and the other files are not emitted with it. Copy the recognizer's folder into the folder
146
+ your site serves as-is, and pass its URL as `assetBase` to every call that loads something:
147
+
148
+ ```js
149
+ import { MillirecCharLite, loadSet } from 'millirec'
150
+ import { MillirecCharCnn } from 'millirec/char-cnn'
151
+
152
+ const lite = '/millirec/char-lite/' // copied from node_modules/millirec/dist/char-lite/
153
+ const training = await loadSet('digits', { assetBase: lite })
154
+ const rec = await MillirecCharLite.create({ training, assetBase: lite })
155
+
156
+ const cnn = await MillirecCharCnn.create({ option: 'fast', assetBase: '/millirec/char-cnn/' }) // dist/char-cnn/
157
+ // loadOption(name, { assetBase }) takes it too
158
+ ```
159
+
160
+ Vite — copy into `public/`, which is served (and copied into the build) unchanged:
161
+
162
+ ```sh
163
+ mkdir -p public/millirec
164
+ cp -R node_modules/millirec/dist/char-lite node_modules/millirec/dist/char-cnn public/millirec/
165
+ ```
166
+
167
+ (a `postinstall` script with those two lines keeps it in step with the installed version).
168
+ In `vite` dev alone, `optimizeDeps: { exclude: ['millirec'] }` also works without copying (the dev
169
+ server then serves the package from `node_modules`), but `vite build` does not emit the files, so a
170
+ production build still needs the copy and `assetBase`.
171
+
172
+ webpack 5 — with `copy-webpack-plugin`:
99
173
 
100
174
  ```js
101
- // copy node_modules/millirec/dist/char-lite/ to /millirec/char-lite/ on your site
102
- await MillirecCharLite.create({ training, assetBase: '/millirec/char-lite/' })
175
+ // webpack.config.js
176
+ import CopyPlugin from 'copy-webpack-plugin'
177
+ export default {
178
+ plugins: [new CopyPlugin({ patterns: [
179
+ { from: 'node_modules/millirec/dist/char-lite', to: 'millirec/char-lite' },
180
+ { from: 'node_modules/millirec/dist/char-cnn', to: 'millirec/char-cnn' },
181
+ ] })],
182
+ }
103
183
  ```
104
184
 
105
185
  `assetBase` may be absolute, root-relative or relative to the page, with or without the trailing
106
- slash. With Vite, either do that or exclude the package from dependency pre-bundling
107
- (`optimizeDeps: { exclude: ['millirec'] }`).
186
+ slash. If the files are not there, the error names the URL it tried and what came back (a dev
187
+ server's index.html fallback is recognised as such) instead of failing inside the matcher.
108
188
 
109
189
  **`assetBase` (and char-cnn's `kernel`) decide which code is loaded** — the worker and kernel are
110
190
  fetched from there and run. Set them in your own code; never fill them from a URL parameter, a
@@ -136,6 +216,14 @@ No build step needed:
136
216
  script finds its worker and wasm next to itself, on any origin that sends CORS
137
217
  headers (jsDelivr and unpkg do).
138
218
 
219
+ ## Stable paths
220
+
221
+ The documented entry points are the stable API: `millirec`, `millirec/char-lite`,
222
+ `millirec/char-cnn`, `millirec/char-cnn/core`, `millirec/char-lite/sets/<name>.json`,
223
+ `millirec/char-cnn/options/<name>.json`, `millirec/overlap/<file>` and the script-tag files in "Script tag / CDN"
224
+ above. `millirec/dist/*` exposes every built file as an escape hatch; the layout under it may change
225
+ in any release.
226
+
139
227
  ## Where the data comes from
140
228
 
141
229
  - **char-lite training sets and the overlap templates**: one writer's own handwriting, drawn for
@@ -17,19 +17,20 @@ export type OptionName = (typeof OPTIONS)[number]
17
17
  export declare function loadOption(name: OptionName, opts?: { assetBase?: string }): Promise<CnnConfig>
18
18
 
19
19
  export declare class MillirecCharCnnCore {
20
- static create(opts?: CreateOptions): Promise<MillirecCharCnnCore>
20
+ /** A string is a shipped option's name: create('fast') = create({ option: 'fast' }). */
21
+ static create(opts?: CreateOptions | OptionName): Promise<MillirecCharCnnCore>
21
22
  readonly classes: string[]
22
23
  readonly ready: Promise<void>
23
24
  /** `only` restricts the reading to these classes. */
24
- recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] }): Promise<(Reading[] & { stage?: number }) | null>
25
+ recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] | Set<string> }): Promise<(Reading[] & { stage?: number }) | null>
25
26
  /** Refit the last stage's head on your own drawings: { 'A': [strokes, ...], ... }.
26
27
  * Anchored to the shipped head, so a few samples nudge a letter and many take it over.
27
28
  * Classes outside `classes` are ignored (the CNN cannot learn new characters this way). */
28
29
  personalize(samples: Record<string, Array<Strokes | Stroke>>, opts?: { steps?: number; lr?: number; prior?: number }): Promise<{ n: number; classes: string[] } | null>
29
30
  /** Back to the shipped head. */
30
31
  depersonalize(): void
31
- /** The last stage's unit embedding of a drawing — what the head reads. */
32
+ /** The last stage's unit embedding of a drawing — what the head reads. Throws after destroy(). */
32
33
  embedding(strokes: Strokes | Stroke): Promise<Float32Array>
33
- /** Let go of the models; recognize() returns null afterwards. */
34
+ /** Let go of the models; recognize() and personalize() return null afterwards. */
34
35
  destroy(): void
35
36
  }
@@ -299,6 +299,33 @@ function assetBaseOf(base) {
299
299
  return typeof location !== "undefined" ? new URL(s, location.href).href : s;
300
300
  }
301
301
  var asStrokes = (s) => Array.isArray(s) && s.length && !Array.isArray(s[0]) ? [s] : s;
302
+ var notServed = (url2, what, base, recognizer) => new Error(`millirec: ${url2} is not ${what} \u2014 the package files are not served at ${base}; copy node_modules/millirec/dist/${recognizer}/ and pass assetBase (see README "Serving the files")`);
303
+ async function fetchAsset(url2, { as = "json", what, base, recognizer }) {
304
+ const fail = (detail) => {
305
+ const e = notServed(url2, what, base, recognizer);
306
+ if (detail) e.message += ` (${detail})`;
307
+ return e;
308
+ };
309
+ let r;
310
+ try {
311
+ r = await fetch(url2);
312
+ } catch (e) {
313
+ throw fail(e && e.message);
314
+ }
315
+ const type = r.headers && r.headers.get("content-type") || "";
316
+ if (!r.ok) throw fail(`HTTP ${r.status}`);
317
+ if (as === "json") {
318
+ try {
319
+ return await r.json();
320
+ } catch (e) {
321
+ throw fail(/html/i.test(type) ? "an HTML page" : e && e.message);
322
+ }
323
+ }
324
+ const buf = await r.arrayBuffer();
325
+ const head = String.fromCharCode(...new Uint8Array(buf, 0, Math.min(buf.byteLength, 16))).trimStart().toLowerCase();
326
+ if (head.startsWith("<!doctype") || head.startsWith("<html")) throw fail("an HTML page");
327
+ return buf;
328
+ }
302
329
 
303
330
  // ../../library/src/char-cnn-core.js
304
331
  function scriptBase() {
@@ -306,15 +333,17 @@ function scriptBase() {
306
333
  return src ? src.slice(0, src.lastIndexOf("/") + 1) : "";
307
334
  }
308
335
  var ASSET_BASE = scriptBase();
309
- var fetchBuf = (url) => fetch(url).then((r) => {
310
- if (!r.ok) throw new Error(`${url}: ${r.status}`);
311
- return r.arrayBuffer();
312
- });
336
+ var fetchBuf = (url2, base) => fetchAsset(url2, { as: "buf", what: "a char-cnn model file", base, recognizer: "char-cnn" });
337
+ var DESTROYED = "millirec: recognizer destroyed";
338
+ var makeCanvas = (n) => typeof document !== "undefined" && document.createElement ? Object.assign(document.createElement("canvas"), { width: n, height: n }) : typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(n, n) : null;
313
339
  var MillirecCharCnnCore = class {
314
340
  static async create(opts = {}) {
315
341
  const g = typeof window !== "undefined" ? window : globalThis;
316
342
  const config = { ...g.MILLIREC_CNN || {}, ...opts };
317
343
  if (!config.stages || !config.stages.length) throw new Error("MillirecCharCnn: no stages configured");
344
+ if (typeof fetch === "undefined" || typeof document === "undefined" && typeof OffscreenCanvas === "undefined") {
345
+ throw new Error("millirec: char-cnn needs a browser (fetch, and a canvas or OffscreenCanvas); importing is SSR-safe but call create() on the client");
346
+ }
318
347
  const inst = new this(config);
319
348
  await inst.ready;
320
349
  return inst;
@@ -324,26 +353,35 @@ var MillirecCharCnnCore = class {
324
353
  this.base = assetBaseOf(config.assetBase || ASSET_BASE);
325
354
  this.classes = typeof config.classes === "string" ? config.classes.split("") : config.classes;
326
355
  this.stages = [];
327
- this.off = typeof document !== "undefined" ? document.createElement("canvas") : null;
328
- if (this.off) {
329
- this.off.width = this.off.height = 140;
330
- this.octx = this.off.getContext("2d", { willReadFrequently: true });
331
- }
356
+ this.off = makeCanvas(140);
357
+ this.octx = this.off ? this.off.getContext("2d", { willReadFrequently: true }) : null;
332
358
  this.ready = this.load();
333
359
  }
334
360
  async load() {
335
361
  const { base, config } = this;
336
362
  let factory = null;
337
- if (config.kernel) factory = (await import(
338
- /* @vite-ignore */
339
- base + config.kernel
340
- )).default;
363
+ if (config.kernel) {
364
+ const url2 = base + config.kernel;
365
+ try {
366
+ factory = (await import(
367
+ /* @vite-ignore */
368
+ /* webpackIgnore: true */
369
+ url2
370
+ )).default;
371
+ } catch (e) {
372
+ const err = notServed(url2, "the char-cnn kernel", base, "char-cnn");
373
+ err.message += ` (${e && e.message})`;
374
+ throw err;
375
+ }
376
+ }
341
377
  for (const st of config.stages) {
342
- const [modelBuf, headBuf] = await Promise.all([fetchBuf(base + st.model), fetchBuf(base + st.head)]);
378
+ const [modelBuf, headBuf] = await Promise.all([fetchBuf(base + st.model, base), fetchBuf(base + st.head, base)]);
379
+ if (this.destroyed) return;
343
380
  const head = parseHead(headBuf);
344
381
  const stage = { theta: st.theta == null ? null : st.theta, head, headNorm: st.headNorm !== false, size: 0 };
345
382
  if (factory) {
346
383
  const M = await factory();
384
+ if (this.destroyed) return;
347
385
  const bytes = expandToInt8(new Uint8Array(modelBuf));
348
386
  const ptr = M._malloc(bytes.byteLength);
349
387
  M.HEAPU8.set(bytes, ptr);
@@ -376,6 +414,7 @@ var MillirecCharCnnCore = class {
376
414
  * The canvas draw + readback is the dear part (~1 ms) and is shared by every
377
415
  * stage of one recognize() call; only the resample differs per size. */
378
416
  raster(strokes, size) {
417
+ if (!this.octx) throw new Error("millirec: char-cnn needs a canvas to draw strokes on (a document, or OffscreenCanvas in a worker)");
379
418
  if (this._planeFor !== strokes) {
380
419
  const W2 = drawStrokes(this.octx, strokes);
381
420
  this._plane = { ink: inkPlane(this.octx.getImageData(0, 0, W2, W2).data, W2, W2), W: W2 };
@@ -394,7 +433,7 @@ var MillirecCharCnnCore = class {
394
433
  strokes = asStrokes(strokes);
395
434
  if (!strokes || !strokes.length) return null;
396
435
  await this.ready;
397
- if (!this.stages.length) return null;
436
+ if (this.destroyed || !this.stages.length) return null;
398
437
  this._planeFor = null;
399
438
  const keep = only ? new Set(only) : null;
400
439
  let z = null, used = 0;
@@ -432,6 +471,7 @@ var MillirecCharCnnCore = class {
432
471
  async embedding(strokes) {
433
472
  strokes = asStrokes(strokes);
434
473
  await this.ready;
474
+ if (this.destroyed || !this.stages.length) throw new Error(DESTROYED);
435
475
  this._planeFor = null;
436
476
  const st = this.stages[this.stages.length - 1];
437
477
  return st.embed(this.raster(strokes, st.size));
@@ -446,6 +486,7 @@ var MillirecCharCnnCore = class {
446
486
  */
447
487
  async personalize(samples, { steps = 250, lr = 0.5, prior = 1 } = {}) {
448
488
  await this.ready;
489
+ if (this.destroyed || !this.stages.length) return null;
449
490
  const st = this.stages[this.stages.length - 1];
450
491
  const H0 = st.head0 || (st.head0 = st.head);
451
492
  const X = [], Y = [];
@@ -459,6 +500,7 @@ var MillirecCharCnnCore = class {
459
500
  Y.push(c);
460
501
  }
461
502
  }
503
+ if (this.destroyed) return null;
462
504
  if (!X.length) {
463
505
  st.head = H0;
464
506
  this.personal = null;
@@ -490,8 +532,9 @@ var MillirecCharCnnCore = class {
490
532
  this.personal = { n, classes: [...new Set(Y)].map((c) => this.classes[c]).sort() };
491
533
  return this.personal;
492
534
  }
493
- /** Let go of the models and kernels; recognize() returns null afterwards. */
535
+ /** Let go of the models and kernels; recognize() and personalize() return null afterwards, embedding() throws. */
494
536
  destroy() {
537
+ this.destroyed = true;
495
538
  this.stages = [];
496
539
  this.personal = null;
497
540
  this._plane = null;
@@ -499,23 +542,38 @@ var MillirecCharCnnCore = class {
499
542
  }
500
543
  depersonalize() {
501
544
  const st = this.stages[this.stages.length - 1];
502
- if (st.head0) st.head = st.head0;
545
+ if (st && st.head0) st.head = st.head0;
503
546
  this.personal = null;
504
547
  }
505
548
  };
506
549
  if (typeof window !== "undefined" && false) window.MillirecCharCnn = MillirecCharCnnCore;
507
550
 
551
+ // src/here.js
552
+ var url = (import.meta.url || "").replace(/[?#].*$/, "");
553
+ var HERE = url.slice(0, url.lastIndexOf("/") + 1);
554
+ function nodeFileUrl(url2, spec) {
555
+ const g = globalThis;
556
+ const node = typeof g.process !== "undefined" && g.process.versions && g.process.versions.node && typeof g.Deno === "undefined" && typeof g.Bun === "undefined";
557
+ if (url2.startsWith("file:") && node && typeof document === "undefined" && typeof WorkerGlobalScope === "undefined") {
558
+ throw new Error(`millirec: cannot fetch ${url2} outside a browser \u2014 in Node, import the JSON instead: import x from '${spec}' with { type: 'json' }`);
559
+ }
560
+ }
561
+
508
562
  // src/options.js
509
- var HERE = new URL("./", import.meta.url).href;
510
563
  var OPTIONS = ["accurate", "fast", "small"];
511
564
  async function loadOption(name, { assetBase = HERE } = {}) {
512
565
  if (!OPTIONS.includes(name)) throw new Error(`millirec: no CNN option "${name}" (one of ${OPTIONS.join(", ")})`);
513
- const url = new URL(`options/${name}.json`, assetBaseOf(assetBase));
514
- const r = await fetch(url);
515
- if (!r.ok) throw new Error(`millirec: ${url}: ${r.status}`);
516
- return r.json();
566
+ const base = assetBaseOf(assetBase);
567
+ const url2 = new URL(`options/${name}.json`, base).href;
568
+ nodeFileUrl(url2, `millirec/char-cnn/options/${name}.json`);
569
+ return fetchAsset(url2, { what: `the ${name} CNN option`, base, recognizer: "char-cnn" });
517
570
  }
518
571
  async function withOption(opts) {
572
+ if (typeof opts === "string") opts = { option: opts };
573
+ opts = opts || {};
574
+ if (typeof document === "undefined" && typeof OffscreenCanvas === "undefined") {
575
+ throw new Error("millirec: char-cnn needs a browser (fetch, and a canvas or OffscreenCanvas); importing is SSR-safe but call create() on the client");
576
+ }
519
577
  const assetBase = assetBaseOf(opts.assetBase || HERE);
520
578
  const preset = opts.stages ? {} : await loadOption(opts.option || "accurate", { assetBase });
521
579
  return { ...preset, ...opts, assetBase };
@@ -524,7 +582,8 @@ async function withOption(opts) {
524
582
  // src/char-cnn-core.js
525
583
  var MillirecCharCnnCore2 = class extends MillirecCharCnnCore {
526
584
  /** opts: option ('accurate' | 'fast' | 'small', default 'accurate') or your own
527
- * { classes, stages, kernel }, plus assetBase (default: this module's folder). */
585
+ * { classes, stages, kernel }, plus assetBase (default: this module's folder).
586
+ * A string is the option's name: create('fast') = create({ option: 'fast' }). */
528
587
  static async create(opts = {}) {
529
588
  return super.create(await withOption(opts));
530
589
  }
@@ -1,9 +1,10 @@
1
1
  import type { AttachOptions, Pad } from '../char-lite/index.js'
2
- import { MillirecCharCnnCore, type CreateOptions } from './core.js'
2
+ import { MillirecCharCnnCore, type CreateOptions, type OptionName } from './core.js'
3
3
 
4
+ export type { ResultDetail, ClearDetail } from '../char-lite/index.js'
4
5
  export { OPTIONS, loadOption, type OptionName, type CnnConfig, type Stage, type CreateOptions } from './core.js'
5
6
 
6
7
  export declare class MillirecCharCnn extends MillirecCharCnnCore {
7
- static create(opts?: CreateOptions): Promise<MillirecCharCnn>
8
+ static create(opts?: CreateOptions | OptionName): Promise<MillirecCharCnn>
8
9
  attach(el: HTMLElement, opts?: AttachOptions): Pad
9
10
  }
@@ -299,6 +299,33 @@ function assetBaseOf(base) {
299
299
  return typeof location !== "undefined" ? new URL(s, location.href).href : s;
300
300
  }
301
301
  var asStrokes = (s) => Array.isArray(s) && s.length && !Array.isArray(s[0]) ? [s] : s;
302
+ var notServed = (url2, what, base, recognizer) => new Error(`millirec: ${url2} is not ${what} \u2014 the package files are not served at ${base}; copy node_modules/millirec/dist/${recognizer}/ and pass assetBase (see README "Serving the files")`);
303
+ async function fetchAsset(url2, { as = "json", what, base, recognizer }) {
304
+ const fail = (detail) => {
305
+ const e = notServed(url2, what, base, recognizer);
306
+ if (detail) e.message += ` (${detail})`;
307
+ return e;
308
+ };
309
+ let r;
310
+ try {
311
+ r = await fetch(url2);
312
+ } catch (e) {
313
+ throw fail(e && e.message);
314
+ }
315
+ const type = r.headers && r.headers.get("content-type") || "";
316
+ if (!r.ok) throw fail(`HTTP ${r.status}`);
317
+ if (as === "json") {
318
+ try {
319
+ return await r.json();
320
+ } catch (e) {
321
+ throw fail(/html/i.test(type) ? "an HTML page" : e && e.message);
322
+ }
323
+ }
324
+ const buf = await r.arrayBuffer();
325
+ const head = String.fromCharCode(...new Uint8Array(buf, 0, Math.min(buf.byteLength, 16))).trimStart().toLowerCase();
326
+ if (head.startsWith("<!doctype") || head.startsWith("<html")) throw fail("an HTML page");
327
+ return buf;
328
+ }
302
329
 
303
330
  // ../../library/src/char-cnn-core.js
304
331
  function scriptBase() {
@@ -306,15 +333,17 @@ function scriptBase() {
306
333
  return src ? src.slice(0, src.lastIndexOf("/") + 1) : "";
307
334
  }
308
335
  var ASSET_BASE = scriptBase();
309
- var fetchBuf = (url) => fetch(url).then((r) => {
310
- if (!r.ok) throw new Error(`${url}: ${r.status}`);
311
- return r.arrayBuffer();
312
- });
336
+ var fetchBuf = (url2, base) => fetchAsset(url2, { as: "buf", what: "a char-cnn model file", base, recognizer: "char-cnn" });
337
+ var DESTROYED = "millirec: recognizer destroyed";
338
+ var makeCanvas = (n) => typeof document !== "undefined" && document.createElement ? Object.assign(document.createElement("canvas"), { width: n, height: n }) : typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(n, n) : null;
313
339
  var MillirecCharCnnCore = class {
314
340
  static async create(opts = {}) {
315
341
  const g = typeof window !== "undefined" ? window : globalThis;
316
342
  const config = { ...g.MILLIREC_CNN || {}, ...opts };
317
343
  if (!config.stages || !config.stages.length) throw new Error("MillirecCharCnn: no stages configured");
344
+ if (typeof fetch === "undefined" || typeof document === "undefined" && typeof OffscreenCanvas === "undefined") {
345
+ throw new Error("millirec: char-cnn needs a browser (fetch, and a canvas or OffscreenCanvas); importing is SSR-safe but call create() on the client");
346
+ }
318
347
  const inst = new this(config);
319
348
  await inst.ready;
320
349
  return inst;
@@ -324,26 +353,35 @@ var MillirecCharCnnCore = class {
324
353
  this.base = assetBaseOf(config.assetBase || ASSET_BASE);
325
354
  this.classes = typeof config.classes === "string" ? config.classes.split("") : config.classes;
326
355
  this.stages = [];
327
- this.off = typeof document !== "undefined" ? document.createElement("canvas") : null;
328
- if (this.off) {
329
- this.off.width = this.off.height = 140;
330
- this.octx = this.off.getContext("2d", { willReadFrequently: true });
331
- }
356
+ this.off = makeCanvas(140);
357
+ this.octx = this.off ? this.off.getContext("2d", { willReadFrequently: true }) : null;
332
358
  this.ready = this.load();
333
359
  }
334
360
  async load() {
335
361
  const { base, config } = this;
336
362
  let factory = null;
337
- if (config.kernel) factory = (await import(
338
- /* @vite-ignore */
339
- base + config.kernel
340
- )).default;
363
+ if (config.kernel) {
364
+ const url2 = base + config.kernel;
365
+ try {
366
+ factory = (await import(
367
+ /* @vite-ignore */
368
+ /* webpackIgnore: true */
369
+ url2
370
+ )).default;
371
+ } catch (e) {
372
+ const err = notServed(url2, "the char-cnn kernel", base, "char-cnn");
373
+ err.message += ` (${e && e.message})`;
374
+ throw err;
375
+ }
376
+ }
341
377
  for (const st of config.stages) {
342
- const [modelBuf, headBuf] = await Promise.all([fetchBuf(base + st.model), fetchBuf(base + st.head)]);
378
+ const [modelBuf, headBuf] = await Promise.all([fetchBuf(base + st.model, base), fetchBuf(base + st.head, base)]);
379
+ if (this.destroyed) return;
343
380
  const head = parseHead(headBuf);
344
381
  const stage = { theta: st.theta == null ? null : st.theta, head, headNorm: st.headNorm !== false, size: 0 };
345
382
  if (factory) {
346
383
  const M = await factory();
384
+ if (this.destroyed) return;
347
385
  const bytes = expandToInt8(new Uint8Array(modelBuf));
348
386
  const ptr = M._malloc(bytes.byteLength);
349
387
  M.HEAPU8.set(bytes, ptr);
@@ -376,6 +414,7 @@ var MillirecCharCnnCore = class {
376
414
  * The canvas draw + readback is the dear part (~1 ms) and is shared by every
377
415
  * stage of one recognize() call; only the resample differs per size. */
378
416
  raster(strokes, size) {
417
+ if (!this.octx) throw new Error("millirec: char-cnn needs a canvas to draw strokes on (a document, or OffscreenCanvas in a worker)");
379
418
  if (this._planeFor !== strokes) {
380
419
  const W2 = drawStrokes(this.octx, strokes);
381
420
  this._plane = { ink: inkPlane(this.octx.getImageData(0, 0, W2, W2).data, W2, W2), W: W2 };
@@ -394,7 +433,7 @@ var MillirecCharCnnCore = class {
394
433
  strokes = asStrokes(strokes);
395
434
  if (!strokes || !strokes.length) return null;
396
435
  await this.ready;
397
- if (!this.stages.length) return null;
436
+ if (this.destroyed || !this.stages.length) return null;
398
437
  this._planeFor = null;
399
438
  const keep = only ? new Set(only) : null;
400
439
  let z = null, used = 0;
@@ -432,6 +471,7 @@ var MillirecCharCnnCore = class {
432
471
  async embedding(strokes) {
433
472
  strokes = asStrokes(strokes);
434
473
  await this.ready;
474
+ if (this.destroyed || !this.stages.length) throw new Error(DESTROYED);
435
475
  this._planeFor = null;
436
476
  const st = this.stages[this.stages.length - 1];
437
477
  return st.embed(this.raster(strokes, st.size));
@@ -446,6 +486,7 @@ var MillirecCharCnnCore = class {
446
486
  */
447
487
  async personalize(samples, { steps = 250, lr = 0.5, prior = 1 } = {}) {
448
488
  await this.ready;
489
+ if (this.destroyed || !this.stages.length) return null;
449
490
  const st = this.stages[this.stages.length - 1];
450
491
  const H0 = st.head0 || (st.head0 = st.head);
451
492
  const X = [], Y = [];
@@ -459,6 +500,7 @@ var MillirecCharCnnCore = class {
459
500
  Y.push(c);
460
501
  }
461
502
  }
503
+ if (this.destroyed) return null;
462
504
  if (!X.length) {
463
505
  st.head = H0;
464
506
  this.personal = null;
@@ -490,8 +532,9 @@ var MillirecCharCnnCore = class {
490
532
  this.personal = { n, classes: [...new Set(Y)].map((c) => this.classes[c]).sort() };
491
533
  return this.personal;
492
534
  }
493
- /** Let go of the models and kernels; recognize() returns null afterwards. */
535
+ /** Let go of the models and kernels; recognize() and personalize() return null afterwards, embedding() throws. */
494
536
  destroy() {
537
+ this.destroyed = true;
495
538
  this.stages = [];
496
539
  this.personal = null;
497
540
  this._plane = null;
@@ -499,7 +542,7 @@ var MillirecCharCnnCore = class {
499
542
  }
500
543
  depersonalize() {
501
544
  const st = this.stages[this.stages.length - 1];
502
- if (st.head0) st.head = st.head0;
545
+ if (st && st.head0) st.head = st.head0;
503
546
  this.personal = null;
504
547
  }
505
548
  };
@@ -978,17 +1021,32 @@ var MillirecCharCnn = class extends MillirecCharCnnCore {
978
1021
  };
979
1022
  if (typeof window !== "undefined" && false) window.MillirecCharCnn = MillirecCharCnn;
980
1023
 
1024
+ // src/here.js
1025
+ var url = (import.meta.url || "").replace(/[?#].*$/, "");
1026
+ var HERE = url.slice(0, url.lastIndexOf("/") + 1);
1027
+ function nodeFileUrl(url2, spec) {
1028
+ const g = globalThis;
1029
+ const node = typeof g.process !== "undefined" && g.process.versions && g.process.versions.node && typeof g.Deno === "undefined" && typeof g.Bun === "undefined";
1030
+ if (url2.startsWith("file:") && node && typeof document === "undefined" && typeof WorkerGlobalScope === "undefined") {
1031
+ throw new Error(`millirec: cannot fetch ${url2} outside a browser \u2014 in Node, import the JSON instead: import x from '${spec}' with { type: 'json' }`);
1032
+ }
1033
+ }
1034
+
981
1035
  // src/options.js
982
- var HERE = new URL("./", import.meta.url).href;
983
1036
  var OPTIONS = ["accurate", "fast", "small"];
984
1037
  async function loadOption(name, { assetBase = HERE } = {}) {
985
1038
  if (!OPTIONS.includes(name)) throw new Error(`millirec: no CNN option "${name}" (one of ${OPTIONS.join(", ")})`);
986
- const url = new URL(`options/${name}.json`, assetBaseOf(assetBase));
987
- const r = await fetch(url);
988
- if (!r.ok) throw new Error(`millirec: ${url}: ${r.status}`);
989
- return r.json();
1039
+ const base = assetBaseOf(assetBase);
1040
+ const url2 = new URL(`options/${name}.json`, base).href;
1041
+ nodeFileUrl(url2, `millirec/char-cnn/options/${name}.json`);
1042
+ return fetchAsset(url2, { what: `the ${name} CNN option`, base, recognizer: "char-cnn" });
990
1043
  }
991
1044
  async function withOption(opts) {
1045
+ if (typeof opts === "string") opts = { option: opts };
1046
+ opts = opts || {};
1047
+ if (typeof document === "undefined" && typeof OffscreenCanvas === "undefined") {
1048
+ throw new Error("millirec: char-cnn needs a browser (fetch, and a canvas or OffscreenCanvas); importing is SSR-safe but call create() on the client");
1049
+ }
992
1050
  const assetBase = assetBaseOf(opts.assetBase || HERE);
993
1051
  const preset = opts.stages ? {} : await loadOption(opts.option || "accurate", { assetBase });
994
1052
  return { ...preset, ...opts, assetBase };
@@ -997,7 +1055,8 @@ async function withOption(opts) {
997
1055
  // src/char-cnn.js
998
1056
  var MillirecCharCnn2 = class extends MillirecCharCnn {
999
1057
  /** opts: option ('accurate' | 'fast' | 'small', default 'accurate') or your own
1000
- * { classes, stages, kernel }, plus assetBase (default: this module's folder). */
1058
+ * { classes, stages, kernel }, plus assetBase (default: this module's folder).
1059
+ * A string is the option's name: create('fast') = create({ option: 'fast' }). */
1001
1060
  static async create(opts = {}) {
1002
1061
  return super.create(await withOption(opts));
1003
1062
  }