@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.
- package/LICENSE +373 -0
- package/README.md +210 -2
- package/lib/cache.d.ts +58 -0
- package/lib/cache.js +196 -0
- package/lib/canonical.d.ts +26 -0
- package/lib/canonical.js +82 -0
- package/lib/fonts.d.ts +177 -0
- package/lib/fonts.js +89 -0
- package/lib/load.d.ts +138 -0
- package/lib/load.js +38 -0
- package/lib/nixos.d.ts +26 -0
- package/lib/nixos.js +315 -0
- package/lib/persistence.d.ts +127 -0
- package/lib/persistence.js +294 -0
- package/lib/precompute-html-projection.d.ts +32 -0
- package/lib/precompute-html-projection.js +140 -0
- package/lib/precompute-html.d.ts +98 -0
- package/lib/precompute-html.js +324 -0
- package/lib/precompute.d.ts +323 -0
- package/lib/precompute.js +539 -0
- package/lib/sqlite-store.d.ts +57 -0
- package/lib/sqlite-store.js +365 -0
- package/lib/stable-stringify.d.ts +8 -0
- package/lib/stable-stringify.js +40 -0
- package/lib/transport.d.ts +74 -0
- package/lib/transport.js +165 -0
- package/lib/vite.d.ts +6 -0
- package/lib/vite.js +22 -0
- package/package.json +115 -4
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
// The host-facing persistence SDK over the cache bridge (ADR 0052). Hosts
|
|
2
|
+
// hand over a plain address-to-bytes store; this module derives the cache
|
|
3
|
+
// addresses from the context fingerprint and the content hashes, hydrates
|
|
4
|
+
// the memory tier from the store, drives the hash-first submission lanes,
|
|
5
|
+
// verifies hits against the artifact digests and persists drained records
|
|
6
|
+
// back. Record bytes stay opaque to the host: the store never learns the
|
|
7
|
+
// entry format, and a format change invalidates through the context
|
|
8
|
+
// fingerprint alone. Stored blobs carry the bridge record deflated
|
|
9
|
+
// (ADR 0052 DeflatedStoreRecords): the artifact JSON repeats field names
|
|
10
|
+
// and decimal text per glyph, so the compressed row is a fraction of the
|
|
11
|
+
// plain form while the inflated bytes still verify against the artifact
|
|
12
|
+
// digest, keeping the hit contract unchanged. Plain records written before
|
|
13
|
+
// deflation stay readable; their next rewrite compresses.
|
|
14
|
+
import { createHash } from "node:crypto";
|
|
15
|
+
import { deflateSync, inflateSync } from "node:zlib";
|
|
16
|
+
import { packRecords, submissionItem, unpackRecords } from "./cache.js";
|
|
17
|
+
import { KIND_CONTRACT, KIND_SNAPSHOT } from "./canonical.js";
|
|
18
|
+
import { backfillRenderFields } from "./precompute.js";
|
|
19
|
+
function artifactSha(artifact) {
|
|
20
|
+
return createHash("sha256").update(artifact).digest();
|
|
21
|
+
}
|
|
22
|
+
function parseEntry(artifact) {
|
|
23
|
+
// A stored artifact carries the native entry; the render fields are derived
|
|
24
|
+
// by the shared renderer, so every lane adds them back exactly as the direct
|
|
25
|
+
// prepare calls do.
|
|
26
|
+
return backfillRenderFields(JSON.parse(Buffer.from(artifact).toString("utf8")));
|
|
27
|
+
}
|
|
28
|
+
/** One store blob holds exactly one record. */
|
|
29
|
+
function decodeRecord(blob) {
|
|
30
|
+
try {
|
|
31
|
+
const records = unpackRecords(blob);
|
|
32
|
+
return records.length === 1 ? (records[0] ?? null) : null;
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
// DeflatedStoreRecords: the stored envelope is a magic, a version byte and
|
|
39
|
+
// the deflated plain record. Blobs without the envelope are plain records
|
|
40
|
+
// from before deflation and read as they are; an unknown envelope version
|
|
41
|
+
// is a miss, and the content path recomputes and overwrites it.
|
|
42
|
+
const STORED_MAGIC = Buffer.from("TQZL", "ascii");
|
|
43
|
+
const STORED_VERSION = 1;
|
|
44
|
+
function packStoredRecord(record) {
|
|
45
|
+
return Buffer.concat([
|
|
46
|
+
STORED_MAGIC,
|
|
47
|
+
Buffer.from([STORED_VERSION]),
|
|
48
|
+
deflateSync(packRecords([record])),
|
|
49
|
+
]);
|
|
50
|
+
}
|
|
51
|
+
function unpackStoredRecord(blob) {
|
|
52
|
+
if (blob.length < 5 || !Buffer.from(blob.subarray(0, 4)).equals(STORED_MAGIC)) {
|
|
53
|
+
return decodeRecord(blob);
|
|
54
|
+
}
|
|
55
|
+
if (blob[4] !== STORED_VERSION)
|
|
56
|
+
return null;
|
|
57
|
+
try {
|
|
58
|
+
return decodeRecord(inflateSync(Buffer.from(blob.subarray(5))));
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/** Binds one lane host to one host store. */
|
|
65
|
+
export function createPersistentCache(host, store) {
|
|
66
|
+
const bridge = host.cache;
|
|
67
|
+
const address = (contentHash) => `${bridge.context()}:${Buffer.from(contentHash).toString("hex")}`;
|
|
68
|
+
/** The Article layer rides the store, not the bridge: hosts without an
|
|
69
|
+
* article-capable store keep their own index and the API reports by name. */
|
|
70
|
+
const articleStore = () => {
|
|
71
|
+
if (store.recordArticles == null ||
|
|
72
|
+
store.readArticles == null ||
|
|
73
|
+
store.deleteArticles == null) {
|
|
74
|
+
throw new Error("ArticleIndexUnavailable");
|
|
75
|
+
}
|
|
76
|
+
return store;
|
|
77
|
+
};
|
|
78
|
+
/** Reads and verifies the stored record addressed by one hex hash; a
|
|
79
|
+
* record that fails to decode, to live under its own hash or to match
|
|
80
|
+
* its digest is absent, matching the miss semantics of readStored. */
|
|
81
|
+
const readIndexedRecord = async (hex) => {
|
|
82
|
+
const recordAddress = `${bridge.context()}:${hex}`;
|
|
83
|
+
const blobs = await store.read([recordAddress]);
|
|
84
|
+
const blob = blobs.get(recordAddress);
|
|
85
|
+
if (blob === undefined)
|
|
86
|
+
return null;
|
|
87
|
+
const record = unpackStoredRecord(blob);
|
|
88
|
+
if (record === null)
|
|
89
|
+
return null;
|
|
90
|
+
if (Buffer.from(record.contentHash).toString("hex") !== hex)
|
|
91
|
+
return null;
|
|
92
|
+
if (!Buffer.from(record.artifactSha).equals(artifactSha(record.artifact))) {
|
|
93
|
+
return null;
|
|
94
|
+
}
|
|
95
|
+
return record;
|
|
96
|
+
};
|
|
97
|
+
/** Reads stored records for the items; a record only counts when its
|
|
98
|
+
* content hash matches the item it was addressed under. */
|
|
99
|
+
const readStored = async (items) => {
|
|
100
|
+
const itemByAddress = new Map();
|
|
101
|
+
for (const item of items) {
|
|
102
|
+
itemByAddress.set(address(item.hash), item);
|
|
103
|
+
}
|
|
104
|
+
const blobs = await store.read([...itemByAddress.keys()]);
|
|
105
|
+
const found = new Map();
|
|
106
|
+
for (const [recordAddress, blob] of blobs) {
|
|
107
|
+
const item = itemByAddress.get(recordAddress);
|
|
108
|
+
const record = blob === undefined ? null : unpackStoredRecord(blob);
|
|
109
|
+
// A store entry that fails to decode, to match its claimed content
|
|
110
|
+
// hash or to verify its own digest is a miss, not an error: the
|
|
111
|
+
// content path re-renders and the next flush overwrites it. The
|
|
112
|
+
// digest check runs here so prefetch never receives a corrupt record.
|
|
113
|
+
if (item === undefined || record === null)
|
|
114
|
+
continue;
|
|
115
|
+
if (!Buffer.from(record.contentHash).equals(Buffer.from(item.hash)))
|
|
116
|
+
continue;
|
|
117
|
+
if (!Buffer.from(record.artifactSha).equals(artifactSha(record.artifact)))
|
|
118
|
+
continue;
|
|
119
|
+
found.set(recordAddress, record);
|
|
120
|
+
}
|
|
121
|
+
return found;
|
|
122
|
+
};
|
|
123
|
+
const warmLane = async (items) => {
|
|
124
|
+
const found = await readStored(items);
|
|
125
|
+
if (found.size === 0)
|
|
126
|
+
return 0;
|
|
127
|
+
return bridge.prefetch([...found.values()]);
|
|
128
|
+
};
|
|
129
|
+
const renderLane = async (inputs, kind) => {
|
|
130
|
+
const items = inputs.map((input) => submissionItem(input, kind));
|
|
131
|
+
// Hydration: found records enter the memory tier so the hash lane can
|
|
132
|
+
// hit, while the same copies stay here for artifact parsing.
|
|
133
|
+
const found = await readStored(items);
|
|
134
|
+
if (found.size > 0) {
|
|
135
|
+
bridge.prefetch([...found.values()]);
|
|
136
|
+
}
|
|
137
|
+
const markers = bridge.submitHashes(items.map((item) => item.hash));
|
|
138
|
+
const results = items.map(() => null);
|
|
139
|
+
const pending = [];
|
|
140
|
+
for (const [index, marker] of markers.entries()) {
|
|
141
|
+
const item = items[index];
|
|
142
|
+
if (item === undefined) {
|
|
143
|
+
throw new Error("CacheSubmissionIndexLost");
|
|
144
|
+
}
|
|
145
|
+
if (marker.status !== "hit") {
|
|
146
|
+
pending.push(index);
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
const record = found.get(address(item.hash));
|
|
150
|
+
// The digest comparison is the hit contract: the local copy is the
|
|
151
|
+
// entry Rust holds. A missing or mismatched copy demotes the item to
|
|
152
|
+
// the content path instead of trusting stale bytes.
|
|
153
|
+
if (record !== undefined &&
|
|
154
|
+
Buffer.from(marker.artifactSha).equals(artifactSha(record.artifact))) {
|
|
155
|
+
results[index] = parseEntry(record.artifact);
|
|
156
|
+
}
|
|
157
|
+
else {
|
|
158
|
+
pending.push(index);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
// The content path. A need-content after the job completed means an
|
|
162
|
+
// eviction raced the write-through; one resubmit settles it.
|
|
163
|
+
let queue = pending;
|
|
164
|
+
for (let attempt = 0; attempt < 2 && queue.length > 0; attempt += 1) {
|
|
165
|
+
const resend = [];
|
|
166
|
+
for (const index of queue) {
|
|
167
|
+
const item = items[index];
|
|
168
|
+
if (item === undefined) {
|
|
169
|
+
throw new Error("CacheSubmissionIndexLost");
|
|
170
|
+
}
|
|
171
|
+
resend.push(item);
|
|
172
|
+
}
|
|
173
|
+
const outcomes = bridge.submitContents(resend);
|
|
174
|
+
const retry = [];
|
|
175
|
+
for (const [slot, outcome] of outcomes.entries()) {
|
|
176
|
+
const index = queue[slot];
|
|
177
|
+
if (index === undefined) {
|
|
178
|
+
throw new Error("CacheSubmissionIndexLost");
|
|
179
|
+
}
|
|
180
|
+
if (outcome.status === "computed") {
|
|
181
|
+
results[index] = parseEntry(outcome.artifact);
|
|
182
|
+
}
|
|
183
|
+
else {
|
|
184
|
+
retry.push(index);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
queue = retry;
|
|
188
|
+
}
|
|
189
|
+
const entries = [];
|
|
190
|
+
for (const result of results) {
|
|
191
|
+
// A null left after the retry pass means the submission never
|
|
192
|
+
// resolved; report it by name instead of returning a short array.
|
|
193
|
+
if (result === null) {
|
|
194
|
+
throw new Error("CacheSubmissionUnresolved");
|
|
195
|
+
}
|
|
196
|
+
entries.push(result);
|
|
197
|
+
}
|
|
198
|
+
return entries;
|
|
199
|
+
};
|
|
200
|
+
return {
|
|
201
|
+
context() {
|
|
202
|
+
return bridge.context();
|
|
203
|
+
},
|
|
204
|
+
async warmSnapshots(inputs) {
|
|
205
|
+
return warmLane(inputs.map((input) => submissionItem(input, KIND_SNAPSHOT)));
|
|
206
|
+
},
|
|
207
|
+
async warmContracts(inputs) {
|
|
208
|
+
return warmLane(inputs.map((input) => submissionItem(input, KIND_CONTRACT)));
|
|
209
|
+
},
|
|
210
|
+
async renderSnapshots(inputs) {
|
|
211
|
+
return renderLane(inputs, KIND_SNAPSHOT);
|
|
212
|
+
},
|
|
213
|
+
async renderContracts(inputs) {
|
|
214
|
+
return renderLane(inputs, KIND_CONTRACT);
|
|
215
|
+
},
|
|
216
|
+
prefillSnapshots(inputs) {
|
|
217
|
+
return bridge.prefillContents(inputs.map((input) => submissionItem(input, KIND_SNAPSHOT)));
|
|
218
|
+
},
|
|
219
|
+
prefillContracts(inputs) {
|
|
220
|
+
return bridge.prefillContents(inputs.map((input) => submissionItem(input, KIND_CONTRACT)));
|
|
221
|
+
},
|
|
222
|
+
async recordArticle(articleKey, bucket, inputs) {
|
|
223
|
+
const hashes = new Set();
|
|
224
|
+
for (const input of inputs.snapshots ?? []) {
|
|
225
|
+
hashes.add(Buffer.from(submissionItem(input, KIND_SNAPSHOT).hash).toString("hex"));
|
|
226
|
+
}
|
|
227
|
+
for (const input of inputs.contracts ?? []) {
|
|
228
|
+
hashes.add(Buffer.from(submissionItem(input, KIND_CONTRACT).hash).toString("hex"));
|
|
229
|
+
}
|
|
230
|
+
const contentHashes = [...hashes];
|
|
231
|
+
await articleStore().recordArticles(bridge.context(), [
|
|
232
|
+
{ articleKey, bucket, contentHashes },
|
|
233
|
+
]);
|
|
234
|
+
return contentHashes;
|
|
235
|
+
},
|
|
236
|
+
async articleHashes(articleKey) {
|
|
237
|
+
const rows = await articleStore().readArticles(bridge.context());
|
|
238
|
+
return rows.find((row) => row.articleKey === articleKey)?.contentHashes ?? null;
|
|
239
|
+
},
|
|
240
|
+
async warmArticle(articleKey) {
|
|
241
|
+
const rows = await articleStore().readArticles(bridge.context());
|
|
242
|
+
const row = rows.find((candidate) => candidate.articleKey === articleKey);
|
|
243
|
+
if (row === undefined)
|
|
244
|
+
return 0;
|
|
245
|
+
const records = [];
|
|
246
|
+
for (const hex of row.contentHashes) {
|
|
247
|
+
const record = await readIndexedRecord(hex);
|
|
248
|
+
if (record !== null)
|
|
249
|
+
records.push(record);
|
|
250
|
+
}
|
|
251
|
+
return records.length === 0 ? 0 : bridge.prefetch(records);
|
|
252
|
+
},
|
|
253
|
+
async pruneUnreferencedEntries(dropArticles) {
|
|
254
|
+
// The index computes the keep list, so its absence reports first; a
|
|
255
|
+
// store with rows but no prune keeps its entries until the host adds
|
|
256
|
+
// one.
|
|
257
|
+
const articles = articleStore();
|
|
258
|
+
if (store.prune == null) {
|
|
259
|
+
throw new Error("EntryPruneUnavailable");
|
|
260
|
+
}
|
|
261
|
+
const context = bridge.context();
|
|
262
|
+
const dropped = new Set(dropArticles ?? []);
|
|
263
|
+
if (dropped.size > 0) {
|
|
264
|
+
await articles.deleteArticles(context, [...dropped]);
|
|
265
|
+
}
|
|
266
|
+
const rows = (await articles.readArticles(context))
|
|
267
|
+
.filter((row) => !dropped.has(row.articleKey));
|
|
268
|
+
const keep = new Set();
|
|
269
|
+
for (const row of rows) {
|
|
270
|
+
for (const hex of row.contentHashes) {
|
|
271
|
+
keep.add(`${context}:${hex}`);
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
return store.prune(context, [...keep]);
|
|
275
|
+
},
|
|
276
|
+
async pruneBucket(bucket, keep) {
|
|
277
|
+
// The bucket scope lives in the article tables, so the operation rides
|
|
278
|
+
// one store method: a plain prune cannot express "leave other buckets
|
|
279
|
+
// and unattributed entries alone".
|
|
280
|
+
if (store.pruneBucket == null) {
|
|
281
|
+
throw new Error("BucketPruneUnavailable");
|
|
282
|
+
}
|
|
283
|
+
return store.pruneBucket(bridge.context(), bucket, keep);
|
|
284
|
+
},
|
|
285
|
+
async flush() {
|
|
286
|
+
const records = bridge.drainWrites();
|
|
287
|
+
if (records.length === 0)
|
|
288
|
+
return 0;
|
|
289
|
+
const entries = records.map((record) => [address(record.contentHash), packStoredRecord(record)]);
|
|
290
|
+
await store.write(entries);
|
|
291
|
+
return records.length;
|
|
292
|
+
},
|
|
293
|
+
};
|
|
294
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
import type { DomNode } from "@tiqian/shared/org/tiqian/shared/html/DomNode";
|
|
2
|
+
export interface RawSemanticSpan {
|
|
3
|
+
readonly start: number;
|
|
4
|
+
readonly end: number;
|
|
5
|
+
readonly tagName: string;
|
|
6
|
+
readonly attributes: readonly (readonly [string, string])[];
|
|
7
|
+
readonly order: number;
|
|
8
|
+
}
|
|
9
|
+
export interface SourceArtifact {
|
|
10
|
+
readonly text: string;
|
|
11
|
+
readonly semantics: readonly RawSemanticSpan[];
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* snapshotSourceArtifactFromDom: collects the raw text, the hard breaks and the
|
|
15
|
+
* semantic ranges of one paragraph, folds the normal flow and maps the ranges
|
|
16
|
+
* through the fold. A null result is a declined artifact.
|
|
17
|
+
*/
|
|
18
|
+
export declare function snapshotSourceArtifactFromDom(element: DomNode): SourceArtifact | null;
|
|
19
|
+
/**
|
|
20
|
+
* snapshotProjection: the canonical artifact first, then the plain-only rule.
|
|
21
|
+
* A paragraph with any surviving inline semantics declines the snapshot; an
|
|
22
|
+
* artifact that failed (an unsafe tag or an invalid range) declines as well.
|
|
23
|
+
*/
|
|
24
|
+
export declare function snapshotProjection(element: DomNode): {
|
|
25
|
+
readonly text: string;
|
|
26
|
+
} | null;
|
|
27
|
+
/**
|
|
28
|
+
* projectedTextOnly: text content with br kept as a hard break and every other
|
|
29
|
+
* whitespace run collapsed to one space. It is the contract-lane text the Rust
|
|
30
|
+
* lane used for paragraphs without a snapshot projection.
|
|
31
|
+
*/
|
|
32
|
+
export declare function projectedTextOnly(element: DomNode): string;
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import { SnapshotSource } from "@tiqian/shared/org/tiqian/shared/snapshot/SnapshotSource";
|
|
2
|
+
const ELEMENT_NODE = 1;
|
|
3
|
+
const TEXT_NODE = 3;
|
|
4
|
+
function textOf(node) {
|
|
5
|
+
const value = node.nodeValue;
|
|
6
|
+
return typeof value === "string" ? value : "";
|
|
7
|
+
}
|
|
8
|
+
function attributesOf(node) {
|
|
9
|
+
const attributes = node.attributes;
|
|
10
|
+
const pairs = [];
|
|
11
|
+
for (let index = 0; index < attributes.length; index += 1) {
|
|
12
|
+
pairs.push([attributes[index].name, attributes[index].value]);
|
|
13
|
+
}
|
|
14
|
+
return pairs;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* The appendDomNode walk: text appends verbatim, br records a hard break, a
|
|
18
|
+
* safe semantic tag opens a range around its children, and any other element
|
|
19
|
+
* declines the artifact (the caller falls back to the contract lane).
|
|
20
|
+
*/
|
|
21
|
+
function appendDomNode(node, state) {
|
|
22
|
+
if (node.nodeType === TEXT_NODE) {
|
|
23
|
+
state.text += textOf(node);
|
|
24
|
+
return true;
|
|
25
|
+
}
|
|
26
|
+
if (node.nodeType !== ELEMENT_NODE)
|
|
27
|
+
return true;
|
|
28
|
+
const tagName = node.tagName.toLowerCase();
|
|
29
|
+
if (tagName === "br") {
|
|
30
|
+
state.hardBreaks.push(state.text.length);
|
|
31
|
+
state.text += "\n";
|
|
32
|
+
return true;
|
|
33
|
+
}
|
|
34
|
+
if (!SnapshotSource.isSafeTag(tagName))
|
|
35
|
+
return false;
|
|
36
|
+
const start = state.text.length;
|
|
37
|
+
const order = state.order;
|
|
38
|
+
state.order += 1;
|
|
39
|
+
for (let index = 0; index < node.childNodes.length; index += 1) {
|
|
40
|
+
if (!appendDomNode(node.childNodes[index], state))
|
|
41
|
+
return false;
|
|
42
|
+
}
|
|
43
|
+
const end = state.text.length;
|
|
44
|
+
if (end > start) {
|
|
45
|
+
state.spans.push({ start, end, tagName, attributes: attributesOf(node), order });
|
|
46
|
+
}
|
|
47
|
+
return true;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* snapshotSourceArtifactFromDom: collects the raw text, the hard breaks and the
|
|
51
|
+
* semantic ranges of one paragraph, folds the normal flow and maps the ranges
|
|
52
|
+
* through the fold. A null result is a declined artifact.
|
|
53
|
+
*/
|
|
54
|
+
export function snapshotSourceArtifactFromDom(element) {
|
|
55
|
+
const node = element;
|
|
56
|
+
const state = { text: "", spans: [], hardBreaks: [], order: 0 };
|
|
57
|
+
for (let index = 0; index < node.childNodes.length; index += 1) {
|
|
58
|
+
if (!appendDomNode(node.childNodes[index], state))
|
|
59
|
+
return null;
|
|
60
|
+
}
|
|
61
|
+
const fold = SnapshotSource.foldNormalFlow(state.text, state.hardBreaks);
|
|
62
|
+
const semantics = [];
|
|
63
|
+
for (const span of state.spans) {
|
|
64
|
+
const start = fold.boundaryMap[span.start];
|
|
65
|
+
const end = fold.boundaryMap[span.end];
|
|
66
|
+
if (start === undefined || end === undefined || end <= start)
|
|
67
|
+
continue;
|
|
68
|
+
semantics.push(Object.freeze({ ...span, start, end }));
|
|
69
|
+
}
|
|
70
|
+
return Object.freeze({ text: fold.text, semantics: Object.freeze(semantics) });
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* snapshotProjection: the canonical artifact first, then the plain-only rule.
|
|
74
|
+
* A paragraph with any surviving inline semantics declines the snapshot; an
|
|
75
|
+
* artifact that failed (an unsafe tag or an invalid range) declines as well.
|
|
76
|
+
*/
|
|
77
|
+
export function snapshotProjection(element) {
|
|
78
|
+
const artifact = snapshotSourceArtifactFromDom(element);
|
|
79
|
+
if (artifact === null)
|
|
80
|
+
return null;
|
|
81
|
+
if (artifact.semantics.length > 0)
|
|
82
|
+
return null;
|
|
83
|
+
return Object.freeze({ text: artifact.text });
|
|
84
|
+
}
|
|
85
|
+
function appendProjectedRaw(node, state) {
|
|
86
|
+
if (node.nodeType === TEXT_NODE) {
|
|
87
|
+
state.text += textOf(node);
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
if (node.nodeType !== ELEMENT_NODE)
|
|
91
|
+
return;
|
|
92
|
+
const tagName = node.tagName.toLowerCase();
|
|
93
|
+
if (tagName === "br") {
|
|
94
|
+
state.hardBreaks.push(state.text.length);
|
|
95
|
+
state.text += "\n";
|
|
96
|
+
return;
|
|
97
|
+
}
|
|
98
|
+
if (tagName === "script" || tagName === "style" || tagName === "template")
|
|
99
|
+
return;
|
|
100
|
+
for (let index = 0; index < node.childNodes.length; index += 1) {
|
|
101
|
+
appendProjectedRaw(node.childNodes[index], state);
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* projectedTextOnly: text content with br kept as a hard break and every other
|
|
106
|
+
* whitespace run collapsed to one space. It is the contract-lane text the Rust
|
|
107
|
+
* lane used for paragraphs without a snapshot projection.
|
|
108
|
+
*/
|
|
109
|
+
export function projectedTextOnly(element) {
|
|
110
|
+
const node = element;
|
|
111
|
+
const state = { text: "", spans: [], hardBreaks: [], order: 0 };
|
|
112
|
+
for (let index = 0; index < node.childNodes.length; index += 1) {
|
|
113
|
+
appendProjectedRaw(node.childNodes[index], state);
|
|
114
|
+
}
|
|
115
|
+
const hardBreaks = new Set(state.hardBreaks);
|
|
116
|
+
let output = "";
|
|
117
|
+
let pendingWhitespace = false;
|
|
118
|
+
let offset = 0;
|
|
119
|
+
for (const character of state.text) {
|
|
120
|
+
if (character === "\n" && hardBreaks.has(offset)) {
|
|
121
|
+
pendingWhitespace = false;
|
|
122
|
+
output += "\n";
|
|
123
|
+
}
|
|
124
|
+
else if (character === " " ||
|
|
125
|
+
character === "\t" ||
|
|
126
|
+
character === "\n" ||
|
|
127
|
+
character === "\r" ||
|
|
128
|
+
character === "\f") {
|
|
129
|
+
pendingWhitespace = output.length > 0 && !output.endsWith("\n");
|
|
130
|
+
}
|
|
131
|
+
else {
|
|
132
|
+
if (pendingWhitespace)
|
|
133
|
+
output += " ";
|
|
134
|
+
pendingWhitespace = false;
|
|
135
|
+
output += character;
|
|
136
|
+
}
|
|
137
|
+
offset += character.length;
|
|
138
|
+
}
|
|
139
|
+
return output;
|
|
140
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { type BuildFontFace, type BuildFontStylesheet, type NormalizedTypography, type Precomputer, type SnapshotBundle, type SnapshotTypography } from "./precompute.js";
|
|
2
|
+
export interface SnapshotServerAssets {
|
|
3
|
+
readonly id: string;
|
|
4
|
+
readonly initialStyle: string;
|
|
5
|
+
readonly inertTemplate: string;
|
|
6
|
+
readonly fontPreloads: readonly string[];
|
|
7
|
+
}
|
|
8
|
+
export interface ClientSnapshotBundle {
|
|
9
|
+
readonly id: string;
|
|
10
|
+
readonly clientTemplate: string;
|
|
11
|
+
readonly initialStyle: string;
|
|
12
|
+
readonly fontPreloads: readonly string[];
|
|
13
|
+
}
|
|
14
|
+
export interface PreparedHtmlIssue {
|
|
15
|
+
readonly index: number;
|
|
16
|
+
readonly key: string;
|
|
17
|
+
readonly stage: "snapshot" | "font-contract";
|
|
18
|
+
readonly issue: string;
|
|
19
|
+
}
|
|
20
|
+
/** The snapshot-table file one `prepare` call emitted (ADR 0052 schema 2). */
|
|
21
|
+
export interface PreparedHtmlTables {
|
|
22
|
+
readonly bytes: Buffer;
|
|
23
|
+
readonly sha256: string;
|
|
24
|
+
}
|
|
25
|
+
export interface PreparedHtml {
|
|
26
|
+
readonly html: string;
|
|
27
|
+
readonly rootAttributes: Readonly<Record<string, string>>;
|
|
28
|
+
readonly bundle: SnapshotBundle | null;
|
|
29
|
+
readonly clientBundle: ClientSnapshotBundle | null;
|
|
30
|
+
readonly serverAssets: SnapshotServerAssets | null;
|
|
31
|
+
/** Hosts serve `bytes` under the sha address; the manifest pins the sha. */
|
|
32
|
+
readonly tables: PreparedHtmlTables | null;
|
|
33
|
+
readonly issues: readonly PreparedHtmlIssue[];
|
|
34
|
+
}
|
|
35
|
+
export interface HtmlPrepareOptions {
|
|
36
|
+
/** Distinct retained asset payloads must not share an explicit id within one adapter scope. */
|
|
37
|
+
readonly id?: string;
|
|
38
|
+
/** Optional fixed-measure prepared geometry; omit for width-independent font evidence. */
|
|
39
|
+
readonly snapshot?: {
|
|
40
|
+
readonly maxWidthPx: number;
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
export interface HtmlPreparer {
|
|
44
|
+
readonly typography: NormalizedTypography;
|
|
45
|
+
/** Prepares the whole document: parse, project, then run the native lanes. */
|
|
46
|
+
prepare(html: string, options?: HtmlPrepareOptions): Promise<PreparedHtml>;
|
|
47
|
+
close(): void;
|
|
48
|
+
}
|
|
49
|
+
export type HtmlPreparerOptions = {
|
|
50
|
+
/** Only simple tag-name lists such as `p, li` are supported. */
|
|
51
|
+
readonly paragraphSelector?: string;
|
|
52
|
+
readonly skippedAncestorSelector?: string;
|
|
53
|
+
/**
|
|
54
|
+
* Rejected in this lane with `UnsupportedHtmlProjector`: projection needs a
|
|
55
|
+
* host DOM. Kept for type parity with the `@tiqian/web-component` entry.
|
|
56
|
+
*/
|
|
57
|
+
readonly projectSnapshotParagraph?: (...args: never[]) => unknown;
|
|
58
|
+
} & ({
|
|
59
|
+
/** Reuse an existing precomputer instead of opening another exact-font session. */
|
|
60
|
+
readonly precomputer: Precomputer;
|
|
61
|
+
readonly fontStylesheets?: never;
|
|
62
|
+
readonly faces?: never;
|
|
63
|
+
readonly typography?: never;
|
|
64
|
+
} | {
|
|
65
|
+
readonly precomputer?: undefined;
|
|
66
|
+
readonly fontStylesheets?: readonly BuildFontStylesheet[];
|
|
67
|
+
readonly faces?: readonly BuildFontFace[];
|
|
68
|
+
readonly typography: SnapshotTypography;
|
|
69
|
+
});
|
|
70
|
+
export interface HtmlOpeningTag {
|
|
71
|
+
readonly end: number;
|
|
72
|
+
readonly source: string;
|
|
73
|
+
readonly tagName: string;
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Locates source opening tags without serializing the host's HTML; the scan
|
|
77
|
+
* runs on UTF-16 code units and skips raw-text containers and inert templates
|
|
78
|
+
* so a literal `<p>` example never receives a live snapshot key.
|
|
79
|
+
*/
|
|
80
|
+
export declare function findHtmlOpeningTags(html: string, tagNames?: readonly string[]): readonly HtmlOpeningTag[];
|
|
81
|
+
/** Inserts attribute strings at the given offsets, highest offset first. */
|
|
82
|
+
export declare function injectHtmlAttributes(html: string, insertions: readonly {
|
|
83
|
+
readonly offset: number;
|
|
84
|
+
readonly attribute: string;
|
|
85
|
+
}[]): string;
|
|
86
|
+
/** The payload a server template inlines. */
|
|
87
|
+
export declare function snapshotServerAssets(bundle: SnapshotBundle | null): SnapshotServerAssets | null;
|
|
88
|
+
/** Preload links, the first paint style and the inert template, concatenated. */
|
|
89
|
+
export declare function renderSnapshotServerAssets(assets: SnapshotServerAssets | null): string;
|
|
90
|
+
/**
|
|
91
|
+
* Creates the framework-neutral server boundary consumed by SvelteKit and
|
|
92
|
+
* Astro integrations. Host HTML remains byte-for-byte intact except for
|
|
93
|
+
* snapshot keys inserted into paragraphs that produced reusable geometry.
|
|
94
|
+
* `projectSnapshotParagraph` needs a host DOM and throws
|
|
95
|
+
* `UnsupportedHtmlProjector` here; hosts projecting rich semantics keep the
|
|
96
|
+
* `@tiqian/web-component` entry.
|
|
97
|
+
*/
|
|
98
|
+
export declare function createHtmlPreparer(options: HtmlPreparerOptions): Promise<HtmlPreparer>;
|