millirec 0.0.0-stage → 0.1.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.
Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +156 -2
  3. package/dist/char-cnn/base-p25.bin +0 -0
  4. package/dist/char-cnn/base-p25.head.bin +0 -0
  5. package/dist/char-cnn/base.head.bin +0 -0
  6. package/dist/char-cnn/base.q4.bin +0 -0
  7. package/dist/char-cnn/cnn-web.js +8 -0
  8. package/dist/char-cnn/cnn-web.wasm +0 -0
  9. package/dist/char-cnn/core.d.ts +35 -0
  10. package/dist/char-cnn/core.js +536 -0
  11. package/dist/char-cnn/index.d.ts +9 -0
  12. package/dist/char-cnn/index.js +1009 -0
  13. package/dist/char-cnn/millirec-char-cnn-core.min.js +1 -0
  14. package/dist/char-cnn/millirec-char-cnn.min.js +1 -0
  15. package/dist/char-cnn/options/accurate.js +17 -0
  16. package/dist/char-cnn/options/accurate.json +15 -0
  17. package/dist/char-cnn/options/fast.js +17 -0
  18. package/dist/char-cnn/options/fast.json +15 -0
  19. package/dist/char-cnn/options/small.js +11 -0
  20. package/dist/char-cnn/options/small.json +9 -0
  21. package/dist/char-cnn/tiny.bin +0 -0
  22. package/dist/char-cnn/tiny.head.bin +0 -0
  23. package/dist/char-lite/index.d.ts +77 -0
  24. package/dist/char-lite/index.js +894 -0
  25. package/dist/char-lite/millirec-char-lite.min.js +1 -0
  26. package/dist/char-lite/millirec.wasm +0 -0
  27. package/dist/char-lite/sets/all.js +2 -0
  28. package/dist/char-lite/sets/all.json +1 -0
  29. package/dist/char-lite/sets/capitals.js +2 -0
  30. package/dist/char-lite/sets/capitals.json +1 -0
  31. package/dist/char-lite/sets/digits.js +2 -0
  32. package/dist/char-lite/sets/digits.json +1 -0
  33. package/dist/char-lite/sets/lowercase.js +2 -0
  34. package/dist/char-lite/sets/lowercase.json +1 -0
  35. package/dist/char-lite/sets/punctuation.js +2 -0
  36. package/dist/char-lite/sets/punctuation.json +1 -0
  37. package/dist/char-lite/sets.json +163 -0
  38. package/dist/char-lite/worker-stroke.js +11 -0
  39. package/dist/overlap/millirec-overlap.min.js +45 -0
  40. package/dist/overlap/millirec.wasm +0 -0
  41. package/dist/overlap/training.all.json +1 -0
  42. package/dist/overlap/training.capitals.json +1 -0
  43. package/dist/overlap/training.digits.json +1 -0
  44. package/dist/overlap/training.lowercase.json +1 -0
  45. package/dist/overlap/training.punctuation.json +1 -0
  46. package/dist/overlap/words.json +1 -0
  47. package/package.json +53 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Robert Wilcox
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,157 @@
1
- # Temporary Holding Version
1
+ # millirec
2
2
 
3
- 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.
3
+ Small, fast handwriting recognition in the browser. Draw a character, get the
4
+ three likeliest readings back. Runs entirely on the device — no server, no
5
+ upload of anyone's ink.
6
+
7
+ Three pieces, pick by what you need to read:
8
+
9
+ | | reads | size (gzip) | trainable on your own strokes |
10
+ |---|---|---|---|
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
+ | `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 | — |
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ npm install millirec
19
+ ```
20
+
21
+ `import … from 'millirec'` is the same as `'millirec/char-lite'`. The package is ES modules only
22
+ (use `import`, not `require`), or the script-tag builds below.
23
+
24
+ ## char-lite
25
+
26
+ ```js
27
+ import { MillirecCharLite, loadSet } from 'millirec/char-lite'
28
+
29
+ const training = await loadSet('digits') // 'all' | 'capitals' | 'digits' | 'lowercase' | 'punctuation'
30
+ const rec = await MillirecCharLite.create({ training })
31
+
32
+ // a drawing pad that reports after every stroke
33
+ const pad = rec.attach(document.querySelector('#pad'))
34
+ document.querySelector('#pad').addEventListener('millirec:result', (e) => {
35
+ console.log(e.detail.results) // [{ char: '7', prob: 0.91 }, ...]
36
+ })
37
+
38
+ // or your own strokes: arrays of {x, y} points
39
+ await rec.recognize([[{ x: 50, y: 10 }, /* ... */ { x: 52, y: 120 }]])
40
+ ```
41
+
42
+ ### Training on your users' strokes
43
+
44
+ A class name is any string, so a recognizer can learn one person's hand, or
45
+ symbols nobody else uses:
46
+
47
+ ```js
48
+ const mine = MillirecCharLite.withSamples(training, {
49
+ '7': [strokesOfASeven, anotherSeven], // appended to the shipped 7s
50
+ '★': [star1, star2, star3], // a brand-new class
51
+ })
52
+ const rec = await MillirecCharLite.create({ training: mine })
53
+ ```
54
+
55
+ Drawings are resampled to the set's points-per-shape, so pass raw strokes.
56
+ `{ replace: true }` drops a class's shipped samples instead of appending —
57
+ worth it once you have three or four of the writer's own. Keep the raw strokes
58
+ (in localStorage, IndexedDB, your server — the library never stores anything)
59
+ and rebuild the training object when the recognizer starts. The format is
60
+ plain JSON (`version: 2`, see `Training` in the type declarations), so a
61
+ training set can also be built offline and loaded with `fetch`.
62
+
63
+ ## char-cnn
64
+
65
+ ```js
66
+ import { MillirecCharCnn } from 'millirec/char-cnn'
67
+
68
+ const rec = await MillirecCharCnn.create() // 'accurate' (default), 'fast' or 'small'
69
+ rec.attach(document.querySelector('#pad'))
70
+ await rec.recognize(strokes, { only: 'AEIOU' }) // restrict the answer to some letters
71
+ await rec.personalize({ A: [a1, a2, a3], R: [r1, r2] }) // lean toward this writer's hand
72
+ ```
73
+
74
+ `millirec/char-cnn/core` is the same recognizer without the drawing pad.
75
+
76
+ ## overlap: words written in one box
77
+
78
+ Letters written one on top of another in a single box, read against a word list. Script tag only
79
+ for now:
80
+
81
+ ```html
82
+ <script src="/millirec/overlap/millirec-overlap.min.js"></script>
83
+ <div id="box"></div>
84
+ <script>
85
+ MillirecOverlap.create(document.getElementById('box'), { set: 'capitals', words: ['HELLO', 'WORLD'] })
86
+ </script>
87
+ ```
88
+
89
+ Copy `dist/overlap/` to your site (or load it from a CDN); the script finds its wasm, training and
90
+ default word list beside itself. `set` is `capitals`, `lowercase`, `digits`, `punctuation` or `all`.
91
+
92
+ ## Serving the files
93
+
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:
99
+
100
+ ```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/' })
103
+ ```
104
+
105
+ `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'] }`).
108
+
109
+ **`assetBase` (and char-cnn's `kernel`) decide which code is loaded** — the worker and kernel are
110
+ fetched from there and run. Set them in your own code; never fill them from a URL parameter, a
111
+ query string or anything a visitor can type.
112
+
113
+ ### Content-Security-Policy
114
+
115
+ If your site sends a CSP, the recognizers need:
116
+
117
+ - `worker-src blob:` — char-lite boots its worker from a blob that loads `worker-stroke.js`;
118
+ - `script-src 'wasm-unsafe-eval' 'unsafe-eval'` — the matcher is WebAssembly, and its generated
119
+ bindings (char-lite's worker, overlap) use `new Function`;
120
+ - `connect-src` for wherever the files are served from, if that is another origin.
121
+
122
+ ## Script tag / CDN
123
+
124
+ No build step needed:
125
+
126
+ ```html
127
+ <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/millirec-char-lite.min.js"></script>
128
+ <script src="https://cdn.jsdelivr.net/npm/millirec@0.1/dist/char-lite/sets/digits.js"></script>
129
+ <script>
130
+ MillirecCharLite.create().then((rec) => rec.attach(document.querySelector('#pad')))
131
+ </script>
132
+ ```
133
+
134
+ `sets/<name>.js` sets `window.MILLIREC_TRAINING`; for char-cnn load
135
+ `dist/char-cnn/options/accurate.js` and then `millirec-char-cnn.min.js`. The
136
+ script finds its worker and wasm next to itself, on any origin that sends CORS
137
+ headers (jsDelivr and unpkg do).
138
+
139
+ ## Where the data comes from
140
+
141
+ - **char-lite training sets and the overlap templates**: one writer's own handwriting, drawn for
142
+ this project.
143
+ - **char-cnn models**: small CNNs trained on handwritten capitals from EMNIST (derived from NIST
144
+ Special Database 19).
145
+ - **overlap's default word list** (`words.json`): the 10,000 commonest English words by millirec's
146
+ own count over about 1.9 billion words of English, mostly news — names and offensive words
147
+ removed. It leans toward news vocabulary; pass your own `words` for anything specific.
148
+
149
+ Recognition runs entirely in the browser: nothing a user draws is sent anywhere by this package.
150
+
151
+ ## Versions
152
+
153
+ 0.x: the API may still change between minor versions. 1.0 will mark it stable.
154
+
155
+ ## License
156
+
157
+ MIT
Binary file
Binary file
Binary file
Binary file
@@ -0,0 +1,8 @@
1
+ async function CnnEmbed(moduleArg={}){var moduleRtn;var b=moduleArg,f=!!globalThis.WorkerGlobalScope,g=import.meta.url,h="",l,m;if(globalThis.window||f){try{h=(new URL(".",g)).href}catch{}f&&(m=a=>{var d=new XMLHttpRequest;d.open("GET",a,!1);d.responseType="arraybuffer";d.send(null);return new Uint8Array(d.response)});l=async a=>{a=await fetch(a,{credentials:"same-origin"});if(a.ok)return a.arrayBuffer();throw Error(a.status+" : "+a.url);}}var n=console.error.bind(console),p,q=!1,r,t,u,v=!1;
2
+ function w(){var a=x.buffer;new Int8Array(a);new Int16Array(a);b.HEAPU8=u=new Uint8Array(a);new Uint16Array(a);new Int32Array(a);new Uint32Array(a);b.HEAPF32=new Float32Array(a);new Float64Array(a);new BigInt64Array(a);new BigUint64Array(a)}var y;async function z(a){if(!p)try{var d=await l(a);return new Uint8Array(d)}catch{}if(a==y&&p)a=new Uint8Array(p);else if(m)a=m(a);else throw"both async and sync fetching of the wasm failed";return a}
3
+ async function A(a,d){try{var c=await z(a);return await WebAssembly.instantiate(c,d)}catch(e){throw n(`failed to asynchronously prepare wasm: ${e}`),a=e,b.onAbort?.(a),a="Aborted("+a+")",n(a),q=!0,a=new WebAssembly.RuntimeError(a+". Build with -sASSERTIONS for more info."),t?.(a),a;}}
4
+ async function B(a){var d=y;if(!p)try{var c=fetch(d,{credentials:"same-origin"});return await WebAssembly.instantiateStreaming(c,a)}catch(e){n(`wasm streaming compile failed: ${e}`),n("falling back to ArrayBuffer instantiation")}return A(d,a)}var C=a=>{for(;0<a.length;)a.shift()(b)},D=[],E=[],F=()=>{var a=b.preRun.shift();E.push(a)};b.printErr&&(n=b.printErr);b.wasmBinary&&(p=b.wasmBinary);if(b.preInit)for("function"==typeof b.preInit&&(b.preInit=[b.preInit]);0<b.preInit.length;)b.preInit.shift()();
5
+ var x,G={a:a=>{var d=u.length;a>>>=0;if(2147483648<a)return!1;for(var c=1;4>=c;c*=2){var e=d*(1+.2/c);e=Math.min(e,a+100663296);a:{e=(Math.min(2147483648,65536*Math.ceil(Math.max(a,e)/65536))-x.buffer.byteLength+65535)/65536|0;try{x.grow(e);w();var k=1;break a}catch(I){}k=void 0}if(k)return!0}return!1}},H;
6
+ H=await (async function(){function a(c){c=H=c.exports;b._cnnLoad=c.d;b._free=c.e;b._malloc=c.f;b._cnnSize=c.g;b._cnnDim=c.h;b._cnnInputPtr=c.i;b._cnnEmbedPtr=c.j;b._cnnRun=c.k;x=c.b;w();return H}var d={a:G};if(b.instantiateWasm)return new Promise(c=>{b.instantiateWasm(d,(e,k)=>{c(a(e,k))})});y??=b.locateFile?b.locateFile?b.locateFile("cnn-web.wasm",h):h+"cnn-web.wasm":(new URL("cnn-web.wasm",import.meta.url)).href;return a((await B(d)).instance)}());
7
+ (function(){function a(){b.calledRun=!0;if(!q){v=!0;H.c();r?.(b);b.onRuntimeInitialized?.();if(b.postRun)for("function"==typeof b.postRun&&(b.postRun=[b.postRun]);b.postRun.length;){var d=b.postRun.shift();D.push(d)}C(D)}}if(b.preRun)for("function"==typeof b.preRun&&(b.preRun=[b.preRun]);b.preRun.length;)F();C(E);b.setStatus?(b.setStatus("Running..."),setTimeout(()=>{setTimeout(()=>b.setStatus(""),1);a()},1)):a()})();v?moduleRtn=b:moduleRtn=new Promise((a,d)=>{r=a;t=d});
8
+ ;return moduleRtn}export default CnnEmbed;
Binary file
@@ -0,0 +1,35 @@
1
+ import type { Strokes, Stroke, Reading } from '../char-lite/index.js'
2
+
3
+ export interface Stage { model: string; head: string; theta?: number; headNorm?: boolean }
4
+ export interface CnnConfig { classes: string | string[]; stages: Stage[]; kernel?: string }
5
+
6
+ export interface CreateOptions extends Partial<CnnConfig> {
7
+ /** A shipped option, used when `stages` is not given. Default 'accurate'. */
8
+ option?: OptionName
9
+ /** Folder holding the model files and kernel. Default: next to this module. Absolute, root-relative
10
+ * or page-relative; the trailing slash is optional. It (and `kernel`) decide what code is loaded:
11
+ * never fill them from a URL parameter or user input. */
12
+ assetBase?: string
13
+ }
14
+
15
+ export declare const OPTIONS: readonly ['accurate', 'fast', 'small']
16
+ export type OptionName = (typeof OPTIONS)[number]
17
+ export declare function loadOption(name: OptionName, opts?: { assetBase?: string }): Promise<CnnConfig>
18
+
19
+ export declare class MillirecCharCnnCore {
20
+ static create(opts?: CreateOptions): Promise<MillirecCharCnnCore>
21
+ readonly classes: string[]
22
+ readonly ready: Promise<void>
23
+ /** `only` restricts the reading to these classes. */
24
+ recognize(strokes: Strokes | Stroke, opts?: { only?: string | string[] }): Promise<(Reading[] & { stage?: number }) | null>
25
+ /** Refit the last stage's head on your own drawings: { 'A': [strokes, ...], ... }.
26
+ * Anchored to the shipped head, so a few samples nudge a letter and many take it over.
27
+ * Classes outside `classes` are ignored (the CNN cannot learn new characters this way). */
28
+ personalize(samples: Record<string, Array<Strokes | Stroke>>, opts?: { steps?: number; lr?: number; prior?: number }): Promise<{ n: number; classes: string[] } | null>
29
+ /** Back to the shipped head. */
30
+ depersonalize(): void
31
+ /** The last stage's unit embedding of a drawing — what the head reads. */
32
+ embedding(strokes: Strokes | Stroke): Promise<Float32Array>
33
+ /** Let go of the models; recognize() returns null afterwards. */
34
+ destroy(): void
35
+ }