@tiavision/sinter-mail 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +113 -2
- package/docs/mail.md +298 -0
- package/docs/proposals/progressive-rendering.md +180 -0
- package/docs/proposals/sinter-mail.md +520 -0
- package/llms.txt +21 -0
- package/package.json +65 -4
- package/sinter/autolink.ts +98 -0
- package/sinter/components/internal/mail-a.html +5 -0
- package/sinter/components/internal/mail-abbr.html +5 -0
- package/sinter/components/internal/mail-address.html +5 -0
- package/sinter/components/internal/mail-article.html +5 -0
- package/sinter/components/internal/mail-aside.html +5 -0
- package/sinter/components/internal/mail-b.html +5 -0
- package/sinter/components/internal/mail-bdi.html +5 -0
- package/sinter/components/internal/mail-bdo.html +5 -0
- package/sinter/components/internal/mail-blockquote.html +5 -0
- package/sinter/components/internal/mail-br.html +5 -0
- package/sinter/components/internal/mail-center.html +5 -0
- package/sinter/components/internal/mail-cite.html +5 -0
- package/sinter/components/internal/mail-code.html +5 -0
- package/sinter/components/internal/mail-dd.html +5 -0
- package/sinter/components/internal/mail-del.html +5 -0
- package/sinter/components/internal/mail-details.html +5 -0
- package/sinter/components/internal/mail-dfn.html +5 -0
- package/sinter/components/internal/mail-div.html +5 -0
- package/sinter/components/internal/mail-dl.html +5 -0
- package/sinter/components/internal/mail-dt.html +5 -0
- package/sinter/components/internal/mail-em.html +5 -0
- package/sinter/components/internal/mail-figcaption.html +5 -0
- package/sinter/components/internal/mail-figure.html +5 -0
- package/sinter/components/internal/mail-font.html +5 -0
- package/sinter/components/internal/mail-footer.html +5 -0
- package/sinter/components/internal/mail-h1.html +5 -0
- package/sinter/components/internal/mail-h2.html +5 -0
- package/sinter/components/internal/mail-h3.html +5 -0
- package/sinter/components/internal/mail-h4.html +5 -0
- package/sinter/components/internal/mail-h5.html +5 -0
- package/sinter/components/internal/mail-h6.html +5 -0
- package/sinter/components/internal/mail-header.html +5 -0
- package/sinter/components/internal/mail-hr.html +5 -0
- package/sinter/components/internal/mail-i.html +5 -0
- package/sinter/components/internal/mail-img.html +5 -0
- package/sinter/components/internal/mail-ins.html +5 -0
- package/sinter/components/internal/mail-kbd.html +5 -0
- package/sinter/components/internal/mail-li.html +5 -0
- package/sinter/components/internal/mail-main.html +5 -0
- package/sinter/components/internal/mail-mark.html +5 -0
- package/sinter/components/internal/mail-nav.html +5 -0
- package/sinter/components/internal/mail-node.html +5 -0
- package/sinter/components/internal/mail-ol.html +5 -0
- package/sinter/components/internal/mail-orphan.html +5 -0
- package/sinter/components/internal/mail-p.html +5 -0
- package/sinter/components/internal/mail-pre.html +5 -0
- package/sinter/components/internal/mail-q.html +5 -0
- package/sinter/components/internal/mail-s.html +5 -0
- package/sinter/components/internal/mail-samp.html +5 -0
- package/sinter/components/internal/mail-section.html +5 -0
- package/sinter/components/internal/mail-small.html +5 -0
- package/sinter/components/internal/mail-span.html +5 -0
- package/sinter/components/internal/mail-steps.html +5 -0
- package/sinter/components/internal/mail-steps.ts +46 -0
- package/sinter/components/internal/mail-strike.html +5 -0
- package/sinter/components/internal/mail-strong.html +5 -0
- package/sinter/components/internal/mail-sub.html +5 -0
- package/sinter/components/internal/mail-summary.html +5 -0
- package/sinter/components/internal/mail-sup.html +5 -0
- package/sinter/components/internal/mail-table.html +5 -0
- package/sinter/components/internal/mail-time.html +5 -0
- package/sinter/components/internal/mail-tt.html +5 -0
- package/sinter/components/internal/mail-u.html +5 -0
- package/sinter/components/internal/mail-ul.html +5 -0
- package/sinter/components/internal/mail-var.html +5 -0
- package/sinter/components/internal/mail-wbr.html +5 -0
- package/sinter/components/mail-body.html +21 -0
- package/sinter/css/hints.ts +259 -0
- package/sinter/css/index.ts +348 -0
- package/sinter/css/media.ts +254 -0
- package/sinter/css/parse.ts +124 -0
- package/sinter/css/selectors.ts +530 -0
- package/sinter/css/tokenize.ts +279 -0
- package/sinter/css/values.ts +669 -0
- package/sinter/engine.ts +6 -0
- package/sinter/index.ts +5 -0
- package/sinter/parse.ts +359 -0
- package/sinter/parser/entities.ts +22 -0
- package/sinter/parser/index.ts +54 -0
- package/sinter/parser/tokenizer.ts +275 -0
- package/sinter/parser/tree.ts +1265 -0
- package/sinter/plain.ts +125 -0
- package/sinter/raw.ts +28 -0
- package/sinter/sinter.helpers.ts +11 -0
- package/sinter/sinter.types.ts +144 -0
- package/sinter/tags.ts +169 -0
- package/sinter/tree.ts +168 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tia Heinrich
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,114 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tiavision/sinter-mail
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Show email in your [sinter](https://github.com/tiaforge/sinter) app, without an iframe.
|
|
4
|
+
|
|
5
|
+
Hand it an email's HTML (or plain text) and it renders as a normal part of your page: it scrolls, selects,
|
|
6
|
+
searches and prints with the rest, and picks up your fonts where the email sets none. Nothing in an email
|
|
7
|
+
runs, loads from the network without your say-so, or reaches outside its box.
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<sn-resource name="msg" src="/api/messages/{$url.id}"></sn-resource>
|
|
11
|
+
<article data-sn-let="{ body: msg.html ? mail.parse(msg.html, { images: 'proxy', proxy: '/img?url={url}' }) : mail.plain(msg.text) }">
|
|
12
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
13
|
+
</article>
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Why
|
|
17
|
+
|
|
18
|
+
Webmail UIs usually put a message in an iframe, or sanitize its HTML and inject it with `innerHTML`.
|
|
19
|
+
sinter never builds HTML from data, so this library takes a third route: `mail.parse` turns the email into a
|
|
20
|
+
tree, and generated components render each element, with every attribute and style checked.
|
|
21
|
+
|
|
22
|
+
- **Safe by construction.** No script, handler, `javascript:` link, SVG, form or iframe can exist in the tree.
|
|
23
|
+
The page's CSP can stay strict (`script-src 'self'`, Trusted Types).
|
|
24
|
+
- **Private images.** Remote images are left out by default, so tracking pixels never fire. Turn them on, or
|
|
25
|
+
route them through your own proxy so senders never see your readers' addresses.
|
|
26
|
+
- **Looks like the sender's email.** The parser follows the HTML standard, and the email's styles
|
|
27
|
+
(`<style>` rules, inline styles, legacy attributes like `bgcolor` and `<font>`) are resolved the way a
|
|
28
|
+
browser's cascade would.
|
|
29
|
+
- **Fast where it counts.** An email in a file is folded into plain HTML at build time, with no JavaScript.
|
|
30
|
+
Long messages render progressively. Parse in the browser, lazily, or on your server.
|
|
31
|
+
- **Plain text too.** `mail.plain` handles `text/plain` bodies: links, quotes, signatures and
|
|
32
|
+
`format=flowed`.
|
|
33
|
+
|
|
34
|
+
## Install
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
npm install @tiavision/sinter-mail
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Needs sinter 0.20.0 or later.
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
// vite.config.js
|
|
44
|
+
import { defineConfig } from 'vite';
|
|
45
|
+
import sinter from '@tiaforge-ui/sinter/vite';
|
|
46
|
+
|
|
47
|
+
export default defineConfig({
|
|
48
|
+
plugins: [sinter({ components: ['@tiavision/sinter-mail'] })],
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
// src/sinter.helpers.ts: the helpers, as the namespace `mail`
|
|
54
|
+
export * as mail from '@tiavision/sinter-mail';
|
|
55
|
+
|
|
56
|
+
// src/sinter.types.ts: the tree's types, for your own declarations
|
|
57
|
+
export type { Body, Element } from '@tiavision/sinter-mail';
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
## Usage
|
|
61
|
+
|
|
62
|
+
**HTML email**
|
|
63
|
+
|
|
64
|
+
```html
|
|
65
|
+
<article data-sn-let="{ body: mail.parse(msg.html) }">
|
|
66
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
67
|
+
</article>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Images through your proxy**
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
mail.parse(html, { images: 'proxy', proxy: '/img?url={url}' })
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
**Inline (`cid:`) images**
|
|
77
|
+
|
|
78
|
+
```js
|
|
79
|
+
mail.parse(html, { cid: '/api/messages/42/parts?cid={cid}' })
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Plain text**
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
mail.plain(text, { flowed: true })
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**An email from a file, folded at build time** (`src="file:./welcome.html"`): the page ships it as plain
|
|
89
|
+
HTML, with no JavaScript. See [the guide](docs/mail.md#three-places-one-function).
|
|
90
|
+
|
|
91
|
+
**Previews and search snippets**
|
|
92
|
+
|
|
93
|
+
```js
|
|
94
|
+
mail.text(body) // the text, blocks separated by newlines
|
|
95
|
+
mail.links(body) // every link with its text
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Links and images can be restyled by filling the `link` and `image` slots of `<mail-body>`.
|
|
99
|
+
|
|
100
|
+
## Documentation
|
|
101
|
+
|
|
102
|
+
- **[The guide](docs/mail.md)**: all options, what is kept and dropped, styling, proxies, progressive
|
|
103
|
+
rendering, slots, CSP, and the security guarantees.
|
|
104
|
+
- **[Design notes](docs/proposals/sinter-mail.md)**: why it is built the way it is.
|
|
105
|
+
- **[Contributing](CONTRIBUTING.md)**: layout, tests and the release process.
|
|
106
|
+
|
|
107
|
+
## Limits
|
|
108
|
+
|
|
109
|
+
Only the email's own styles apply (no `:hover`, animation or web fonts), `@media` is decided once at parse
|
|
110
|
+
time (but for the colour scheme: colours set by `prefers-color-scheme: dark` rules follow the page's), and the library is tested in Chromium so far. [The guide](docs/mail.md#limits) has the full list.
|
|
111
|
+
|
|
112
|
+
## License
|
|
113
|
+
|
|
114
|
+
MIT
|
package/docs/mail.md
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
# Email
|
|
2
|
+
|
|
3
|
+
`@tiavision/sinter-mail` shows the body of an email in a sinter app, without an iframe. `mail.parse`
|
|
4
|
+
turns an email's HTML into a tree, `mail.plain` does the same for a plain-text email, and `<mail-body>`
|
|
5
|
+
renders the tree as part of the page: it scrolls, selects, searches and prints with it, and takes the
|
|
6
|
+
page's fonts where the email sets none.
|
|
7
|
+
|
|
8
|
+
```html
|
|
9
|
+
<sn-resource name="msg" src="/api/messages/{$url.id}"></sn-resource>
|
|
10
|
+
<article data-sn-let="{ body: msg.html ? mail.parse(msg.html, { images: 'proxy', proxy: '/img?url={url}' }) : mail.plain(msg.text) }">
|
|
11
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
12
|
+
</article>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Nothing an email contains runs, loads from the network without the app's consent, or reaches outside
|
|
16
|
+
its box. The rest of this page says what is kept, how it looks, and what the app decides.
|
|
17
|
+
|
|
18
|
+
## Setup
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install @tiavision/sinter-mail
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```js
|
|
25
|
+
// vite.config.js
|
|
26
|
+
import { defineConfig } from 'vite';
|
|
27
|
+
import sinter from '@tiaforge-ui/sinter/vite';
|
|
28
|
+
|
|
29
|
+
export default defineConfig({
|
|
30
|
+
plugins: [sinter({ components: ['@tiavision/sinter-mail'] })],
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
// src/sinter.helpers.ts: the helpers, as the namespace `mail`
|
|
36
|
+
export * as mail from '@tiavision/sinter-mail';
|
|
37
|
+
|
|
38
|
+
// src/sinter.types.ts: the tree's types, for your own declarations
|
|
39
|
+
export type { Body, Element } from '@tiavision/sinter-mail';
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
sinter-mail needs a sinter with the changes made for it (the branch `ccr-dc349183-ubeji7` of
|
|
43
|
+
tiaforge/sinter, until they are released).
|
|
44
|
+
|
|
45
|
+
## Three places, one function
|
|
46
|
+
|
|
47
|
+
`mail.parse(html, options)` is a pure function, so sinter runs it wherever its argument is:
|
|
48
|
+
|
|
49
|
+
| The email | Where it is parsed | What the page ships |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| A file: `src="file:./welcome.html"` | at build time | the email as plain HTML, no JavaScript |
|
|
52
|
+
| HTML from an API, in a `data-sn-let` | in the browser, once per source and options | the parser, about 32 kB gzip, and the components, about 16 kB |
|
|
53
|
+
| The same, with the package lazy | in the browser, once the parser has loaded | the parser in a chunk of its own |
|
|
54
|
+
| A tree from your API (`mail.parse` run on the server, in Node) | on the server | no parser: the components only |
|
|
55
|
+
|
|
56
|
+
To make the parser lazy, list the package in `lazy`; a let that calls `mail.parse` is `undefined` until the
|
|
57
|
+
parser has arrived, and `<mail-body>` with no body renders an empty `<div class="mail">`:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
sinter({ components: ['@tiavision/sinter-mail'], lazy: ['@tiavision/sinter-mail'] })
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`mail.plain`, `mail.text` and `mail.links` live in modules that do not import the parser, so they stay
|
|
64
|
+
ordinary helpers either way.
|
|
65
|
+
|
|
66
|
+
A server that sends the tree (`/api/messages/42/body` answering `mail.parse(html, options)` as JSON) is the
|
|
67
|
+
cheapest for the browser: on a 2,000-element newsletter, the page's JavaScript is the components' and
|
|
68
|
+
sinter's, and the email is painted about 50 ms sooner than when the browser parses it (Chromium).
|
|
69
|
+
|
|
70
|
+
## `mail.parse(html, options)`
|
|
71
|
+
|
|
72
|
+
| Option | Values | |
|
|
73
|
+
| --- | --- | --- |
|
|
74
|
+
| `images` | `'block'` (default), `'allow'`, `'proxy'` | what a remote (`http:`, `https:`) image becomes: left out (its box kept), kept as written, or kept through `proxy` |
|
|
75
|
+
| `proxy` | a URL template with `{url}` once | with `images: 'proxy'`: `'/img?url={url}'`; `{url}` is the image's absolute URL, percent-encoded. A path on your site or an `https:` URL |
|
|
76
|
+
| `cid` | a map, or a template with `{cid}` once | `cid:` images (inline parts of the message): `{ 'logo@acme': 'data:image/png;base64,…' }` or `'/api/messages/42/parts?cid={cid}'`. An unresolved one is left out |
|
|
77
|
+
| `media` | `'wide'` (default), `'narrow'` | the width the email's `@media` rules are evaluated at: 800 px, or 375 px for a narrow reading pane |
|
|
78
|
+
| `dataImages` | a length, default 65536 | the largest `data:` image kept, in characters; 0 keeps none |
|
|
79
|
+
|
|
80
|
+
An invalid option throws at each call (`mail.parse: \`images\` is 'block', 'allow' or 'proxy', not …`). The
|
|
81
|
+
same source and options give the same tree, frozen and shared: change a copy (`structuredClone(body)`).
|
|
82
|
+
|
|
83
|
+
The tree (`Body`) has the email's elements (`type: 'element'`, `tag`, `attrs`, `style`, `children`) and
|
|
84
|
+
texts, the body's own `style` (its background and font, rendered on the root), `images.origins`: every
|
|
85
|
+
remote image's origin, sorted, for a "show images from …" control, and `schemes` ([Colour
|
|
86
|
+
schemes](#colour-schemes)).
|
|
87
|
+
|
|
88
|
+
### What is kept
|
|
89
|
+
|
|
90
|
+
- **71 tags**: text, lists, tables, headings, links, images, and the legacy ones email still uses
|
|
91
|
+
(`<font>`, `<center>`). `<script>`, `<style>` (read for its rules, then dropped), forms and their controls,
|
|
92
|
+
iframes, objects, media, SVG and MathML are dropped with their content. An unknown element (`<o:p>`, a
|
|
93
|
+
custom tag) is a `span`, as the browser renders one.
|
|
94
|
+
- **Each tag's own attributes**, values checked: `href` on links, `src`, `alt`, `width`, `height` on images,
|
|
95
|
+
`colspan`, `rowspan` on cells, `dir`, `lang`, `title` everywhere. No `class`, no `style` attribute (its
|
|
96
|
+
declarations are in the element's `style`), no handler.
|
|
97
|
+
- **Links**: `http:`, `https:`, `mailto:` and `tel:`, normalized; anything else loses its `href`. Every link
|
|
98
|
+
opens in a new tab with `rel="noopener noreferrer"`. A `#fragment` link keeps its `href` only when the
|
|
99
|
+
email has its target, which keeps its id, written `mail-…`.
|
|
100
|
+
- **Images**: as the options say. `data:` images only as base64 PNG, JPEG, GIF, WebP or AVIF, never SVG.
|
|
101
|
+
- **The structure the browser would build**: the parser follows the HTML standard's tree construction
|
|
102
|
+
(implied end tags, tables, misnested formatting), so the tree is the browser's own, and a page built at
|
|
103
|
+
build time is not reparsed into another one. Nesting deeper than 256 elements is flattened.
|
|
104
|
+
|
|
105
|
+
### Styles
|
|
106
|
+
|
|
107
|
+
There is no stylesheet. `mail.parse` resolves each element's styles, as a browser's cascade would:
|
|
108
|
+
|
|
109
|
+
1. its legacy attributes (`bgcolor`, `width`, `align`, `valign`, `border`, `cellpadding`, `cellspacing`,
|
|
110
|
+
`<font color face size>`, `<center>`, `<body text>`), lowest;
|
|
111
|
+
2. the email's `<style>` rules that match it, by specificity and order;
|
|
112
|
+
3. its `style` attribute; `!important` as CSS says.
|
|
113
|
+
|
|
114
|
+
It keeps 60 properties (colours, fonts, text, box, borders, table layout, display, float), each
|
|
115
|
+
value re-serialized. Selectors with `:hover`, `:focus`, `::before` and the like never match; `@media` rules
|
|
116
|
+
are evaluated at the `media` option's width (and `prefers-color-scheme` for both schemes, below); `@import`, `@font-face`, `@keyframes` and `@supports` are
|
|
117
|
+
dropped. Never kept: `position`, `z-index`, `transform`, `url()` in any value (background images
|
|
118
|
+
included), `var()`, `calc()`, negative margins.
|
|
119
|
+
|
|
120
|
+
`<mail-body>` writes each element's styles inline. So:
|
|
121
|
+
|
|
122
|
+
- **The email's styles win over the page's.** An inline style beats every normal rule of your stylesheets,
|
|
123
|
+
and the legacy attributes are inline too, so `td { padding: 1rem }` in your CSS does not undo
|
|
124
|
+
`cellpadding="0"`.
|
|
125
|
+
- **The page fills in what the email does not set.** An email with no font takes the page's font, its
|
|
126
|
+
links your link colour. A plain email looks like part of the app. A mail client shows such an email in
|
|
127
|
+
its own default font (Gmail and Outlook use a sans-serif); to do the same, give the root one:
|
|
128
|
+
`.mail { font-family: Arial, sans-serif; }`.
|
|
129
|
+
- **Where your page still wins**: a rule with `!important`, and what the email takes from browser defaults
|
|
130
|
+
when your CSS resets them (a reset that makes images `display: block`, headings unsized, lists unmarked).
|
|
131
|
+
For newsletters exactly as sent, restore the defaults under `.mail` in your stylesheet.
|
|
132
|
+
- **The email stays in its box.** The root is `display: flow-root`, so floats and margins do not escape it.
|
|
133
|
+
A wide newsletter (600 px of tables) is as wide as it is: put `<mail-body>` in a box with
|
|
134
|
+
`overflow-x: auto` for narrow screens.
|
|
135
|
+
|
|
136
|
+
### Colour schemes
|
|
137
|
+
|
|
138
|
+
Most emails are written for a white page: dark text, if they set a colour at all. Some say they work on a dark
|
|
139
|
+
one too, and `body.schemes` reports it (`['light', 'dark']`; absent when the email says nothing):
|
|
140
|
+
|
|
141
|
+
- **declared**: its `color-scheme` or `supported-color-schemes` meta, or `color-scheme` on `<html>` or
|
|
142
|
+
`<body>` (as a style attribute or a rule). The email's colours are kept as written: it is saying they work
|
|
143
|
+
on either page.
|
|
144
|
+
- **dark rules**: `@media (prefers-color-scheme: dark)` (or a `<style media>` with it). The cascade runs for
|
|
145
|
+
both schemes, and a colour that differs (`color`, `background-color`, the border and decoration colours) is
|
|
146
|
+
written `light-dark(<light>, <dark>)`, the initial value standing in for a scheme that does not set it
|
|
147
|
+
(`light-dark(currentcolor, #fff)`). The browser picks one by the colour scheme the element is shown in: the
|
|
148
|
+
page's (`<meta name="color-scheme" content="light dark">` follows the system), or what the app sets around
|
|
149
|
+
the body. Then `schemes` includes `dark`.
|
|
150
|
+
|
|
151
|
+
So an app in dark mode can show an email with `dark` in `schemes` as it is, on its own dark page, and keep any
|
|
152
|
+
other email that sets colours light:
|
|
153
|
+
|
|
154
|
+
```css
|
|
155
|
+
.mail-light { color-scheme: light; background: Canvas; color: CanvasText; }
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```html
|
|
159
|
+
<div data-sn-class="{ 'mail-light': !tree.schemes?.includes('dark') }"><mail-body data-sn-prop="{ body: tree }"></mail-body></div>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
A dark rule's other properties (a light logo hidden, a dark one shown) keep their light values:
|
|
163
|
+
`light-dark()` takes colours only.
|
|
164
|
+
|
|
165
|
+
Quotes and signatures that `mail.plain` finds carry the classes `mail-quote` and `mail-signature`, for
|
|
166
|
+
your styles (`.mail-signature { opacity: .7 }`).
|
|
167
|
+
|
|
168
|
+
## Images and a proxy
|
|
169
|
+
|
|
170
|
+
Remote images are left out by default: a tracking pixel never loads, and a left-out image keeps its box
|
|
171
|
+
(`width`, `height`, `alt`), so the layout does not move when images are shown. `body.images.origins` lists
|
|
172
|
+
the origins the email would load from.
|
|
173
|
+
|
|
174
|
+
With a proxy, every remote image goes through your server and the sender never sees the reader's
|
|
175
|
+
address, browser, or when the email was opened:
|
|
176
|
+
|
|
177
|
+
```html
|
|
178
|
+
<article data-sn-let="{ body: mail.parse(msg.html, {
|
|
179
|
+
images: 'proxy', proxy: '/api/email/proxy-image?url={url}',
|
|
180
|
+
cid: `/api/email/proxy-image?uid=${msg.uid}&cid={cid}` }) }">
|
|
181
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
182
|
+
</article>
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
What the proxy does is yours: which origins it fetches (an allowlist the reader edits), checking the
|
|
186
|
+
address (no private or loopback targets, no redirects to them), serving only what the bytes show is an
|
|
187
|
+
image, with `X-Content-Type-Options: nosniff`, fetching when the email arrives so opening it is not
|
|
188
|
+
tracked. A proxy that answers a refused image with a transparent pixel shows an empty box; once the
|
|
189
|
+
reader allows an origin, put a version in the template (`'/img?v=3&url={url}'`) so the browser does not
|
|
190
|
+
keep the pixel.
|
|
191
|
+
|
|
192
|
+
The tree never rewrites the email's HTML, so a reply or a forward quotes the original image URLs.
|
|
193
|
+
|
|
194
|
+
## Plain text: `mail.plain(text, options)`
|
|
195
|
+
|
|
196
|
+
The same tree from a `text/plain` body: paragraphs with their line breaks (`white-space: pre-wrap`),
|
|
197
|
+
URLs, `www.` addresses and email addresses as links (GFM's rules), `>` quotes as nested blockquotes
|
|
198
|
+
(`mail-quote`), and everything after a `-- ` line as the signature (`mail-signature`).
|
|
199
|
+
|
|
200
|
+
| Option | |
|
|
201
|
+
| --- | --- |
|
|
202
|
+
| `flowed: true` | the text is `format=flowed` (RFC 3676): soft line breaks (a trailing space) are joined back into paragraphs, so they reflow on narrow screens. The flag is in the message's `Content-Type` |
|
|
203
|
+
| `delsp: true` | with `flowed`: `DelSp=yes`, the space before a soft break is removed too |
|
|
204
|
+
|
|
205
|
+
## `mail.text(node)` and `mail.links(body)`
|
|
206
|
+
|
|
207
|
+
`mail.text` is the text of a body or node, blocks separated by newlines, hidden content left out: for
|
|
208
|
+
previews and search snippets. `mail.links` is every link with its text, in order.
|
|
209
|
+
|
|
210
|
+
## Long messages: `mail.progressive(body)`
|
|
211
|
+
|
|
212
|
+
A long email (a newsletter of 2,000 elements) takes one task of about 45 ms to render, and nothing of it
|
|
213
|
+
shows until that task ends; on a phone, several times that. Number the body with `mail.progressive`, and
|
|
214
|
+
`<mail-body>` renders it progressively: the first part in the task that receives the body, the rest in steps
|
|
215
|
+
after the browser has painted that, a task each.
|
|
216
|
+
|
|
217
|
+
```html
|
|
218
|
+
<sn-resource name="message" src="/api/messages/{$url.id}"></sn-resource>
|
|
219
|
+
<mail-body data-sn-prop="{ body: mail.progressive(message.tree) }"></mail-body>
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`mail.progressive(body, head = 200)` numbers the nodes in document order and sets `body.head` (the first 200
|
|
223
|
+
nodes render first) and `body.first` (the body up to there). Run it in the page, as above, or on the server
|
|
224
|
+
before the tree is sent; there, `body.first` repeats the first nodes in the JSON (about 18% more for the
|
|
225
|
+
newsletter, less after gzip). A body that is not numbered renders whole in one task, as before, so short
|
|
226
|
+
emails are not affected.
|
|
227
|
+
|
|
228
|
+
Measured on the 2,000-element newsletter (Chromium, [measurements](proposals/progressive-rendering.md)): the
|
|
229
|
+
email starts to show after about 50 ms instead of about 100; the rest renders in steps of 5 to 15 ms, each
|
|
230
|
+
sized by how long the one before took (about 12 ms of script, so a step fits in a frame on any device), with
|
|
231
|
+
input and paint between them; the whole email is in place about 6% later than when the rest renders in one
|
|
232
|
+
task, and no frame is dropped.
|
|
233
|
+
|
|
234
|
+
- **Static pages are not affected.** The steps need a script, which only the progressive branch of
|
|
235
|
+
`<mail-body>` has: an email from a file is not numbered, the build decides that branch away, and the page
|
|
236
|
+
ships no JavaScript. Calling `mail.progressive` on a static page's body is `SN322` (the page would ship
|
|
237
|
+
JavaScript).
|
|
238
|
+
- **One element more.** A progressive render ends with a hidden empty element (`<i hidden>`, the component
|
|
239
|
+
that runs the steps) at the end of the email: a selector like `:last-child` in the app's CSS sees it.
|
|
240
|
+
- **The slots work as before.** Fills render in every step.
|
|
241
|
+
|
|
242
|
+
## Changing how links and images look
|
|
243
|
+
|
|
244
|
+
`<mail-body>` has two slots. A fill reads the element as `$slot.node`:
|
|
245
|
+
|
|
246
|
+
```html
|
|
247
|
+
<mail-body data-sn-prop="{ body }">
|
|
248
|
+
<a slot="link" target="_blank" rel="noopener noreferrer nofollow" data-sn-attr="{ href: $slot.node.attrs.href, title: $slot.node.attrs.href }"><slot></slot></a>
|
|
249
|
+
<template slot="image" data-sn-if="$slot.node.attrs.src"><img loading="lazy" data-sn-attr="{ src: $slot.node.attrs.src, alt: $slot.node.attrs.alt, width: $slot.node.attrs.width, height: $slot.node.attrs.height, srcset: null }"></template>
|
|
250
|
+
<template data-sn-else><span class="blocked" data-sn-text="$slot.node.attrs.alt ?? 'image'"></span></template>
|
|
251
|
+
</mail-body>
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`<slot></slot>` in the link's fill is the link's content. A fill that writes the element itself drops its
|
|
255
|
+
styles unless it binds them (`$slot.node.style`).
|
|
256
|
+
|
|
257
|
+
## Content Security Policy
|
|
258
|
+
|
|
259
|
+
An email rendered in the browser (HTML or a tree from an API) needs nothing beyond
|
|
260
|
+
`script-src 'self'; style-src 'self'; require-trusted-types-for 'script'`: styles are set with
|
|
261
|
+
`style.setProperty`, which a policy does not block, and nothing is written as HTML.
|
|
262
|
+
|
|
263
|
+
An email folded at build time (a `file:` email, or a page that renders it in its first frame) has its
|
|
264
|
+
styles in `style` attributes, which `style-src 'self'` blocks: the email then shows without its look. Such
|
|
265
|
+
a page needs `style-src-attr 'unsafe-inline'` (or `'unsafe-inline'` in `style-src`). The values are the
|
|
266
|
+
cascade's, sanitized: no `url()`, no escapes, no property outside the list.
|
|
267
|
+
|
|
268
|
+
## Security
|
|
269
|
+
|
|
270
|
+
What `mail.parse` guarantees, whatever the email:
|
|
271
|
+
|
|
272
|
+
- **Nothing runs.** No script, handler, `javascript:` or `data:` link, SVG, form or iframe survives; the
|
|
273
|
+
tree has no way to hold one (each tag's attributes are a fixed list, written as literal keys), and
|
|
274
|
+
sinter's runtime checks every URL it sets once more.
|
|
275
|
+
- **Nothing loads without your consent.** Remote images only under `'allow'` or through your proxy; no
|
|
276
|
+
CSS `url()`, `@import` or `@font-face`; no other element that loads.
|
|
277
|
+
- **Nothing reaches outside the email's box.** No `position` or negative margins; no stylesheet, so no
|
|
278
|
+
rule of the email applies to the page; no classes; ids only as in-email link targets, prefixed.
|
|
279
|
+
- **Bounded work.** Linear parsing, nesting bounded, a budget on selector matching (2 million steps) and
|
|
280
|
+
at most 10,000 style rules per email; a plain-text body makes at most 2,000 links, the rest stays text. A
|
|
281
|
+
hostile email of a megabyte parses in well under a second.
|
|
282
|
+
|
|
283
|
+
Rendering each body of a message on its own (never joining bodies into one HTML string) keeps PGP/MIME
|
|
284
|
+
open for later (EFAIL's direct exfiltration needs joined parts); reading MIME is not part of the library
|
|
285
|
+
yet.
|
|
286
|
+
|
|
287
|
+
## Limits
|
|
288
|
+
|
|
289
|
+
- Only the email's own styles and the browser's: no `:hover`, no animation, no web fonts, no background
|
|
290
|
+
images.
|
|
291
|
+
- `@media` is decided at parse time, for one width (`media`), not as the reader resizes. Only the colour
|
|
292
|
+
scheme follows the page, and only for colours (`light-dark()`).
|
|
293
|
+
- Quirks mode is not followed: class names match case-sensitively and unitless lengths are dropped.
|
|
294
|
+
- The parser's size: about 32 kB gzip with the cascade, most of it the HTML standard's entity table and
|
|
295
|
+
tree construction. A server that sends the tree ships none of it.
|
|
296
|
+
- A very large email may exceed sinter's budget of components expanded at build time (10,000): it then
|
|
297
|
+
renders in the browser (SN536).
|
|
298
|
+
- Tested in Chromium; Firefox and Safari are not yet part of the tests.
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Rendering faster: two ideas, measured
|
|
2
|
+
|
|
3
|
+
Status: built: `<mail-body>` renders a body that `mail.progressive` numbered progressively, in steps ([the
|
|
4
|
+
guide](../mail.md#long-messages-mailprogressivebody)), on sinter's #77 and #78. Measured against sinter `main` built
|
|
5
|
+
from source, not a release. Chromium (Playwright's headless build), the 2,012-element generated newsletter of
|
|
6
|
+
`test/app.ts`, served as a tree from the API; medians of 11 to 15 interleaved runs; times from the API's answer. The
|
|
7
|
+
sections below are in the order the work went: the first version rendered in two phases, as its own component.
|
|
8
|
+
|
|
9
|
+
## Where the time goes
|
|
10
|
+
|
|
11
|
+
A trace of today's render: about 15 to 20 ms after the answer before rendering starts (the resource and
|
|
12
|
+
its JSON), then **one 44 ms task of script**, then 4 ms style, 7 ms layout and 3 ms paint. Script is
|
|
13
|
+
where the time is.
|
|
14
|
+
|
|
15
|
+
## Idea 2, batched style writes: not worth it
|
|
16
|
+
|
|
17
|
+
The idea: write each element's styles as one declaration block (`style.cssText`), not a `setProperty`
|
|
18
|
+
per property, "30 to 80k calls down to 2k".
|
|
19
|
+
|
|
20
|
+
- **The calls are fewer than assumed.** The render makes 8,448 `setProperty` calls for 1,743 styled
|
|
21
|
+
elements (4.8 each). sinter's e56b2a2 (a first write skips unset entries) already removed the rest.
|
|
22
|
+
- **A call is cheap.** 2,000 fresh elements: 5 properties take 1.9 ms with `setProperty` and 2.2 ms
|
|
23
|
+
with `cssText`. 10 properties take 3.9 and 4.7 ms. One block is slower, not faster: Blink parses it
|
|
24
|
+
whole, and the string has to be built first. All the render's style writes are about 2 to 3 ms of 70.
|
|
25
|
+
(A sampling profile showed 10 ms in the style writer. That was profiler overhead.)
|
|
26
|
+
- **Prototyped and measured anyway** (`bench/sinter-batched-style.diff`, in sinter's `W.g`): 67.2 ms
|
|
27
|
+
without, 68.9 ms with, which is noise. The output was identical.
|
|
28
|
+
- CSP was never the obstacle: `style.cssText` is CSSOM, which `style-src 'self'` allows, as it allows
|
|
29
|
+
`setProperty`. The real carve-out would be injection. A value that `setProperty` rejects alone
|
|
30
|
+
(`red; position: fixed`, `red !important`, an unclosed `(` or quote, a comment) changes the block
|
|
31
|
+
around it. The prototype has a check for that (`declSafe`), which is cost the batching cannot pay
|
|
32
|
+
back.
|
|
33
|
+
|
|
34
|
+
Dropped. Caching a string per shared style object would not help either: the browser still parses the
|
|
35
|
+
string for each element.
|
|
36
|
+
|
|
37
|
+
## Idea 1, rendering incrementally: worth it for long messages
|
|
38
|
+
|
|
39
|
+
The prototype changes sinter-mail only, with no change to sinter:
|
|
40
|
+
|
|
41
|
+
- `mail.progressive(body, head = 200)` numbers the nodes in document order: `n` on each node, and `z`
|
|
42
|
+
on an element, the last number in its subtree. It also sets `body.head`. It is opt-in, so a tree
|
|
43
|
+
without it renders as before. A `file:` email folded at build time stays whole.
|
|
44
|
+
- The generated components take a `limit` prop. A loop filters `n < limit` only on an element the cut
|
|
45
|
+
passes through (`z >= limit`). Every other element gets the same array, and its children get the
|
|
46
|
+
constant `1e9`.
|
|
47
|
+
- `<mail-body-progressive>` has a script (`<mail-body>` does not, and stays foldable). After the first frame has painted (`requestAnimationFrame`, then a
|
|
48
|
+
task), it lifts the limit. The rows already rendered are kept: the objects are the same, and rows
|
|
49
|
+
match by item.
|
|
50
|
+
|
|
51
|
+
| (ms) | first paint of the email | all rendered | longest frame gap |
|
|
52
|
+
| --- | --- | --- | --- |
|
|
53
|
+
| today | 103.4 | 72.9 | 50 |
|
|
54
|
+
| progressive, two phases (200 nodes, then the rest) | **49.7** | 93.1 | 50 |
|
|
55
|
+
| progressive, 1,000-node steps | 48.4 | 244.1 | 67 |
|
|
56
|
+
|
|
57
|
+
The final DOM is identical in every variant. In the trace, the first phase is one 10 ms task, and the
|
|
58
|
+
email's top paints about 42 ms sooner. The second phase is one 48 ms task, against 44 ms for the whole
|
|
59
|
+
email in one go.
|
|
60
|
+
|
|
61
|
+
What it costs:
|
|
62
|
+
|
|
63
|
+
- **About 20 ms more in total** (+28%): the first phase's own task, a second style and layout pass, and
|
|
64
|
+
the second phase walking the cut path again.
|
|
65
|
+
- **The remaining block is as long as today.** The second phase still blocks input for about 48 ms.
|
|
66
|
+
Splitting it does not work in this design. Every list already rendered reads `limit`, so sinter's
|
|
67
|
+
dependency paths reach all of them, and each step re-evaluates and reconciles every list on the page.
|
|
68
|
+
Steps start at 15 ms and climb to 87 ms, about 3× the total. That growth also comes from
|
|
69
|
+
`<sn-component use>`. It passes a new props object per evaluation, and `toggle()` then force-walks the
|
|
70
|
+
case's whole subtree. A shallow comparison stops the growth (`bench/sinter-shallow-props-unsafe.diff`:
|
|
71
|
+
steps level at about 27 ms) but is **not correct**. sinter's `anchors.test` and `wrapper-fuzz.test`
|
|
72
|
+
fail, because an in-place change under a prop reaches the case's row only through that forced walk.
|
|
73
|
+
- **The JSON is 12% bigger** (411 kB to 460 kB) when the API numbers the tree. Numbering in the browser
|
|
74
|
+
instead is about one walk.
|
|
75
|
+
- **A page that uses it ships JavaScript.** The script is why the progressive path is its own component:
|
|
76
|
+
`<mail-body>` has none, and a static page with it still folds with no JavaScript.
|
|
77
|
+
- Emails under `head` nodes are not affected. The corpus emails are all smaller than that.
|
|
78
|
+
|
|
79
|
+
## For sinter in general
|
|
80
|
+
|
|
81
|
+
The win, first content in about half the time, is not specific to email. Any long list or deep tree
|
|
82
|
+
rendered from one answer has it. In sinter, though, the right place is the runtime, not data:
|
|
83
|
+
|
|
84
|
+
- **A render budget in `reconcile`/`instantiate`.** Create rows until a budget is spent (rows, or about
|
|
85
|
+
8 ms), then queue the rest in document order and continue in later tasks, after a paint. There is no
|
|
86
|
+
limit for every list to read, so nothing already rendered is walked again. Total cost stays near
|
|
87
|
+
today's, every task stays short (input is never blocked for long), and no component, prop or script
|
|
88
|
+
changes. The work is a placeholder row (a node that holds its place, matched and moved like a row)
|
|
89
|
+
and the cases where a placeholder's list changes, or its parent row moves or goes, before the
|
|
90
|
+
placeholder is filled. That is where the effort and the risk are.
|
|
91
|
+
- **Tracing dependency paths through `<sn-component use>` props** would make the shallow comparison
|
|
92
|
+
above correct, and would save every recursive component tree a forced re-walk on each render, with or
|
|
93
|
+
without progressive rendering.
|
|
94
|
+
|
|
95
|
+
## Streaming the tree as it arrives: not now
|
|
96
|
+
|
|
97
|
+
The idea is for the API (or a parser in the browser) to stream the tree into a binding that renders while
|
|
98
|
+
the answer arrives, so that receiving and rendering interleave. `bench/network.mjs` measures the newsletter
|
|
99
|
+
gzipped, as a server sends it, under Chromium's throttling (medians of 3):
|
|
100
|
+
|
|
101
|
+
| | first byte | body transfer | page JS arrives after the body | first paint after both |
|
|
102
|
+
| --- | --- | --- | --- | --- |
|
|
103
|
+
| no throttling | 4 ms | 1 ms | 1 ms | 97 ms |
|
|
104
|
+
| fast 4G (9 Mbps, 85 ms RTT) | 86 ms | 9 ms | 319 ms | 84 ms |
|
|
105
|
+
| slow 4G (1.6 Mbps, 150 ms RTT) | 154 ms | 48 ms | 1,784 ms | 84 ms |
|
|
106
|
+
|
|
107
|
+
- **What streaming could save is the body's transfer.** The time spent rendering moves to before the
|
|
108
|
+
last byte, so the win is at most the transfer time (and the server's parse, if it streams that too, about
|
|
109
|
+
50 ms). The generated tree gzips from 402 kB to 5.3 kB, so its transfer is 1 to 48 ms. A real email
|
|
110
|
+
compresses less (a large one perhaps 30 to 60 kB gzip, about 50 to 300 ms on slow 4G), so a large email
|
|
111
|
+
on a slow network is where it would matter.
|
|
112
|
+
- **The answer is not on the critical path of a first visit.** It arrives long before the page's
|
|
113
|
+
JavaScript. In an open app (the next message, scripts cached), the critical path is a round trip
|
|
114
|
+
(85 to 150 ms), the transfer, then the render. sinter's `embed` layer removes the round trip for the
|
|
115
|
+
first message, and progressive rendering (`mail.progressive`) puts the first paint about 10 ms after the answer.
|
|
116
|
+
- **sinter cannot render a growing tree cheaply.** A streamed tree grows at its open spine, so each chunk
|
|
117
|
+
changes the root's descendants: in place (an append to `children`) or as new objects along the spine.
|
|
118
|
+
Either way the recursive components above it render their subtrees again, forced. That is correct:
|
|
119
|
+
a change inside a prop's value must reach the bindings that read it, and sinter's #77 keeps exactly that
|
|
120
|
+
case forced. So each chunk would cost about as much as what is already rendered, which the stepped
|
|
121
|
+
limit above measures (400-node steps: 264 ms in all, against 70 ms in one task). A cheap streamed tree
|
|
122
|
+
needs the runtime to append rows to a list without walking what is already rendered (a stream-aware
|
|
123
|
+
`data-sn-for`, or the render budget above), and the tree delivered as appends to lists (each node's
|
|
124
|
+
children as their own stream). That is a new runtime primitive, not a binding.
|
|
125
|
+
- A flat list (search results, a message list) streams well today: an append reconciles the list (a key
|
|
126
|
+
per item), and only the new rows render. That, not email, is where a streamed resource would be the
|
|
127
|
+
smaller change.
|
|
128
|
+
|
|
129
|
+
Not spiked: the measurements bound the gain (the body's transfer) below what embedding and the progressive
|
|
130
|
+
component already give. The work is in sinter's runtime. It would be worth revisiting with a real corpus of
|
|
131
|
+
large emails and an app's own latency profile.
|
|
132
|
+
|
|
133
|
+
## Steps: what shipped
|
|
134
|
+
|
|
135
|
+
The two-phase render left one task of about 48 ms after the first paint (150 to 240 ms on a phone): input
|
|
136
|
+
waits for it. Stepping the limit cost about 3 times the total, since every list read the limit. Two designs were
|
|
137
|
+
spiked against sinter with #77:
|
|
138
|
+
|
|
139
|
+
- **Identity** (`bench/sinter-identity-spike.diff`): the tree grows in place and the runtime is told which
|
|
140
|
+
objects changed (an index from objects to the components holding them). Steps of 3 to 10 ms, +331 B gzip on the
|
|
141
|
+
core, +0.7 to 2 ms on a recursive tree's first render. It needs an API: a component script can only say that a
|
|
142
|
+
top-level state field changed, so it would need `this.changed(obj)`.
|
|
143
|
+
- **Copies** (`bench/sinter-copy-spike.diff`, `bench/sinter-mail-copy-spike.diff`): each step is a new tree, a
|
|
144
|
+
copy of the elements down to the step's end, the rest shared; rows are keyed by the nodes' numbers, so a copy
|
|
145
|
+
keeps its row. In sinter (#78) a replaced item or props render down to the components whose props did not change,
|
|
146
|
+
instead of everything below. No API, +44 B gzip, first renders and js-framework-benchmark unchanged.
|
|
147
|
+
|
|
148
|
+
Copies shipped. `<mail-body>` has two branches: a body that is not numbered renders as before (a static page's is
|
|
149
|
+
decided at build time and ships no script); a numbered one renders `body.first`, then the trees a small internal
|
|
150
|
+
component (`mail-steps`, the only one with a script) emits after each paint, 400 nodes further each time.
|
|
151
|
+
|
|
152
|
+
The first version of the steps took twice as long as two phases: each step re-rendered most of what was on the
|
|
153
|
+
page. Two leaks in sinter caused that, fixed in #78 too: the tree slots' fills a component passes down are an
|
|
154
|
+
object built at each evaluation, so a component that a tree slot reaches never had equal props; and a component
|
|
155
|
+
used inside itself renders through a computed list of its props, whose rule (kept rows render forced) overrode
|
|
156
|
+
the props comparison. With those fixed a step walks a few hundred rows instead of every row on the page. Steps
|
|
157
|
+
are then sized by time (about 12 ms of script each, the size of the next following how long the last one took)
|
|
158
|
+
and follow each other without waiting a frame (a message-channel task, so input and paint still come first).
|
|
159
|
+
|
|
160
|
+
One interleaved run, 25 page loads each:
|
|
161
|
+
|
|
162
|
+
| 2,012 elements | email starts showing | whole email in place | longest frame gap |
|
|
163
|
+
| --- | --- | --- | --- |
|
|
164
|
+
| whole, one task | 107.6 ms | 81.2 ms | 66.7 ms |
|
|
165
|
+
| two phases (the rest in one task) | 51.2 ms | 116.0 ms | 33.3 ms |
|
|
166
|
+
| **steps (shipped)** | **53.1 ms** | **122.4 ms** | **16.8 ms** |
|
|
167
|
+
|
|
168
|
+
Earlier runs, for the history: 400-node steps, one per frame, before the leaks were fixed: ~180-200 ms in place,
|
|
169
|
+
steps of 10-20 ms; the limit in 400-node steps (#77): ~264 ms, steps of up to 31 ms and growing.
|
|
170
|
+
|
|
171
|
+
The final DOM equals a whole render in every variant. What it changes in sinter: a computed list's kept rows,
|
|
172
|
+
which rendered everything below them on every evaluation in case an item changed in place unseen, now do so only
|
|
173
|
+
when a change inside a value the list reads reaches it (sinter's changelog).
|
|
174
|
+
|
|
175
|
+
## Running the benches
|
|
176
|
+
|
|
177
|
+
`node --experimental-strip-types bench/prog.mjs [runs] [elements] [head] gen '<variants>'` (variants:
|
|
178
|
+
`plain:` or `prog:step=N`, comma-separated). `bench/trace.mjs prog|plain` prints the main thread's tasks.
|
|
179
|
+
`bench/grow.mjs` grows a tree in place (the identity spike). `bench/network.mjs [elements] [runs]` splits the wait under throttling. `bench/micro.mjs` compares `setProperty` with `cssText`. `bench/count.mjs` counts the style calls. They
|
|
180
|
+
need sinter built beside this package (`../sinter`, `npm run build`).
|