@ascii-fx/compiler 0.2.0 → 0.3.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.
Files changed (2) hide show
  1. package/README.md +45 -13
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,26 +1,58 @@
1
1
  # @ascii-fx/compiler
2
2
 
3
- Node-only build-time compiler: deterministic font rasterization (fontkit parsing + an in-house fixed-point scanline rasterizer — no system rasterizers, so `.asciip` bytes are identical across platforms), glyph atlases, structural masks, and static frame precompilation.
3
+ Build-time only: turns a font into a glyph profile the matcher can use, and an image into a precompiled frame. Node, never the browser.
4
+
5
+ ```sh
6
+ pnpm add -D @ascii-fx/compiler
7
+ ```
8
+
9
+ Most people never import this directly — [`@ascii-fx/vite`](../vite) wraps it as a plugin, and the runtime packages can compile a profile themselves at startup. Reach for it when you want to compile ahead of time, or in a build that isn't Vite.
4
10
 
5
11
  ```ts
6
12
  import { readFile } from 'node:fs/promises'
7
- import { buildProfile, buildFrame, decodePng } from '@ascii-fx/compiler'
13
+ import { buildProfile } from '@ascii-fx/compiler'
14
+
15
+ const font = new Uint8Array(await readFile('GeistMono-Regular.ttf'))
16
+ const { profile, binary } = buildProfile({ font, characters: ' .:-=+*#%@' })
17
+ await writeFile('public/default.asciip', binary)
18
+ ```
8
19
 
9
- const { profile, binary } = buildProfile({
10
- font: await readFile('./GeistMono-Regular.ttf'),
11
- charset: 'ascii', // or characters: '@#*+. '
12
- shape6: { lut: true }, // optional approximate-matcher data (adds ~514KiB raw)
13
- })
20
+ ## Deterministic on purpose
14
21
 
15
- const frame = buildFrame({ image: decodePng(pngBytes), profile, columns: 140, color: 'full' })
22
+ Rasterization is an in-house fixed-point scanline rasterizer over [fontkit](https://github.com/foliojs/fontkit)'s glyph outlines — **no system rasterizer anywhere in the path**. The same font and the same options produce byte-identical `.asciip` output on macOS, Linux, and CI.
23
+
24
+ That matters because a profile's fingerprint is what a `.asciif` frame is validated against. If rasterization drifted between machines, frames compiled on your laptop would be refused by the same code running in CI. Golden-file tests pin it.
25
+
26
+ ## Colour glyphs
27
+
28
+ `buildChromaticProfile` builds from decoded colour images rather than a font, carrying an RGBA atlas alongside the coverage plane, so the profile still works with the mask-fitting matchers:
29
+
30
+ ```ts
31
+ import { buildChromaticProfile } from '@ascii-fx/compiler'
32
+
33
+ const { binary } = buildChromaticProfile({ glyphs: [{ char: '🌊', image }, ...] })
16
34
  ```
17
35
 
36
+ ## Static frames
37
+
38
+ `buildFrame` matches an image at build time and emits `.asciif`, so the client ships glyph ids instead of doing any matching:
39
+
40
+ ```ts
41
+ import { buildFrame, decodePng } from '@ascii-fx/compiler'
42
+
43
+ const { binary } = buildFrame({ profile, image: decodePng(png), columns: 160 })
44
+ ```
45
+
46
+ A frame records the fingerprint of the profile it was built against and refuses to decode against a different one — a stale `.asciif` fails loudly rather than rendering garbage.
47
+
18
48
  ## CLI
19
49
 
20
- ```bash
21
- ascii-fx profile build --font GeistMono-Regular.ttf --out default.asciip [--shape6|--shape6-lut]
22
- ascii-fx frame build --image hero.png --profile default.asciip --columns 140 --color full --out hero.asciif
23
- ascii-fx inspect default.asciip
50
+ ```sh
51
+ npx ascii-fx profile build --font GeistMono-Regular.ttf --out default.asciip
52
+ npx ascii-fx frame build --image hero.png --profile default.asciip --columns 160 --out hero.asciif
53
+ npx ascii-fx inspect default.asciip
24
54
  ```
25
55
 
26
- Constraints: monospace fonts only (equal advances over the charset — enforced); the charset must be fully covered by the font (missing glyphs are listed, never tofu'd); PNG only for `frame build` in v1. Profiles embed content fingerprints; identical inputs → identical bytes, verified by tests.
56
+ ## License
57
+
58
+ [MIT](../../LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ascii-fx/compiler",
3
- "version": "0.2.0",
3
+ "version": "0.3.1",
4
4
  "description": "Build-time compiler for ASCII FX: deterministic font rasterization, glyph atlases, .asciip/.asciif generation.",
5
5
  "keywords": [
6
6
  "ascii",
@@ -43,7 +43,7 @@
43
43
  "dependencies": {
44
44
  "fontkit": "^2.0.4",
45
45
  "pngjs": "^7.0.0",
46
- "@ascii-fx/core": "0.2.0"
46
+ "@ascii-fx/core": "0.3.1"
47
47
  },
48
48
  "devDependencies": {
49
49
  "@types/node": "^26.2.0",