@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
|
@@ -0,0 +1,520 @@
|
|
|
1
|
+
# Proposal: sinter-mail, email bodies rendered by sinter templates
|
|
2
|
+
|
|
3
|
+
Status: built (version 0.1, not released), steps 2 to 7 of the [Plan](#plan); the guide is
|
|
4
|
+
[docs/mail.md](../mail.md). It needs changes to sinter, made on its branch `ccr-dc349183-ubeji7`
|
|
5
|
+
([sinter changes](#sinter-changes)). Where the build departs from this text is listed in
|
|
6
|
+
[Implementation status](#implementation-status); the sections below are the design as proposed. Sections are
|
|
7
|
+
numbered in the order of the [Plan](#plan); every design choice is recorded in [Decisions](#decisions).
|
|
8
|
+
|
|
9
|
+
## Implementation status
|
|
10
|
+
|
|
11
|
+
Built in one session, the parts in parallel (parser, cascade, plain text, components), each reviewed and
|
|
12
|
+
integrated against the tests; the spike (step 1) was skipped and its questions are answered by measurement
|
|
13
|
+
below.
|
|
14
|
+
|
|
15
|
+
| Step | State | Where it departs from this text |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| 1, the spike | skipped | the parser was chosen without it: see section 2 below |
|
|
18
|
+
| 2, tags, types, components | done | the table component, the parts' classes, the dispatch over every tag: section 6 |
|
|
19
|
+
| 3, mail.parse | done | ids and fragment links: section 1 |
|
|
20
|
+
| 4, styles | done | `@media`, the values kept, `text-align`: section 4 |
|
|
21
|
+
| 5, mail.plain | done | as proposed |
|
|
22
|
+
| 6, mail.text, mail.links, slots | done | as proposed |
|
|
23
|
+
| 7, corpus, attacks, browser, docs | partly | a small corpus written for the tests; attacks checked on the tree, not rendered; Chromium only; no screenshot comparison in the tests; no recipe |
|
|
24
|
+
|
|
25
|
+
### As built, by section
|
|
26
|
+
|
|
27
|
+
- **1, the tree.** `Body` also has `style`: the email's `<body>` (and `<html>`) style, its text properties and
|
|
28
|
+
background, rendered on the root. `images.origins` lists every remote image's origin, whatever `images`
|
|
29
|
+
is. An id is kept only when an in-email `#fragment` link points at it and the email has it (or an
|
|
30
|
+
`<a name>`); the link then reads `#mail-…`, and the component writes the id with the prefix.
|
|
31
|
+
- **2, parsing.** Our own parser, not parse5 or htmlparser2: the standard's tokenizer and every insertion
|
|
32
|
+
mode used by documents, foreign content parsed and dropped, `<template>` content parsed and discarded. It
|
|
33
|
+
equals parse5 on every targeted case and on about 450,000 random documents below the depth bound (256,
|
|
34
|
+
enforced on the stack, as Blink flattens deep trees). 15.9 kB gzip, 7.3 kB of it the HTML standard's whole
|
|
35
|
+
entity table, which an HTML parser must decode (parse5 bundled is 46 kB gzip). About 32 ms on a 101 kB
|
|
36
|
+
newsletter of 2,000 elements, in Node.
|
|
37
|
+
- **3, what is kept.** 71 tags. Unknown elements are a `span` (inline, styled), not unwrapped; a few
|
|
38
|
+
known ones are renamed (`fieldset`, `legend` to `div`, `menu`, `dir` to `ul`, `big`, `label` to `span`).
|
|
39
|
+
Table structure is enforced in the tree (a table's children only caption, colgroup and sections, a row's
|
|
40
|
+
only cells), so the table component can render it with literal tags.
|
|
41
|
+
- **4, styles.** 60 properties. `@media` is evaluated at a width rather than dropped: 800 px (`'wide'`, the
|
|
42
|
+
default) or 375 px (`'narrow'`), 16 px root font, light colour scheme. The legacy hints follow Chromium's,
|
|
43
|
+
including `text-align: -webkit-center` for `<center>` and `align=center` (what centres a nested table in
|
|
44
|
+
Chromium; whether Firefox and Safari read it the same is untested here). Negative margins and text
|
|
45
|
+
indents are written as 0. A matching budget (2 million steps per resolve) and a cap of 10,000 author rules
|
|
46
|
+
bound a hostile stylesheet; past them, the rest of the email keeps its hints and inline styles. `test/css.browser.test.ts` compares every
|
|
47
|
+
property on every element with Chromium's computed style and lists the accepted differences. The cascade
|
|
48
|
+
resolves in about 19 ms on a 1,756-element newsletter with 300 rules; 16.2 kB gzip.
|
|
49
|
+
- **4, CSP.** An email rendered in the browser needs nothing beyond the policy in the goals: styles are set
|
|
50
|
+
with `style.setProperty`. An email folded at build time has its styles in `style` attributes, which
|
|
51
|
+
`style-src 'self'` blocks: it needs `style-src-attr 'unsafe-inline'`. (sinter's own security guide says
|
|
52
|
+
`style-src 'self'` is enough; that holds only for pages with no `data-sn-style` folded at build time.)
|
|
53
|
+
- **6, components.** The dispatch (`mail-node`) maps every tag, a table part outside a table to
|
|
54
|
+
`mail-orphan` (which the parse never produces), since indexing the map by the `Tag` union must type-check.
|
|
55
|
+
`<mail-body>`'s `display: flow-root` depends on the body (`body ? 'flow-root' : null`): a constant style is
|
|
56
|
+
written into the HTML as an attribute even on pages rendered in the browser, which `style-src 'self'`
|
|
57
|
+
blocks. The parts' classes (`mail-quote`, `mail-signature`) are bound on `blockquote` and `div` only.
|
|
58
|
+
- **7, three places.** Measured on a 2,005-element newsletter (Chromium, the API's answer to the content
|
|
59
|
+
painted, median of 7), against Caley's approach (DOMPurify, then a sized iframe) on the same email:
|
|
60
|
+
|
|
61
|
+
| Path | Time | Page JS gzip |
|
|
62
|
+
| --- | --- | --- |
|
|
63
|
+
| Caley's approach | 74 ms | about 27 kB |
|
|
64
|
+
| sinter-mail, a tree from the API | 94 ms | 27.1 kB |
|
|
65
|
+
| sinter-mail, HTML from the API | 143 ms | 61.8 kB |
|
|
66
|
+
| sinter-mail, a `file:` email | in the first frame | none |
|
|
67
|
+
|
|
68
|
+
A bare sinter page is 14.5 kB. A session investigates making the parse and the components smaller and
|
|
69
|
+
faster (parse5, the entity table, a scoped CSS sink in sinter that would hold the same guarantees);
|
|
70
|
+
its findings will be in `docs/proposals/sinter-mail-performance.md`.
|
|
71
|
+
|
|
72
|
+
### sinter changes
|
|
73
|
+
|
|
74
|
+
The components as first generated added 97.9 kB gzip to a page, and a static build could fold only trees
|
|
75
|
+
about 9 elements deep. Five changes to sinter, on its branch `ccr-dc349183-ubeji7`, each with its tests and
|
|
76
|
+
sinter's full suite passing:
|
|
77
|
+
|
|
78
|
+
1. **SN503 accepts a choice of literal-prefixed values** (`node.attrs.id ? 'mail-' + node.attrs.id : null`).
|
|
79
|
+
Before, each tag component held its element twice (with an id, and without), which doubled everything.
|
|
80
|
+
2. **`<sn-component use>` with many candidates is a lookup table**, not a chain of comparisons per candidate,
|
|
81
|
+
each with its own props: the dispatch is compiled once per place the tree recurses (66 places).
|
|
82
|
+
3. **An element's `data-sn-style` entries are one binding** in the page module, its names listed once per
|
|
83
|
+
distinct list; the runtime writes the values that changed. Before, each property was a binding and a
|
|
84
|
+
function of its own, in the page module and again in every row template's creation function.
|
|
85
|
+
4. **Constant data may nest 1,024 levels deep** (was 20) for build-time folding, walked without recursion.
|
|
86
|
+
5. **A component a map names under two keys is one candidate**: the build-time rendering drew it twice.
|
|
87
|
+
|
|
88
|
+
With them: the components add 15.7 kB gzip instead of 97.9, a 2,012-element tree renders in about 84 to 118
|
|
89
|
+
ms instead of 136 to 180 (Chromium, the same machine; the range is this machine's variance), and the deep
|
|
90
|
+
fixtures fold. sinter-mail depends on that branch through a sibling checkout until it is released.
|
|
91
|
+
|
|
92
|
+
## Goals
|
|
93
|
+
|
|
94
|
+
`@tiavision/sinter-mail` shows the body of an email in a sinter app, the way
|
|
95
|
+
[sinter-markdown](https://github.com/tiaforge/sinter/tree/main/packages/sinter-markdown) shows markdown:
|
|
96
|
+
|
|
97
|
+
- **No iframe.** The email is part of the page: it scrolls, sizes, selects and prints with it, and the
|
|
98
|
+
page's styles fill in what the email does not set.
|
|
99
|
+
- **The email's own look.** Its `<style>` rules, inline styles and legacy attributes (`bgcolor`,
|
|
100
|
+
`cellpadding`, `<font>`) are kept, and win over the page's styles.
|
|
101
|
+
- **All markup comes from sinter templates.** sinter never creates HTML from data, and this library does
|
|
102
|
+
not change that: the email is parsed into a tree, and components render the tree, element by element.
|
|
103
|
+
No `innerHTML`, no `srcdoc`, no stylesheet built from data, no change to sinter's core.
|
|
104
|
+
- **Three places, one function**, as for markdown: an email in a file is plain HTML at build time and
|
|
105
|
+
ships no JavaScript; an email from an API is parsed in the browser (the parser with the page, or lazy);
|
|
106
|
+
an API may run the parse itself and send the tree, and the page ships no parser.
|
|
107
|
+
- **Plain-text email too**, through the same tree and the same components.
|
|
108
|
+
- **Safe for hostile input**, under `script-src 'self'; style-src 'self'; require-trusted-types-for
|
|
109
|
+
'script'`: nothing an email contains runs, loads from the network without the app's consent, or
|
|
110
|
+
reaches outside its own box.
|
|
111
|
+
|
|
112
|
+
### Not in version 1
|
|
113
|
+
|
|
114
|
+
Listed so that version 1 does not close them off ([Later](#later)): reading MIME messages, PGP/MIME,
|
|
115
|
+
detecting and collapsing quoted replies in HTML email, background images.
|
|
116
|
+
|
|
117
|
+
## The case
|
|
118
|
+
|
|
119
|
+
An app that shows email today has two choices:
|
|
120
|
+
|
|
121
|
+
| | iframe (`srcdoc`, sandboxed) | sanitize, then `innerHTML` |
|
|
122
|
+
| --- | --- | --- |
|
|
123
|
+
| Styles | isolated both ways | the email's `<style>` leaks into the page, or is dropped |
|
|
124
|
+
| Layout | the iframe's height must be measured and set by script, and is wrong until then | part of the page |
|
|
125
|
+
| Under sinter | `srcdoc` is `SN207`; the iframe needs script | `innerHTML` is `SN207`; Trusted Types need a policy |
|
|
126
|
+
| First frame | empty, then the email | the email, if rendered on the server |
|
|
127
|
+
| From a file | a document per email | a sanitizer in the build |
|
|
128
|
+
|
|
129
|
+
Email is a good fit for sinter's model because email HTML is already constrained. Senders write for
|
|
130
|
+
clients that strip most of CSS (Gmail, Outlook), so an email's look is in inline styles, table
|
|
131
|
+
attributes and one `<style>` block that inliner tools are made for. No script, form or iframe is
|
|
132
|
+
expected to work. The compromises a renderer without a stylesheet must make are the ones email clients
|
|
133
|
+
already make, and those are the ones this library makes.
|
|
134
|
+
|
|
135
|
+
## What sinter has to build on
|
|
136
|
+
|
|
137
|
+
Everything below exists in sinter 0.19 and is used as it is:
|
|
138
|
+
|
|
139
|
+
- **Component libraries** ([libraries](https://github.com/tiaforge/sinter/blob/main/docs/libraries.md)):
|
|
140
|
+
a package ships source in `sinter/`, public and internal components, one prefix, helpers re-exported
|
|
141
|
+
under a namespace the app chooses.
|
|
142
|
+
- **Pure helpers fold at build time**: a helper over a constant (a `file:` resource) runs in the build,
|
|
143
|
+
if it uses only the language's own globals, `URL`, `URLSearchParams`, `structuredClone`,
|
|
144
|
+
`TextEncoder` and `TextDecoder`. `src="file:./welcome.html"` reads any file but `.md` and `.json` as
|
|
145
|
+
its text.
|
|
146
|
+
- **`memo()`** (`@tiaforge-ui/sinter/memo`) keeps a helper's results: same input, same frozen tree.
|
|
147
|
+
- **Choosing a component by data**: `<sn-component use="{ p: 'mail-p', … }[node.tag]">`, one choice per
|
|
148
|
+
node; in a library, the map form names every candidate (`SN312`).
|
|
149
|
+
- **Text runs** as `<template data-sn-text>`, a text node with no element.
|
|
150
|
+
- **Tree slots**: a public root declares a slot, internal components place it (`SN331`).
|
|
151
|
+
- **`data-sn-attr`** with literal keys; URL attributes checked at runtime (`http:`, `https:`,
|
|
152
|
+
`mailto:`, `tel:`, relative; `data:` and `blob:` only in media `src`).
|
|
153
|
+
- **`data-sn-style`** with literal property names, set with `style.setProperty`; `null` removes the
|
|
154
|
+
property; a value with `url(`, `image(`, `image-set(` or a backslash is refused at runtime.
|
|
155
|
+
- **Lazy packages**: `sinter({ lazy: ['@tiavision/sinter-mail'] })` covers the package's subpaths, so
|
|
156
|
+
the parser, imported as `@tiavision/sinter-mail/parser`, loads on first need; a helper module that
|
|
157
|
+
does not import it stays an ordinary helper.
|
|
158
|
+
|
|
159
|
+
What sinter does not have, and this proposal does not add: a way to bind a stylesheet, a `<style>`, a
|
|
160
|
+
`style` attribute or arbitrary property names from data. Those stay closed ([Decisions](#decisions), 1).
|
|
161
|
+
|
|
162
|
+
## The package
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
package.json @tiavision/sinter-mail, "sinter": "./sinter", exports ".", "./parser"
|
|
166
|
+
sinter/
|
|
167
|
+
components/
|
|
168
|
+
mail-body.html public: one body, HTML or plain text
|
|
169
|
+
internal/
|
|
170
|
+
mail-node.html one element, by its tag: the only place elements are dispatched
|
|
171
|
+
mail-p.html … one component per allowed tag (generated, committed)
|
|
172
|
+
sinter.helpers.ts re-exports parse.ts, plain.ts, tree.ts
|
|
173
|
+
parse.ts mail.parse: imports the parser, sanitizes, resolves styles
|
|
174
|
+
plain.ts mail.plain: plain text to the same tree; imports no parser
|
|
175
|
+
tree.ts mail.text, mail.links: read a tree; import no parser
|
|
176
|
+
parser.js the HTML and CSS parser, prebundled (generated; committed)
|
|
177
|
+
sinter.types.ts the tree's types
|
|
178
|
+
index.ts the entry
|
|
179
|
+
scripts/
|
|
180
|
+
tags.mjs the tag table: tags, their attributes, their style properties
|
|
181
|
+
build-components.mjs writes components/internal/ from the table; --check
|
|
182
|
+
build-parser.mjs writes parser.js; --check
|
|
183
|
+
fixtures/ pages for sinter check; a corpus of real emails
|
|
184
|
+
test/
|
|
185
|
+
docs/
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The prefix is `mail-`, the namespace an app writes `mail`:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
// src/sinter.helpers.ts
|
|
192
|
+
export * as mail from '@tiavision/sinter-mail';
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
```html
|
|
196
|
+
<sn-resource name="msg" src="/api/messages/{$url.id}"></sn-resource>
|
|
197
|
+
<article data-sn-let="{ body: msg.html ? mail.parse(msg.html, { images: 'block' }) : mail.plain(msg.text) }">
|
|
198
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
199
|
+
</article>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Design
|
|
203
|
+
|
|
204
|
+
### 1. The tree
|
|
205
|
+
|
|
206
|
+
`mail.parse` and `mail.plain` return the same type, deep-frozen:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
interface Body { type: 'body'; children: Node[]; images: ImageInfo; }
|
|
210
|
+
type Node = Element | Text;
|
|
211
|
+
interface Text { type: 'text'; value: string; }
|
|
212
|
+
interface Element {
|
|
213
|
+
type: 'element';
|
|
214
|
+
tag: Tag; // one of the allowed tags, lowercase
|
|
215
|
+
attrs: Attrs; // only the tag's allowed attributes, values checked
|
|
216
|
+
style: Style; // resolved declarations, only allowed properties
|
|
217
|
+
part?: 'quote' | 'signature'; // what the element is in the message
|
|
218
|
+
children: Node[];
|
|
219
|
+
}
|
|
220
|
+
interface ImageInfo {
|
|
221
|
+
origins: string[]; // every remote image's origin (`https://cdn.example`), sorted, once each
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- **One node per element the browser would build**, no more: the parse produces the tree that the
|
|
226
|
+
browser's own parser builds from the same HTML, restricted to the allowed tags (section 2). A tree
|
|
227
|
+
that differs would be reparsed into another one when a page built at build time loads.
|
|
228
|
+
- **`part`** marks what the app may want to style or fold. In version 1, `mail.plain` sets it for
|
|
229
|
+
quotes and the signature; detecting quotes in HTML email sets the same field later.
|
|
230
|
+
- **No classes.** Every selector is resolved at parse time (section 4), so the email's class names are
|
|
231
|
+
not needed, and keeping them would let the page's rules for `.button` or `.header` reach the email by
|
|
232
|
+
accident. They are dropped.
|
|
233
|
+
- **Ids** are kept only when an in-email link points to them (`href="#top"`), and written as
|
|
234
|
+
`'mail-' + id` (`SN503`), with the link rewritten to match.
|
|
235
|
+
- An API can send this tree instead of the HTML (`mail.parse` run on the server, in Node): the
|
|
236
|
+
components render it as any other data.
|
|
237
|
+
|
|
238
|
+
### 2. Parsing HTML
|
|
239
|
+
|
|
240
|
+
The parser turns email HTML into the tree of section 1. It is prebundled into `parser.js`, committed,
|
|
241
|
+
and checked by `npm run build:parser -- --check`, as sinter-markdown's is.
|
|
242
|
+
|
|
243
|
+
- **The tree must match the browser's.** That means HTML's tree construction for what emails contain:
|
|
244
|
+
implied end tags (`<p>`, `<li>`, `<td>`, `<tr>`, `<option>`), void elements, `<tbody>` inserted into a
|
|
245
|
+
table that has none, content outside cells moved before the table, misnested inline tags (`<b><i></b>`),
|
|
246
|
+
`<html>`, `<head>` and `<body>` implied, and the head's `<style>` blocks collected. Full HTML5 tree
|
|
247
|
+
construction (frames, `<template>`, foreign content beyond what is dropped, scripting flags) is not
|
|
248
|
+
needed: those parts of a document are dropped anyway.
|
|
249
|
+
- **The candidates** are a tokenizer from htmlparser2 with a tree builder of our own for the rules above,
|
|
250
|
+
or parse5 trimmed to what is used. The spike decides on size and on the corpus test (section 9).
|
|
251
|
+
parse5 is the reference in the tests either way.
|
|
252
|
+
- **Entities** decode from a table, never through the DOM, as in sinter-markdown (the same packed table).
|
|
253
|
+
- **Charset** is not the parser's job: it takes a string. Decoding bytes is the caller's (the API, or
|
|
254
|
+
later the MIME step).
|
|
255
|
+
- **Linear** in the input: a test parses long runs of open tags, attributes and entities within a second.
|
|
256
|
+
- **Limits**: nesting deeper than a bound (256) is flattened, as browsers bound theirs; the bound is an option.
|
|
257
|
+
|
|
258
|
+
### 3. What an email may contain
|
|
259
|
+
|
|
260
|
+
A tag table (`scripts/tags.mjs`) is the single source for what is allowed. From it come the parser's
|
|
261
|
+
allowlist, the tree's `Tag` type and the generated components.
|
|
262
|
+
|
|
263
|
+
- **Tags, about 60**: the text and structure tags (`p`, `div`, `span`, `h1`–`h6`, `br`, `hr`, `b`,
|
|
264
|
+
`strong`, `i`, `em`, `u`, `s`, `strike`, `small`, `sub`, `sup`, `code`, `pre`, `blockquote`, `q`,
|
|
265
|
+
`ul`, `ol`, `li`, `dl`, `dt`, `dd`, `a`, `img`, `abbr`, `cite`, `mark`, `kbd`, `address`, `wbr`), the
|
|
266
|
+
table tags (`table`, `caption`, `colgroup`, `col`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`), the
|
|
267
|
+
legacy tags email still uses (`font`, `center`), and `section`, `article`, `header`, `footer`,
|
|
268
|
+
`main`, `nav`, `aside`, `figure`, `figcaption`, `details`, `summary`.
|
|
269
|
+
- **Unknown or unwanted tags** have two fates, as in the table: content tags (`custom-tag`, `o:p`,
|
|
270
|
+
`label`) are unwrapped, their children kept; dangerous or empty ones (`script`, `style` after it is
|
|
271
|
+
read, `iframe`, `object`, `embed`, `form` and its controls, `svg`, `math`, `video`, `audio`,
|
|
272
|
+
`canvas`, `link`, `meta`, `base`, `title`, `template`, `noscript`) are dropped with their content.
|
|
273
|
+
- **Attributes per tag**, literal in the components: `href` and `title` on `a`; `src`, `alt`, `width`,
|
|
274
|
+
`height` on `img`; `colspan`, `rowspan`, `headers`, `scope` on cells; `start`, `reversed`, `type` on
|
|
275
|
+
lists; `dir` and `lang` everywhere; `open` on `details`. The legacy presentational attributes are read
|
|
276
|
+
by the parser and turned into styles (section 4); they are not rendered as attributes, except `width`
|
|
277
|
+
and `height` on images, which also reserve the image's space.
|
|
278
|
+
- **Links**: `http:`, `https:`, `mailto:`, `tel:` and in-email `#fragments`; anything else is dropped by
|
|
279
|
+
the parser, and the runtime's check stays as a second gate. Every `<a>` gets `target="_blank"` and
|
|
280
|
+
`rel="noopener noreferrer"`, written literally in its component.
|
|
281
|
+
- **Images.** Two options decide what a remote (`http:`, `https:`) image becomes; the pattern they are
|
|
282
|
+
made for is [an image proxy](#an-image-proxy), as Caley's.
|
|
283
|
+
- `images`: `'block'` (the default) leaves every remote image out; `'allow'` keeps it, loading from
|
|
284
|
+
the sender's server; `'proxy'` keeps it, through the `proxy` template.
|
|
285
|
+
- `proxy`: a URL template of the app's, `'/api/email/proxy-image?url={url}'`. `{url}` is the image's
|
|
286
|
+
absolute URL, percent-encoded as a query value; the template must contain it once, and an absolute
|
|
287
|
+
template must be `https:` (an error otherwise, at each call, as an invalid option).
|
|
288
|
+
- A left-out image keeps its box (`width`, `height`, `alt`), so the layout does not move when images
|
|
289
|
+
are shown.
|
|
290
|
+
- `body.images.origins` lists every remote image's origin (`scheme://host`, as `new URL(src).origin`
|
|
291
|
+
writes it), whatever the option, for a "show images from …" control.
|
|
292
|
+
- Options are values, not functions: `memo()` keys on them, an API can pass the same options when it
|
|
293
|
+
runs the parse on the server, and an email from a file folds at build time.
|
|
294
|
+
- **`cid:` images** (inline parts of the message) are kept when the `cid` option resolves them: a map
|
|
295
|
+
(`{ 'logo@acme': 'data:image/png;base64,…' }`, as for a decrypted message whose parts the app holds),
|
|
296
|
+
or a template with `{cid}` (`'/api/email/proxy-image?uid=42&cid={cid}'`, the message's own values
|
|
297
|
+
written into it by the app). An unresolved one is left out. `cid:` images do not count as remote.
|
|
298
|
+
- **`data:` images** are kept for raster types (`image/png`, `jpeg`, `gif`, `webp`, `avif`), base64,
|
|
299
|
+
up to a size bound (an option); `data:image/svg+xml` never.
|
|
300
|
+
- Images bind `srcset: null`, so an app's image pipeline does not resize user content (as
|
|
301
|
+
sinter-markdown's `md-image`).
|
|
302
|
+
- **Comments, processing instructions, conditional comments** (`<!--[if mso]>`) are dropped. Outlook's
|
|
303
|
+
conditional content is for Outlook; what other clients show is what is outside it.
|
|
304
|
+
|
|
305
|
+
#### An image proxy
|
|
306
|
+
|
|
307
|
+
The pattern sinter-mail is made for, as Caley (a sinter mail app) runs it today with DOMPurify and an
|
|
308
|
+
iframe: every remote image goes through the app's server (`/api/email/proxy-image?url=…`), so the
|
|
309
|
+
sender never sees the reader. Which origins the proxy fetches (an allowlist the user edits, an ignore
|
|
310
|
+
list), how it checks addresses and what it answers for a refused image are the proxy's, not this
|
|
311
|
+
library's. sinter-mail only writes the URLs and reports the origins:
|
|
312
|
+
|
|
313
|
+
```html
|
|
314
|
+
<article data-sn-let="{ body: mail.parse(msg.html, {
|
|
315
|
+
images: 'proxy', proxy: '/api/email/proxy-image?url={url}',
|
|
316
|
+
cid: `/api/email/proxy-image?account_id=${encodeURIComponent(msg.account)}&uid=${msg.uid}&cid={cid}` }) }">
|
|
317
|
+
<mail-body data-sn-prop="{ body }"></mail-body>
|
|
318
|
+
</article>
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
- **No URL rewriting to undo**: the source HTML is never changed, only the tree, so a reply or a
|
|
322
|
+
forward quotes the original image URLs as they were (Caley restores them from its proxied HTML
|
|
323
|
+
today, `restoreForwardedImageSources`).
|
|
324
|
+
- **The origins come from the parse** (`body.images.origins`), not from a regular expression over
|
|
325
|
+
HTML (Caley's `imageOriginsFromHtml`), for the app's own "allow this origin" control.
|
|
326
|
+
- **Showing newly allowed images** is the app's: a URL the proxy answers differently after the change
|
|
327
|
+
needs a new URL (a `v={version}` in the template the app bumps), or the browser keeps the cached answer.
|
|
328
|
+
|
|
329
|
+
### 4. Styles
|
|
330
|
+
|
|
331
|
+
The email's styles are resolved by the parser into each element's `style`, and rendered inline. There is
|
|
332
|
+
no stylesheet.
|
|
333
|
+
|
|
334
|
+
**Resolving.** For each element, in the order of the cascade:
|
|
335
|
+
|
|
336
|
+
1. The legacy attributes, turned into declarations, as the browser's presentational hints rank them
|
|
337
|
+
(lowest): `bgcolor` to `background-color`, `width` and `height`, `align` to `text-align` (and
|
|
338
|
+
`margin-inline: auto` for a centred table), `valign` to `vertical-align`, `border` to the table's
|
|
339
|
+
and its cells' borders, `cellpadding` to the cells' `padding`, `cellspacing` to `border-spacing`,
|
|
340
|
+
`<font color face size>` to `color`, `font-family`, `font-size`, `<center>` to `text-align: center`.
|
|
341
|
+
2. The `<style>` rules that match it, by specificity and order, `!important` last.
|
|
342
|
+
3. Its `style=""` attribute, `!important` in it last.
|
|
343
|
+
|
|
344
|
+
Then only the allowed properties are kept, and the result is the element's `style`.
|
|
345
|
+
|
|
346
|
+
- **Selectors**: type, class, id, attribute (`[align=center]`), universal, descendant, child, adjacent
|
|
347
|
+
and general sibling, `:first-child`, `:last-child`, `:nth-child()`, `:not()` of those, matched against
|
|
348
|
+
the parsed tree. A rule with a selector outside that (`:hover`, `::before`, `:focus`) is dropped.
|
|
349
|
+
- **At-rules**: `@media` is resolved by the `media` option: `'wide'` (the default) drops its rules,
|
|
350
|
+
`'narrow'` applies those for a width below 600 px, which email layouts are written for, so an app
|
|
351
|
+
that shows email in a narrow column can choose the mobile layout. `@import`, `@font-face`, `@keyframes`,
|
|
352
|
+
`@supports` and the rest are dropped. A `@media` rule cannot follow the viewport, since there is no
|
|
353
|
+
stylesheet: the choice is made at parse time.
|
|
354
|
+
- **Properties, about 40** (`scripts/tags.mjs`): `color`, `background-color`, the `font-*` longhands,
|
|
355
|
+
`line-height`, `letter-spacing`, `text-align`, `text-decoration`, `text-transform`, `text-indent`,
|
|
356
|
+
`white-space`, `vertical-align`, `width`, `height`, `min-`/`max-width`, `min-`/`max-height`,
|
|
357
|
+
`padding-*`, `margin-*`, `border-*` longhands, `border-radius`, `border-collapse`, `border-spacing`,
|
|
358
|
+
`table-layout`, `display` (`block`, `inline`, `inline-block`, `none`, the table values), `list-style-type`,
|
|
359
|
+
`overflow` (`hidden`, `visible`), `opacity`, `box-sizing`. Shorthands are expanded at parse time.
|
|
360
|
+
Not allowed: `position`, `z-index`, `transform`, `filter`, `animation`, `transition`, `content`,
|
|
361
|
+
`cursor`, `pointer-events`, `background-image` and any value with `url(`, custom properties and
|
|
362
|
+
`var()`, `expression()`.
|
|
363
|
+
- **Values** are re-serialized from the parsed tokens, so CSS escapes are decoded (`"\5FAE\8F6F"` is
|
|
364
|
+
written as the characters), no backslash remains, and the runtime's style check never refuses a
|
|
365
|
+
value the parser kept. A value is kept when it parses as the property's grammar allows, in a simple
|
|
366
|
+
form (lengths, percentages, colours, keywords, font lists); `calc()` is not kept in version 1.
|
|
367
|
+
- **The CSS parser** is a tokenizer after CSS Syntax Level 3 and a small selector parser, bundled into
|
|
368
|
+
`parser.js` with the HTML parser.
|
|
369
|
+
|
|
370
|
+
**Rendering.** Each generated component binds the element's resolved style with a literal list:
|
|
371
|
+
|
|
372
|
+
```html
|
|
373
|
+
<template data-sn-component="{ node: Element }"><td data-sn-attr="{ colspan: node.attrs.colspan, rowspan: node.attrs.rowspan, … }" data-sn-style="{ color: node.style.color, 'background-color': node.style['background-color'], … }"><template data-sn-for="c in node.children"><template data-sn-if="c.type === 'text'" data-sn-text="c.value"></template><template data-sn-else><mail-node data-sn-prop="{ node: c }"></mail-node></template></template></td></template>
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
- Each tag lists the properties that do something on it (no `border-spacing` on a `<span>`), so a
|
|
377
|
+
binding reads about 15 to 40 properties. A missing property is `undefined`: nothing is written. The
|
|
378
|
+
spike measures the cost on a large newsletter (section 9).
|
|
379
|
+
- **The email wins over the page.** Inline styles beat every normal rule of the page's stylesheets,
|
|
380
|
+
whatever their specificity; the legacy attributes are inline too, so a page rule `td { padding: 1rem }`
|
|
381
|
+
does not undo `cellpadding="0"`.
|
|
382
|
+
- **The page fills in.** What the email does not set comes from the page: the font, the colour, link
|
|
383
|
+
styles, line height. A plain email looks native to the app.
|
|
384
|
+
- **Where the page still wins**: a page rule with `!important` (`data-sn-style` sets no priority), and
|
|
385
|
+
whatever the email takes from browser defaults when the page resets them (a reset that makes images
|
|
386
|
+
`display: block` or headings unsized). That is the app's choice. A recipe shows an opt-in reset to
|
|
387
|
+
browser defaults under `.mail` for apps that want designed newsletters exactly as sent.
|
|
388
|
+
|
|
389
|
+
### 5. Plain text
|
|
390
|
+
|
|
391
|
+
`mail.plain(text, options)` is in `plain.ts`, which imports no parser: it stays an ordinary helper when
|
|
392
|
+
the package is lazy, and folds at build time over a `file:` resource.
|
|
393
|
+
|
|
394
|
+
- **Paragraphs**: text between blank lines is a `<p>` with `white-space: pre-wrap`, so line breaks and
|
|
395
|
+
spacing are as written.
|
|
396
|
+
- **Links**: URLs, `www.` addresses and email addresses become links, with GFM's autolink rules
|
|
397
|
+
(sinter-markdown's `autolink.js`, copied with its tests: the same organisation and licence).
|
|
398
|
+
- **Quotes**: lines starting with `>` become `blockquote` elements with `part: 'quote'`, nested per level (`> >`).
|
|
399
|
+
Space-stuffed lines (`format=flowed`) are read as RFC 3676 says.
|
|
400
|
+
- **Signature**: from a line that is exactly `-- ` to the end is a `div` with `part: 'signature'`.
|
|
401
|
+
- **`flowed: true`** (with `delsp`) joins soft line breaks back into paragraphs, as RFC 3676 says, so
|
|
402
|
+
they reflow on narrow screens. The flag is in the message's `Content-Type`, so the caller passes it.
|
|
403
|
+
- **Linear** in the text, and the same limits as `mail.parse`.
|
|
404
|
+
|
|
405
|
+
### 6. The components
|
|
406
|
+
|
|
407
|
+
- **`<mail-body>`** takes `body` and renders `<div class="mail">` with the body's children; with no
|
|
408
|
+
`body`, an empty `<div class="mail">` (a lazy parser that has not arrived). It declares the slots.
|
|
409
|
+
- **`<mail-node>`** (internal) is the dispatch: its root is `<sn-component use="{ p: 'mail-p', … }[node.tag]">`.
|
|
410
|
+
Every loop over children renders text runs first and `<mail-node>` for each element, so the map is
|
|
411
|
+
written once.
|
|
412
|
+
- **One component per tag** (internal, generated by `scripts/build-components.mjs` from the tag table,
|
|
413
|
+
committed, `--check` in the tests): the element with its literal attribute and style lists and the
|
|
414
|
+
loop over its children, written without whitespace between tags (whitespace is text, and would show
|
|
415
|
+
in tables and phrasing content).
|
|
416
|
+
- **Constant parts**: `part` adds the class `mail-quote` or `mail-signature`, a literal class the page
|
|
417
|
+
styles (`.mail-signature { opacity: .7 }`).
|
|
418
|
+
- **Slots, version 1**: `link: Slot<{ node: Element }>` (a warning before an outgoing link, a link
|
|
419
|
+
whose text and address differ) and `image: Slot<{ node: Element }>` (a placeholder for a blocked
|
|
420
|
+
image, a lightbox). Placed by `mail-a` and `mail-img` as their roots, defaults inside, as
|
|
421
|
+
sinter-markdown's are. More slots later are additive.
|
|
422
|
+
- **Tables** render as components like everything else; a `<template>` is allowed in a table by the
|
|
423
|
+
HTML parser, so a row loop inside `<tbody>` stays where it is written.
|
|
424
|
+
|
|
425
|
+
### 7. Three places, one function
|
|
426
|
+
|
|
427
|
+
| Email body | Where it is parsed | What the page ships |
|
|
428
|
+
| --- | --- | --- |
|
|
429
|
+
| A file: `src="file:./welcome.html"` | at build time | the email as plain HTML with inline styles, no JavaScript |
|
|
430
|
+
| A string from an API, in a `data-sn-let` | in the browser, once per source and options (`memo()`) | the parser with the page |
|
|
431
|
+
| The same, with the package lazy | in the browser, once the parser has loaded | the parser in a chunk of its own |
|
|
432
|
+
| A tree from the API (`mail.parse` run on the server) | on the server | no parser |
|
|
433
|
+
|
|
434
|
+
`mail.parse` keeps its trees as `md.parse` does: same source and same normalized options, same frozen
|
|
435
|
+
tree, about 8 MiB of trees kept, the least recently used dropped first.
|
|
436
|
+
|
|
437
|
+
### 8. Reading a tree
|
|
438
|
+
|
|
439
|
+
`tree.ts`, no parser: `mail.text(node)` (the text of a node, for previews and search snippets) and
|
|
440
|
+
`mail.links(body)` (every link, for an app that lists or checks them).
|
|
441
|
+
|
|
442
|
+
### 9. Tests
|
|
443
|
+
|
|
444
|
+
| Test | What it covers |
|
|
445
|
+
| --- | --- |
|
|
446
|
+
| `parse.test.ts` | `mail.parse` and its options; the tag and attribute allowlists; URLs; ids; linear time on hostile runs |
|
|
447
|
+
| `styles.test.ts` | the cascade: legacy attributes, specificity, `!important`, `@media` both ways, selectors kept and dropped, escapes decoded, nothing the runtime refuses |
|
|
448
|
+
| `corpus.test.ts` | real emails (newsletters, receipts, notifications, Outlook, Gmail, Apple Mail and inliner output): our tree equals the browser's own parse of the same HTML restricted to the allowed tags (parse5 in Node, the DOM in Chromium), and serializing our tree and parsing it again gives the same tree |
|
|
449
|
+
| `plain.test.ts` | paragraphs, links, quotes, signature, `format=flowed` |
|
|
450
|
+
| `components.test.ts` | the tag table, the `Tag` type, the dispatch map and the component files agree; generated files up to date |
|
|
451
|
+
| `check.test.ts` | `sinter check` over the fixture pages: no error, no warning |
|
|
452
|
+
| `static.test.ts` | an email from `file:` built with `sinter({ static })`: no JavaScript, the styles inline |
|
|
453
|
+
| `browser.test.ts` | the fixture app in Chromium, Firefox and WebKit under `script-src 'self'; style-src 'self'; require-trusted-types-for 'script'`, failing on any violation or console error; a corpus of hostile emails (script in every place, `javascript:` and `data:` links, CSS with `url()`, `expression()`, escapes, `position: fixed` overlays): no request leaves the page, nothing outside `.mail` changes; screenshots of corpus emails against an iframe rendering of the same HTML, as a measure of fidelity |
|
|
454
|
+
|
|
455
|
+
## Decisions
|
|
456
|
+
|
|
457
|
+
1. **No stylesheet sink in sinter's core.** Binding a stylesheet from data would open what sinter's
|
|
458
|
+
security model keeps closed. The cascade is resolved at parse time instead, and email is where that
|
|
459
|
+
costs least: email clients already drop most of what this drops.
|
|
460
|
+
2. **Email, not HTML in general.** The tag set, the styles kept, the image policy and the parser's
|
|
461
|
+
scope are email's. The name says so; a request for more of HTML is judged by what email clients do.
|
|
462
|
+
3. **The page's styles reach the email; the email's win.** No isolation layer: inline styles override
|
|
463
|
+
the page, the page fills in the rest, and a plain email looks like part of the app.
|
|
464
|
+
4. **Legacy attributes become inline styles**, so the page cannot undo them by accident.
|
|
465
|
+
5. **Classes are dropped** after the cascade is resolved; ids are kept only as link targets, prefixed.
|
|
466
|
+
6. **Remote images are blocked by default**, with their boxes kept, so tracking pixels need the app's
|
|
467
|
+
consent and showing images does not move the layout. An app that shows images should prefer
|
|
468
|
+
`'proxy'` over `'allow'`; it is in version 1 because it is what makes showing images private.
|
|
469
|
+
Which origins a proxy serves is the proxy's: the library writes URLs and reports the origins.
|
|
470
|
+
7. **One tag table generates the allowlists, the types and the components**, so they cannot disagree.
|
|
471
|
+
8. **Plain text is in version 1**, through the same tree, in a module without the parser.
|
|
472
|
+
9. **One document per body.** A body is parsed and rendered on its own; bodies are never joined. This
|
|
473
|
+
keeps MIME and PGP/MIME open ([Later](#later)): EFAIL's direct exfiltration relies on parts joined into
|
|
474
|
+
one document.
|
|
475
|
+
10. **No MIME in version 1.** The caller passes a decoded string, and a map or template for `cid:`
|
|
476
|
+
images.
|
|
477
|
+
|
|
478
|
+
## Plan
|
|
479
|
+
|
|
480
|
+
1. **Spike**: the parser candidates against the corpus (size, speed, tree equality); the style binding's
|
|
481
|
+
cost on the largest corpus email (render time, bundle size of the generated components). Not merged.
|
|
482
|
+
2. The tag table, the tree's types, `build-components.mjs`, `<mail-body>` and `<mail-node>`, over
|
|
483
|
+
hand-written trees.
|
|
484
|
+
3. `mail.parse`: HTML, the allowlists, URLs, images, ids.
|
|
485
|
+
4. Styles: the CSS parser, the cascade, legacy attributes, `@media`.
|
|
486
|
+
5. `mail.plain`.
|
|
487
|
+
6. `mail.text`, `mail.links`, the slots.
|
|
488
|
+
7. The corpus, hostile and browser tests; the docs page and a recipe (an inbox with a message pane,
|
|
489
|
+
plain and HTML messages, "show images").
|
|
490
|
+
|
|
491
|
+
## Open questions
|
|
492
|
+
|
|
493
|
+
Answered: the parser (our own; section 2 of the status), the style binding's cost (sinter change 3),
|
|
494
|
+
`media: 'narrow'` (375 px, evaluated rather than chosen by a breakpoint).
|
|
495
|
+
|
|
496
|
+
- **Size and speed** of the browser path: 47 kB gzip and about twice the iframe's time on a large
|
|
497
|
+
newsletter. Being investigated (`docs/proposals/sinter-mail-performance.md`).
|
|
498
|
+
- **`data:` images**: kept up to 65,536 characters by default (`dataImages`); whether that is the right bound.
|
|
499
|
+
- **Outlook's conditional comments**: dropped with their content, as the browser treats them; whether
|
|
500
|
+
emails exist whose content is only inside `<!--[if mso]>` needs a corpus of real mail.
|
|
501
|
+
- **Firefox and Safari**: the cascade writes `-webkit-center` and `-webkit-left`/`-right` as Chromium's
|
|
502
|
+
hints do; the tests run in Chromium only.
|
|
503
|
+
- **Reconstruction of formatting elements** can make the tree much larger than its input (many distinct
|
|
504
|
+
unclosed formatting elements, re-created after each block), as in browsers; a budget on the tree's
|
|
505
|
+
size would bound it.
|
|
506
|
+
- **sinter's expansion budget** (10,000 rows and components per page at build time): a very large email
|
|
507
|
+
folded at build time renders in the browser instead (SN536).
|
|
508
|
+
|
|
509
|
+
## Later
|
|
510
|
+
|
|
511
|
+
- **MIME**: reading a message into its bodies and attachments, through
|
|
512
|
+
[postal-mime](https://github.com/postalsys/postal-mime) (browser and Node, limits on nesting, headers
|
|
513
|
+
and parts, careful charset handling), not a parser of our own. It joins a message's HTML parts into one
|
|
514
|
+
string, which is safe only for content that was all encrypted or all not: see PGP.
|
|
515
|
+
- **PGP/MIME**: the app decrypts and verifies (openpgp.js in a `data-sn-call` action); this library would
|
|
516
|
+
check the outer structure (`multipart/encrypted` with its two parts, nothing else), read the decrypted
|
|
517
|
+
payload, and mark which bodies were encrypted or signed. Verifying a `multipart/signed` part needs its
|
|
518
|
+
raw bytes, which postal-mime does not return: to be asked upstream.
|
|
519
|
+
- **Quoted replies in HTML email** (`blockquote type=cite`, Gmail's and Outlook's markers), into `part`.
|
|
520
|
+
- **Background images**, through a checked `background` attribute on tables and cells.
|
package/llms.txt
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# @tiavision/sinter-mail
|
|
2
|
+
|
|
3
|
+
> Email bodies in a sinter app, without an iframe: `mail.parse(html, options)` turns an email's HTML into a sanitized tree (the browser's own tree construction, every element's CSS resolved), `mail.plain(text, options)` does the same for plain text, and `<mail-body data-sn-prop="{ body }">` renders the tree as part of the page. Pure helpers: an email in a `file:` resource is plain HTML at build time.
|
|
4
|
+
|
|
5
|
+
Setup: `sinter({ components: ['@tiavision/sinter-mail'] })`; `export * as mail from '@tiavision/sinter-mail'` in src/sinter.helpers.ts; `export type { Body, Element } from '@tiavision/sinter-mail'` in src/sinter.types.ts. Lazy parser: also `lazy: ['@tiavision/sinter-mail']` (a let over mail.parse is undefined until it loads).
|
|
6
|
+
|
|
7
|
+
- `mail.parse(html, { images, proxy, cid, media, dataImages })`: `images` 'block' (default: remote images left out, their box kept) | 'allow' | 'proxy' (with `proxy: '/img?url={url}'`, `{url}` once); `cid` a map `{ 'id@host': url }` or a template with `{cid}`; `media` 'wide' (800 px, default) | 'narrow' (375 px), the width `@media` rules are evaluated at; `dataImages` the largest data: image kept (characters, default 65536). Invalid options throw. Same source and options give the same frozen tree.
|
|
8
|
+
- `mail.plain(text, { flowed, delsp })`: paragraphs, autolinks, `>` quotes (class mail-quote), `-- ` signature (class mail-signature); `flowed` for format=flowed.
|
|
9
|
+
- `mail.text(node)`: the text, for previews. `mail.links(body)`: every link with its text.
|
|
10
|
+
- `body.images.origins`: the origins of the remote images, for a "show images from …" control.
|
|
11
|
+
- `<mail-body>` slots: `link` (`$slot.node`, its children through `<slot></slot>`) and `image` (`$slot.node.attrs.src` absent when blocked).
|
|
12
|
+
- `mail.progressive(tree)`: `<mail-body data-sn-prop="{ body: mail.progressive(tree) }">` renders a long body progressively, its first 200 nodes first, the rest in steps of 5 to 15 ms after a paint; a body not numbered renders whole (static pages stay script-free).
|
|
13
|
+
|
|
14
|
+
Styles: the email's own win over the page's (inline); the page fills in what the email does not set (fonts, link colours). Kept: colours, fonts, text, box, borders, tables, display, float. Never: position, url(), web fonts, :hover, negative margins.
|
|
15
|
+
|
|
16
|
+
CSP: rendered in the browser, nothing beyond `script-src 'self'; style-src 'self'`. Folded at build time (file: emails): `style-src-attr 'unsafe-inline'`.
|
|
17
|
+
|
|
18
|
+
Security: nothing runs (no script, handler, javascript: link, SVG, form, iframe), nothing loads without the app (images blocked or through its proxy, no CSS url()), nothing leaves the email's box, no class or stylesheet reaches the page, ids only for in-email links (prefixed mail-).
|
|
19
|
+
|
|
20
|
+
Guide: docs/mail.md. Design: docs/proposals/sinter-mail.md.
|
package/package.json
CHANGED
|
@@ -1,6 +1,67 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tiavision/sinter-mail",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Email bodies for sinter: HTML and plain-text mail parsed into a tree that folds at build time, rendered by mail-* components without an iframe.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "Tia Heinrich",
|
|
7
|
+
"homepage": "https://github.com/tiavision/sinter-mail#readme",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://github.com/tiavision/sinter-mail.git"
|
|
11
|
+
},
|
|
12
|
+
"bugs": {
|
|
13
|
+
"url": "https://github.com/tiavision/sinter-mail/issues"
|
|
14
|
+
},
|
|
15
|
+
"keywords": [
|
|
16
|
+
"sinter",
|
|
17
|
+
"email",
|
|
18
|
+
"mail",
|
|
19
|
+
"html",
|
|
20
|
+
"sanitizer",
|
|
21
|
+
"components"
|
|
22
|
+
],
|
|
23
|
+
"type": "module",
|
|
24
|
+
"sideEffects": false,
|
|
25
|
+
"sinter": "./sinter",
|
|
26
|
+
"exports": {
|
|
27
|
+
".": "./sinter/index.ts",
|
|
28
|
+
"./parser": "./sinter/engine.ts",
|
|
29
|
+
"./package.json": "./package.json"
|
|
30
|
+
},
|
|
31
|
+
"files": [
|
|
32
|
+
"sinter",
|
|
33
|
+
"!sinter/sinter.components.d.ts",
|
|
34
|
+
"docs",
|
|
35
|
+
"llms.txt",
|
|
36
|
+
"README.md"
|
|
37
|
+
],
|
|
38
|
+
"scripts": {
|
|
39
|
+
"build:entities": "node scripts/build-entities.mjs",
|
|
40
|
+
"build:components": "node --experimental-strip-types scripts/build-components.mjs",
|
|
41
|
+
"check": "sinter check",
|
|
42
|
+
"typecheck": "tsc --noEmit",
|
|
43
|
+
"test": "vitest run"
|
|
44
|
+
},
|
|
45
|
+
"peerDependencies": {
|
|
46
|
+
"@tiaforge-ui/sinter": ">=0.20.0 <1"
|
|
47
|
+
},
|
|
48
|
+
"engines": {
|
|
49
|
+
"node": "^20.19.0 || >=22.12.0"
|
|
50
|
+
},
|
|
51
|
+
"publishConfig": {
|
|
52
|
+
"access": "public"
|
|
53
|
+
},
|
|
54
|
+
"devDependencies": {
|
|
55
|
+
"@tiaforge-ui/sinter": "0.20.0",
|
|
56
|
+
"@types/jsdom": "30.0.0",
|
|
57
|
+
"@types/node": "26.6.6",
|
|
58
|
+
"character-entities": "2.0.2",
|
|
59
|
+
"character-entities-legacy": "3.0.0",
|
|
60
|
+
"jsdom": "31.0.1",
|
|
61
|
+
"parse5": "8.1.1",
|
|
62
|
+
"playwright": "1.63.0",
|
|
63
|
+
"typescript": "7.0.2",
|
|
64
|
+
"vite": "8.3.5",
|
|
65
|
+
"vitest": "5.1.0"
|
|
66
|
+
}
|
|
67
|
+
}
|