@tiavision/sinter-mail 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 +137 -2
- package/docs/mail.md +267 -0
- package/docs/proposals/progressive-rendering.md +180 -0
- package/docs/proposals/sinter-mail.md +520 -0
- package/llms.txt +20 -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 +270 -0
- package/sinter/css/media.ts +251 -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 +647 -0
- package/sinter/engine.ts +6 -0
- package/sinter/index.ts +5 -0
- package/sinter/parse.ts +355 -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 +135 -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,138 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tiavision/sinter-mail
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Email for [sinter](https://github.com/tiaforge/sinter): a parser, `mail.parse`, that turns an email's HTML
|
|
4
|
+
body into a tree, `mail.plain` for plain-text bodies, and a component, `<mail-body>`, that renders the tree
|
|
5
|
+
as part of the page, without an iframe. An email in a file is plain HTML at build time; an email from an
|
|
6
|
+
API is parsed in the browser, or on the server.
|
|
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
|
+
**Using it:** [docs/mail.md](docs/mail.md). **Why it is built this way:**
|
|
16
|
+
[docs/proposals/sinter-mail.md](docs/proposals/sinter-mail.md).
|
|
17
|
+
|
|
18
|
+
The rest of this file is for working on the library: what each part is, why it is where it is, and how it
|
|
19
|
+
is checked.
|
|
20
|
+
|
|
21
|
+
## Status
|
|
22
|
+
|
|
23
|
+
Version 0.1. It needs sinter 0.20.0 or later, the first release with the changes made for this library
|
|
24
|
+
(tiaforge/sinter#76, #77 and #78); `sinter check` says so (SN537) when an app has an older one.
|
|
25
|
+
|
|
26
|
+
## Releasing
|
|
27
|
+
|
|
28
|
+
From GitHub's UI: Actions → Release → Run workflow (on `main`) → the version. The [Release
|
|
29
|
+
workflow](.github/workflows/release.yml) sets package.json to it and commits on a temporary branch, checks
|
|
30
|
+
that the package builds against a sinter from npm, runs CI on that commit, and only then tags it `v<version>`
|
|
31
|
+
and publishes to npm with a provenance attestation; then it moves `main` to the release commit, makes the
|
|
32
|
+
GitHub release and deletes the branch. A run that fails before the tag leaves nothing to clean up. A pre-release
|
|
33
|
+
(`0.2.0-rc.1`) goes out under the `next` dist-tag. Publishing a GitHub release for an existing tag
|
|
34
|
+
`v<the version in package.json>` runs the same checks and publish.
|
|
35
|
+
|
|
36
|
+
Publishing needs, once:
|
|
37
|
+
|
|
38
|
+
- Before the first release: the `release` environment (Settings → Environments) with the secret `NPM_TOKEN`, a
|
|
39
|
+
granular npm token that may publish under `@tiavision`. Trusted publishing can only be set up for a package
|
|
40
|
+
that exists, so the first publish uses it.
|
|
41
|
+
- After it: `@tiavision/sinter-mail` → Settings → Trusted publishing → GitHub Actions: `tiavision/sinter-mail`,
|
|
42
|
+
workflow `release.yml`, environment `release`, allowed to publish (the workflow runs `npm publish`; a
|
|
43
|
+
publisher that may only stage is refused, with a 404). Then delete `NPM_TOKEN` and revoke the token: later
|
|
44
|
+
releases need no secret.
|
|
45
|
+
|
|
46
|
+
## The package
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
package.json "sinter": "./sinter", exports ".", "./parser" (the lazy part)
|
|
50
|
+
sinter/
|
|
51
|
+
components/
|
|
52
|
+
mail-body.html public: one body, and the slots an app fills (`link`, `image`)
|
|
53
|
+
internal/ generated from tags.ts: one component per tag, the dispatch, the table, the
|
|
54
|
+
steps of a progressive render (mail-steps.ts beside it)
|
|
55
|
+
sinter.types.ts the tree's types: what apps and the components name
|
|
56
|
+
tags.ts the tag table: tags, their attributes, the properties each binds, what is dropped
|
|
57
|
+
parse.ts mail.parse: options, the tree from the raw document and the resolved styles
|
|
58
|
+
engine.ts what mail.parse runs, behind `@tiavision/sinter-mail/parser`: parser and cascade
|
|
59
|
+
parser/ the HTML parser: the standard's tokenizer and tree construction; entities.ts generated
|
|
60
|
+
css/ the cascade: tokenizer, selectors, media, values, legacy hints
|
|
61
|
+
raw.ts the raw tree between the parser and the cascade
|
|
62
|
+
plain.ts, autolink.ts mail.plain, with GFM's autolinks
|
|
63
|
+
tree.ts mail.text, mail.links, mail.progressive
|
|
64
|
+
sinter.helpers.ts the helpers, re-exported by the entry
|
|
65
|
+
index.ts the entry
|
|
66
|
+
scripts/
|
|
67
|
+
build-components.mjs writes sinter/components/internal/ from tags.ts; --check
|
|
68
|
+
build-entities.mjs writes sinter/parser/entities.ts; --check
|
|
69
|
+
fixtures/ pages for `sinter check`, and trees as JSON
|
|
70
|
+
test/ the tests (vitest), test/corpus/ the emails they read
|
|
71
|
+
docs/ the guide and the proposals
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
### Why it is built this way
|
|
75
|
+
|
|
76
|
+
- **The email is a tree, rendered by templates.** sinter never creates HTML from data, so an email cannot
|
|
77
|
+
be `innerHTML`. `mail.parse` builds a tree, and each element of it is rendered by a generated component
|
|
78
|
+
whose root is that tag: its attributes and styles are bindings with literal names, which sinter checks
|
|
79
|
+
at build time and sets with its checked writers at runtime.
|
|
80
|
+
- **The parser is the HTML standard's.** The tree must be the one the browser would build from the same
|
|
81
|
+
HTML; otherwise a page built at build time would be reparsed into another tree, and an email would look
|
|
82
|
+
different from what its sender tested. `test/parser.test.ts` compares it with parse5 on targeted cases and
|
|
83
|
+
thousands of random documents.
|
|
84
|
+
- **Styles are resolved, not shipped.** A stylesheet from data would be a sink sinter does not have. The
|
|
85
|
+
cascade runs at parse time instead and every element carries its own declarations. Email is where that
|
|
86
|
+
costs least: email clients already drop most of what this drops.
|
|
87
|
+
- **One table for every list.** `sinter/tags.ts` is the only place that says what an email may contain;
|
|
88
|
+
the parser's allowlist, the tree's types and the components come from it, and
|
|
89
|
+
`test/components.test.ts` fails when they disagree.
|
|
90
|
+
- **The table is one component.** The HTML parser moves a component's tag written inside a `<table>` out
|
|
91
|
+
of it, so a table's caption, columns, sections, rows and cells are literal in `mail-table`; cell content
|
|
92
|
+
goes through `mail-node` as everywhere else.
|
|
93
|
+
- **No whitespace between tags** in the generated components: whitespace in a component is text in the
|
|
94
|
+
page, once per row, and would show in tables and inline content.
|
|
95
|
+
- **Pure helpers.** `mail.parse`, `mail.plain`, `mail.text` and `mail.links` use only the language's
|
|
96
|
+
globals and `URL`, and no module keeps state between calls, so sinter runs them at build time over a
|
|
97
|
+
`file:` email. `mail.parse` keeps its trees with sinter's `memo()`; its options are normalized to
|
|
98
|
+
primitives first, so equal policies share a tree.
|
|
99
|
+
- **The parser is behind its own specifier.** `parse.ts` imports the parser and the cascade as
|
|
100
|
+
`@tiavision/sinter-mail/parser`, so an app that lists the package in `sinter({ lazy })` loads them on
|
|
101
|
+
demand; `plain.ts` and `tree.ts` import neither and stay ordinary helpers.
|
|
102
|
+
|
|
103
|
+
## Changing it
|
|
104
|
+
|
|
105
|
+
- **A tag:** add it to `Tag` in `sinter/sinter.types.ts` and to `TAGS` in `sinter/tags.ts` (its attributes
|
|
106
|
+
and the property groups it binds), then `npm run build:components`. A tag that only makes sense inside a
|
|
107
|
+
table is `inTable` and goes into the table component's structure (`scripts/build-components.mjs`).
|
|
108
|
+
- **An attribute:** add it to `Attrs`, to the tag in `TAGS`, and to `attribute()` in `sinter/parse.ts`, which
|
|
109
|
+
checks its value.
|
|
110
|
+
- **A property:** add it to `Property` and to a group in `sinter/tags.ts`, give it a grammar in
|
|
111
|
+
`sinter/css/values.ts`, then `npm run build:components`. Never one that positions, loads or escapes the
|
|
112
|
+
box (docs/mail.md, Security).
|
|
113
|
+
- **The entity table:** `npm run build:entities` after updating `character-entities`.
|
|
114
|
+
|
|
115
|
+
## Checking and testing
|
|
116
|
+
|
|
117
|
+
```sh
|
|
118
|
+
npm ci
|
|
119
|
+
npx sinter check # the fixture pages: compiled, type-checked, the library's rules
|
|
120
|
+
npm run typecheck
|
|
121
|
+
npm test # vitest: 200 tests, Chromium included
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
| Test | What it covers |
|
|
125
|
+
| --- | --- |
|
|
126
|
+
| `test/parser.test.ts` | the parser against parse5: targeted cases, seeded random documents, the depth bound, hostile timings, the entity table up to date, purity |
|
|
127
|
+
| `test/css.test.ts` | tokenizer, values and shorthands, selectors and specificity, media, the cascade's order, legacy hints, hostile stylesheets |
|
|
128
|
+
| `test/css.browser.test.ts` | the cascade against Chromium's computed styles on email-like documents, at both widths |
|
|
129
|
+
| `test/parse.test.ts` | mail.parse: what is kept, links, ids, images, options, the cache, the corpus's invariants, 35 attacks |
|
|
130
|
+
| `test/plain.test.ts`, `test/tree.test.ts` | mail.plain and autolinks, mail.text and mail.links |
|
|
131
|
+
| `test/components.test.ts` | the tag table, the types, the dispatch and the files agree; the generated files are current |
|
|
132
|
+
| `test/check.test.ts` | `sinter check --strict` over the fixtures: no error, no warning |
|
|
133
|
+
| `test/static.test.ts` | an email folded at build time: no JavaScript, the HTML is the tree |
|
|
134
|
+
| `test/browser.test.ts` | Chromium under `script-src 'self'; style-src 'self'; require-trusted-types-for 'script'`: no violation, the styles applied; the CSP a folded email needs; render time and size |
|
|
135
|
+
|
|
136
|
+
## License
|
|
137
|
+
|
|
138
|
+
MIT
|
package/docs/mail.md
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
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), and `images.origins`: every
|
|
85
|
+
remote image's origin, sorted, for a "show images from …" control.
|
|
86
|
+
|
|
87
|
+
### What is kept
|
|
88
|
+
|
|
89
|
+
- **71 tags**: text, lists, tables, headings, links, images, and the legacy ones email still uses
|
|
90
|
+
(`<font>`, `<center>`). `<script>`, `<style>` (read for its rules, then dropped), forms and their controls,
|
|
91
|
+
iframes, objects, media, SVG and MathML are dropped with their content. An unknown element (`<o:p>`, a
|
|
92
|
+
custom tag) is a `span`, as the browser renders one.
|
|
93
|
+
- **Each tag's own attributes**, values checked: `href` on links, `src`, `alt`, `width`, `height` on images,
|
|
94
|
+
`colspan`, `rowspan` on cells, `dir`, `lang`, `title` everywhere. No `class`, no `style` attribute (its
|
|
95
|
+
declarations are in the element's `style`), no handler.
|
|
96
|
+
- **Links**: `http:`, `https:`, `mailto:` and `tel:`, normalized; anything else loses its `href`. Every link
|
|
97
|
+
opens in a new tab with `rel="noopener noreferrer"`. A `#fragment` link keeps its `href` only when the
|
|
98
|
+
email has its target, which keeps its id, written `mail-…`.
|
|
99
|
+
- **Images**: as the options say. `data:` images only as base64 PNG, JPEG, GIF, WebP or AVIF, never SVG.
|
|
100
|
+
- **The structure the browser would build**: the parser follows the HTML standard's tree construction
|
|
101
|
+
(implied end tags, tables, misnested formatting), so the tree is the browser's own, and a page built at
|
|
102
|
+
build time is not reparsed into another one. Nesting deeper than 256 elements is flattened.
|
|
103
|
+
|
|
104
|
+
### Styles
|
|
105
|
+
|
|
106
|
+
There is no stylesheet. `mail.parse` resolves each element's styles, as a browser's cascade would:
|
|
107
|
+
|
|
108
|
+
1. its legacy attributes (`bgcolor`, `width`, `align`, `valign`, `border`, `cellpadding`, `cellspacing`,
|
|
109
|
+
`<font color face size>`, `<center>`, `<body text>`), lowest;
|
|
110
|
+
2. the email's `<style>` rules that match it, by specificity and order;
|
|
111
|
+
3. its `style` attribute; `!important` as CSS says.
|
|
112
|
+
|
|
113
|
+
It keeps 60 properties (colours, fonts, text, box, borders, table layout, display, float), each
|
|
114
|
+
value re-serialized. Selectors with `:hover`, `:focus`, `::before` and the like never match; `@media` rules
|
|
115
|
+
are evaluated at the `media` option's width; `@import`, `@font-face`, `@keyframes` and `@supports` are
|
|
116
|
+
dropped. Never kept: `position`, `z-index`, `transform`, `url()` in any value (background images
|
|
117
|
+
included), `var()`, `calc()`, negative margins.
|
|
118
|
+
|
|
119
|
+
`<mail-body>` writes each element's styles inline. So:
|
|
120
|
+
|
|
121
|
+
- **The email's styles win over the page's.** An inline style beats every normal rule of your stylesheets,
|
|
122
|
+
and the legacy attributes are inline too, so `td { padding: 1rem }` in your CSS does not undo
|
|
123
|
+
`cellpadding="0"`.
|
|
124
|
+
- **The page fills in what the email does not set.** An email with no font takes the page's font, its
|
|
125
|
+
links your link colour. A plain email looks like part of the app. A mail client shows such an email in
|
|
126
|
+
its own default font (Gmail and Outlook use a sans-serif); to do the same, give the root one:
|
|
127
|
+
`.mail { font-family: Arial, sans-serif; }`.
|
|
128
|
+
- **Where your page still wins**: a rule with `!important`, and what the email takes from browser defaults
|
|
129
|
+
when your CSS resets them (a reset that makes images `display: block`, headings unsized, lists unmarked).
|
|
130
|
+
For newsletters exactly as sent, restore the defaults under `.mail` in your stylesheet.
|
|
131
|
+
- **The email stays in its box.** The root is `display: flow-root`, so floats and margins do not escape it.
|
|
132
|
+
A wide newsletter (600 px of tables) is as wide as it is: put `<mail-body>` in a box with
|
|
133
|
+
`overflow-x: auto` for narrow screens.
|
|
134
|
+
|
|
135
|
+
Quotes and signatures that `mail.plain` finds carry the classes `mail-quote` and `mail-signature`, for
|
|
136
|
+
your styles (`.mail-signature { opacity: .7 }`).
|
|
137
|
+
|
|
138
|
+
## Images and a proxy
|
|
139
|
+
|
|
140
|
+
Remote images are left out by default: a tracking pixel never loads, and a left-out image keeps its box
|
|
141
|
+
(`width`, `height`, `alt`), so the layout does not move when images are shown. `body.images.origins` lists
|
|
142
|
+
the origins the email would load from.
|
|
143
|
+
|
|
144
|
+
With a proxy, every remote image goes through your server and the sender never sees the reader's
|
|
145
|
+
address, browser, or when the email was opened:
|
|
146
|
+
|
|
147
|
+
```html
|
|
148
|
+
<article data-sn-let="{ body: mail.parse(msg.html, {
|
|
149
|
+
images: 'proxy', proxy: '/api/email/proxy-image?url={url}',
|
|
150
|
+
cid: `/api/email/proxy-image?uid=${msg.uid}&cid={cid}` }) }">
|
|
151
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
152
|
+
</article>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
What the proxy does is yours: which origins it fetches (an allowlist the reader edits), checking the
|
|
156
|
+
address (no private or loopback targets, no redirects to them), serving only what the bytes show is an
|
|
157
|
+
image, with `X-Content-Type-Options: nosniff`, fetching when the email arrives so opening it is not
|
|
158
|
+
tracked. A proxy that answers a refused image with a transparent pixel shows an empty box; once the
|
|
159
|
+
reader allows an origin, put a version in the template (`'/img?v=3&url={url}'`) so the browser does not
|
|
160
|
+
keep the pixel.
|
|
161
|
+
|
|
162
|
+
The tree never rewrites the email's HTML, so a reply or a forward quotes the original image URLs.
|
|
163
|
+
|
|
164
|
+
## Plain text: `mail.plain(text, options)`
|
|
165
|
+
|
|
166
|
+
The same tree from a `text/plain` body: paragraphs with their line breaks (`white-space: pre-wrap`),
|
|
167
|
+
URLs, `www.` addresses and email addresses as links (GFM's rules), `>` quotes as nested blockquotes
|
|
168
|
+
(`mail-quote`), and everything after a `-- ` line as the signature (`mail-signature`).
|
|
169
|
+
|
|
170
|
+
| Option | |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| `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` |
|
|
173
|
+
| `delsp: true` | with `flowed`: `DelSp=yes`, the space before a soft break is removed too |
|
|
174
|
+
|
|
175
|
+
## `mail.text(node)` and `mail.links(body)`
|
|
176
|
+
|
|
177
|
+
`mail.text` is the text of a body or node, blocks separated by newlines, hidden content left out: for
|
|
178
|
+
previews and search snippets. `mail.links` is every link with its text, in order.
|
|
179
|
+
|
|
180
|
+
## Long messages: `mail.progressive(body)`
|
|
181
|
+
|
|
182
|
+
A long email (a newsletter of 2,000 elements) takes one task of about 45 ms to render, and nothing of it
|
|
183
|
+
shows until that task ends; on a phone, several times that. Number the body with `mail.progressive`, and
|
|
184
|
+
`<mail-body>` renders it progressively: the first part in the task that receives the body, the rest in steps
|
|
185
|
+
after the browser has painted that, a task each.
|
|
186
|
+
|
|
187
|
+
```html
|
|
188
|
+
<sn-resource name="message" src="/api/messages/{$url.id}"></sn-resource>
|
|
189
|
+
<mail-body data-sn-prop="{ body: mail.progressive(message.tree) }"></mail-body>
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`mail.progressive(body, head = 200)` numbers the nodes in document order and sets `body.head` (the first 200
|
|
193
|
+
nodes render first) and `body.first` (the body up to there). Run it in the page, as above, or on the server
|
|
194
|
+
before the tree is sent; there, `body.first` repeats the first nodes in the JSON (about 18% more for the
|
|
195
|
+
newsletter, less after gzip). A body that is not numbered renders whole in one task, as before, so short
|
|
196
|
+
emails are not affected.
|
|
197
|
+
|
|
198
|
+
Measured on the 2,000-element newsletter (Chromium, [measurements](proposals/progressive-rendering.md)): the
|
|
199
|
+
email starts to show after about 50 ms instead of about 100; the rest renders in steps of 5 to 15 ms, each
|
|
200
|
+
sized by how long the one before took (about 12 ms of script, so a step fits in a frame on any device), with
|
|
201
|
+
input and paint between them; the whole email is in place about 6% later than when the rest renders in one
|
|
202
|
+
task, and no frame is dropped.
|
|
203
|
+
|
|
204
|
+
- **Static pages are not affected.** The steps need a script, which only the progressive branch of
|
|
205
|
+
`<mail-body>` has: an email from a file is not numbered, the build decides that branch away, and the page
|
|
206
|
+
ships no JavaScript. Calling `mail.progressive` on a static page's body is `SN322` (the page would ship
|
|
207
|
+
JavaScript).
|
|
208
|
+
- **One element more.** A progressive render ends with a hidden empty element (`<i hidden>`, the component
|
|
209
|
+
that runs the steps) at the end of the email: a selector like `:last-child` in the app's CSS sees it.
|
|
210
|
+
- **The slots work as before.** Fills render in every step.
|
|
211
|
+
|
|
212
|
+
## Changing how links and images look
|
|
213
|
+
|
|
214
|
+
`<mail-body>` has two slots. A fill reads the element as `$slot.node`:
|
|
215
|
+
|
|
216
|
+
```html
|
|
217
|
+
<mail-body data-sn-prop="{ body }">
|
|
218
|
+
<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>
|
|
219
|
+
<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>
|
|
220
|
+
<template data-sn-else><span class="blocked" data-sn-text="$slot.node.attrs.alt ?? 'image'"></span></template>
|
|
221
|
+
</mail-body>
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
`<slot></slot>` in the link's fill is the link's content. A fill that writes the element itself drops its
|
|
225
|
+
styles unless it binds them (`$slot.node.style`).
|
|
226
|
+
|
|
227
|
+
## Content Security Policy
|
|
228
|
+
|
|
229
|
+
An email rendered in the browser (HTML or a tree from an API) needs nothing beyond
|
|
230
|
+
`script-src 'self'; style-src 'self'; require-trusted-types-for 'script'`: styles are set with
|
|
231
|
+
`style.setProperty`, which a policy does not block, and nothing is written as HTML.
|
|
232
|
+
|
|
233
|
+
An email folded at build time (a `file:` email, or a page that renders it in its first frame) has its
|
|
234
|
+
styles in `style` attributes, which `style-src 'self'` blocks: the email then shows without its look. Such
|
|
235
|
+
a page needs `style-src-attr 'unsafe-inline'` (or `'unsafe-inline'` in `style-src`). The values are the
|
|
236
|
+
cascade's, sanitized: no `url()`, no escapes, no property outside the list.
|
|
237
|
+
|
|
238
|
+
## Security
|
|
239
|
+
|
|
240
|
+
What `mail.parse` guarantees, whatever the email:
|
|
241
|
+
|
|
242
|
+
- **Nothing runs.** No script, handler, `javascript:` or `data:` link, SVG, form or iframe survives; the
|
|
243
|
+
tree has no way to hold one (each tag's attributes are a fixed list, written as literal keys), and
|
|
244
|
+
sinter's runtime checks every URL it sets once more.
|
|
245
|
+
- **Nothing loads without your consent.** Remote images only under `'allow'` or through your proxy; no
|
|
246
|
+
CSS `url()`, `@import` or `@font-face`; no other element that loads.
|
|
247
|
+
- **Nothing reaches outside the email's box.** No `position` or negative margins; no stylesheet, so no
|
|
248
|
+
rule of the email applies to the page; no classes; ids only as in-email link targets, prefixed.
|
|
249
|
+
- **Bounded work.** Linear parsing, nesting bounded, a budget on selector matching (2 million steps) and
|
|
250
|
+
at most 10,000 style rules per email; a plain-text body makes at most 2,000 links, the rest stays text. A
|
|
251
|
+
hostile email of a megabyte parses in well under a second.
|
|
252
|
+
|
|
253
|
+
Rendering each body of a message on its own (never joining bodies into one HTML string) keeps PGP/MIME
|
|
254
|
+
open for later (EFAIL's direct exfiltration needs joined parts); reading MIME is not part of the library
|
|
255
|
+
yet.
|
|
256
|
+
|
|
257
|
+
## Limits
|
|
258
|
+
|
|
259
|
+
- Only the email's own styles and the browser's: no `:hover`, no animation, no web fonts, no background
|
|
260
|
+
images.
|
|
261
|
+
- `@media` is decided at parse time, for one width (`media`), not as the reader resizes.
|
|
262
|
+
- Quirks mode is not followed: class names match case-sensitively and unitless lengths are dropped.
|
|
263
|
+
- The parser's size: about 32 kB gzip with the cascade, most of it the HTML standard's entity table and
|
|
264
|
+
tree construction. A server that sends the tree ships none of it.
|
|
265
|
+
- A very large email may exceed sinter's budget of components expanded at build time (10,000): it then
|
|
266
|
+
renders in the browser (SN536).
|
|
267
|
+
- 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`).
|