@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.
Files changed (95) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +137 -2
  3. package/docs/mail.md +267 -0
  4. package/docs/proposals/progressive-rendering.md +180 -0
  5. package/docs/proposals/sinter-mail.md +520 -0
  6. package/llms.txt +20 -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 +270 -0
  78. package/sinter/css/media.ts +251 -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 +647 -0
  83. package/sinter/engine.ts +6 -0
  84. package/sinter/index.ts +5 -0
  85. package/sinter/parse.ts +355 -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 +135 -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,138 @@
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
+ 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`).