@open-pencil/html-engine 0.0.0-stage → 0.17.0-beta.4

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/src/engine.ts ADDED
@@ -0,0 +1,282 @@
1
+ import * as v from 'valibot'
2
+
3
+ import { imageStandIn, rasterImageSize } from './images'
4
+ import { captureSchema, requestsSchema, type HTMLEngineCapture } from './schema'
5
+
6
+ /**
7
+ * The module's exports: strings and bytes cross as (pointer, length), and results land in one
8
+ * output buffer whose length the call returns.
9
+ */
10
+ const EXPORTS = [
11
+ 'alloc',
12
+ 'dealloc',
13
+ 'output_ptr',
14
+ 'fonts_reset',
15
+ 'font_decode',
16
+ 'font_add',
17
+ 'font_generic',
18
+ 'open',
19
+ 'pump',
20
+ 'provide',
21
+ 'fail',
22
+ 'capture'
23
+ ] as const
24
+
25
+ type EngineExports = Record<(typeof EXPORTS)[number], (...args: number[]) => number> & {
26
+ memory: WebAssembly.Memory
27
+ }
28
+
29
+ /** A resource the document asked for, as the host fetched it: its final URL and its bytes. */
30
+ export interface HTMLEngineResource {
31
+ url: string
32
+ bytes: Uint8Array
33
+ /** The resource's media type, such as `text/css`, when the host knows it. */
34
+ contentType?: string
35
+ }
36
+
37
+ /**
38
+ * Fetches a stylesheet, font, or image the document refers to; null when it cannot. `signal`
39
+ * aborts when the request runs out of time, and the layout goes on without it.
40
+ */
41
+ export type HTMLEngineFetch = (
42
+ url: string,
43
+ signal: AbortSignal
44
+ ) => Promise<HTMLEngineResource | null>
45
+
46
+ export interface HTMLEngineLayoutOptions {
47
+ /** The document's URL, which relative URLs in it resolve against. */
48
+ baseURL?: string
49
+ /** In whole CSS pixels. */
50
+ viewport: { width: number; height: number }
51
+ /** Answers the document's requests; without one, every request fails. */
52
+ fetch?: HTMLEngineFetch
53
+ /** How long one request may take before the layout goes on without it. */
54
+ requestTimeoutMs?: number
55
+ }
56
+
57
+ /**
58
+ * How long a request may take by default: as long as the browser runtime waits for an image, so
59
+ * one request that never ends cannot hold this layout, or the ones queued behind it, forever.
60
+ */
61
+ const REQUEST_TIMEOUT_MS = 10_000
62
+
63
+ /** The largest viewport side the module takes, as a signed 32-bit length. */
64
+ const MAX_VIEWPORT = 0x7fffffff
65
+
66
+ function checkViewport({ width, height }: HTMLEngineLayoutOptions['viewport']): void {
67
+ for (const side of [width, height]) {
68
+ if (!Number.isInteger(side) || side <= 0 || side > MAX_VIEWPORT) {
69
+ throw new RangeError(`The viewport needs whole positive pixel sizes, not ${width}×${height}`)
70
+ }
71
+ }
72
+ }
73
+
74
+ /** A fetch that gives up, answering null, once `signal` aborts. */
75
+ function withDeadline<T>(request: Promise<T>, signal: AbortSignal): Promise<T | null> {
76
+ const expired = new Promise<null>((resolve) => {
77
+ signal.addEventListener('abort', () => resolve(null), { once: true })
78
+ })
79
+ return Promise.race([request.catch(() => null), expired])
80
+ }
81
+
82
+ /** Blitz's wasm-bindgen imports, which no capture calls: they trap with their name instead. */
83
+ function unboundImports(module: WebAssembly.Module): WebAssembly.Imports {
84
+ const imports: Record<string, Record<string, () => never>> = {}
85
+ for (const { module: namespace, name } of WebAssembly.Module.imports(module)) {
86
+ imports[namespace] ??= {}
87
+ imports[namespace][name] = () => {
88
+ throw new Error(`The HTML engine called its unbound import ${namespace}.${name}`)
89
+ }
90
+ }
91
+ return imports
92
+ }
93
+
94
+ function engineExports(exports: WebAssembly.Exports): EngineExports {
95
+ const { memory } = exports
96
+ if (!(memory instanceof WebAssembly.Memory)) throw new Error('The HTML engine has no memory')
97
+ const functions: Partial<Record<(typeof EXPORTS)[number], (...args: number[]) => number>> = {}
98
+ for (const name of EXPORTS) {
99
+ const exported = exports[name]
100
+ if (typeof exported !== 'function') throw new Error(`The HTML engine lacks ${name}`)
101
+ functions[name] = (...args) => Number(Reflect.apply(exported, undefined, args))
102
+ }
103
+ return {
104
+ ...(functions as Record<(typeof EXPORTS)[number], (...args: number[]) => number>),
105
+ memory
106
+ }
107
+ }
108
+
109
+ /** The URL an image element's `src` resolves to, or null when it does not parse. */
110
+ function imageURL(src: string, baseURL: string | undefined): string | null {
111
+ try {
112
+ return new URL(src, baseURL).href
113
+ } catch {
114
+ return null
115
+ }
116
+ }
117
+
118
+ /**
119
+ * The engine lays raster images out from SVG stand-ins and reports them as SVG; `rasters` holds
120
+ * what each stood-in URL really was, which the capture reports instead.
121
+ */
122
+ function restoreImageKinds(
123
+ capture: HTMLEngineCapture,
124
+ rasters: ReadonlyMap<string, string>,
125
+ baseURL: string | undefined
126
+ ): void {
127
+ for (const node of capture.nodes) {
128
+ const src = node.attrs?.src
129
+ if (node.image !== 'svg' || src === undefined) continue
130
+ const url = imageURL(src, baseURL)
131
+ const kind = url === null ? undefined : rasters.get(url)
132
+ if (kind) node.image = kind
133
+ }
134
+ }
135
+
136
+ /**
137
+ * Blitz, Stylo, Taffy, and Parley compiled to WebAssembly: lays HTML out as a browser does and
138
+ * captures every element's box and computed styles, and the lines its text sets. The engine holds one document at a
139
+ * time, so layouts on one instance run one after another.
140
+ */
141
+ export class HTMLEngine {
142
+ readonly #exports: EngineExports
143
+ readonly #encoder = new TextEncoder()
144
+ readonly #decoder = new TextDecoder()
145
+ #queue: Promise<unknown> = Promise.resolve()
146
+
147
+ private constructor(exports: EngineExports) {
148
+ this.#exports = exports
149
+ }
150
+
151
+ /** Instantiates the module from its bytes or a compiled `WebAssembly.Module`. */
152
+ static async instantiate(source: BufferSource | WebAssembly.Module): Promise<HTMLEngine> {
153
+ const module = source instanceof WebAssembly.Module ? source : await WebAssembly.compile(source)
154
+ const instance = await WebAssembly.instantiate(module, unboundImports(module))
155
+ return new HTMLEngine(engineExports(instance.exports))
156
+ }
157
+
158
+ #withBytes<T>(bytes: Uint8Array, use: (pointer: number, length: number) => T): T {
159
+ const pointer = this.#exports.alloc(bytes.length)
160
+ new Uint8Array(this.#exports.memory.buffer, pointer, bytes.length).set(bytes)
161
+ try {
162
+ return use(pointer, bytes.length)
163
+ } finally {
164
+ this.#exports.dealloc(pointer, bytes.length)
165
+ }
166
+ }
167
+
168
+ #withText<T>(text: string, use: (pointer: number, length: number) => T): T {
169
+ return this.#withBytes(this.#encoder.encode(text), use)
170
+ }
171
+
172
+ #output(length: number): string {
173
+ const pointer = this.#exports.output_ptr()
174
+ return this.#decoder.decode(new Uint8Array(this.#exports.memory.buffer, pointer, length))
175
+ }
176
+
177
+ /**
178
+ * Registers a font file for layouts that start after it; `alias` also registers it under
179
+ * that family name, as browsers alias `-apple-system` to the system font. Returns the number
180
+ * of faces it holds.
181
+ */
182
+ addFont(bytes: Uint8Array, alias?: string): number {
183
+ return this.#withBytes(bytes, (pointer, length) =>
184
+ this.#withText(alias ?? '', (aliasPointer, aliasLength) =>
185
+ this.#exports.font_add(pointer, length, aliasPointer, aliasLength)
186
+ )
187
+ )
188
+ }
189
+
190
+ /**
191
+ * Sets the registered families a generic family such as `sans-serif` falls back to, in order.
192
+ * False when none of them is registered.
193
+ */
194
+ setGenericFamily(generic: string, families: readonly string[]): boolean {
195
+ return this.#withText(generic, (genericPointer, genericLength) =>
196
+ this.#withText(families.join('\n'), (pointer, length) =>
197
+ Boolean(this.#exports.font_generic(genericPointer, genericLength, pointer, length))
198
+ )
199
+ )
200
+ }
201
+
202
+ /** A font file as TrueType or OpenType, with WOFF and WOFF2 decompressed; others unchanged. */
203
+ decodeFont(bytes: Uint8Array): Uint8Array {
204
+ const length = this.#withBytes(bytes, (pointer, size) =>
205
+ this.#exports.font_decode(pointer, size)
206
+ )
207
+ return new Uint8Array(this.#exports.memory.buffer, this.#exports.output_ptr(), length).slice()
208
+ }
209
+
210
+ /** Forgets every registered font. */
211
+ resetFonts(): void {
212
+ this.#exports.fonts_reset()
213
+ }
214
+
215
+ #pump(): [number, string][] {
216
+ const parsed = v.safeParse(
217
+ v.pipe(v.string(), v.parseJson(), requestsSchema),
218
+ this.#output(this.#exports.pump())
219
+ )
220
+ if (!parsed.success) throw new Error('The HTML engine reported requests in an unknown shape')
221
+ return parsed.output
222
+ }
223
+
224
+ /**
225
+ * Answers one request, and returns what an image really was when the engine got a stand-in
226
+ * for it, keyed by the URLs it was asked for and fetched from.
227
+ */
228
+ async #answer(
229
+ id: number,
230
+ url: string,
231
+ options: HTMLEngineLayoutOptions
232
+ ): Promise<[string[], string] | null> {
233
+ const signal = AbortSignal.timeout(options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS)
234
+ const { fetch } = options
235
+ // An async wrapper turns a callback that throws before it returns into a rejection.
236
+ const resource = fetch ? await withDeadline((async () => fetch(url, signal))(), signal) : null
237
+ if (!resource) {
238
+ this.#exports.fail(id)
239
+ return null
240
+ }
241
+ const size = rasterImageSize(resource.bytes)
242
+ const bytes = size ? imageStandIn(size) : resource.bytes
243
+ this.#withText(resource.url, (urlPointer, urlLength) =>
244
+ this.#withBytes(bytes, (pointer, length) =>
245
+ this.#exports.provide(id, urlPointer, urlLength, pointer, length)
246
+ )
247
+ )
248
+ return size ? [[url, resource.url], `raster ${size[0]}x${size[1]}`] : null
249
+ }
250
+
251
+ async #layout(html: string, options: HTMLEngineLayoutOptions): Promise<HTMLEngineCapture> {
252
+ checkViewport(options.viewport)
253
+ const { width, height } = options.viewport
254
+ this.#withText(html, (htmlPointer, htmlLength) =>
255
+ this.#withText(options.baseURL ?? '', (urlPointer, urlLength) =>
256
+ this.#exports.open(htmlPointer, htmlLength, urlPointer, urlLength, width, height)
257
+ )
258
+ )
259
+ // Answers can ask for more, such as a stylesheet's fonts, so pump until nothing is waiting.
260
+ const rasters = new Map<string, string>()
261
+ for (let requests = this.#pump(); requests.length > 0; requests = this.#pump()) {
262
+ const answers = await Promise.all(requests.map(([id, url]) => this.#answer(id, url, options)))
263
+ for (const [urls, kind] of answers.filter((answer) => answer !== null)) {
264
+ for (const key of urls) rasters.set(key, kind)
265
+ }
266
+ }
267
+ const parsed = v.safeParse(
268
+ v.pipe(v.string(), v.parseJson(), captureSchema),
269
+ this.#output(this.#exports.capture())
270
+ )
271
+ if (!parsed.success) throw new Error('The HTML engine captured a document in an unknown shape')
272
+ restoreImageKinds(parsed.output, rasters, options.baseURL)
273
+ return parsed.output
274
+ }
275
+
276
+ /** Lays the document out once every resource it asks for is answered, and captures it. */
277
+ layout(html: string, options: HTMLEngineLayoutOptions): Promise<HTMLEngineCapture> {
278
+ const run = this.#queue.then(() => this.#layout(html, options))
279
+ this.#queue = run.catch(() => undefined)
280
+ return run
281
+ }
282
+ }
package/src/images.ts ADDED
@@ -0,0 +1,136 @@
1
+ /**
2
+ * The engine decodes no raster images, so layout learns an image's size from a stand-in SVG of
3
+ * the same pixel size, read from the file's header. Formats are the ones browsers lay out from
4
+ * their headers alone: PNG, GIF, WebP, JPEG, and AVIF.
5
+ */
6
+
7
+ type Size = [width: number, height: number]
8
+
9
+ function ascii(bytes: Uint8Array, at: number, length: number): string {
10
+ return String.fromCharCode(...bytes.subarray(at, at + length))
11
+ }
12
+
13
+ function webpSize(bytes: Uint8Array, view: DataView): Size | null {
14
+ const chunk = ascii(bytes, 12, 4)
15
+ if (chunk === 'VP8 ')
16
+ return [view.getUint16(26, true) & 0x3fff, view.getUint16(28, true) & 0x3fff]
17
+ if (chunk === 'VP8L') {
18
+ const bits = view.getUint32(21, true)
19
+ return [(bits & 0x3fff) + 1, ((bits >> 14) & 0x3fff) + 1]
20
+ }
21
+ if (chunk === 'VP8X') {
22
+ const width = 1 + (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16))
23
+ const height = 1 + (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16))
24
+ return [width, height]
25
+ }
26
+ return null
27
+ }
28
+
29
+ /** Start-of-frame markers, which carry the size; C4, C8, and CC are other segments. */
30
+ function isStartOfFrame(marker: number): boolean {
31
+ return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc
32
+ }
33
+
34
+ const APP1 = 0xe1
35
+ const ORIENTATION_TAG = 0x0112
36
+
37
+ /**
38
+ * The Exif Orientation in an APP1 segment starting at `at`: 1 when the Exif data names none,
39
+ * and null when the segment is not Exif, such as XMP, which says nothing about orientation. Orientations 5
40
+ * to 8 turn the image a quarter, so browsers lay it out with width and height swapped.
41
+ */
42
+ function exifOrientation(
43
+ bytes: Uint8Array,
44
+ view: DataView,
45
+ at: number,
46
+ end: number
47
+ ): number | null {
48
+ const tiff = at + 10
49
+ if (tiff + 8 > end || ascii(bytes, at + 4, 6) !== 'Exif\0\0') return null
50
+ const littleEndian = ascii(bytes, tiff, 2) === 'II'
51
+ const firstIFD = tiff + view.getUint32(tiff + 4, littleEndian)
52
+ if (firstIFD + 2 > end) return 1
53
+ const entries = view.getUint16(firstIFD, littleEndian)
54
+ for (let entry = 0; entry < entries; entry++) {
55
+ const offset = firstIFD + 2 + entry * 12
56
+ if (offset + 12 > end) return 1
57
+ if (view.getUint16(offset, littleEndian) === ORIENTATION_TAG) {
58
+ return view.getUint16(offset + 8, littleEndian)
59
+ }
60
+ }
61
+ return 1
62
+ }
63
+
64
+ function jpegSize(bytes: Uint8Array, view: DataView): Size | null {
65
+ let orientation = 1
66
+ let at = 2
67
+ while (at + 9 < bytes.length) {
68
+ if (bytes[at] !== 0xff) return null
69
+ // Any number of 0xFF fill bytes may come before a marker.
70
+ let markerAt = at + 1
71
+ while (markerAt < bytes.length && bytes[markerAt] === 0xff) markerAt++
72
+ if (markerAt + 7 >= bytes.length) return null
73
+ const marker = bytes[markerAt]
74
+ // A segment's length counts its own two bytes, so less is a broken file.
75
+ const length = view.getUint16(markerAt + 1)
76
+ if (length < 2) return null
77
+ const segment = markerAt - 1
78
+ const end = Math.min(bytes.length, markerAt + 1 + length)
79
+ if (marker === APP1) orientation = exifOrientation(bytes, view, segment, end) ?? orientation
80
+ if (isStartOfFrame(marker)) {
81
+ const size: Size = [view.getUint16(markerAt + 6), view.getUint16(markerAt + 4)]
82
+ return orientation >= 5 && orientation <= 8 ? [size[1], size[0]] : size
83
+ }
84
+ at = end
85
+ }
86
+ return null
87
+ }
88
+
89
+ const ISPE = [0x69, 0x73, 0x70, 0x65]
90
+
91
+ /**
92
+ * An AVIF's size from its `ispe` box, wherever the file puts it: the box's type, then its
93
+ * version and flags, then two 32-bit sizes. A match counts only when the size the box header
94
+ * before it gives holds all of that and fits in the file.
95
+ */
96
+ function avifSize(bytes: Uint8Array, view: DataView): Size | null {
97
+ for (let at = 4; at + 16 <= bytes.length; at++) {
98
+ if (ISPE.some((byte, index) => bytes[at + index] !== byte)) continue
99
+ const boxSize = view.getUint32(at - 4)
100
+ if (boxSize < 20 || at - 4 + boxSize > bytes.length) continue
101
+ return [view.getUint32(at + 8), view.getUint32(at + 12)]
102
+ }
103
+ return null
104
+ }
105
+
106
+ /** An image file's pixel size from its header, or null for a format it does not know. */
107
+ export function rasterImageSize(bytes: Uint8Array): Size | null {
108
+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
109
+ // The size is in the IHDR chunk, which a PNG must start with.
110
+ if (
111
+ bytes.length > 24 &&
112
+ bytes[0] === 0x89 &&
113
+ ascii(bytes, 1, 3) === 'PNG' &&
114
+ ascii(bytes, 12, 4) === 'IHDR'
115
+ ) {
116
+ return [view.getUint32(16), view.getUint32(20)]
117
+ }
118
+ if (bytes.length > 10 && ascii(bytes, 0, 3) === 'GIF') {
119
+ return [view.getUint16(6, true), view.getUint16(8, true)]
120
+ }
121
+ if (bytes.length > 30 && ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') {
122
+ return webpSize(bytes, view)
123
+ }
124
+ if (bytes.length > 4 && bytes[0] === 0xff && bytes[1] === 0xd8) return jpegSize(bytes, view)
125
+ if (bytes.length > 32 && ascii(bytes, 4, 4) === 'ftyp' && /avi[fs]/.test(ascii(bytes, 8, 4))) {
126
+ return avifSize(bytes, view)
127
+ }
128
+ return null
129
+ }
130
+
131
+ /** An empty SVG of the image's size, which the engine lays out as the image would be. */
132
+ export function imageStandIn([width, height]: Size): Uint8Array {
133
+ return new TextEncoder().encode(
134
+ `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"/>`
135
+ )
136
+ }
package/src/index.ts ADDED
@@ -0,0 +1,14 @@
1
+ export {
2
+ HTMLEngine,
3
+ type HTMLEngineFetch,
4
+ type HTMLEngineLayoutOptions,
5
+ type HTMLEngineResource
6
+ } from './engine'
7
+ export { rasterImageSize } from './images'
8
+ export { loadHTMLEngine, setHTMLEngineLocator, type HTMLEngineLocator } from './load'
9
+ export {
10
+ createHTMLEngineRuntime,
11
+ type HTMLEngineFontFace,
12
+ type HTMLEngineRuntimeOptions
13
+ } from './runtime'
14
+ export type { HTMLEngineCapture, HTMLEngineLine, HTMLEngineNode } from './schema'
package/src/load.ts ADDED
@@ -0,0 +1,53 @@
1
+ import { HTMLEngine } from './engine'
2
+
3
+ /**
4
+ * Where the engine's module (`html-engine.wasm`) loads from. By default it is read beside this
5
+ * package, as Node and Bun resolve it; a host that serves it elsewhere, such as a bundled app,
6
+ * points here instead.
7
+ */
8
+ export type HTMLEngineLocator = () => string
9
+
10
+ let locator: HTMLEngineLocator = () =>
11
+ import.meta.resolve('@open-pencil/html-engine/wasm/html-engine.wasm')
12
+
13
+ let loading: Promise<HTMLEngine> | null = null
14
+
15
+ /**
16
+ * How long a remote module may take to arrive, so a request that never settles cannot hold every
17
+ * later load waiting on it; a failed load is retried by the next caller.
18
+ */
19
+ const MODULE_LOAD_TIMEOUT_MS = 60_000
20
+
21
+ /** Points the engine at the host's copy of its module. Call before the first `loadHTMLEngine`. */
22
+ export function setHTMLEngineLocator(locate: HTMLEngineLocator): void {
23
+ locator = locate
24
+ loading = null
25
+ }
26
+
27
+ async function readModule(url: string): Promise<ArrayBuffer> {
28
+ if (!url.startsWith('file:')) {
29
+ const response = await fetch(url, { signal: AbortSignal.timeout(MODULE_LOAD_TIMEOUT_MS) })
30
+ if (!response.ok)
31
+ throw new Error(`html-engine.wasm failed to load from ${url}: ${response.status}`)
32
+ return response.arrayBuffer()
33
+ }
34
+ const { readFile } = await import(/* @vite-ignore */ 'node:fs/promises')
35
+ const file = await readFile(new URL(url)).catch((error: unknown) => {
36
+ throw new Error(
37
+ `html-engine.wasm is missing at ${url}; build it with bun run build in packages/html-engine`,
38
+ { cause: error }
39
+ )
40
+ })
41
+ return file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength)
42
+ }
43
+
44
+ /** The engine, loaded once; a failed load is retried by the next caller. */
45
+ export function loadHTMLEngine(): Promise<HTMLEngine> {
46
+ if (loading) return loading
47
+ const load = readModule(locator()).then((bytes) => HTMLEngine.instantiate(bytes))
48
+ loading = load
49
+ load.catch(() => {
50
+ if (loading === load) loading = null
51
+ })
52
+ return load
53
+ }