@drupflare/spool 0.1.0 → 0.2.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/README.md CHANGED
@@ -36,6 +36,7 @@ has no runtime dependencies. A site with no server code can load it from two fil
36
36
  - [Shadow Mode](#-shadow-mode)
37
37
  - [Proxy Mode](#-proxy-mode)
38
38
  - [Trimmed Stylesheets](#-trimmed-stylesheets)
39
+ - [Images and Video](#-images-and-video)
39
40
  - [Out of Scope](#-out-of-scope)
40
41
  - [Browser Support](#-browser-support)
41
42
  - [Subpath Exports](#-subpath-exports)
@@ -1419,7 +1420,8 @@ in the instance: a restart forgets them, and each instance of a scaled-out proxy
1419
1420
  A whole page is a large artifact, and the provisioning rule declines one that costs more than the
1420
1421
  priors say it saves, so set `provision` on the spool for large pages. A `Content-Security-Policy`
1421
1422
  that allows only nonce or hash scripts blocks the injected client tag. A URL with a query string
1422
- always goes to the origin. [Trimmed Stylesheets](#-trimmed-stylesheets) covers the `trim` option.
1423
+ always goes to the origin. [Trimmed Stylesheets](#-trimmed-stylesheets) covers the `trim` option
1424
+ and [Images and Video](#-images-and-video) the `images` and `video` options.
1423
1425
 
1424
1426
  ---
1425
1427
 
@@ -1475,6 +1477,195 @@ seen, never to a repeat or local view, and it is not part of the per-view headli
1475
1477
 
1476
1478
  ---
1477
1479
 
1480
+ ## 🎬 Images and Video
1481
+
1482
+ A browser that has fetched an image cannot make it smaller, so conversion happens where the file is
1483
+ served. `@drupflare/spool/media` gives `spoolProxy` three options, each off until set. `images`
1484
+ converts a JPEG or PNG response to WebP for a browser whose `Accept` lists it. `video` rewrites
1485
+ the `<video>` tags of an HTML response, such as adding `preload="none"`. `embeds` swaps a YouTube
1486
+ or Vimeo iframe for a link that loads the player on click.
1487
+
1488
+ ```ts
1489
+ import { type ImageEncoder } from '@drupflare/spool/media';
1490
+ import { spoolProxy } from '@drupflare/spool/proxy';
1491
+ import { memoryStore } from '@drupflare/spool/stores';
1492
+
1493
+ export function mediaProxy(encoder: ImageEncoder) {
1494
+ return spoolProxy({
1495
+ origin: 'https://origin.example.edu',
1496
+ spool: { store: memoryStore() },
1497
+ images: { encoder, width: { fallback: 1600 } },
1498
+ video: { preload: 'none', autoplay: 'defer', when: 'slow' }
1499
+ });
1500
+ }
1501
+ ```
1502
+
1503
+ An `ImageEncoder` takes the origin's bytes and `{ format: 'webp', quality, width }` and returns
1504
+ `{ bytes }`. It never upscales, so `width` is a ceiling, and it throws on input it cannot decode.
1505
+ spool has no runtime dependencies and ships an adapter for [tinyimg](https://tinyimg.gmitch215.dev),
1506
+ which decodes and encodes inside WebAssembly:
1507
+
1508
+ ```js
1509
+ import { readFile } from 'node:fs/promises';
1510
+ import { TinyImgModule, transform } from '@gmitch215/tinyimg';
1511
+ import { tinyimgEncoder } from '@drupflare/spool/media';
1512
+
1513
+ const wasm = new URL(import.meta.resolve('@gmitch215/tinyimg/tinyimg.wasm'));
1514
+ const module = await TinyImgModule.loadBytes(await readFile(wasm));
1515
+
1516
+ export const encoder = tinyimgEncoder({ module, transform });
1517
+ ```
1518
+
1519
+ Use tinyimg 1.1.1 or later. Version 1.1.0 and earlier drop the EXIF orientation tag without
1520
+ rotating the pixels, so a phone photo comes out sideways. `tinyimgEncoder` throws when the module
1521
+ reports an older version.
1522
+
1523
+ Quality is 80, 65 for `Save-Data: on` and 70 for an `ECT` of `slow-2g`, `2g` or `3g`. The width
1524
+ comes from `Sec-CH-Width`, then `Sec-CH-Viewport-Width` times `Sec-CH-DPR`, then
1525
+ `width.fallback`. The proxy converts a `GET` that matches `paths` (JPEG and PNG names by default),
1526
+ has no `Range` or `Authorization`, and gets a `200` JPEG or PNG without a cookie between
1527
+ `minBytes` (4096) and `maxBytes` (15,000,000). Anything else, and any file the encoder cannot
1528
+ shrink, goes out as the origin sent it. The proxy fetches the origin for every request, so a
1529
+ visitor only gets bytes the origin sent that visitor.
1530
+
1531
+ A converted response carries `Vary` for `Accept`, `Save-Data`, `Sec-CH-Width`, `Sec-CH-DPR`,
1532
+ `Sec-CH-Viewport-Width` and `ECT`, a weak `ETag` and `X-Spool-Image`. HTML responses gain
1533
+ `Accept-CH` for the three size hints and `ECT` unless `hints` is false, and the browser then
1534
+ sends them with later image requests to the same origin.
1535
+
1536
+ `maxWidth` (2560) is the width for a request that carries no hint, and `false` removes it. `png`
1537
+ is `'lossy'` by default. `'lossless'` encodes every PNG without loss, and `'auto'` encodes a PNG
1538
+ under 200 KB both ways and serves the smaller file, which suits screenshots and flat graphics.
1539
+ Requests for the same file, quality and width share one encoder call while it runs. The proxy
1540
+ waits `timeoutMs` (10,000) for the encoder and then serves the origin's file, and the late result
1541
+ is cached for the next request. `timeoutMs: false` waits without limit.
1542
+
1543
+ Drupal's video formatter has no `preload` setting, and `preload="none"` does not stop `autoplay`.
1544
+ `autoplay: 'defer'` removes the attribute, adds `controls` and marks the tag
1545
+ `data-spool-autoplay`. With `when: 'always'` the page the spool keeps carries the rewrite. With
1546
+ `'save-data'` or `'slow'` the rewritten page is private to that visitor: it gets `private` in
1547
+ `Cache-Control` and `Save-Data, ECT` in `Vary`, and the spool does not keep it. A device's stored
1548
+ copy of that page keeps the origin's tags.
1549
+
1550
+ `proxy.images` counts `converted`, `bytesIn` and `bytesOut` (converted responses only),
1551
+ `cacheHits`, `coalesced`, `lazied`, `responsive`, and `skipped` by reason. `proxy.video` counts
1552
+ `pages` and `rewritten`. Read the saving as `bytesIn - bytesOut` over real traffic on the site. A
1553
+ request for any other path counts under `skipped.path`, so that key follows total traffic.
1554
+ [docs/security.md](docs/security.md#images-and-video) covers the decoder.
1555
+
1556
+ ### Page Rewrites
1557
+
1558
+ Three options change the HTML the origin sends. Each edits start tags only and leaves every other
1559
+ byte as it was, and a rewritten page gets a weak `ETag`.
1560
+
1561
+ ```ts
1562
+ import { type ImageEncoder } from '@drupflare/spool/media';
1563
+ import { spoolProxy } from '@drupflare/spool/proxy';
1564
+ import { memoryStore } from '@drupflare/spool/stores';
1565
+
1566
+ export function rewriteProxy(encoder: ImageEncoder) {
1567
+ return spoolProxy({
1568
+ origin: 'https://origin.example.edu',
1569
+ spool: { store: memoryStore() },
1570
+ images: {
1571
+ encoder,
1572
+ png: 'auto',
1573
+ maxWidth: 1920,
1574
+ timeoutMs: 5000,
1575
+ lazy: { skip: 3 },
1576
+ responsive: { widths: [480, 960, 1440], sizes: '(min-width: 60em) 50vw, 100vw' }
1577
+ },
1578
+ embeds: { providers: ['youtube'], thumbnail: false }
1579
+ });
1580
+ }
1581
+ ```
1582
+
1583
+ `lazy` adds `loading="lazy"` and `decoding="async"` to each `<img>` after the first `skip` (2 by
1584
+ default), and `iframes: true` does the same for `<iframe>`. It leaves a tag that has `loading`,
1585
+ `fetchpriority` or a lazy-loading library's `data-src`, a tag inside a `<header>` or `<noscript>`,
1586
+ and an image that a `<link rel="preload" as="image">` names. A browser that defers the largest
1587
+ image of a page paints it later, so `skip` is the only guard and the option is off until set. In a
1588
+ crawl of 70 pages per profile on 16 sites, the default `skip` of 2 made the largest image lazy on 2
1589
+ of 23 desktop pages and 2 of 20 phone pages that had an image as their largest element, and no
1590
+ `skip` from 2 to 4 reached zero on both profiles.
1591
+
1592
+ `responsive` adds a `srcset` of `?spool-w=<width>` variants to a same-origin `<img>` that has none,
1593
+ one per entry of `widths` (320, 480, 640, 960, 1280 and 1920 by default), and a `sizes` of `100vw`
1594
+ unless the tag has one. The proxy removes `spool-w` before it asks the origin, answers only widths
1595
+ from the list and never sends a file larger than the origin's. Firefox and Safari send no
1596
+ `Sec-CH-Width`, and this is how they get a resized file. Name the layout width in `sizes`, since
1597
+ `100vw` makes the browser pick the widest candidate it can use. A tag with `srcset` or `data-src`,
1598
+ and any tag inside `<picture>`, stays as it is.
1599
+
1600
+ `embeds` replaces a server-rendered YouTube or Vimeo `<iframe>` with one whose `srcdoc` holds a
1601
+ link to the player. YouTube shows its thumbnail (`thumbnail: false` shows a plain frame) and the
1602
+ player loads on click. A page that sends `Content-Security-Policy` is left alone unless
1603
+ `ignoreCsp` is true, and so is an embed with `enablejsapi=1`. `proxy.embeds` counts `pages`,
1604
+ `rewritten` and `skipped`. [docs/security.md](docs/security.md#embed-facades) covers the rules.
1605
+
1606
+ ### Dictionary Transport
1607
+
1608
+ A visitor who holds an earlier stylesheet or script of a directory can fetch the next one as the
1609
+ difference from it. `dictionary` implements this for Chromium 130 and later
1610
+ ([RFC 9842](https://www.rfc-editor.org/rfc/rfc9842)). The proxy marks public `.css` and `.js`
1611
+ responses with `Use-As-Dictionary` and answers a request that names one of them with
1612
+ `Content-Encoding: dcz`. spool has no compression library, so the caller supplies the `encoder`,
1613
+ and Node's `zlib` does zstd:
1614
+
1615
+ ```ts
1616
+ import { promisify } from 'node:util';
1617
+ import { zstdCompress } from 'node:zlib';
1618
+ import { spoolProxy } from '@drupflare/spool/proxy';
1619
+ import { memoryStore } from '@drupflare/spool/stores';
1620
+
1621
+ const compress = promisify(zstdCompress);
1622
+
1623
+ export const proxy = spoolProxy({
1624
+ origin: 'https://origin.example.edu',
1625
+ spool: { store: memoryStore() },
1626
+ dictionary: {
1627
+ encoder: async (dictionary, input) => new Uint8Array(await compress(input, { dictionary }))
1628
+ }
1629
+ });
1630
+ ```
1631
+
1632
+ The `encoder` gets the dictionary, the new file and the coding (`'dcz'`, or `'dcb'` when `formats`
1633
+ lists it) and returns the compressed stream. spool adds the coding's header. An encoder that
1634
+ throws, or whose output is no smaller, leaves the plain file. Only responses the proxy would keep
1635
+ as public ones, with no cookie, ever become dictionaries. `proxy.dictionary` counts `registered`,
1636
+ `encoded`, `bytesIn`, `bytesOut` and `skipped`.
1637
+ [docs/security.md](docs/security.md#dictionary-transport) covers the exposure.
1638
+
1639
+ `base` names the files that register as dictionaries, as a function of the pathname, a regular
1640
+ expression or a list of them. Without it the browser holds the latest file of each directory it
1641
+ fetched, and the sizing in [docs/impact.md](docs/impact.md#savings-today-and-at-maximum) shows that
1642
+ choice recovers little. With it the browser holds only the files you name, one per directory, and
1643
+ every other file of the directory is encoded against the base the request names.
1644
+ `scripts/measure/dictionary-size.ts` records the best base of each directory of a site.
1645
+
1646
+ ### Defaults
1647
+
1648
+ Every option is absent by default. The table shows what a feature does once its parent option is
1649
+ set and how to change it.
1650
+
1651
+ | Feature | Option | Default once the parent is set | Leave or enter |
1652
+ | ------------------------------------------ | ------------------- | ------------------------------------------- | ----------------------------------------------------- |
1653
+ | WebP conversion, `304` and `X-Spool-Image` | `images` | on, needs an `encoder` | leave `images` out |
1654
+ | `Accept-CH` hints and `Vary` | `images.hints` | on | `hints: false` |
1655
+ | Quality by `Save-Data` and `ECT` | `images.quality` | 80, 65 and 70 | give all three one number |
1656
+ | Width ceiling for a request with no width | `images.maxWidth` | 2560 | `maxWidth: false`, or another number |
1657
+ | Shared encodes and the encoder time limit | `images.timeoutMs` | 10,000 ms, identical encodes share one call | `timeoutMs: false` removes the limit |
1658
+ | PNG mode | `images.png` | `'lossy'` | `'auto'` or `'lossless'` |
1659
+ | `loading="lazy"` on images and iframes | `images.lazy` | off | `lazy: {}` or `{ skip, iframes }` |
1660
+ | `srcset` variants | `images.responsive` | off | `responsive: {}` or `{ widths, sizes }` |
1661
+ | `preload="none"` on video | `video.preload` | `'none'` | `preload: false` |
1662
+ | Video autoplay deferral | `video.autoplay` | off | `autoplay: 'defer'` |
1663
+ | YouTube and Vimeo facades | `embeds` | off | `embeds: {}` or `{ providers, thumbnail, ignoreCsp }` |
1664
+ | Dictionary transport | `dictionary` | off | `dictionary: { encoder }` |
1665
+ | Which files become dictionaries | `dictionary.base` | every `.css` and `.js` response | `base: /\/base\.js$/`, a list or a function |
1666
+
1667
+ ---
1668
+
1478
1669
  ## 🚫 Out of Scope
1479
1670
 
1480
1671
  - spool never authorises on the client. The device holds only what the server already sent that
@@ -1520,6 +1711,7 @@ loads per view and reports the view as such.
1520
1711
  | `@drupflare/spool/client` | `register` and the page handle |
1521
1712
  | `@drupflare/spool/report` | the energy model |
1522
1713
  | `@drupflare/spool/trim` | `buildTrimManifest`, `trimCss` and `guardPage` |
1714
+ | `@drupflare/spool/media` | `tinyimgEncoder`, `imageVariant` and `rewriteVideo` |
1523
1715
 
1524
1716
  ---
1525
1717
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schema": 2,
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "files": {
5
5
  "client.js": {
6
6
  "bytes": 2155,
@@ -0,0 +1,59 @@
1
+ /** the embed hosts `embeds` knows */
2
+ export type EmbedProvider = 'youtube' | 'vimeo';
3
+ /**
4
+ * What `spoolProxy({ embeds })` does to a server-rendered `<iframe>` of a YouTube or Vimeo embed:
5
+ * it becomes an iframe whose `srcdoc` is one link to the real embed, so the player loads when the
6
+ * visitor clicks. `providers` defaults to both. `thumbnail` shows YouTube's `hqdefault.jpg` in the
7
+ * link; default true, and Vimeo always gets a plain placeholder. A page that sends a
8
+ * `Content-Security-Policy` header is left alone, because the facade needs an inline style and the
9
+ * thumbnail host, unless `ignoreCsp` is true.
10
+ */
11
+ export type EmbedOptions = {
12
+ providers?: readonly EmbedProvider[];
13
+ thumbnail?: boolean;
14
+ ignoreCsp?: boolean;
15
+ };
16
+ /** `EmbedOptions` with every default applied */
17
+ export type ResolvedEmbedOptions = {
18
+ providers: ReadonlySet<EmbedProvider>;
19
+ thumbnail: boolean;
20
+ ignoreCsp: boolean;
21
+ };
22
+ /** what the proxy counted for `embeds`: pages with a rewritten embed, the embeds, and the ones left alone by reason (`csp`, `jsapi`) */
23
+ export type EmbedStats = {
24
+ pages: number;
25
+ rewritten: number;
26
+ skipped: Record<string, number>;
27
+ };
28
+ /** applies the defaults to `options` */
29
+ export declare function resolveEmbedOptions(options?: EmbedOptions): ResolvedEmbedOptions;
30
+ /** the provider and id of an embed URL, with the URL made absolute, or null for any other address */
31
+ export declare function embedOf(src: string): {
32
+ provider: EmbedProvider;
33
+ id: string;
34
+ url: URL;
35
+ } | null;
36
+ /** the document a facade iframe carries in `srcdoc`, before it is escaped for the attribute */
37
+ export declare function facadeDocument(embed: {
38
+ provider: EmbedProvider;
39
+ id: string;
40
+ url: URL;
41
+ }, title: string, thumbnail: boolean): string;
42
+ /**
43
+ * Replaces each server-rendered YouTube or Vimeo `<iframe src>` in `html` with a facade, as
44
+ * `options` allow, and says how many it replaced and how many it left alone. Only an `https`,
45
+ * `http` or protocol-relative `src` on a known embed host and path, with an id of 6 to 64 letters,
46
+ * digits, `-` and `_`, is touched. An iframe inside an HTML comment or `<noscript>`, one that has
47
+ * `srcdoc`, and one whose URL sets `enablejsapi=1` (the page's script expects the real player) stay
48
+ * as they are; the last is counted as `jsapi`. With `page.csp` set, and no `ignoreCsp`, every
49
+ * matching iframe is left alone and counted as `csp`. The facade keeps `width`, `height`, `title`,
50
+ * `class`, `style`, `allow`, `allowfullscreen`, `loading`, `id`, `sandbox` and `referrerpolicy`.
51
+ * Everything outside the replaced start tags stays byte for byte.
52
+ */
53
+ export declare function rewriteEmbeds(html: string, options?: EmbedOptions | ResolvedEmbedOptions, page?: {
54
+ csp: boolean;
55
+ }): {
56
+ html: string;
57
+ rewritten: number;
58
+ skipped: Record<string, number>;
59
+ };
@@ -0,0 +1,120 @@
1
+ import { decodeEntities, tagsOf } from '../trim/tokens.js';
2
+ import { applyEdits, commentRanges, find, noscriptRanges, within } from './html.js';
3
+ /** applies the defaults to `options` */
4
+ export function resolveEmbedOptions(options = {}) {
5
+ return {
6
+ providers: new Set(options.providers ?? ['youtube', 'vimeo']),
7
+ thumbnail: options.thumbnail !== false,
8
+ ignoreCsp: options.ignoreCsp === true
9
+ };
10
+ }
11
+ const HOSTS = {
12
+ 'youtube.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
13
+ 'www.youtube.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
14
+ 'youtube-nocookie.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
15
+ 'www.youtube-nocookie.com': {
16
+ provider: 'youtube',
17
+ path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/
18
+ },
19
+ 'player.vimeo.com': { provider: 'vimeo', path: /^\/video\/([A-Za-z0-9_-]{6,64})\/?$/ }
20
+ };
21
+ /** the provider and id of an embed URL, with the URL made absolute, or null for any other address */
22
+ export function embedOf(src) {
23
+ const text = decodeEntities(src).trim();
24
+ if (!/^(?:https?:)?\/\//i.test(text))
25
+ return null;
26
+ let url;
27
+ try {
28
+ url = new URL(text.startsWith('//') ? `https:${text}` : text);
29
+ }
30
+ catch {
31
+ return null;
32
+ }
33
+ const host = HOSTS[url.hostname.toLowerCase()];
34
+ const id = host?.path.exec(url.pathname)?.[1];
35
+ // the playlist embed is `/embed/videoseries?list=...` and has no single video id
36
+ if (!host || !id || id === 'videoseries')
37
+ return null;
38
+ return { provider: host.provider, id, url };
39
+ }
40
+ const escape = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
41
+ const KEPT = new Set([
42
+ 'width',
43
+ 'height',
44
+ 'title',
45
+ 'class',
46
+ 'style',
47
+ 'allow',
48
+ 'allowfullscreen',
49
+ 'loading',
50
+ 'id',
51
+ 'sandbox',
52
+ 'referrerpolicy'
53
+ ]);
54
+ const STYLE = 'html,body{margin:0;height:100%;background:#000}a{position:relative;display:block;height:100%;color:#fff;font:14px/1.2 sans-serif;text-decoration:none}' +
55
+ 'img{position:absolute;top:0;left:0;width:100%;height:100%;object-fit:cover}' +
56
+ '.g{position:absolute;top:0;right:0;bottom:0;left:0;margin:auto;width:64px;height:44px;border-radius:12px;background:rgba(0,0,0,.7);text-align:center;font-size:26px;line-height:44px}' +
57
+ '.t{position:absolute;left:0;right:0;bottom:0;padding:8px 12px;background:rgba(0,0,0,.6);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}';
58
+ /** the document a facade iframe carries in `srcdoc`, before it is escaped for the attribute */
59
+ export function facadeDocument(embed, title, thumbnail) {
60
+ const link = new URL(embed.url);
61
+ link.searchParams.set('autoplay', '1');
62
+ const label = escape(title);
63
+ const picture = thumbnail && embed.provider === 'youtube'
64
+ ? `<img src="https://i.ytimg.com/vi/${embed.id}/hqdefault.jpg" alt="">`
65
+ : '';
66
+ return (`<!doctype html><meta charset=utf-8><style>${STYLE}</style>` +
67
+ `<a href="${escape(link.href)}" aria-label="${label}">${picture}` +
68
+ `<span class=g>&#9654;</span><span class=t>${label}</span></a>`);
69
+ }
70
+ function facadeTag(html, tag, embed, o) {
71
+ const kept = tag.attributes
72
+ .filter((a) => KEPT.has(a.name))
73
+ .map((a) => html.slice(a.start, a.end));
74
+ const title = decodeEntities(find(tag, 'title')?.value ?? '').trim() || 'Play video';
75
+ const doc = escape(facadeDocument(embed, title, o.thumbnail));
76
+ return `<iframe ${[...kept, `srcdoc="${doc}"`].join(' ')}>`;
77
+ }
78
+ /**
79
+ * Replaces each server-rendered YouTube or Vimeo `<iframe src>` in `html` with a facade, as
80
+ * `options` allow, and says how many it replaced and how many it left alone. Only an `https`,
81
+ * `http` or protocol-relative `src` on a known embed host and path, with an id of 6 to 64 letters,
82
+ * digits, `-` and `_`, is touched. An iframe inside an HTML comment or `<noscript>`, one that has
83
+ * `srcdoc`, and one whose URL sets `enablejsapi=1` (the page's script expects the real player) stay
84
+ * as they are; the last is counted as `jsapi`. With `page.csp` set, and no `ignoreCsp`, every
85
+ * matching iframe is left alone and counted as `csp`. The facade keeps `width`, `height`, `title`,
86
+ * `class`, `style`, `allow`, `allowfullscreen`, `loading`, `id`, `sandbox` and `referrerpolicy`.
87
+ * Everything outside the replaced start tags stays byte for byte.
88
+ */
89
+ export function rewriteEmbeds(html, options = {}, page = { csp: false }) {
90
+ const resolved = options.providers instanceof Set
91
+ ? options
92
+ : resolveEmbedOptions(options);
93
+ const tags = tagsOf(html);
94
+ const comments = commentRanges(html);
95
+ const noscripts = noscriptRanges(html, tags);
96
+ const edits = [];
97
+ const skipped = {};
98
+ for (const tag of tags) {
99
+ if (tag.name !== 'iframe' || html[tag.end] !== '>')
100
+ continue;
101
+ if (within(comments, tag.start) || within(noscripts, tag.start))
102
+ continue;
103
+ const src = find(tag, 'src')?.value;
104
+ if (src === undefined || find(tag, 'srcdoc'))
105
+ continue;
106
+ const embed = embedOf(src);
107
+ if (!embed || !resolved.providers.has(embed.provider))
108
+ continue;
109
+ if (embed.url.searchParams.get('enablejsapi') === '1') {
110
+ skipped.jsapi = (skipped.jsapi ?? 0) + 1;
111
+ continue;
112
+ }
113
+ if (page.csp && !resolved.ignoreCsp) {
114
+ skipped.csp = (skipped.csp ?? 0) + 1;
115
+ continue;
116
+ }
117
+ edits.push({ at: tag.start, to: tag.end + 1, text: facadeTag(html, tag, embed, resolved) });
118
+ }
119
+ return { html: applyEdits(html, edits), rewritten: edits.length, skipped };
120
+ }
@@ -0,0 +1,13 @@
1
+ /** what a request says about the visitor's connection */
2
+ export type MediaSignals = {
3
+ /** `Save-Data: on` */
4
+ saveData: boolean;
5
+ /** `ECT` of `slow-2g`, `2g` or `3g` */
6
+ slow: boolean;
7
+ };
8
+ /** the connection signals in a request's `Save-Data` and `ECT` headers */
9
+ export declare function signalsOf(headers: Headers): MediaSignals;
10
+ /** adds each name to a comma-separated header, skipping any it already lists in any case */
11
+ export declare function mergeList(headers: Headers, name: string, additions: readonly string[]): void;
12
+ /** makes `Cache-Control` private: `public` becomes `private`, and a header with none gets `private, max-age=0` */
13
+ export declare function makePrivate(headers: Headers): void;
@@ -0,0 +1,44 @@
1
+ /** the connection signals in a request's `Save-Data` and `ECT` headers */
2
+ export function signalsOf(headers) {
3
+ const ect = (headers.get('ect') ?? '').trim().toLowerCase();
4
+ return {
5
+ saveData: (headers.get('save-data') ?? '').trim().toLowerCase() === 'on',
6
+ slow: ect === 'slow-2g' || ect === '2g' || ect === '3g'
7
+ };
8
+ }
9
+ /** adds each name to a comma-separated header, skipping any it already lists in any case */
10
+ export function mergeList(headers, name, additions) {
11
+ const current = headers.get(name);
12
+ const have = (current ?? '')
13
+ .split(',')
14
+ .map((part) => part.trim())
15
+ .filter((part) => part !== '');
16
+ if (have.includes('*'))
17
+ return;
18
+ const lower = new Set(have.map((part) => part.toLowerCase()));
19
+ const added = additions.filter((part) => !lower.has(part.toLowerCase()));
20
+ if (added.length === 0)
21
+ return;
22
+ headers.set(name, [...have, ...added].join(', '));
23
+ }
24
+ /** makes `Cache-Control` private: `public` becomes `private`, and a header with none gets `private, max-age=0` */
25
+ export function makePrivate(headers) {
26
+ const value = headers.get('cache-control');
27
+ if (!value) {
28
+ headers.set('cache-control', 'private, max-age=0');
29
+ return;
30
+ }
31
+ const parts = value
32
+ .split(',')
33
+ .map((part) => part.trim())
34
+ .filter((part) => part !== '');
35
+ const names = parts.map((part) => (part.split('=')[0] ?? '').trim().toLowerCase());
36
+ if (names.includes('private'))
37
+ return;
38
+ const at = names.indexOf('public');
39
+ if (at >= 0)
40
+ parts[at] = 'private';
41
+ else
42
+ parts.unshift('private');
43
+ headers.set('cache-control', parts.join(', '));
44
+ }
@@ -0,0 +1,27 @@
1
+ import { type Attribute, type Tag } from '../trim/tokens.js';
2
+ /** one replacement in an HTML string: the text from `at` to `to` becomes `text` */
3
+ export type Edit = {
4
+ at: number;
5
+ to: number;
6
+ text: string;
7
+ };
8
+ /** the `[start, end)` ranges of the HTML comments in `html`; a comment that never closes runs to the end */
9
+ export declare function commentRanges(html: string): Array<[number, number]>;
10
+ /** the ranges of every `<noscript>` element, from its start tag to its end tag or the end of the HTML */
11
+ export declare function noscriptRanges(html: string, tags: readonly Tag[]): Array<[number, number]>;
12
+ /** the ranges of the outermost elements called `name`, from the start tag to the matching end tag or the end of the HTML */
13
+ export declare function elementRanges(html: string, tags: readonly Tag[], name: string): Array<[number, number]>;
14
+ /** the range of `<head>`, from its start tag to the first `<body>` or `</head>`, or null without one */
15
+ export declare function headRange(html: string, tags: readonly Tag[]): [number, number] | null;
16
+ /** whether `at` falls inside any of `ranges` */
17
+ export declare const within: (ranges: ReadonlyArray<[number, number]>, at: number) => boolean;
18
+ /** the first attribute of `tag` called `name`, whose name is already lowercase */
19
+ export declare const find: (tag: Tag, name: string) => Attribute | undefined;
20
+ /** the edit that gives the attribute `a` the value `value`, keeping its quote style */
21
+ export declare function setValue(html: string, a: Attribute, value: string): Edit;
22
+ /** the edit that adds `attributes` (such as `preload="none"`) to the end of `tag`, before a closing slash */
23
+ export declare function appendAttributes(html: string, tag: Tag, attributes: readonly string[]): Edit;
24
+ /** `html` with `edits` applied; they may arrive in any order and must not overlap */
25
+ export declare function applyEdits(html: string, edits: readonly Edit[]): string;
26
+ /** the start tags of `html` that are named `name`, close with `>` and sit outside comments */
27
+ export declare function tagsNamed(html: string, name: string, tags?: readonly Tag[]): Tag[];
@@ -0,0 +1,93 @@
1
+ import { tagsOf } from '../trim/tokens.js';
2
+ /** the `[start, end)` ranges of the HTML comments in `html`; a comment that never closes runs to the end */
3
+ export function commentRanges(html) {
4
+ const ranges = [];
5
+ let at = html.indexOf('<!--');
6
+ while (at >= 0) {
7
+ const close = html.indexOf('-->', at + 4);
8
+ const end = close < 0 ? html.length : close + 3;
9
+ ranges.push([at, end]);
10
+ at = html.indexOf('<!--', end);
11
+ }
12
+ return ranges;
13
+ }
14
+ /** the ranges of every `<noscript>` element, from its start tag to its end tag or the end of the HTML */
15
+ export function noscriptRanges(html, tags) {
16
+ const ranges = [];
17
+ for (const tag of tags) {
18
+ if (tag.name !== 'noscript')
19
+ continue;
20
+ const after = html.slice(tag.end).search(/<\/noscript\s*>/i);
21
+ ranges.push([tag.start, after < 0 ? html.length : tag.end + after]);
22
+ }
23
+ return ranges;
24
+ }
25
+ /** the ranges of the outermost elements called `name`, from the start tag to the matching end tag or the end of the HTML */
26
+ export function elementRanges(html, tags, name) {
27
+ const ranges = [];
28
+ let open = -1;
29
+ for (const tag of tags) {
30
+ if (tag.name !== name || tag.start < open)
31
+ continue;
32
+ const pattern = new RegExp(`<(/?)${name}\\b[^>]*>`, 'gi');
33
+ pattern.lastIndex = tag.end;
34
+ let depth = 1;
35
+ let end = html.length;
36
+ for (let hit = pattern.exec(html); hit; hit = pattern.exec(html)) {
37
+ depth += hit[1] ? -1 : 1;
38
+ if (depth === 0) {
39
+ end = hit.index + hit[0].length;
40
+ break;
41
+ }
42
+ }
43
+ ranges.push([tag.start, end]);
44
+ open = end;
45
+ }
46
+ return ranges;
47
+ }
48
+ /** the range of `<head>`, from its start tag to the first `<body>` or `</head>`, or null without one */
49
+ export function headRange(html, tags) {
50
+ const head = tags.find((tag) => tag.name === 'head');
51
+ if (!head)
52
+ return null;
53
+ const rest = html.slice(head.end);
54
+ const stop = rest.search(/<\/head\s*>|<body[\s>]/i);
55
+ return [head.start, stop < 0 ? html.length : head.end + stop];
56
+ }
57
+ /** whether `at` falls inside any of `ranges` */
58
+ export const within = (ranges, at) => ranges.some(([start, end]) => at >= start && at < end);
59
+ /** the first attribute of `tag` called `name`, whose name is already lowercase */
60
+ export const find = (tag, name) => tag.attributes.find((a) => a.name === name);
61
+ /** the edit that gives the attribute `a` the value `value`, keeping its quote style */
62
+ export function setValue(html, a, value) {
63
+ const raw = html.slice(a.start, a.end);
64
+ const prefix = /^[^=\s]+\s*=\s*/.exec(raw);
65
+ if (!prefix)
66
+ return { at: a.end, to: a.end, text: `="${value}"` };
67
+ const quote = raw[prefix[0].length];
68
+ const q = quote === '"' || quote === "'" ? quote : '';
69
+ return { at: a.start + prefix[0].length, to: a.end, text: `${q}${value}${q}` };
70
+ }
71
+ /** the edit that adds `attributes` (such as `preload="none"`) to the end of `tag`, before a closing slash */
72
+ export function appendAttributes(html, tag, attributes) {
73
+ const floor = tag.attributes.at(-1)?.end ?? tag.start + 1 + tag.name.length;
74
+ const slash = html[tag.end - 1] === '/' && floor < tag.end;
75
+ const at = slash ? tag.end - 1 : tag.end;
76
+ const gap = /\s/.test(html[at - 1]) ? '' : ' ';
77
+ return { at, to: at, text: `${gap}${attributes.join(' ')}` };
78
+ }
79
+ /** `html` with `edits` applied; they may arrive in any order and must not overlap */
80
+ export function applyEdits(html, edits) {
81
+ let out = '';
82
+ let from = 0;
83
+ for (const edit of [...edits].sort((a, b) => a.at - b.at)) {
84
+ out += html.slice(from, edit.at) + edit.text;
85
+ from = edit.to;
86
+ }
87
+ return out + html.slice(from);
88
+ }
89
+ /** the start tags of `html` that are named `name`, close with `>` and sit outside comments */
90
+ export function tagsNamed(html, name, tags = tagsOf(html)) {
91
+ const comments = commentRanges(html);
92
+ return tags.filter((tag) => tag.name === name && html[tag.end] === '>' && !within(comments, tag.start));
93
+ }