@tiqian/precompute 0.0.0-stage → 0.1.0-alpha.9

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/lib/cache.js ADDED
@@ -0,0 +1,196 @@
1
+ // The cache and submission bridge over the native addon (ADR 0052). The
2
+ // host-side SDK absorbs the wire complexity: callers hand over plain input
3
+ // objects, this module builds the canonical bytes, packs the binary buffers
4
+ // and reads the results back. Keys arrive from Rust as opaque 32-byte values;
5
+ // the store-key combination never exists on this side.
6
+ import { addon } from "./load.js";
7
+ import { canonicalSubmission, memberOf, } from "./canonical.js";
8
+ const RESULTS_MAGIC = Buffer.from("TQSR", "ascii");
9
+ const RECORDS_MAGIC = Buffer.from("TQCR", "ascii");
10
+ const SUBMISSIONS_MAGIC = Buffer.from("TQSU", "ascii");
11
+ const BRIDGE_VERSION = 1;
12
+ /** Builds one submission item from a wire input; the canonical bytes and
13
+ * their hash are derived here, the caller never touches them. */
14
+ export function submissionItem(input, kind) {
15
+ const { canonical, hash } = canonicalSubmission(input, kind);
16
+ const rawKey = memberOf(input, "key");
17
+ const logicalKey = rawKey === undefined || rawKey === null ? "" : String(rawKey);
18
+ return { hash, logicalKey, canonical };
19
+ }
20
+ /** Grows a buffer in chunks; every multi-byte integer is little-endian. */
21
+ class BridgeWriter {
22
+ chunks = [];
23
+ scratch = new DataView(new ArrayBuffer(4));
24
+ pushScratch() {
25
+ this.chunks.push(Buffer.from(new Uint8Array(this.scratch.buffer, 0, 4)));
26
+ }
27
+ u8(value) {
28
+ this.chunks.push(Buffer.from([value]));
29
+ }
30
+ count(value) {
31
+ this.scratch.setUint32(0, value, true);
32
+ this.pushScratch();
33
+ }
34
+ bytes(value) {
35
+ this.count(value.length);
36
+ this.chunks.push(Buffer.from(value));
37
+ }
38
+ /** Fixed-width fields (hashes) travel without a length prefix. */
39
+ raw(value) {
40
+ this.chunks.push(Buffer.from(value));
41
+ }
42
+ str(value) {
43
+ this.bytes(Buffer.from(value, "utf8"));
44
+ }
45
+ header(magic) {
46
+ this.chunks.push(magic);
47
+ this.u8(BRIDGE_VERSION);
48
+ }
49
+ finish() {
50
+ return Buffer.concat(this.chunks);
51
+ }
52
+ }
53
+ /** Bounds-checked reading over one packed buffer. */
54
+ class BridgeReader {
55
+ bytes;
56
+ view;
57
+ cursor = 0;
58
+ constructor(bytes) {
59
+ this.bytes = bytes;
60
+ this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
61
+ }
62
+ take(length) {
63
+ const end = this.cursor + length;
64
+ if (end > this.bytes.length) {
65
+ throw new Error("InvalidCacheBuffer");
66
+ }
67
+ const slice = this.bytes.subarray(this.cursor, end);
68
+ this.cursor = end;
69
+ return slice;
70
+ }
71
+ u8() {
72
+ return this.take(1)[0] ?? 0;
73
+ }
74
+ u32() {
75
+ const value = this.view.getUint32(this.cursor, true);
76
+ this.cursor += 4;
77
+ return value;
78
+ }
79
+ hash() {
80
+ return Buffer.from(this.take(32));
81
+ }
82
+ takeLength() {
83
+ const length = this.u32();
84
+ return this.take(length);
85
+ }
86
+ header(magic) {
87
+ if (!this.take(4).equals(magic)) {
88
+ throw new Error("InvalidCacheMagic");
89
+ }
90
+ if (this.u8() !== BRIDGE_VERSION) {
91
+ throw new Error("InvalidCacheBridgeVersion");
92
+ }
93
+ return this.u32();
94
+ }
95
+ done() {
96
+ if (this.cursor !== this.bytes.length) {
97
+ throw new Error("InvalidCacheBuffer");
98
+ }
99
+ }
100
+ }
101
+ function packHashes(hashes) {
102
+ const writer = new BridgeWriter();
103
+ for (const hash of hashes) {
104
+ writer.raw(hash);
105
+ }
106
+ return writer.finish();
107
+ }
108
+ function packSubmissions(items) {
109
+ const writer = new BridgeWriter();
110
+ writer.header(SUBMISSIONS_MAGIC);
111
+ writer.count(items.length);
112
+ for (const item of items) {
113
+ writer.raw(item.hash);
114
+ writer.str(item.logicalKey);
115
+ writer.bytes(item.canonical);
116
+ }
117
+ return writer.finish();
118
+ }
119
+ /** Serializes records for a host store; each blob holds its own header. */
120
+ export function packRecords(records) {
121
+ const writer = new BridgeWriter();
122
+ writer.header(RECORDS_MAGIC);
123
+ writer.count(records.length);
124
+ for (const record of records) {
125
+ writer.u8(record.tier === "fontContract" ? 1 : 0);
126
+ writer.raw(record.key);
127
+ writer.raw(record.contentHash);
128
+ writer.raw(record.artifactSha);
129
+ writer.bytes(record.artifact);
130
+ }
131
+ return writer.finish();
132
+ }
133
+ /** Reads records back from one packed blob. */
134
+ export function unpackRecords(buffer) {
135
+ const reader = new BridgeReader(Buffer.from(buffer));
136
+ const count = reader.header(RECORDS_MAGIC);
137
+ const records = [];
138
+ for (let index = 0; index < count; index += 1) {
139
+ const tierCode = reader.u8();
140
+ const tier = tierCode === 1 ? "fontContract" : "snapshot";
141
+ records.push({
142
+ tier,
143
+ key: reader.hash(),
144
+ contentHash: reader.hash(),
145
+ artifactSha: reader.hash(),
146
+ artifact: reader.takeLength(),
147
+ });
148
+ }
149
+ reader.done();
150
+ return records;
151
+ }
152
+ function unpackResults(buffer) {
153
+ const reader = new BridgeReader(Buffer.from(buffer));
154
+ const count = reader.header(RESULTS_MAGIC);
155
+ const outcomes = [];
156
+ for (let index = 0; index < count; index += 1) {
157
+ const status = reader.u8();
158
+ if (status === 0) {
159
+ outcomes.push({ status: "computed", artifact: reader.takeLength() });
160
+ }
161
+ else if (status === 1) {
162
+ outcomes.push({ status: "hit", artifactSha: reader.hash() });
163
+ }
164
+ else {
165
+ outcomes.push({ status: "needContent" });
166
+ }
167
+ }
168
+ reader.done();
169
+ return outcomes;
170
+ }
171
+ /** Internal: the bridge bound to one native registry handle. */
172
+ export function createCacheBridge(handle) {
173
+ return {
174
+ context() {
175
+ return addon.cacheContext(handle);
176
+ },
177
+ submitHashes(hashes) {
178
+ return unpackResults(addon.cacheSubmitHashes(handle, packHashes(hashes)));
179
+ },
180
+ submitContents(items) {
181
+ return unpackResults(addon.cacheSubmitContents(handle, packSubmissions(items)));
182
+ },
183
+ prefillContents(items) {
184
+ return addon.cachePrefillContents(handle, packSubmissions(items));
185
+ },
186
+ prefetch(records) {
187
+ return addon.cachePrefetch(handle, packRecords(records));
188
+ },
189
+ drainWrites() {
190
+ return unpackRecords(addon.cacheDrainWrites(handle));
191
+ },
192
+ evictExcept(keys) {
193
+ addon.cacheEvictExcept(handle, packHashes(keys));
194
+ },
195
+ };
196
+ }
@@ -0,0 +1,26 @@
1
+ /** Snapshot paragraph submission: carries `maxWidthPx`. */
2
+ export declare const KIND_SNAPSHOT = 0;
3
+ /** Font contract submission: the capture width is derived in Rust. */
4
+ export declare const KIND_CONTRACT = 1;
5
+ export type CanonicalKind = typeof KIND_SNAPSHOT | typeof KIND_CONTRACT;
6
+ /**
7
+ * The wire input the encoder reads. The members match the paragraph and
8
+ * contract input interfaces of `precompute.ts`; the walk below applies the
9
+ * same loose coercions the generated encoder carries.
10
+ */
11
+ export type CanonicalSubmissionInput = Readonly<object>;
12
+ /** One dynamically read member: absent and null both read as absent. */
13
+ export declare function memberOf(input: unknown, name: string): unknown;
14
+ /**
15
+ * Encodes one wire input object into its canonical bytes. `kind` selects the
16
+ * snapshot or contract form; snapshot inputs carry `maxWidthPx`, contract
17
+ * inputs never do.
18
+ */
19
+ export declare function encodeCanonicalInput(input: CanonicalSubmissionInput, kind: CanonicalKind): Buffer;
20
+ /** Raw SHA-256 digest, the cache-layer content hash of the canonical bytes. */
21
+ export declare function canonicalDigest(bytes: Uint8Array): Buffer;
22
+ /** The canonical bytes of one input and their content hash, in one step. */
23
+ export declare function canonicalSubmission(input: CanonicalSubmissionInput, kind: CanonicalKind): {
24
+ canonical: Buffer;
25
+ hash: Buffer;
26
+ };
@@ -0,0 +1,65 @@
1
+ // The TypeScript adapter of the single-source canonical encoder (ADR 0052).
2
+ // The byte form itself lives in the Haxe module org.tiqian.protocol.Canonical
3
+ // and arrives through the generated tree in the @tiqian/protocol package
4
+ // (driver bundle protocol-ts). The bytes
5
+ // are the hash preimage of the cache layers and the content of the binary
6
+ // bridge; golden vectors in test/canonical.test.ts pin the same hex strings
7
+ // the Haxe-generated test and the Rust unit tests assert.
8
+ //
9
+ // This adapter owns only the platform seam: it walks the live JS submission
10
+ // into the generated wire value (insertion order preserved, the identity
11
+ // order of attribute pairs), raises the named issue as a JS error, and keeps
12
+ // the digest on node:crypto until the consumer rewiring task switches it to
13
+ // the generated haxe.crypto.Sha256 entry.
14
+ import { createHash } from "node:crypto";
15
+ import { Canonical } from "@tiqian/protocol/org/tiqian/protocol/Canonical";
16
+ /** Snapshot paragraph submission: carries `maxWidthPx`. */
17
+ export const KIND_SNAPSHOT = 0;
18
+ /** Font contract submission: the capture width is derived in Rust. */
19
+ export const KIND_CONTRACT = 1;
20
+ /** Walks one live JS value into the generated wire value. */
21
+ function toWire(value) {
22
+ if (value === undefined || value === null) {
23
+ return { kind: "WNull" };
24
+ }
25
+ const typeofValue = typeof value;
26
+ if (typeofValue === "boolean") {
27
+ return { kind: "WBool", value: value };
28
+ }
29
+ if (typeofValue === "number") {
30
+ return { kind: "WNum", value: value };
31
+ }
32
+ if (typeofValue === "string") {
33
+ return { kind: "WStr", value: value };
34
+ }
35
+ if (Array.isArray(value)) {
36
+ return { kind: "WArr", items: value.map((item) => toWire(item)) };
37
+ }
38
+ const fields = Object.entries(value).map(([name, member]) => ({ name, value: toWire(member) }));
39
+ return { kind: "WObj", fields };
40
+ }
41
+ /** One dynamically read member: absent and null both read as absent. */
42
+ export function memberOf(input, name) {
43
+ return input?.[name];
44
+ }
45
+ /**
46
+ * Encodes one wire input object into its canonical bytes. `kind` selects the
47
+ * snapshot or contract form; snapshot inputs carry `maxWidthPx`, contract
48
+ * inputs never do.
49
+ */
50
+ export function encodeCanonicalInput(input, kind) {
51
+ const result = Canonical.encode(toWire(input), kind);
52
+ if (result.kind === "CErr") {
53
+ throw new Error(result.issue);
54
+ }
55
+ return Buffer.from(result.bytes);
56
+ }
57
+ /** Raw SHA-256 digest, the cache-layer content hash of the canonical bytes. */
58
+ export function canonicalDigest(bytes) {
59
+ return createHash("sha256").update(bytes).digest();
60
+ }
61
+ /** The canonical bytes of one input and their content hash, in one step. */
62
+ export function canonicalSubmission(input, kind) {
63
+ const canonical = encodeCanonicalInput(input, kind);
64
+ return { canonical, hash: canonicalDigest(canonical) };
65
+ }
package/lib/fonts.d.ts ADDED
@@ -0,0 +1,177 @@
1
+ /**
2
+ * One `@font-face` input of `createFontSession`.
3
+ */
4
+ export interface FontFaceSpecInput {
5
+ family: string;
6
+ publicUrl: string;
7
+ source: Uint8Array | Buffer;
8
+ weight?: number | [number, number];
9
+ style?: string;
10
+ unicodeRange?: string;
11
+ sourceOrder?: number;
12
+ faceIndex?: number;
13
+ }
14
+ export interface FontSessionOptions {
15
+ sessionPrefix?: string;
16
+ /** Only `lnum` is accepted; any other tag throws `UnsupportedFontSessionBaseFeatures`. */
17
+ baseFeatures?: string[];
18
+ }
19
+ export interface ShapeGlyph {
20
+ id: number;
21
+ cluster: number;
22
+ advance: number;
23
+ x: number;
24
+ y: number;
25
+ bounds?: number[];
26
+ }
27
+ export interface ShapeResult {
28
+ faceId: string;
29
+ fontInstanceId: string;
30
+ script: string;
31
+ features: string[];
32
+ probeFeatures: string[];
33
+ unsafeBreakCount: number;
34
+ advance: number;
35
+ glyphs: ShapeGlyph[];
36
+ }
37
+ export interface FaceInfo {
38
+ family: string;
39
+ style: string;
40
+ weight: [number, number];
41
+ unicodeRange: string;
42
+ publicUrl: string;
43
+ sourceSha256: string;
44
+ sfntSha256: string;
45
+ faceIndex: number;
46
+ sourceOrder: number;
47
+ axisTags: string[];
48
+ localNames: string[];
49
+ }
50
+ export interface BoundaryStyleInput {
51
+ fontFamilies: string[];
52
+ fontSizePx: number;
53
+ fontWeight: number;
54
+ italic: boolean;
55
+ baselineShiftPx?: number;
56
+ }
57
+ export interface BoundaryTextSpanInput {
58
+ start: number;
59
+ end: number;
60
+ style: BoundaryStyleInput;
61
+ }
62
+ /** Paragraph typography of the `precomputeParagraph` call. */
63
+ export interface ParagraphTypography {
64
+ fontFamilies: string[];
65
+ fontSizePx: number;
66
+ lineHeightPx: number;
67
+ locale: string;
68
+ fontWeight: number;
69
+ italic: boolean;
70
+ firstLineIndentIc: number;
71
+ lineLengthGridEnabled: boolean;
72
+ }
73
+ /** One styled span inside a paragraph. Indices count UTF-16 code units. */
74
+ export interface ParagraphTextSpanInput {
75
+ start: number;
76
+ end: number;
77
+ families: string[];
78
+ fontSizePx: number;
79
+ fontWeight: number;
80
+ italic: boolean;
81
+ baselineShiftPx: number;
82
+ }
83
+ /** One inline box inside a paragraph. */
84
+ export interface ParagraphInlineBoxInput {
85
+ start: number;
86
+ end: number;
87
+ inlineStartPx: number;
88
+ inlineEndPx: number;
89
+ /** Omitted boxes use the `Narrow` default of the protocol. */
90
+ outerSpacing?: "Narrow" | "Source";
91
+ }
92
+ /** One line-break policy span inside a paragraph. */
93
+ export interface ParagraphLineBreakSpanInput {
94
+ start: number;
95
+ end: number;
96
+ policy: "ProgressiveTechnical";
97
+ }
98
+ /** Optional span sections of a paragraph request. */
99
+ export interface ParagraphSpans {
100
+ sourceBoundaries?: number[];
101
+ textSpans?: ParagraphTextSpanInput[];
102
+ inlineBoxes?: ParagraphInlineBoxInput[];
103
+ lineBreakSpans?: ParagraphLineBreakSpanInput[];
104
+ }
105
+ /** Why a line ended; the engine names match `LineEndReason`. */
106
+ export type PlanEndReason = "AutoWrap" | "MandatoryBreak" | "ParagraphEnd";
107
+ /** One laid-out cell of a plan line. */
108
+ export interface PlanCell {
109
+ rangeStart: number;
110
+ rangeEnd: number;
111
+ source: string;
112
+ display: string;
113
+ drawX: number;
114
+ naturalWidth: number;
115
+ leadingLayoutAdvance: number;
116
+ /** Present only when the cell opens a shaping boundary. */
117
+ shapingBoundary?: true;
118
+ /** Present only when the run carries OpenType features. */
119
+ openTypeFeatures?: string[];
120
+ }
121
+ /** One line of the plan JSON. */
122
+ export interface PlanLine {
123
+ rangeStart: number;
124
+ rangeEnd: number;
125
+ top: number;
126
+ bottom: number;
127
+ baseline: number;
128
+ indent: number;
129
+ visualWidth: number;
130
+ hyphenAdvance: number;
131
+ endReason: PlanEndReason;
132
+ cells: PlanCell[];
133
+ }
134
+ /** The plan JSON of one paragraph, parsed at the boundary. */
135
+ export interface PreparedPlan {
136
+ schema: string;
137
+ layoutRevision: string;
138
+ width: number;
139
+ height: number;
140
+ lines: PlanLine[];
141
+ }
142
+ export interface FontEvidence {
143
+ backendRevision: string;
144
+ harfbuzzVersion: string;
145
+ faces: Array<Record<string, unknown>>;
146
+ replay: {
147
+ revision: string;
148
+ shapes: Array<Record<string, unknown>>;
149
+ metrics: Array<Record<string, unknown>>;
150
+ };
151
+ }
152
+ export interface FontSession {
153
+ id: string;
154
+ backendRevision: string;
155
+ harfbuzzVersion: string;
156
+ readonly faces: FaceInfo[];
157
+ shape(displayText: string, families: string[], fontSize: number, fontWeight: number, italic: boolean, locale: string, role?: string | null, sourceText?: string | null): ShapeResult;
158
+ metrics(families: string[], fontSize: number, fontWeight: number, italic: boolean, role?: string | null, faceSelectionText?: string | null): number[];
159
+ renderFamilies(requestedFamilies: string[]): string[];
160
+ sourceBoundaries(text: string, baseStyle: BoundaryStyleInput, textSpans: BoundaryTextSpanInput[]): number[];
161
+ /**
162
+ * Runs one paragraph through the engine with this session as the font
163
+ * backend. Throws the named validation issues of the request; throws
164
+ * `EngineNotLinked` when the addon was built without the engine archive.
165
+ */
166
+ precomputeParagraph(text: string, maxWidthPx: number, typography: ParagraphTypography, spans?: ParagraphSpans): PreparedPlan;
167
+ beginCapture(): void;
168
+ captureEvidence(): FontEvidence;
169
+ close(): void;
170
+ }
171
+ /**
172
+ * Creates a font session from explicit `@font-face` inputs. `faceSpecs`
173
+ * entries carry their font binary as `source` (Uint8Array or Buffer).
174
+ */
175
+ export declare function createFontSession(faceSpecs: FontFaceSpecInput[], options?: FontSessionOptions): Promise<FontSession>;
176
+ export declare const backendRevision: string;
177
+ export declare const harfbuzzVersion: string;
package/lib/fonts.js ADDED
@@ -0,0 +1,89 @@
1
+ // The unified font session over the native addon (ADR 0050). The session
2
+ // surface matches `createFontSession` from the former
3
+ // `@tiqian/web-component/precompute-fonts` module; shape and metrics are session
4
+ // methods here because the native world has no global WASM backend handle
5
+ // protocol.
6
+ import { currentPlatform } from "@neon-rs/load";
7
+ import { addon } from "./load.js";
8
+ const SUPPORTED_PLATFORMS = new Set([
9
+ "win32-x64-msvc",
10
+ "darwin-arm64",
11
+ "linux-x64-gnu",
12
+ "linux-arm64-gnu",
13
+ ]);
14
+ const platform = currentPlatform();
15
+ if (!SUPPORTED_PLATFORMS.has(platform)) {
16
+ throw new Error(`UnsupportedPrecomputePlatform:${platform}`);
17
+ }
18
+ /**
19
+ * Parses a JSON string produced by the shared Rust emitters. The addon and
20
+ * the Kotlin/JS oracle emit the same bytes; parsing happens only here, at
21
+ * the boundary.
22
+ */
23
+ function parse(json) {
24
+ return JSON.parse(json);
25
+ }
26
+ function toBuffer(source) {
27
+ return Buffer.isBuffer(source) ? source : Buffer.from(source);
28
+ }
29
+ /**
30
+ * Creates a font session from explicit `@font-face` inputs. `faceSpecs`
31
+ * entries carry their font binary as `source` (Uint8Array or Buffer).
32
+ */
33
+ export async function createFontSession(faceSpecs, options = {}) {
34
+ if (!Array.isArray(faceSpecs) || faceSpecs.length === 0) {
35
+ throw new Error("MissingExplicitFontFaces");
36
+ }
37
+ const sources = [];
38
+ const faces = faceSpecs.map((face) => {
39
+ sources.push(toBuffer(face.source));
40
+ return {
41
+ family: face.family,
42
+ publicUrl: face.publicUrl,
43
+ font: sources.length - 1,
44
+ faceIndex: face.faceIndex ?? null,
45
+ weight: face.weight,
46
+ style: face.style,
47
+ unicodeRange: face.unicodeRange ?? null,
48
+ sourceOrder: face.sourceOrder ?? null,
49
+ };
50
+ });
51
+ const id = addon.createFontSession(faces, sources, {
52
+ sessionPrefix: options.sessionPrefix ?? null,
53
+ baseFeatures: options.baseFeatures ?? null,
54
+ });
55
+ return {
56
+ id,
57
+ backendRevision: addon.backendRevision(),
58
+ harfbuzzVersion: addon.harfbuzzVersion(),
59
+ get faces() {
60
+ return parse(addon.sessionFaces(id));
61
+ },
62
+ shape(displayText, families, fontSize, fontWeight, italic, locale, role = null, sourceText = null) {
63
+ return parse(addon.shape(id, displayText, families, fontSize, fontWeight, italic, locale, role, sourceText));
64
+ },
65
+ metrics(families, fontSize, fontWeight, italic, role = null, faceSelectionText = null) {
66
+ return parse(addon.metrics(id, families, fontSize, fontWeight, italic, role, faceSelectionText));
67
+ },
68
+ renderFamilies(requestedFamilies) {
69
+ return parse(addon.renderFamilies(id, requestedFamilies));
70
+ },
71
+ sourceBoundaries(text, baseStyle, textSpans) {
72
+ return parse(addon.sourceBoundaries(id, text, baseStyle, textSpans));
73
+ },
74
+ precomputeParagraph(text, maxWidthPx, typography, spans = {}) {
75
+ return parse(addon.precomputeParagraph(id, text, maxWidthPx, typography.fontFamilies, typography.fontSizePx, typography.lineHeightPx, typography.locale, typography.fontWeight, typography.italic, typography.firstLineIndentIc, typography.lineLengthGridEnabled, spans.sourceBoundaries ?? [], spans.textSpans ?? [], spans.inlineBoxes ?? [], spans.lineBreakSpans ?? []));
76
+ },
77
+ beginCapture() {
78
+ addon.beginCapture(id);
79
+ },
80
+ captureEvidence() {
81
+ return parse(addon.captureEvidence(id));
82
+ },
83
+ close() {
84
+ addon.closeSession(id);
85
+ },
86
+ };
87
+ }
88
+ export const backendRevision = addon.backendRevision();
89
+ export const harfbuzzVersion = addon.harfbuzzVersion();
package/lib/load.d.ts ADDED
@@ -0,0 +1,138 @@
1
+ /** One face entry of the `createFontSession` wire protocol. */
2
+ export interface NativeFaceSpec {
3
+ family: string;
4
+ publicUrl: string;
5
+ /** Index into the `sources` array passed alongside the face list. */
6
+ font: number;
7
+ faceIndex: number | null;
8
+ weight?: number | readonly [number, number];
9
+ style?: string;
10
+ unicodeRange: string | null;
11
+ sourceOrder: number | null;
12
+ }
13
+ /** Session options of the `createFontSession` wire protocol. */
14
+ export interface NativeSessionOptions {
15
+ sessionPrefix: string | null;
16
+ baseFeatures: string[] | null;
17
+ }
18
+ /** Boundary style of the `sourceBoundaries` wire protocol. */
19
+ export interface NativeBoundaryStyle {
20
+ fontFamilies: string[];
21
+ fontSizePx: number;
22
+ fontWeight: number;
23
+ italic: boolean;
24
+ baselineShiftPx?: number | null;
25
+ }
26
+ /** Boundary span of the `sourceBoundaries` wire protocol. */
27
+ export interface NativeBoundarySpan {
28
+ start: number;
29
+ end: number;
30
+ style: NativeBoundaryStyle;
31
+ }
32
+ /** One styled span of the `precomputeParagraph` protocol. */
33
+ export interface NativeTextSpan {
34
+ start: number;
35
+ end: number;
36
+ families: string[];
37
+ fontSizePx: number;
38
+ fontWeight: number;
39
+ italic: boolean;
40
+ baselineShiftPx: number;
41
+ }
42
+ /** One inline box of the `precomputeParagraph` protocol. */
43
+ export interface NativeInlineBox {
44
+ start: number;
45
+ end: number;
46
+ inlineStartPx: number;
47
+ inlineEndPx: number;
48
+ /** Omitted boxes use the `Narrow` default of the protocol. */
49
+ outerSpacing?: "Narrow" | "Source";
50
+ }
51
+ /** One line-break policy span of the `precomputeParagraph` protocol. */
52
+ export interface NativeLineBreakSpan {
53
+ start: number;
54
+ end: number;
55
+ policy: "ProgressiveTechnical";
56
+ }
57
+ /**
58
+ * The native surface exported by `tiqian-precompute-neon`. Structured results
59
+ * arrive as JSON strings produced by the shared Rust emitters; flat arguments
60
+ * mirror the backend protocol used by the Kotlin/JS oracle.
61
+ */
62
+ export interface NativeAddon {
63
+ backendRevision(): string;
64
+ harfbuzzVersion(): string;
65
+ createFontSession(faces: NativeFaceSpec[], sources: Buffer[], options: NativeSessionOptions): string;
66
+ sessionFaces(sessionId: string): string;
67
+ shape(sessionId: string, displayText: string, families: string[], fontSize: number, fontWeight: number, italic: boolean, locale: string, role: string | null, sourceText: string | null): string;
68
+ metrics(sessionId: string, families: string[], fontSize: number, fontWeight: number, italic: boolean, role: string | null, faceSelectionText: string | null): string;
69
+ renderFamilies(sessionId: string, requestedFamilies: string[]): string;
70
+ sourceBoundaries(sessionId: string, text: string, baseStyle: NativeBoundaryStyle, textSpans: NativeBoundarySpan[]): string;
71
+ /**
72
+ * The structured form of the js facade call: arrays and span objects arrive
73
+ * as themselves. Returns the plan JSON. An addon built without the engine
74
+ * archive throws `EngineNotLinked`.
75
+ */
76
+ precomputeParagraph(sessionId: string, text: string, maxWidthPx: number, families: string[], fontSizePx: number, lineHeightPx: number, locale: string, fontWeight: number, italic: boolean, firstLineIndentIc: number, lineLengthGridEnabled: boolean, sourceBoundaries: number[], textSpans: NativeTextSpan[], inlineBoxes: NativeInlineBox[], lineBreakSpans: NativeLineBreakSpan[]): string;
77
+ beginCapture(sessionId: string): void;
78
+ captureEvidence(sessionId: string): string;
79
+ closeSession(sessionId: string): void;
80
+ /**
81
+ * The precompute lane (ADR 0050). Structured values cross as JSON strings;
82
+ * every object shape belongs to the wrapper entries in `precompute.ts` and
83
+ * `precompute-html.ts`. Handles address the process-wide registries.
84
+ */
85
+ normalizeTypography(typographyJson: string): string;
86
+ createPrecomputer(typographyJson: string, faces: NativeFaceSpec[], sources: Buffer[], budgetCode: number): string;
87
+ precomputerInfo(handle: string): string;
88
+ prepareParagraph(handle: string, inputJson: string): string;
89
+ /** The batch snapshot lane; the paragraph loop stays inside Rust. */
90
+ prepareParagraphs(handle: string, inputsJson: string): string;
91
+ prepareFontContract(handle: string, inputJson: string): string;
92
+ /** The batch contract lane; the loop stays inside Rust. */
93
+ prepareFontContracts(handle: string, inputsJson: string): string;
94
+ closePrecomputer(handle: string): void;
95
+ htmlPreparerInfo(handle: string): string;
96
+ createHtmlPreparer(precomputerHandle: string | null, typographyJson: string, faces: NativeFaceSpec[], sources: Buffer[], paragraphSelector: string | null, skippedAncestorSelector: string | null, sharedRuntimeStyle: string): string;
97
+ /**
98
+ * The whole document in one call; the paragraph loop stays inside Rust.
99
+ * Returns the result json plus the snapshot-table file the emitted manifest
100
+ * pins (`tablesBytes`/`tablesSha256`, or null/undefined without one).
101
+ */
102
+ prepareHtml(handle: string, html: string, optionsJson: string): {
103
+ result: string;
104
+ tablesBytes: Buffer | null;
105
+ tablesSha256: string | undefined;
106
+ };
107
+ closeHtmlPreparer(handle: string): void;
108
+ /** The assembly phase of ADR 0052 schema 2. */
109
+ assembleSnapshotBundle(dataJson: string, optionsJson: string, sharedRuntimeStyle: string): string;
110
+ assembleFontContractBundle(dataJson: string, optionsJson: string, sharedRuntimeStyle: string): string;
111
+ /** The snapshot-tables lane of one build (ADR 0052 `BundleLayering`). */
112
+ createSnapshotTables(): string;
113
+ restoreSnapshotTables(bytes: Buffer): string;
114
+ absorbSnapshotTables(handle: string, preparedJson: string): number;
115
+ finalizeSnapshotTables(handle: string): {
116
+ bytes: Buffer;
117
+ sha256: string;
118
+ };
119
+ closeSnapshotTables(handle: string): void;
120
+ snapshotPlainTextIssue(text: string): string;
121
+ findHtmlOpeningTags(html: string, tagNamesJson: string): string;
122
+ injectHtmlAttributes(html: string, insertionsJson: string): string;
123
+ snapshotServerAssets(bundleJson: string): string;
124
+ renderSnapshotServerAssets(assetsJson: string): string;
125
+ parseBuildFontStylesheet(css: string, sourceFileUrl: string, publicUrl: string | null): string;
126
+ /**
127
+ * The cache and submission bridge (ADR 0052). Binary buffers in and out;
128
+ * the packers and readers live in `cache.ts`, no JSON crosses.
129
+ */
130
+ cacheContext(handle: string): string;
131
+ cacheSubmitHashes(handle: string, hashes: Buffer): Buffer;
132
+ cacheSubmitContents(handle: string, submissions: Buffer): Buffer;
133
+ cachePrefillContents(handle: string, submissions: Buffer): number;
134
+ cachePrefetch(handle: string, records: Buffer): number;
135
+ cacheDrainWrites(handle: string): Buffer;
136
+ cacheEvictExcept(handle: string, keys: Buffer): void;
137
+ }
138
+ export declare const addon: NativeAddon;