@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.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +113 -2
  3. package/docs/mail.md +298 -0
  4. package/docs/proposals/progressive-rendering.md +180 -0
  5. package/docs/proposals/sinter-mail.md +520 -0
  6. package/llms.txt +21 -0
  7. package/package.json +65 -4
  8. package/sinter/autolink.ts +98 -0
  9. package/sinter/components/internal/mail-a.html +5 -0
  10. package/sinter/components/internal/mail-abbr.html +5 -0
  11. package/sinter/components/internal/mail-address.html +5 -0
  12. package/sinter/components/internal/mail-article.html +5 -0
  13. package/sinter/components/internal/mail-aside.html +5 -0
  14. package/sinter/components/internal/mail-b.html +5 -0
  15. package/sinter/components/internal/mail-bdi.html +5 -0
  16. package/sinter/components/internal/mail-bdo.html +5 -0
  17. package/sinter/components/internal/mail-blockquote.html +5 -0
  18. package/sinter/components/internal/mail-br.html +5 -0
  19. package/sinter/components/internal/mail-center.html +5 -0
  20. package/sinter/components/internal/mail-cite.html +5 -0
  21. package/sinter/components/internal/mail-code.html +5 -0
  22. package/sinter/components/internal/mail-dd.html +5 -0
  23. package/sinter/components/internal/mail-del.html +5 -0
  24. package/sinter/components/internal/mail-details.html +5 -0
  25. package/sinter/components/internal/mail-dfn.html +5 -0
  26. package/sinter/components/internal/mail-div.html +5 -0
  27. package/sinter/components/internal/mail-dl.html +5 -0
  28. package/sinter/components/internal/mail-dt.html +5 -0
  29. package/sinter/components/internal/mail-em.html +5 -0
  30. package/sinter/components/internal/mail-figcaption.html +5 -0
  31. package/sinter/components/internal/mail-figure.html +5 -0
  32. package/sinter/components/internal/mail-font.html +5 -0
  33. package/sinter/components/internal/mail-footer.html +5 -0
  34. package/sinter/components/internal/mail-h1.html +5 -0
  35. package/sinter/components/internal/mail-h2.html +5 -0
  36. package/sinter/components/internal/mail-h3.html +5 -0
  37. package/sinter/components/internal/mail-h4.html +5 -0
  38. package/sinter/components/internal/mail-h5.html +5 -0
  39. package/sinter/components/internal/mail-h6.html +5 -0
  40. package/sinter/components/internal/mail-header.html +5 -0
  41. package/sinter/components/internal/mail-hr.html +5 -0
  42. package/sinter/components/internal/mail-i.html +5 -0
  43. package/sinter/components/internal/mail-img.html +5 -0
  44. package/sinter/components/internal/mail-ins.html +5 -0
  45. package/sinter/components/internal/mail-kbd.html +5 -0
  46. package/sinter/components/internal/mail-li.html +5 -0
  47. package/sinter/components/internal/mail-main.html +5 -0
  48. package/sinter/components/internal/mail-mark.html +5 -0
  49. package/sinter/components/internal/mail-nav.html +5 -0
  50. package/sinter/components/internal/mail-node.html +5 -0
  51. package/sinter/components/internal/mail-ol.html +5 -0
  52. package/sinter/components/internal/mail-orphan.html +5 -0
  53. package/sinter/components/internal/mail-p.html +5 -0
  54. package/sinter/components/internal/mail-pre.html +5 -0
  55. package/sinter/components/internal/mail-q.html +5 -0
  56. package/sinter/components/internal/mail-s.html +5 -0
  57. package/sinter/components/internal/mail-samp.html +5 -0
  58. package/sinter/components/internal/mail-section.html +5 -0
  59. package/sinter/components/internal/mail-small.html +5 -0
  60. package/sinter/components/internal/mail-span.html +5 -0
  61. package/sinter/components/internal/mail-steps.html +5 -0
  62. package/sinter/components/internal/mail-steps.ts +46 -0
  63. package/sinter/components/internal/mail-strike.html +5 -0
  64. package/sinter/components/internal/mail-strong.html +5 -0
  65. package/sinter/components/internal/mail-sub.html +5 -0
  66. package/sinter/components/internal/mail-summary.html +5 -0
  67. package/sinter/components/internal/mail-sup.html +5 -0
  68. package/sinter/components/internal/mail-table.html +5 -0
  69. package/sinter/components/internal/mail-time.html +5 -0
  70. package/sinter/components/internal/mail-tt.html +5 -0
  71. package/sinter/components/internal/mail-u.html +5 -0
  72. package/sinter/components/internal/mail-ul.html +5 -0
  73. package/sinter/components/internal/mail-var.html +5 -0
  74. package/sinter/components/internal/mail-wbr.html +5 -0
  75. package/sinter/components/mail-body.html +21 -0
  76. package/sinter/css/hints.ts +259 -0
  77. package/sinter/css/index.ts +348 -0
  78. package/sinter/css/media.ts +254 -0
  79. package/sinter/css/parse.ts +124 -0
  80. package/sinter/css/selectors.ts +530 -0
  81. package/sinter/css/tokenize.ts +279 -0
  82. package/sinter/css/values.ts +669 -0
  83. package/sinter/engine.ts +6 -0
  84. package/sinter/index.ts +5 -0
  85. package/sinter/parse.ts +359 -0
  86. package/sinter/parser/entities.ts +22 -0
  87. package/sinter/parser/index.ts +54 -0
  88. package/sinter/parser/tokenizer.ts +275 -0
  89. package/sinter/parser/tree.ts +1265 -0
  90. package/sinter/plain.ts +125 -0
  91. package/sinter/raw.ts +28 -0
  92. package/sinter/sinter.helpers.ts +11 -0
  93. package/sinter/sinter.types.ts +144 -0
  94. package/sinter/tags.ts +169 -0
  95. 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
- # Temporary Holding Version
1
+ # @tiavision/sinter-mail
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`).