@drupflare/spool 0.0.0-stage → 0.1.0
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 +21 -0
- package/README.md +1557 -2
- package/dist/cdn/client.js +1 -0
- package/dist/cdn/location.d.ts +11 -0
- package/dist/cdn/location.js +15 -0
- package/dist/cdn/manifest.json +16 -0
- package/dist/cdn/spool-sw.js +1 -0
- package/dist/client/entry.d.ts +1 -0
- package/dist/client/entry.js +25 -0
- package/dist/client/index.d.ts +3 -0
- package/dist/client/index.js +2 -0
- package/dist/client/lifecycle.d.ts +10 -0
- package/dist/client/lifecycle.js +10 -0
- package/dist/client/loads.d.ts +16 -0
- package/dist/client/loads.js +41 -0
- package/dist/client/register.d.ts +34 -0
- package/dist/client/register.js +58 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/node/listener.d.ts +19 -0
- package/dist/node/listener.js +76 -0
- package/dist/protocol/artifact.d.ts +54 -0
- package/dist/protocol/artifact.js +79 -0
- package/dist/protocol/assembly.d.ts +34 -0
- package/dist/protocol/assembly.js +72 -0
- package/dist/protocol/beacon.d.ts +59 -0
- package/dist/protocol/beacon.js +86 -0
- package/dist/protocol/collector.d.ts +41 -0
- package/dist/protocol/collector.js +84 -0
- package/dist/protocol/config.d.ts +89 -0
- package/dist/protocol/config.js +13 -0
- package/dist/protocol/envelope.d.ts +47 -0
- package/dist/protocol/envelope.js +162 -0
- package/dist/protocol/errors.d.ts +7 -0
- package/dist/protocol/errors.js +9 -0
- package/dist/protocol/graph.d.ts +81 -0
- package/dist/protocol/graph.js +201 -0
- package/dist/protocol/index.d.ts +19 -0
- package/dist/protocol/index.js +19 -0
- package/dist/protocol/manifest.d.ts +29 -0
- package/dist/protocol/manifest.js +94 -0
- package/dist/protocol/normalise.d.ts +20 -0
- package/dist/protocol/normalise.js +29 -0
- package/dist/protocol/pattern.d.ts +12 -0
- package/dist/protocol/pattern.js +82 -0
- package/dist/protocol/provision.d.ts +100 -0
- package/dist/protocol/provision.js +105 -0
- package/dist/protocol/route.d.ts +179 -0
- package/dist/protocol/route.js +135 -0
- package/dist/protocol/sync.d.ts +31 -0
- package/dist/protocol/sync.js +87 -0
- package/dist/protocol/tag.d.ts +12 -0
- package/dist/protocol/tag.js +26 -0
- package/dist/protocol/template/compile.d.ts +35 -0
- package/dist/protocol/template/compile.js +82 -0
- package/dist/protocol/template/interpret.d.ts +9 -0
- package/dist/protocol/template/interpret.js +82 -0
- package/dist/protocol/vector.d.ts +32 -0
- package/dist/protocol/vector.js +56 -0
- package/dist/protocol/view.d.ts +110 -0
- package/dist/protocol/view.js +201 -0
- package/dist/proxy/eligible.d.ts +45 -0
- package/dist/proxy/eligible.js +96 -0
- package/dist/proxy/index.d.ts +4 -0
- package/dist/proxy/index.js +4 -0
- package/dist/proxy/proxy.d.ts +86 -0
- package/dist/proxy/proxy.js +388 -0
- package/dist/proxy/purge.d.ts +10 -0
- package/dist/proxy/purge.js +66 -0
- package/dist/proxy/tags.d.ts +8 -0
- package/dist/proxy/tags.js +36 -0
- package/dist/report/derive.d.ts +221 -0
- package/dist/report/derive.js +490 -0
- package/dist/report/economics.d.ts +14 -0
- package/dist/report/economics.js +24 -0
- package/dist/report/index.d.ts +8 -0
- package/dist/report/index.js +8 -0
- package/dist/report/inputs.d.ts +141 -0
- package/dist/report/inputs.js +216 -0
- package/dist/report/measurement.d.ts +48 -0
- package/dist/report/measurement.js +114 -0
- package/dist/report/model.d.ts +42 -0
- package/dist/report/model.js +74 -0
- package/dist/report/thirdparty.d.ts +62 -0
- package/dist/report/thirdparty.js +107 -0
- package/dist/report/traffic.d.ts +140 -0
- package/dist/report/traffic.js +228 -0
- package/dist/report/trim.d.ts +81 -0
- package/dist/report/trim.js +105 -0
- package/dist/server/beacon.d.ts +20 -0
- package/dist/server/beacon.js +47 -0
- package/dist/server/embedded.d.ts +6 -0
- package/dist/server/embedded.js +6 -0
- package/dist/server/ga4.d.ts +70 -0
- package/dist/server/ga4.js +165 -0
- package/dist/server/identity.d.ts +12 -0
- package/dist/server/identity.js +17 -0
- package/dist/server/index.d.ts +7 -0
- package/dist/server/index.js +7 -0
- package/dist/server/sink.d.ts +56 -0
- package/dist/server/sink.js +133 -0
- package/dist/server/size.d.ts +7 -0
- package/dist/server/size.js +18 -0
- package/dist/server/spool.d.ts +97 -0
- package/dist/server/spool.js +463 -0
- package/dist/server/stub.d.ts +9 -0
- package/dist/server/stub.js +19 -0
- package/dist/server/sync.d.ts +12 -0
- package/dist/server/sync.js +48 -0
- package/dist/server/work.d.ts +22 -0
- package/dist/server/work.js +30 -0
- package/dist/stores/durable-object.d.ts +19 -0
- package/dist/stores/durable-object.js +53 -0
- package/dist/stores/index.d.ts +2 -0
- package/dist/stores/index.js +2 -0
- package/dist/stores/memory.d.ts +4 -0
- package/dist/stores/memory.js +10 -0
- package/dist/stores/version-store.d.ts +11 -0
- package/dist/stores/version-store.js +1 -0
- package/dist/sw/analytics.d.ts +81 -0
- package/dist/sw/analytics.js +275 -0
- package/dist/sw/collect.d.ts +8 -0
- package/dist/sw/collect.js +33 -0
- package/dist/sw/core.d.ts +1 -0
- package/dist/sw/core.js +3 -0
- package/dist/sw/freshness.d.ts +15 -0
- package/dist/sw/freshness.js +20 -0
- package/dist/sw/graph/index.d.ts +67 -0
- package/dist/sw/graph/index.js +170 -0
- package/dist/sw/graph/invalidate.d.ts +23 -0
- package/dist/sw/graph/invalidate.js +109 -0
- package/dist/sw/graph/projections.d.ts +7 -0
- package/dist/sw/graph/projections.js +9 -0
- package/dist/sw/graph/records.d.ts +7 -0
- package/dist/sw/graph/records.js +9 -0
- package/dist/sw/graph/store.d.ts +32 -0
- package/dist/sw/graph/store.js +52 -0
- package/dist/sw/idb.d.ts +8 -0
- package/dist/sw/idb.js +117 -0
- package/dist/sw/index.d.ts +2 -0
- package/dist/sw/index.js +1 -0
- package/dist/sw/partition.d.ts +21 -0
- package/dist/sw/partition.js +137 -0
- package/dist/sw/policy.d.ts +8 -0
- package/dist/sw/policy.js +24 -0
- package/dist/sw/provision.d.ts +39 -0
- package/dist/sw/provision.js +61 -0
- package/dist/sw/render.d.ts +21 -0
- package/dist/sw/render.js +53 -0
- package/dist/sw/replica.d.ts +77 -0
- package/dist/sw/replica.js +299 -0
- package/dist/sw/router.d.ts +42 -0
- package/dist/sw/router.js +48 -0
- package/dist/sw/routing.d.ts +23 -0
- package/dist/sw/routing.js +48 -0
- package/dist/sw/runtime.d.ts +112 -0
- package/dist/sw/runtime.js +1070 -0
- package/dist/sw/scheduler.d.ts +83 -0
- package/dist/sw/scheduler.js +149 -0
- package/dist/sw/seal.d.ts +37 -0
- package/dist/sw/seal.js +183 -0
- package/dist/sw/serve.d.ts +15 -0
- package/dist/sw/serve.js +63 -0
- package/dist/sw/shadow.d.ts +16 -0
- package/dist/sw/shadow.js +27 -0
- package/dist/sw/static.d.ts +17 -0
- package/dist/sw/static.js +81 -0
- package/dist/sw/storage.d.ts +64 -0
- package/dist/sw/storage.js +34 -0
- package/dist/sw/thirdparty.d.ts +17 -0
- package/dist/sw/thirdparty.js +36 -0
- package/dist/trim/css.d.ts +38 -0
- package/dist/trim/css.js +328 -0
- package/dist/trim/index.d.ts +3 -0
- package/dist/trim/index.js +3 -0
- package/dist/trim/manifest.d.ts +67 -0
- package/dist/trim/manifest.js +134 -0
- package/dist/trim/tokens.d.ts +43 -0
- package/dist/trim/tokens.js +142 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +3 -0
- package/package.json +146 -5
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import type { Artifact } from '../protocol/artifact.js';
|
|
2
|
+
import type { BeaconEvent } from '../protocol/beacon.js';
|
|
3
|
+
import type { ProjectionEntry, RecordEntry } from '../protocol/graph.js';
|
|
4
|
+
import type { HeaderSet } from './policy.js';
|
|
5
|
+
/** an artifact as held on the device, with the time the worker stored it */
|
|
6
|
+
export type StoredArtifact = {
|
|
7
|
+
artifact: Artifact;
|
|
8
|
+
fetchedAt: number;
|
|
9
|
+
/** when a need-sync last confirmed this artifact; later than `fetchedAt` once it has */
|
|
10
|
+
validatedAt?: number;
|
|
11
|
+
/** set while the artifact is a catalogue entry that no page has opened */
|
|
12
|
+
catalogue?: true;
|
|
13
|
+
};
|
|
14
|
+
/** when the worker last tried a standalone flush, and when it last looked; both epoch milliseconds */
|
|
15
|
+
export type FlushState = {
|
|
16
|
+
lastStandalone: number;
|
|
17
|
+
checkedAt: number;
|
|
18
|
+
/** when a catalogue was last asked for each page path, oldest first; epoch milliseconds */
|
|
19
|
+
catalogue?: Record<string, number>;
|
|
20
|
+
};
|
|
21
|
+
/** the replica's bookkeeping: what runtime wrote it, how far it has synced, what changed when */
|
|
22
|
+
export type ReplicaMeta = {
|
|
23
|
+
version: string;
|
|
24
|
+
/** the vector cursor the replica has caught up to, or null before the first artifact */
|
|
25
|
+
cursor: number | null;
|
|
26
|
+
/** tag and the vector version of its last known change */
|
|
27
|
+
tags: Array<[string, number]>;
|
|
28
|
+
/** when the last sync (or a piggybacked diff) completed, epoch milliseconds */
|
|
29
|
+
syncedAt: number;
|
|
30
|
+
/** the security headers seen on network views: the latest site-wide set and each path's own */
|
|
31
|
+
policy?: {
|
|
32
|
+
site?: HeaderSet;
|
|
33
|
+
paths: Array<[string, HeaderSet]>;
|
|
34
|
+
};
|
|
35
|
+
};
|
|
36
|
+
/** a queued beacon with the key to remove it by */
|
|
37
|
+
export type QueuedBeacon = {
|
|
38
|
+
key: number;
|
|
39
|
+
event: BeaconEvent;
|
|
40
|
+
};
|
|
41
|
+
/** durable state of the replica; IndexedDB in a browser, a Map in tests */
|
|
42
|
+
export interface ReplicaStorage {
|
|
43
|
+
getArtifact(id: string): Promise<StoredArtifact | undefined>;
|
|
44
|
+
putArtifact(stored: StoredArtifact): Promise<void>;
|
|
45
|
+
deleteArtifacts(ids: readonly string[]): Promise<void>;
|
|
46
|
+
allArtifacts(): Promise<StoredArtifact[]>;
|
|
47
|
+
clearArtifacts(): Promise<void>;
|
|
48
|
+
getMeta(): Promise<ReplicaMeta | undefined>;
|
|
49
|
+
setMeta(meta: ReplicaMeta): Promise<void>;
|
|
50
|
+
addBeacon(event: BeaconEvent): Promise<void>;
|
|
51
|
+
readBeacons(): Promise<QueuedBeacon[]>;
|
|
52
|
+
removeBeacons(keys: readonly number[]): Promise<void>;
|
|
53
|
+
getFlush(): Promise<FlushState | undefined>;
|
|
54
|
+
setFlush(state: FlushState): Promise<void>;
|
|
55
|
+
putRecords(entries: readonly RecordEntry[]): Promise<void>;
|
|
56
|
+
allRecords(): Promise<RecordEntry[]>;
|
|
57
|
+
deleteRecords(ids: readonly string[]): Promise<void>;
|
|
58
|
+
putProjections(entries: readonly ProjectionEntry[]): Promise<void>;
|
|
59
|
+
allProjections(): Promise<ProjectionEntry[]>;
|
|
60
|
+
deleteProjections(ids: readonly string[]): Promise<void>;
|
|
61
|
+
clearGraph(): Promise<void>;
|
|
62
|
+
}
|
|
63
|
+
/** storage in memory, for tests and for routes that opt out of persistence */
|
|
64
|
+
export declare function memoryStorage(): ReplicaStorage;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/** storage in memory, for tests and for routes that opt out of persistence */
|
|
2
|
+
export function memoryStorage() {
|
|
3
|
+
const artifacts = new Map();
|
|
4
|
+
const beacons = new Map();
|
|
5
|
+
const records = new Map();
|
|
6
|
+
const projections = new Map();
|
|
7
|
+
let meta;
|
|
8
|
+
let flush;
|
|
9
|
+
let next = 1;
|
|
10
|
+
return {
|
|
11
|
+
getArtifact: async (id) => artifacts.get(id),
|
|
12
|
+
putArtifact: async (stored) => void artifacts.set(stored.artifact.id, stored),
|
|
13
|
+
deleteArtifacts: async (ids) => void ids.forEach((id) => artifacts.delete(id)),
|
|
14
|
+
allArtifacts: async () => [...artifacts.values()],
|
|
15
|
+
clearArtifacts: async () => artifacts.clear(),
|
|
16
|
+
getMeta: async () => meta,
|
|
17
|
+
setMeta: async (value) => void (meta = structuredClone(value)),
|
|
18
|
+
addBeacon: async (event) => void beacons.set(next++, event),
|
|
19
|
+
readBeacons: async () => [...beacons].map(([key, event]) => ({ key, event })),
|
|
20
|
+
removeBeacons: async (keys) => void keys.forEach((key) => beacons.delete(key)),
|
|
21
|
+
getFlush: async () => flush,
|
|
22
|
+
setFlush: async (state) => void (flush = structuredClone(state)),
|
|
23
|
+
putRecords: async (entries) => void entries.forEach((e) => records.set(e.id, e)),
|
|
24
|
+
allRecords: async () => [...records.values()],
|
|
25
|
+
deleteRecords: async (ids) => void ids.forEach((id) => records.delete(id)),
|
|
26
|
+
putProjections: async (entries) => void entries.forEach((e) => projections.set(e.id, e)),
|
|
27
|
+
allProjections: async () => [...projections.values()],
|
|
28
|
+
deleteProjections: async (ids) => void ids.forEach((id) => projections.delete(id)),
|
|
29
|
+
clearGraph: async () => {
|
|
30
|
+
records.clear();
|
|
31
|
+
projections.clear();
|
|
32
|
+
}
|
|
33
|
+
};
|
|
34
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** name of the Cache that holds third-party files; not versioned, since a versioned URL outlives a release */
|
|
2
|
+
export declare const THIRD_CACHE = "spool-third";
|
|
3
|
+
/** how a held file is kept: `immutable` is never checked again, `revalidate` at a network moment once old */
|
|
4
|
+
export type VersionClass = 'immutable' | 'revalidate';
|
|
5
|
+
/** response headers the worker adds to a held copy */
|
|
6
|
+
export declare const THIRD_HEADERS: {
|
|
7
|
+
readonly class: "x-spool-class";
|
|
8
|
+
readonly fetched: "x-spool-fetched";
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* Whether a cross-origin file is safe to answer from a copy, and how. A hash in the file name, a
|
|
12
|
+
* semantic version, a `/v12/` path segment, or an origin that marks the file `immutable` or
|
|
13
|
+
* `max-age` of a year or more means the URL names the bytes: `immutable`. A version in the query,
|
|
14
|
+
* or a match for one of the site's own patterns, is a weaker claim: `revalidate`. Anything else is
|
|
15
|
+
* null and goes to the network every time.
|
|
16
|
+
*/
|
|
17
|
+
export declare function versionClass(url: URL, headers: Headers, extra?: readonly string[]): VersionClass | null;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/** name of the Cache that holds third-party files; not versioned, since a versioned URL outlives a release */
|
|
2
|
+
export const THIRD_CACHE = 'spool-third';
|
|
3
|
+
/** response headers the worker adds to a held copy */
|
|
4
|
+
export const THIRD_HEADERS = { class: 'x-spool-class', fetched: 'x-spool-fetched' };
|
|
5
|
+
const YEAR = 31_536_000;
|
|
6
|
+
const STRONG = [/[._-][0-9a-f]{8,}(?=[._-]|$)/i, /[@/_-]v?\d+\.\d+\.\d+/, /\/v\d+(?:\/|$)/];
|
|
7
|
+
const WEAK = /[?&](?:v|ver|version|hash|h|rev)=[^&]+/i;
|
|
8
|
+
/**
|
|
9
|
+
* Whether a cross-origin file is safe to answer from a copy, and how. A hash in the file name, a
|
|
10
|
+
* semantic version, a `/v12/` path segment, or an origin that marks the file `immutable` or
|
|
11
|
+
* `max-age` of a year or more means the URL names the bytes: `immutable`. A version in the query,
|
|
12
|
+
* or a match for one of the site's own patterns, is a weaker claim: `revalidate`. Anything else is
|
|
13
|
+
* null and goes to the network every time.
|
|
14
|
+
*/
|
|
15
|
+
export function versionClass(url, headers, extra = []) {
|
|
16
|
+
if (STRONG.some((pattern) => pattern.test(url.pathname)))
|
|
17
|
+
return 'immutable';
|
|
18
|
+
const control = headers.get('cache-control') ?? '';
|
|
19
|
+
if (/(?:^|,)\s*immutable\b/i.test(control))
|
|
20
|
+
return 'immutable';
|
|
21
|
+
const age = /max-age=(\d+)/i.exec(control);
|
|
22
|
+
if (age !== null && Number(age[1]) >= YEAR)
|
|
23
|
+
return 'immutable';
|
|
24
|
+
if (WEAK.test(url.search))
|
|
25
|
+
return 'revalidate';
|
|
26
|
+
for (const source of extra) {
|
|
27
|
+
try {
|
|
28
|
+
if (new RegExp(source).test(url.href))
|
|
29
|
+
return 'revalidate';
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
continue;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/** what {@link trimCss} returns */
|
|
2
|
+
export type TrimResult = {
|
|
3
|
+
/** the stylesheet with the provably unmatched style rules removed */
|
|
4
|
+
css: string;
|
|
5
|
+
/** style rules removed, nested ones included */
|
|
6
|
+
removedRules: number;
|
|
7
|
+
/** sorted tokens whose absence removed at least one rule: one per selector of each removed rule */
|
|
8
|
+
missing: string[];
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* Removes the style rules that no page of a site can match, keeping everything else byte for byte.
|
|
12
|
+
*
|
|
13
|
+
* It borrows PurgeCSS's content rule: the default extractor "considers every word of a file as a
|
|
14
|
+
* selector" (purgecss.com/extractors, web page read 2026-10-19), so a word that appears anywhere
|
|
15
|
+
* keeps the rules that name it. It differs on purpose. PurgeCSS needs a `safelist` for what the
|
|
16
|
+
* content never spells out, and this function has none: a rule stays whenever the scanner cannot
|
|
17
|
+
* prove it unmatched, and tokens come from every page and script of the site, not from one build.
|
|
18
|
+
*
|
|
19
|
+
* - A style rule is removed when every selector of its list needs a class, id or type token that
|
|
20
|
+
* `tokens` lacks. One selector that may match keeps the rule.
|
|
21
|
+
* - Type names compare in lowercase, and a class or id present in any ASCII case keeps a rule,
|
|
22
|
+
* since a quirks-mode page matches them that way. `html`, `body`, `*`, `&`, attribute selectors, escaped and
|
|
23
|
+
* non-ASCII identifiers and namespaced selectors never count against a rule.
|
|
24
|
+
* - Pseudo-classes and pseudo-elements are ignored with their arguments, so `.a:hover` needs `a`,
|
|
25
|
+
* and anything inside `:is`, `:where`, `:not` and `:has` is never examined.
|
|
26
|
+
* - `@media`, `@supports`, `@layer`, `@container` and `@scope` are walked into and their shells
|
|
27
|
+
* stay, even when emptied, because an empty `@layer` still orders layers. Every other at-rule
|
|
28
|
+
* (`@font-face`, `@keyframes`, `@import`, `@property`, `@page`, `@charset`, `@namespace`,
|
|
29
|
+
* `@counter-style`) is kept whole.
|
|
30
|
+
* - Rules are only removed, never reordered or rewritten, so the cascade of what remains is
|
|
31
|
+
* unchanged. Whitespace before a removed rule goes with it.
|
|
32
|
+
* - When the scanner meets an unterminated comment, string or block, an unmatched closing bracket
|
|
33
|
+
* or a stray declaration, it keeps the rest of the file as it was.
|
|
34
|
+
*
|
|
35
|
+
* `missing` holds one absent token for each selector of each removed rule. A page whose tokens
|
|
36
|
+
* contain none of them cannot match any removed rule.
|
|
37
|
+
*/
|
|
38
|
+
export declare function trimCss(css: string, tokens: ReadonlySet<string>): TrimResult;
|
package/dist/trim/css.js
ADDED
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
const NESTING = new Set(['media', 'supports', 'layer', 'container', 'scope']);
|
|
2
|
+
const OPENERS = { '(': ')', '[': ']', '{': '}' };
|
|
3
|
+
const isWord = (code) => (code >= 48 && code <= 57) ||
|
|
4
|
+
(code >= 65 && code <= 90) ||
|
|
5
|
+
(code >= 97 && code <= 122) ||
|
|
6
|
+
code === 45 ||
|
|
7
|
+
code === 95;
|
|
8
|
+
const isHex = (c) => c !== undefined && /[0-9a-fA-F]/.test(c);
|
|
9
|
+
function skipComment(css, at) {
|
|
10
|
+
const end = css.indexOf('*/', at + 2);
|
|
11
|
+
return end < 0 ? -1 : end + 2;
|
|
12
|
+
}
|
|
13
|
+
function skipString(css, at) {
|
|
14
|
+
const quote = css[at];
|
|
15
|
+
for (let i = at + 1; i < css.length; i++) {
|
|
16
|
+
const c = css[i];
|
|
17
|
+
if (c === '\\')
|
|
18
|
+
i++;
|
|
19
|
+
else if (c === quote)
|
|
20
|
+
return i + 1;
|
|
21
|
+
else if (c === '\n')
|
|
22
|
+
return -1;
|
|
23
|
+
}
|
|
24
|
+
return -1;
|
|
25
|
+
}
|
|
26
|
+
/** the index after the group that opens at `start` (`(`, `[` or `{`), or -1 when the text ends first */
|
|
27
|
+
function skipGroup(css, start) {
|
|
28
|
+
const stack = [];
|
|
29
|
+
let i = start;
|
|
30
|
+
while (i < css.length) {
|
|
31
|
+
const c = css[i];
|
|
32
|
+
if (c === '\\') {
|
|
33
|
+
i += 2;
|
|
34
|
+
}
|
|
35
|
+
else if (c === '/' && css[i + 1] === '*') {
|
|
36
|
+
i = skipComment(css, i);
|
|
37
|
+
if (i < 0)
|
|
38
|
+
return -1;
|
|
39
|
+
}
|
|
40
|
+
else if (c === '"' || c === "'") {
|
|
41
|
+
i = skipString(css, i);
|
|
42
|
+
if (i < 0)
|
|
43
|
+
return -1;
|
|
44
|
+
}
|
|
45
|
+
else if (c === '(' && /url$/i.test(css.slice(Math.max(0, i - 3), i)) && bare(css, i)) {
|
|
46
|
+
let j = i + 1;
|
|
47
|
+
while (j < css.length && css[j] !== ')')
|
|
48
|
+
j += css[j] === '\\' ? 2 : 1;
|
|
49
|
+
if (j >= css.length)
|
|
50
|
+
return -1;
|
|
51
|
+
i = j + 1;
|
|
52
|
+
if (stack.length === 0)
|
|
53
|
+
return i;
|
|
54
|
+
}
|
|
55
|
+
else if (c in OPENERS) {
|
|
56
|
+
stack.push(OPENERS[c]);
|
|
57
|
+
i++;
|
|
58
|
+
}
|
|
59
|
+
else if (c === ')' || c === ']' || c === '}') {
|
|
60
|
+
if (stack.pop() !== c)
|
|
61
|
+
return -1;
|
|
62
|
+
i++;
|
|
63
|
+
if (stack.length === 0)
|
|
64
|
+
return i;
|
|
65
|
+
}
|
|
66
|
+
else {
|
|
67
|
+
i++;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
return -1;
|
|
71
|
+
}
|
|
72
|
+
/** whether the `url(` at `open` holds an unquoted address */
|
|
73
|
+
function bare(css, open) {
|
|
74
|
+
let i = open + 1;
|
|
75
|
+
while (i < css.length && /\s/.test(css[i]))
|
|
76
|
+
i++;
|
|
77
|
+
return css[i] !== '"' && css[i] !== "'";
|
|
78
|
+
}
|
|
79
|
+
/** where a prelude ends: the index of its `{` or `;`, or -1 when the parser has lost its place */
|
|
80
|
+
function skipPrelude(css, start) {
|
|
81
|
+
let i = start;
|
|
82
|
+
while (i < css.length) {
|
|
83
|
+
const c = css[i];
|
|
84
|
+
if (c === '\\') {
|
|
85
|
+
i += 2;
|
|
86
|
+
}
|
|
87
|
+
else if (c === '/' && css[i + 1] === '*') {
|
|
88
|
+
i = skipComment(css, i);
|
|
89
|
+
if (i < 0)
|
|
90
|
+
return -1;
|
|
91
|
+
}
|
|
92
|
+
else if (c === '"' || c === "'") {
|
|
93
|
+
i = skipString(css, i);
|
|
94
|
+
if (i < 0)
|
|
95
|
+
return -1;
|
|
96
|
+
}
|
|
97
|
+
else if (c === '(' || c === '[') {
|
|
98
|
+
i = skipGroup(css, i);
|
|
99
|
+
if (i < 0)
|
|
100
|
+
return -1;
|
|
101
|
+
}
|
|
102
|
+
else if (c === '{' || c === ';') {
|
|
103
|
+
return i;
|
|
104
|
+
}
|
|
105
|
+
else if (c === '}' || c === ')' || c === ']') {
|
|
106
|
+
return -1;
|
|
107
|
+
}
|
|
108
|
+
else {
|
|
109
|
+
i++;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
return -1;
|
|
113
|
+
}
|
|
114
|
+
function readIdent(text, start) {
|
|
115
|
+
let i = start;
|
|
116
|
+
let plain = true;
|
|
117
|
+
while (i < text.length) {
|
|
118
|
+
const code = text.charCodeAt(i);
|
|
119
|
+
if (code === 92) {
|
|
120
|
+
plain = false;
|
|
121
|
+
i++;
|
|
122
|
+
if (isHex(text[i])) {
|
|
123
|
+
for (let n = 0; n < 6 && isHex(text[i]); n++)
|
|
124
|
+
i++;
|
|
125
|
+
if (/\s/.test(text[i] ?? ''))
|
|
126
|
+
i++;
|
|
127
|
+
}
|
|
128
|
+
else {
|
|
129
|
+
i++;
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
else if (isWord(code)) {
|
|
133
|
+
i++;
|
|
134
|
+
}
|
|
135
|
+
else if (code >= 0x80) {
|
|
136
|
+
plain = false;
|
|
137
|
+
i++;
|
|
138
|
+
}
|
|
139
|
+
else {
|
|
140
|
+
break;
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return { end: i, plain };
|
|
144
|
+
}
|
|
145
|
+
function splitList(text) {
|
|
146
|
+
const parts = [];
|
|
147
|
+
let from = 0;
|
|
148
|
+
let i = 0;
|
|
149
|
+
while (i < text.length) {
|
|
150
|
+
const c = text[i];
|
|
151
|
+
if (c === '\\') {
|
|
152
|
+
i += 2;
|
|
153
|
+
}
|
|
154
|
+
else if (c === '"' || c === "'") {
|
|
155
|
+
const end = skipString(text, i);
|
|
156
|
+
i = end < 0 ? text.length : end;
|
|
157
|
+
}
|
|
158
|
+
else if (c === '(' || c === '[') {
|
|
159
|
+
const end = skipGroup(text, i);
|
|
160
|
+
i = end < 0 ? text.length : end;
|
|
161
|
+
}
|
|
162
|
+
else {
|
|
163
|
+
if (c === ',') {
|
|
164
|
+
parts.push(text.slice(from, i));
|
|
165
|
+
from = i + 1;
|
|
166
|
+
}
|
|
167
|
+
i++;
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
parts.push(text.slice(from));
|
|
171
|
+
return parts.map((part) => part.trim());
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* The first class, id or type a selector needs that `tokens` lacks, or null when the selector may
|
|
175
|
+
* match. Pseudo-classes and pseudo-elements are skipped with their arguments, so `:is`, `:where`,
|
|
176
|
+
* `:not` and `:has` never prove anything. An attribute selector, `*`, `&`, `html`, `body`, an
|
|
177
|
+
* escaped or non-ASCII identifier and a namespace prefix need nothing. Text the scanner does not
|
|
178
|
+
* understand gives null.
|
|
179
|
+
*/
|
|
180
|
+
function firstMissing(selector, tokens, lower) {
|
|
181
|
+
let found = null;
|
|
182
|
+
let compound = true;
|
|
183
|
+
// a quirks-mode page matches classes and ids in any ASCII case, so any case keeps a rule
|
|
184
|
+
const need = (token) => {
|
|
185
|
+
if (found === null && !tokens.has(token) && !lower.has(token.toLowerCase()))
|
|
186
|
+
found = token;
|
|
187
|
+
};
|
|
188
|
+
let i = 0;
|
|
189
|
+
while (i < selector.length) {
|
|
190
|
+
const c = selector[i];
|
|
191
|
+
if (/\s/.test(c) || c === '>' || c === '+' || c === '~') {
|
|
192
|
+
compound = true;
|
|
193
|
+
i++;
|
|
194
|
+
}
|
|
195
|
+
else if (c === '*' || c === '&') {
|
|
196
|
+
compound = false;
|
|
197
|
+
i++;
|
|
198
|
+
}
|
|
199
|
+
else if (c === '.' || c === '#') {
|
|
200
|
+
const { end, plain } = readIdent(selector, i + 1);
|
|
201
|
+
if (end === i + 1)
|
|
202
|
+
return null;
|
|
203
|
+
if (plain)
|
|
204
|
+
need(selector.slice(i + 1, end));
|
|
205
|
+
compound = false;
|
|
206
|
+
i = end;
|
|
207
|
+
}
|
|
208
|
+
else if (c === '[') {
|
|
209
|
+
const end = skipGroup(selector, i);
|
|
210
|
+
if (end < 0)
|
|
211
|
+
return null;
|
|
212
|
+
compound = false;
|
|
213
|
+
i = end;
|
|
214
|
+
}
|
|
215
|
+
else if (c === ':') {
|
|
216
|
+
i += selector[i + 1] === ':' ? 2 : 1;
|
|
217
|
+
i = readIdent(selector, i).end;
|
|
218
|
+
if (selector[i] === '(') {
|
|
219
|
+
const end = skipGroup(selector, i);
|
|
220
|
+
if (end < 0)
|
|
221
|
+
return null;
|
|
222
|
+
i = end;
|
|
223
|
+
}
|
|
224
|
+
compound = false;
|
|
225
|
+
}
|
|
226
|
+
else if (isWord(c.charCodeAt(0)) || c === '\\' || c.charCodeAt(0) >= 0x80) {
|
|
227
|
+
const { end, plain } = readIdent(selector, i);
|
|
228
|
+
const name = selector.slice(i, end).toLowerCase();
|
|
229
|
+
if (compound && plain && name !== 'html' && name !== 'body')
|
|
230
|
+
need(name);
|
|
231
|
+
compound = false;
|
|
232
|
+
i = end;
|
|
233
|
+
}
|
|
234
|
+
else {
|
|
235
|
+
return null;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
return found;
|
|
239
|
+
}
|
|
240
|
+
function trimSheet(css, walk) {
|
|
241
|
+
let out = '';
|
|
242
|
+
let i = 0;
|
|
243
|
+
while (i < css.length) {
|
|
244
|
+
const c = css[i];
|
|
245
|
+
if (/\s/.test(c)) {
|
|
246
|
+
out += c;
|
|
247
|
+
i++;
|
|
248
|
+
continue;
|
|
249
|
+
}
|
|
250
|
+
if (c === '/' && css[i + 1] === '*') {
|
|
251
|
+
const end = skipComment(css, i);
|
|
252
|
+
if (end < 0)
|
|
253
|
+
return out + css.slice(i);
|
|
254
|
+
out += css.slice(i, end);
|
|
255
|
+
i = end;
|
|
256
|
+
continue;
|
|
257
|
+
}
|
|
258
|
+
const open = skipPrelude(css, i);
|
|
259
|
+
if (open < 0)
|
|
260
|
+
return out + css.slice(i);
|
|
261
|
+
const prelude = css.slice(i, open);
|
|
262
|
+
if (css[open] === ';') {
|
|
263
|
+
if (c !== '@')
|
|
264
|
+
return out + css.slice(i);
|
|
265
|
+
out += css.slice(i, open + 1);
|
|
266
|
+
i = open + 1;
|
|
267
|
+
continue;
|
|
268
|
+
}
|
|
269
|
+
const end = skipGroup(css, open);
|
|
270
|
+
if (end < 0)
|
|
271
|
+
return out + css.slice(i);
|
|
272
|
+
if (c === '@') {
|
|
273
|
+
const name = /^@([a-zA-Z-]+)/.exec(prelude)?.[1]?.toLowerCase() ?? '';
|
|
274
|
+
out += NESTING.has(name)
|
|
275
|
+
? `${css.slice(i, open + 1)}${trimSheet(css.slice(open + 1, end - 1), walk)}}`
|
|
276
|
+
: css.slice(i, end);
|
|
277
|
+
}
|
|
278
|
+
else {
|
|
279
|
+
const selectors = splitList(prelude.replace(/\/\*[\s\S]*?\*\//g, ' '));
|
|
280
|
+
const gaps = selectors.map((s) => s === '' ? null : firstMissing(s, walk.tokens, walk.lower));
|
|
281
|
+
if (gaps.every((gap) => gap !== null)) {
|
|
282
|
+
walk.removed++;
|
|
283
|
+
for (const gap of gaps)
|
|
284
|
+
walk.missing.add(gap);
|
|
285
|
+
out = out.trimEnd();
|
|
286
|
+
}
|
|
287
|
+
else {
|
|
288
|
+
out += css.slice(i, end);
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
i = end;
|
|
292
|
+
}
|
|
293
|
+
return out;
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Removes the style rules that no page of a site can match, keeping everything else byte for byte.
|
|
297
|
+
*
|
|
298
|
+
* It borrows PurgeCSS's content rule: the default extractor "considers every word of a file as a
|
|
299
|
+
* selector" (purgecss.com/extractors, web page read 2026-10-19), so a word that appears anywhere
|
|
300
|
+
* keeps the rules that name it. It differs on purpose. PurgeCSS needs a `safelist` for what the
|
|
301
|
+
* content never spells out, and this function has none: a rule stays whenever the scanner cannot
|
|
302
|
+
* prove it unmatched, and tokens come from every page and script of the site, not from one build.
|
|
303
|
+
*
|
|
304
|
+
* - A style rule is removed when every selector of its list needs a class, id or type token that
|
|
305
|
+
* `tokens` lacks. One selector that may match keeps the rule.
|
|
306
|
+
* - Type names compare in lowercase, and a class or id present in any ASCII case keeps a rule,
|
|
307
|
+
* since a quirks-mode page matches them that way. `html`, `body`, `*`, `&`, attribute selectors, escaped and
|
|
308
|
+
* non-ASCII identifiers and namespaced selectors never count against a rule.
|
|
309
|
+
* - Pseudo-classes and pseudo-elements are ignored with their arguments, so `.a:hover` needs `a`,
|
|
310
|
+
* and anything inside `:is`, `:where`, `:not` and `:has` is never examined.
|
|
311
|
+
* - `@media`, `@supports`, `@layer`, `@container` and `@scope` are walked into and their shells
|
|
312
|
+
* stay, even when emptied, because an empty `@layer` still orders layers. Every other at-rule
|
|
313
|
+
* (`@font-face`, `@keyframes`, `@import`, `@property`, `@page`, `@charset`, `@namespace`,
|
|
314
|
+
* `@counter-style`) is kept whole.
|
|
315
|
+
* - Rules are only removed, never reordered or rewritten, so the cascade of what remains is
|
|
316
|
+
* unchanged. Whitespace before a removed rule goes with it.
|
|
317
|
+
* - When the scanner meets an unterminated comment, string or block, an unmatched closing bracket
|
|
318
|
+
* or a stray declaration, it keeps the rest of the file as it was.
|
|
319
|
+
*
|
|
320
|
+
* `missing` holds one absent token for each selector of each removed rule. A page whose tokens
|
|
321
|
+
* contain none of them cannot match any removed rule.
|
|
322
|
+
*/
|
|
323
|
+
export function trimCss(css, tokens) {
|
|
324
|
+
const lower = new Set([...tokens].map((token) => token.toLowerCase()));
|
|
325
|
+
const walk = { tokens, lower, missing: new Set(), removed: 0 };
|
|
326
|
+
const trimmed = trimSheet(css, walk);
|
|
327
|
+
return { css: trimmed, removedRules: walk.removed, missing: [...walk.missing].sort() };
|
|
328
|
+
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** the query parameter that asks the proxy for the full stylesheet */
|
|
2
|
+
export declare const TRIM_PARAM = "spool-trim";
|
|
3
|
+
/** one trimmed stylesheet: what the origin must send for it to be served, and what it needs */
|
|
4
|
+
export type TrimEntry = {
|
|
5
|
+
/** `sha256-<base64>` of the origin's bytes the entry was built from */
|
|
6
|
+
source: string;
|
|
7
|
+
/** the trimmed stylesheet */
|
|
8
|
+
css: string;
|
|
9
|
+
/** tokens whose absence removed a rule; a page that has one gets the full file */
|
|
10
|
+
missing: string[];
|
|
11
|
+
/** the same-origin script keys the tokens were built with */
|
|
12
|
+
scripts: string[];
|
|
13
|
+
};
|
|
14
|
+
/** a manifest that {@link buildTrimManifest} writes and `spoolProxy` reads; plain JSON */
|
|
15
|
+
export type TrimManifest = {
|
|
16
|
+
schema: 1;
|
|
17
|
+
/** entries by {@link trimKey} */
|
|
18
|
+
styles: Record<string, TrimEntry>;
|
|
19
|
+
};
|
|
20
|
+
/** a same-origin file the manifest is built from; `url` may be absolute or site-relative */
|
|
21
|
+
export type TrimFile = {
|
|
22
|
+
url: string;
|
|
23
|
+
text: string;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* A query string with the {@link TRIM_PARAM} parameter removed and every other parameter left
|
|
27
|
+
* byte for byte, so the origin gets the URL the page named.
|
|
28
|
+
*/
|
|
29
|
+
export declare function stripTrimParam(search: string): string;
|
|
30
|
+
/** `pathname + search` of a URL with the {@link TRIM_PARAM} parameter dropped, the manifest key */
|
|
31
|
+
export declare function trimKey(url: string, base?: string): string;
|
|
32
|
+
/** `sha256-<base64>` of `bytes` */
|
|
33
|
+
export declare function sourceHash(bytes: Uint8Array | string): Promise<string>;
|
|
34
|
+
/**
|
|
35
|
+
* Trims every stylesheet against the union of the tokens of all `pages` and all `scripts`, so one
|
|
36
|
+
* file keeps one URL for the whole site. A stylesheet that loses no rule gets no entry. `pages` is
|
|
37
|
+
* HTML, `scripts` the same-origin JavaScript the pages load, `styles` the same-origin CSS.
|
|
38
|
+
*
|
|
39
|
+
* `foreignScripts` are scripts from other origins that the pages load, such as a widget that
|
|
40
|
+
* builds markup. Their words widen the tokens, because a class such a script adds is in the DOM
|
|
41
|
+
* whatever origin served it. The guard never looks at their URLs, so a vendor that starts adding a
|
|
42
|
+
* new class after the crawl is not caught.
|
|
43
|
+
*/
|
|
44
|
+
export declare function buildTrimManifest(input: {
|
|
45
|
+
pages: readonly string[];
|
|
46
|
+
scripts: readonly TrimFile[];
|
|
47
|
+
styles: readonly TrimFile[];
|
|
48
|
+
foreignScripts?: readonly TrimFile[];
|
|
49
|
+
}): Promise<TrimManifest>;
|
|
50
|
+
/** what {@link guardPage} decided for one page */
|
|
51
|
+
export type Guard = {
|
|
52
|
+
/** the page, with the links of its trimmed stylesheets rewritten when the guard fired */
|
|
53
|
+
html: string;
|
|
54
|
+
fired: boolean;
|
|
55
|
+
/** `token` when a stylesheet's missing token is on the page, `script` for an unseen script */
|
|
56
|
+
reason?: 'token' | 'script';
|
|
57
|
+
/** the manifest keys of the trimmed stylesheets the page links */
|
|
58
|
+
files: string[];
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Decides whether `html` may use the trimmed stylesheets it links. It may not when one of its
|
|
62
|
+
* tokens is in a linked entry's `missing` set, or when it loads a same-origin script the manifest
|
|
63
|
+
* was not built with. Then each link to a trimmed file gets `spool-trim=0`, which the proxy
|
|
64
|
+
* answers with the full file. It cannot see a class a third-party script adds, or markup injected
|
|
65
|
+
* after load from a page the manifest never covered.
|
|
66
|
+
*/
|
|
67
|
+
export declare function guardPage(html: string, manifest: TrimManifest, pageUrl: string): Guard;
|