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

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.
@@ -0,0 +1,539 @@
1
+ // The precompute entry over the native addon (ADR 0050). The exported
2
+ // surface matches the former `@tiqian/web-component/precompute` module; every
3
+ // computation runs in Rust behind registry handles, and this file owns the
4
+ // object shapes the js API promises. File reading and URL resolution stay
5
+ // here: the crate never touches the filesystem.
6
+ import { createHash } from "node:crypto";
7
+ import { readFileSync } from "node:fs";
8
+ import { readFile } from "node:fs/promises";
9
+ import { resolve } from "node:path";
10
+ import { fileURLToPath, pathToFileURL } from "node:url";
11
+ import { addon } from "./load.js";
12
+ import { renderPreparedParagraph as sharedRenderPreparedParagraph, renderPreparedParagraphArtifact as sharedRenderPreparedParagraphArtifact, } from "@tiqian/web-component/prepared-dom";
13
+ import { Revision } from "@tiqian/protocol/org/tiqian/protocol/Revision";
14
+ import { SnapshotValueStyle } from "@tiqian/shared/org/tiqian/shared/SnapshotValueStyle";
15
+ import { ValueStyleInterner } from "@tiqian/shared/org/tiqian/shared/ValueStyleInterner";
16
+ import { sha256Hex, stableStringify } from "./stable-stringify.js";
17
+ import { createCacheBridge } from "./cache.js";
18
+ const SHARED_RUNTIME_STYLE = readFileSync(new URL(import.meta.resolve("@tiqian/core/styles.css")), "utf8");
19
+ const URL_SCHEME_PREFIX = /^[a-z][a-z0-9+.-]*:/iu;
20
+ const WINDOWS_DRIVE_ABSOLUTE_PATH = /^[a-z]:[\\/]/iu;
21
+ /**
22
+ * Parses a JSON string produced by the shared Rust emitters; parsing happens
23
+ * only at this boundary.
24
+ */
25
+ function parse(json) {
26
+ return JSON.parse(json);
27
+ }
28
+ function toBuffer(source) {
29
+ return Buffer.isBuffer(source) ? source : Buffer.from(source);
30
+ }
31
+ // WindowsDrivePathBeforeUrlScheme: a drive letter is syntactically a valid
32
+ // URL scheme, but Node callers pass path.resolve()/path.join() results here
33
+ // as ordinary local sources. File paths must win before URL handling.
34
+ function isExplicitUrlString(source) {
35
+ return URL_SCHEME_PREFIX.test(source) && !WINDOWS_DRIVE_ABSOLUTE_PATH.test(source);
36
+ }
37
+ async function readSource(source) {
38
+ if (source instanceof Uint8Array)
39
+ return source;
40
+ if (source instanceof ArrayBuffer)
41
+ return new Uint8Array(source);
42
+ if (source instanceof URL) {
43
+ if (source.protocol !== "file:")
44
+ throw new Error(`RemoteFontSourceNotSupported:${source.href}`);
45
+ return new Uint8Array(await readFile(fileURLToPath(source)));
46
+ }
47
+ if (typeof source === "string") {
48
+ if (isExplicitUrlString(source)) {
49
+ const url = new URL(source);
50
+ if (url.protocol !== "file:")
51
+ throw new Error(`RemoteFontSourceNotSupported:${source}`);
52
+ return new Uint8Array(await readFile(fileURLToPath(url)));
53
+ }
54
+ return new Uint8Array(await readFile(source));
55
+ }
56
+ throw new Error("UnsupportedFontSource");
57
+ }
58
+ function stylesheetFileUrl(source) {
59
+ if (source instanceof URL) {
60
+ if (source.protocol !== "file:") {
61
+ throw new Error(`RemoteFontStylesheetNotSupported:${source.href}`);
62
+ }
63
+ return source;
64
+ }
65
+ if (typeof source !== "string" || !source.trim()) {
66
+ throw new Error("UnsupportedFontStylesheetSource");
67
+ }
68
+ if (isExplicitUrlString(source)) {
69
+ const url = new URL(source);
70
+ if (url.protocol !== "file:")
71
+ throw new Error(`RemoteFontStylesheetNotSupported:${source}`);
72
+ return url;
73
+ }
74
+ return pathToFileURL(resolve(source));
75
+ }
76
+ /**
77
+ * Resolves the face inputs of the create calls. Explicit faces carry their
78
+ * bytes; the stylesheet lane reads the CSS here, parses it in Rust and reads
79
+ * the font files the parse resolved. `sourceOrder` accumulates across
80
+ * stylesheets, the js order.
81
+ */
82
+ export async function resolveFaces(options) {
83
+ const explicitFaces = Array.from(options.faces ?? []);
84
+ const stylesheets = Array.from(options.fontStylesheets ?? []);
85
+ if (explicitFaces.length > 0 && stylesheets.length > 0) {
86
+ throw new Error("ConflictingBuildFontSources");
87
+ }
88
+ const sources = [];
89
+ if (explicitFaces.length > 0) {
90
+ for (const face of explicitFaces) {
91
+ sources.push(toBuffer(await readSource(face.source)));
92
+ }
93
+ return {
94
+ faces: explicitFaces.map((face, index) => ({
95
+ family: face.family,
96
+ publicUrl: face.publicUrl,
97
+ font: index,
98
+ faceIndex: face.faceIndex ?? null,
99
+ weight: face.weight,
100
+ style: face.style,
101
+ unicodeRange: face.unicodeRange ?? null,
102
+ sourceOrder: null,
103
+ })),
104
+ sources,
105
+ };
106
+ }
107
+ // Stylesheet lane: the wrapper reads the CSS, Rust parses it and resolves
108
+ // every asset URL; `sourceOrder` accumulates across stylesheets.
109
+ const stylesheetFaces = [];
110
+ for (const stylesheet of stylesheets) {
111
+ if (!stylesheet || typeof stylesheet !== "object")
112
+ throw new Error("InvalidFontStylesheet");
113
+ const fileUrl = stylesheetFileUrl(stylesheet.source);
114
+ const css = await readFile(fileURLToPath(fileUrl), "utf8");
115
+ stylesheetFaces.push(...parse(addon.parseBuildFontStylesheet(css, fileUrl.href, stylesheet.publicUrl ?? null)));
116
+ }
117
+ if (stylesheetFaces.length === 0)
118
+ throw new Error("MissingBuildFontSource");
119
+ for (const face of stylesheetFaces) {
120
+ sources.push(toBuffer(await readFile(face.source)));
121
+ }
122
+ return {
123
+ faces: stylesheetFaces.map((face, index) => ({
124
+ family: face.family,
125
+ publicUrl: face.publicUrl,
126
+ font: index,
127
+ faceIndex: null,
128
+ weight: face.weight ?? undefined,
129
+ style: face.style,
130
+ unicodeRange: face.unicodeRange,
131
+ sourceOrder: index,
132
+ })),
133
+ sources,
134
+ };
135
+ }
136
+ /** Name constants of {@link CacheWriteBudget}. */
137
+ export const CacheWriteBudget = Object.freeze({
138
+ Tight: "tight",
139
+ Normal: "normal",
140
+ Generous: "generous",
141
+ });
142
+ const writeBudgetCodes = new Map([
143
+ ["tight", 0],
144
+ ["normal", 1],
145
+ ["generous", 2],
146
+ ]);
147
+ function writeBudgetCode(value) {
148
+ const code = writeBudgetCodes.get(value);
149
+ if (code === undefined) {
150
+ throw new TypeError(`UnknownCacheWriteBudget:${String(value)}`);
151
+ }
152
+ return code;
153
+ }
154
+ let defaultCacheWriteBudget = CacheWriteBudget.Normal;
155
+ /**
156
+ * Sets the process default every later `createPrecomputer` call uses when its
157
+ * options name no tier. Precomputers already created keep theirs.
158
+ */
159
+ export function setCacheWriteBudget(budget) {
160
+ writeBudgetCode(budget);
161
+ defaultCacheWriteBudget = budget;
162
+ }
163
+ const precomputerHandles = new WeakMap();
164
+ /**
165
+ * Internal: the native registry handle of a precomputer created by this
166
+ * package, for the HTML preparer entry in `precompute-html.ts`.
167
+ */
168
+ export function precomputerHandle(precomputer) {
169
+ return precomputerHandles.get(precomputer) ?? null;
170
+ }
171
+ function freezeEntry(entry) {
172
+ return Object.freeze(entry);
173
+ }
174
+ /**
175
+ * Replays the shared prepared-DOM renderer in Node to recompute the html field
176
+ * and the renderArtifactSha256 field for one prepared entry. The options replay
177
+ * the exact set precomputer.rs builds in render_options (precomputer.rs L305-327)
178
+ * before handing the plan to render_prepared_paragraph_artifact_from_plan:
179
+ * semantics, inlineBoxes, renderTextSpans and sourceText are supplied, while
180
+ * cjkStrongSemantics and styleClassFor stay unset. The options value carries a
181
+ * cast because the shared module declares its option types in a normalized
182
+ * form; the runtime values entry.semantics, entry.inlineBoxes and
183
+ * entry.renderTextSpans carry back are the raw objects the Rust renderer fed the
184
+ * shared renderer, so the replay is byte-faithful.
185
+ */
186
+ function computeRenderArtifact(entry) {
187
+ if (!isSharedPlanInput(entry.plan)) {
188
+ throw new TypeError("prepareParagraph returned a prepared entry without a renderable plan");
189
+ }
190
+ const rendered = sharedRenderPreparedParagraphArtifact(entry.plan, entry.typography.locale, {
191
+ sourceText: entry.sourceText,
192
+ semantics: entry.semantics,
193
+ renderTextSpans: entry.renderTextSpans,
194
+ inlineBoxes: entry.inlineBoxes,
195
+ });
196
+ return {
197
+ html: rendered.html,
198
+ renderArtifactSha256: createHash("sha256")
199
+ .update(stableStringify(rendered.artifact))
200
+ .digest("hex"),
201
+ };
202
+ }
203
+ /**
204
+ * Overwrites the render fields of a prepared entry with the Node-computed
205
+ * values, then freezes the entry. This applies to snapshots and font contracts.
206
+ * Unsupported entries are frozen without adding render fields.
207
+ */
208
+ export function backfillRenderFields(entry) {
209
+ if (entry.status !== "prepared") {
210
+ return freezeEntry(entry);
211
+ }
212
+ const { html, renderArtifactSha256 } = computeRenderArtifact(entry);
213
+ return freezeEntry({ ...entry, html, renderArtifactSha256 });
214
+ }
215
+ /**
216
+ * Creates a precomputer from explicit faces or a host font stylesheet. The
217
+ * typography is normalized in Rust; every named validation error of the js
218
+ * implementation is thrown at the same step.
219
+ */
220
+ export async function createPrecomputer(options) {
221
+ const typographyJson = JSON.stringify(options.typography ?? {});
222
+ // Typography validates before any font file is read, the js order; the
223
+ // native create normalizes the same value again behind its boundary.
224
+ addon.normalizeTypography(typographyJson);
225
+ // The tier validates before any font IO for the same reason.
226
+ const budgetCode = writeBudgetCode(options.cacheWriteBudget ?? defaultCacheWriteBudget);
227
+ const { faces, sources } = await resolveFaces(options);
228
+ const handle = addon.createPrecomputer(typographyJson, faces, sources, budgetCode);
229
+ const info = parse(addon.precomputerInfo(handle));
230
+ const precomputer = {
231
+ typography: Object.freeze(info.typography),
232
+ renderFontFamilies: Object.freeze(info.renderFontFamilies),
233
+ cache: createCacheBridge(handle),
234
+ async prepareParagraph(input) {
235
+ return backfillRenderFields(parse(addon.prepareParagraph(handle, JSON.stringify(input ?? {}))));
236
+ },
237
+ async prepareParagraphs(inputs) {
238
+ return parse(addon.prepareParagraphs(handle, JSON.stringify(Array.from(inputs ?? [])))).map(backfillRenderFields);
239
+ },
240
+ async prepareFontContract(input) {
241
+ // A contract entry joins the same corpus as the snapshot entries, and
242
+ // the corpus gate requires the derived render fields on every member, so
243
+ // this lane derives them the same way.
244
+ return backfillRenderFields(parse(addon.prepareFontContract(handle, JSON.stringify(input ?? {}))));
245
+ },
246
+ async prepareFontContracts(inputs) {
247
+ return parse(addon.prepareFontContracts(handle, JSON.stringify(Array.from(inputs ?? [])))).map(backfillRenderFields);
248
+ },
249
+ close() {
250
+ addon.closePrecomputer(handle);
251
+ },
252
+ };
253
+ precomputerHandles.set(precomputer, handle);
254
+ return Object.freeze(precomputer);
255
+ }
256
+ /**
257
+ * Narrows the public `unknown` plan input to what the shared renderer accepts.
258
+ * The structural check stays coarse on purpose: the shared module owns plan
259
+ * validation, and this gate only rejects values no plan form can take.
260
+ */
261
+ function isSharedPlanInput(value) {
262
+ return typeof value === "string" || (typeof value === "object" && value !== null);
263
+ }
264
+ /**
265
+ * Widens the local typography interface to the record shape the shared
266
+ * renderer accepts. Interfaces carry no implicit index signature, so the
267
+ * spread produces a structurally identical anonymous type that does.
268
+ */
269
+ function toSharedTypography(typography) {
270
+ return { ...typography };
271
+ }
272
+ /**
273
+ * Renders one prepared plan to prepared DOM. The implementation is the exact
274
+ * browser-shared module `@tiqian/web-component` ships, so server embedders and the
275
+ * browser agree on every revision.
276
+ */
277
+ export function renderPreparedParagraph(plan, typography) {
278
+ if (!isSharedPlanInput(plan)) {
279
+ throw new TypeError("renderPreparedParagraph expects a plan JSON string or object");
280
+ }
281
+ return sharedRenderPreparedParagraph(plan, toSharedTypography(typography));
282
+ }
283
+ /** The named plain-text gate of the snapshot lane. */
284
+ export function snapshotPlainTextIssue(text) {
285
+ return parse(addon.snapshotPlainTextIssue(text));
286
+ }
287
+ function freezeBundle(bundle) {
288
+ return Object.freeze({
289
+ ...bundle,
290
+ renderFontFamilies: Object.freeze([...bundle.renderFontFamilies]),
291
+ fontPreloads: Object.freeze([...bundle.fontPreloads]),
292
+ rootAttributes: Object.freeze({ ...bundle.rootAttributes }),
293
+ entries: Object.freeze(bundle.entries.map((entry) => Object.freeze({ ...entry }))),
294
+ });
295
+ }
296
+ /** Creates the empty, unfrozen table set of one build. */
297
+ export function createSnapshotTables() {
298
+ return {
299
+ kind: "snapshot-tables",
300
+ handle: addon.createSnapshotTables(),
301
+ valueStyles: new ValueStyleInterner(),
302
+ };
303
+ }
304
+ /** Restores a previous build's frozen table so a rebuild extends the union. */
305
+ export function restoreSnapshotTables(bytes) {
306
+ return {
307
+ kind: "snapshot-tables",
308
+ handle: addon.restoreSnapshotTables(bytes),
309
+ valueStyles: new ValueStyleInterner(),
310
+ };
311
+ }
312
+ /**
313
+ * Absorbs one batch of prepared entries into the table; returns the absorbed
314
+ * entry count. Absorb and data-phase calls share one mutable table and may
315
+ * interleave in any order; both throw once the table froze.
316
+ */
317
+ export function absorbSnapshotTables(tables, prepared) {
318
+ return addon.absorbSnapshotTables(tables.handle, JSON.stringify(Array.from(prepared ?? [])));
319
+ }
320
+ /**
321
+ * Absorbs table-scoped render metadata; value styles append to the TS-side
322
+ * interner in first-seen order, and re-absorbing an existing declaration
323
+ * keeps its index. The native table rows stay untouched, so the table hash
324
+ * does not change.
325
+ */
326
+ export function absorbSnapshotTablesMetadata(tables, metadata) {
327
+ const rows = metadata?.valueStyles;
328
+ if (!Array.isArray(rows))
329
+ return;
330
+ for (const row of rows) {
331
+ if (typeof row !== "string")
332
+ throw new Error("SnapshotTableValueStylesInvalid");
333
+ tables.valueStyles.intern(row);
334
+ }
335
+ }
336
+ /**
337
+ * Freezes the rows and returns `{bytes, sha256}`; hosts serve the binary
338
+ * verbatim under the sha address. The handle stays usable for assembly.
339
+ */
340
+ export function finalizeSnapshotTables(tables) {
341
+ const file = addon.finalizeSnapshotTables(tables.handle);
342
+ return Object.freeze({ bytes: file.bytes, sha256: file.sha256 });
343
+ }
344
+ /** Drops the table set once every bundle assembled. */
345
+ export function closeSnapshotTables(tables) {
346
+ addon.closeSnapshotTables(tables.handle);
347
+ }
348
+ const SNAPSHOT_SCHEMA = Revision.SNAPSHOT_SCHEMA;
349
+ const LAYOUT_REVISION = Revision.LAYOUT_REVISION;
350
+ const RENDER_REVISION = Revision.RENDER_REVISION;
351
+ const DEFAULT_LOCALE = "zh-Hans";
352
+ /** `PLAIN_PARAGRAPH_SELECTOR`: canonical plain paragraphs of a snapshot root. */
353
+ const PLAIN_PARAGRAPH_SELECTOR = ":is(p, li)[data-tq-snapshot-key]";
354
+ /** `RUNTIME_PARAGRAPH_SELECTOR`: every live paragraph of a semantic root. */
355
+ const RUNTIME_PARAGRAPH_SELECTOR = ":is(p, li):not([data-tiqian-skip])";
356
+ /** `preparedLocale`: a string typography is its locale, an object carries it. */
357
+ function preparedLocale(typography) {
358
+ if (typeof typography === "string")
359
+ return typography;
360
+ if (typography !== null && typeof typography === "object") {
361
+ const locale = typography.locale;
362
+ if (typeof locale === "string")
363
+ return locale;
364
+ if (typeof locale === "number")
365
+ return String(locale);
366
+ if (typeof locale === "boolean")
367
+ return String(locale);
368
+ }
369
+ return DEFAULT_LOCALE;
370
+ }
371
+ /** The corpus gates of the data phase, in the order the Rust port ran them. */
372
+ function bundleCorpus(entries, fontContractEntries) {
373
+ if (entries.length === 0)
374
+ throw new Error("MissingPreparedParagraphs");
375
+ const corpus = [...entries, ...fontContractEntries];
376
+ if (corpus.some((entry) => entry?.status !== "prepared")) {
377
+ throw new Error("SnapshotTemplateContainsUnsupportedParagraph");
378
+ }
379
+ if (corpus.some((entry) => {
380
+ const row = entry;
381
+ return row.schema !== SNAPSHOT_SCHEMA ||
382
+ row.layoutRevision !== LAYOUT_REVISION ||
383
+ row.renderRevision !== RENDER_REVISION ||
384
+ typeof row.renderArtifactSha256 !== "string";
385
+ })) {
386
+ throw new Error("SnapshotTemplateContainsStalePreparedParagraph");
387
+ }
388
+ const seen = new Set();
389
+ for (const entry of corpus) {
390
+ const key = entry.key ?? null;
391
+ const rendered = stableStringify(key);
392
+ if (seen.has(rendered))
393
+ throw new Error("DuplicateSnapshotKey");
394
+ seen.add(rendered);
395
+ }
396
+ return corpus;
397
+ }
398
+ /** The exact render font families every corpus entry must share. */
399
+ function renderFontFamiliesOf(entries) {
400
+ const families = entries[0]?.renderFontFamilies;
401
+ if (!Array.isArray(families) || families.length === 0) {
402
+ throw new Error("MissingExactRenderFontFamilies");
403
+ }
404
+ for (const family of families) {
405
+ if (typeof family !== "string" || family.trim().length === 0) {
406
+ throw new Error("MissingExactRenderFontFamilies");
407
+ }
408
+ }
409
+ return families;
410
+ }
411
+ /**
412
+ * Renders one prepared entry with the shared renderer and hashes its artifact
413
+ * tree with the same stable encoding the Rust renderer used, so the entry
414
+ * keeps its byte identity when the render loop moves here.
415
+ */
416
+ function renderBundleEntry(entry, styleClassFor) {
417
+ const row = entry;
418
+ const plan = row.plan;
419
+ if (plan === undefined || plan === null)
420
+ throw new Error("InvalidPreparedParagraphGeometry");
421
+ const planText = typeof plan === "string" ? plan : JSON.stringify(plan);
422
+ const rendered = sharedRenderPreparedParagraphArtifact(planText, preparedLocale(row.typography), {
423
+ semantics: row.semantics,
424
+ inlineBoxes: row.inlineBoxes,
425
+ renderTextSpans: row.renderTextSpans,
426
+ sourceText: typeof row.sourceText === "string" ? row.sourceText : undefined,
427
+ styleClassFor,
428
+ });
429
+ return {
430
+ ...row,
431
+ html: rendered.html,
432
+ renderArtifactSha256: sha256Hex(stableStringify(rendered.artifact)),
433
+ };
434
+ }
435
+ /**
436
+ * The data phase over one entry list: gates, per-entry render with the shared
437
+ * renderer, and the class indexes this bundle minted. First-paint rules are
438
+ * appended at assembly from these indexes.
439
+ */
440
+ function renderBundleData(preparedParagraphs, options, supportedParagraphSelector) {
441
+ const entries = Array.from(preparedParagraphs ?? []);
442
+ const fontContractEntries = Array.from(options.fontContractParagraphs ?? []);
443
+ const corpus = bundleCorpus(entries, fontContractEntries);
444
+ const families = renderFontFamiliesOf(entries);
445
+ const familySignature = stableStringify(families);
446
+ for (const entry of corpus) {
447
+ const entryFamilies = entry.renderFontFamilies;
448
+ const signature = entryFamilies === undefined ? "" : stableStringify(entryFamilies);
449
+ if (signature !== familySignature)
450
+ throw new Error("SnapshotRenderFontFamilyConflict");
451
+ }
452
+ const id = typeof options.id === "string" ? options.id.trim() : "";
453
+ if (id.length === 0)
454
+ throw new Error("MissingSnapshotTemplateId");
455
+ if (!/^[A-Za-z][A-Za-z0-9_-]*$/u.test(id))
456
+ throw new Error("InvalidSnapshotTemplateId");
457
+ const paragraphSelector = typeof options.paragraphSelector === "string"
458
+ ? options.paragraphSelector
459
+ : supportedParagraphSelector;
460
+ if (paragraphSelector !== supportedParagraphSelector) {
461
+ throw new Error("UnsupportedSnapshotParagraphSelector");
462
+ }
463
+ const interner = options.snapshotTables.valueStyles;
464
+ const usedValueStyleIndexes = [];
465
+ const styleClassFor = (declaration) => {
466
+ const index = interner.intern(declaration);
467
+ if (!usedValueStyleIndexes.includes(index))
468
+ usedValueStyleIndexes.push(index);
469
+ return SnapshotValueStyle.snapshotValueStyleClass(index);
470
+ };
471
+ const renderedEntries = entries.map((entry) => renderBundleEntry(entry, styleClassFor));
472
+ return Object.freeze({
473
+ kind: "snapshot-bundle-data",
474
+ id,
475
+ usedValueStyleIndexes: Object.freeze([...usedValueStyleIndexes]),
476
+ json: JSON.stringify({
477
+ id,
478
+ paragraphSelector,
479
+ renderFontFamilies: families,
480
+ renderedEntries,
481
+ fontContractEntries,
482
+ }),
483
+ });
484
+ }
485
+ /**
486
+ * The data phase for plain snapshot bundles: renders the bodies with the
487
+ * shared TS renderer and mints `tqv-` classes into the build's TS interner.
488
+ */
489
+ export function renderSnapshotBundleData(preparedParagraphs, options) {
490
+ return renderBundleData(preparedParagraphs, options, PLAIN_PARAGRAPH_SELECTOR);
491
+ }
492
+ /** The data phase for font-contract bundles. */
493
+ export function renderFontContractBundleData(preparedParagraphs, options) {
494
+ return renderBundleData(preparedParagraphs, options, RUNTIME_PARAGRAPH_SELECTOR);
495
+ }
496
+ function assembleWireValues(data, tables) {
497
+ return [
498
+ data.json,
499
+ JSON.stringify({ snapshotTables: tables.handle }),
500
+ ];
501
+ }
502
+ /** `escapeAttribute`: ampersand, quote, and left angle, in that order. */
503
+ function escapeBundleAttribute(value) {
504
+ return value
505
+ .replaceAll("&", "&")
506
+ .replaceAll('"', """)
507
+ .replaceAll("<", "&lt;");
508
+ }
509
+ /**
510
+ * The first-paint rules of the value-style classes this bundle used, in
511
+ * first-mint order. The native assembly owns the templates and the manifest;
512
+ * the declarations live in the shared layer, so the rules append here in the
513
+ * byte form the Rust assembly emitted.
514
+ */
515
+ function valueStyleRules(data, tables) {
516
+ let rules = "";
517
+ for (const index of data.usedValueStyleIndexes) {
518
+ const declaration = tables.valueStyles.at(index);
519
+ if (typeof declaration !== "string")
520
+ throw new Error("SnapshotTableValueStyleMissing");
521
+ rules += `tiqian-prose[snapshot-ref="${escapeBundleAttribute(data.id)}"] ` +
522
+ `[data-tq-rendered="true"] .${SnapshotValueStyle.snapshotValueStyleClass(index)}{${declaration}}`;
523
+ }
524
+ return rules;
525
+ }
526
+ /**
527
+ * The assembly phase: compacts the manifest against the frozen table, builds
528
+ * the templates and the first-paint style. Requires finalizeSnapshotTables.
529
+ */
530
+ export function assembleSnapshotBundle(data, tables) {
531
+ const [dataJson, optionsJson] = assembleWireValues(data, tables);
532
+ const bundle = parse(addon.assembleSnapshotBundle(dataJson, optionsJson, SHARED_RUNTIME_STYLE));
533
+ return freezeBundle({ ...bundle, initialStyle: bundle.initialStyle + valueStyleRules(data, tables) });
534
+ }
535
+ /** The assembly phase for font-contract bundles. */
536
+ export function assembleFontContractBundle(data, tables) {
537
+ const [dataJson, optionsJson] = assembleWireValues(data, tables);
538
+ return freezeBundle(parse(addon.assembleFontContractBundle(dataJson, optionsJson, SHARED_RUNTIME_STYLE)));
539
+ }
@@ -0,0 +1,57 @@
1
+ import type { ArticleIndexRecord, PersistentCacheStore } from "./persistence.js";
2
+ /** One sqlite-backed store plus its maintenance entries. */
3
+ export interface SqliteCacheStore extends PersistentCacheStore {
4
+ /**
5
+ * Drops entries of one context that are not in the keep list. Returns the
6
+ * number of rows removed; other contexts are untouched.
7
+ */
8
+ prune(context: string, keep: readonly string[]): number;
9
+ /**
10
+ * Bucket-scoped eviction (ADR 0052 BucketIntersectionEviction): within the
11
+ * entries this bucket's article rows attribute, keeps the keep list and
12
+ * everything other buckets' rows reference; trims the bucket's hash rows
13
+ * to the list and drops emptied article rows. Returns the entry count
14
+ * removed; other buckets, unattributed entries and other contexts stay.
15
+ */
16
+ pruneBucket(context: string, bucket: string, keep: readonly string[]): number;
17
+ /**
18
+ * Deletes every entry, article row and hash row that belongs to a context
19
+ * outside `contexts`. A context fingerprint rotates when the engine or its
20
+ * inputs change, and the old context's rows are unreachable afterwards. A
21
+ * host serving a fixed context set usually declares it at open
22
+ * (createSqliteCacheStore options.contexts) instead of calling this; the
23
+ * method stays for stores shared beyond what one open call can list. An
24
+ * empty list removes nothing. Returns the entry count removed.
25
+ */
26
+ dropOtherContexts(contexts: readonly string[]): number;
27
+ /**
28
+ * Rebuilds the file when deleted rows left free pages inside it, returning
29
+ * the space to the filesystem. Reads the free-page count first, so a file
30
+ * without free pages returns at once.
31
+ */
32
+ compact(): void;
33
+ /**
34
+ * Records article-index rows (ADR 0052 Article layer), replacing the rows
35
+ * of the same article keys.
36
+ */
37
+ recordArticles(context: string, articles: readonly ArticleIndexRecord[]): void;
38
+ /** Reads every article row of one context, ordered by article key. */
39
+ readArticles(context: string): ArticleIndexRecord[];
40
+ /** Deletes article rows by key; returns the row count removed. */
41
+ deleteArticles(context: string, articleKeys: readonly string[]): number;
42
+ /** Closes the database; later calls report by name. */
43
+ close(): void;
44
+ }
45
+ /**
46
+ * Opens (or creates) the database at `path`. The parent directory is created
47
+ * when missing; the file belongs to the caller's cache directory policy.
48
+ *
49
+ * `options.contexts` declares the full set of contexts this file serves: at
50
+ * open, rows of every other context drop (entries, article rows and hash
51
+ * rows) and the file rebuilds around the survivors. Omit it when the file
52
+ * serves contexts this caller cannot list. The rebuild also runs without a
53
+ * declaration whenever earlier deletes left free pages inside the file.
54
+ */
55
+ export declare function createSqliteCacheStore(path: string, options?: {
56
+ contexts?: readonly string[];
57
+ }): Promise<SqliteCacheStore>;