@typstream/html-compat 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ikram Hasan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @typstream/html-compat
 
-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.
+Typst 0.15.1's HTML export drops layout elements it can't express, and the text inside them: `#grid[…]`, `#align(center)[…]`, `#rect[…]`, `#place(…)`, `#stack`, `#columns`, `#pad`, the transforms and `layout` all come out empty ("grid was ignored during HTML export"). This package is a Typst prelude that maps each one to HTML (or, for drawings, an inline SVG), plus the CSS for that HTML.
+
+```ts
+import { HTML_COMPAT_PATH, htmlCompatCss, htmlCompatPreamble, htmlCompatSource } from "@typstream/html-compat";
+
+engine.set_source(HTML_COMPAT_PATH, htmlCompatSource); // mount the prelude
+engine.set_source("/main.typ", htmlCompatPreamble + document); // diagnostics: shift spans by the preamble's length
+const { html } = engine.compile_html();
+// In the page: <style>{htmlCompatCss}</style> and the output inside <div class="typstream">.
+```
+
+`htmlCompat` is the same as a `TypstreamPlugin` (files, preamble, sanitizer allowances). The preamble imports the prelude, applies it with `#show: html-compat`, and replaces `layout` with one that works in HTML. The rules act only when `target()` is `"html"`, so the same preamble leaves paged output byte-identical (tested).
+
+## What it does
+
+| Element | HTML |
+|---|---|
+| `grid` | CSS grid (`div.ts-grid`). Cells are placed like Typst places them (spans, explicit `x`/`y`); fill, stroke, align and inset may be functions of `(x, y)`; `hline`/`vline` become cell borders. |
+| `table` | Native `<table>`; each cell gets a `div.ts-cell` with its resolved fill, inset and alignment. `stroke: none` removes the borders. |
+| `align` | `div.ts-align` with `text-align`; blocks inside move the same way. Vertical alignment is dropped. |
+| `block`, `box` | `div.ts-block` / `span.ts-box` with width, height, fill, stroke, inset, radius, baseline. |
+| `rect`, `square`, `circle`, `ellipse` | `div.ts-shape` with the same properties. |
+| `stack`, `columns`, `colbreak`, `pad` | flexbox, CSS columns, `break-after: column`, padding. |
+| `place` | Absolutely positioned against the nearest box, block or shape, inside its `inset` as in Typst (the container writes its inset as `--ts-inset-top`/`-right`/`-bottom`/`-left`); text with a vertical alignment gets Typst's text box, cap height to baseline (`text-box`). `float: true` stays in flow. |
+| `v`, `h` | Fixed-size gaps. Fractional spacing (`h(1fr)`) becomes a small gap. Weak spacing and spacing in math are left to Typst. |
+| `pagebreak` | `div.ts-pagebreak`: a rule on screen, a page break in print. |
+| `move`, `rotate`, `scale`, `skew` | CSS transforms. `hide` is `visibility: hidden`. `repeat` repeats its body, clipped to the box. |
+| `line` | A border when horizontal; otherwise drawn. |
+| `curve`, `polygon`, angled lines; boxes and blocks that hold them; boxes and blocks made only of `place`d pieces (diagrams, CeTZ canvases); equations with `cancel` | Inline SVG (`html.frame`) in a `.ts-frame` with `role="img"` and the text as `aria-label` (`aria-hidden` when it has no text). |
+| Numbered block equations | `div.ts-equation` with the number. `overline` in math becomes an accent (MathML has no overline). |
+| `enum` with a pattern (`"a)"`) | Explicit markers. |
+| `layout(f)` | Calls `f` with a fixed size: `compat-size`, the text width of an A4 page. |
+
+Inside a box (an inline element), the prelude writes `span.ts-b` instead of `div`: a `<div>` there would make the browser close the paragraph and move everything after it out.
+
+## Known gaps
+
+- **Pages need @typstream/dom.** The prelude writes each block's page settings (size, margins, columns, binding,
+  numbering, header and footer) on the engine's source anchors, and marks where the page counter is set; dom's HTML
+  renderer lays the pages out from them. Typst still warns ("page set rule was ignored during HTML export", listed in
+  `KNOWN_HTML_WARNINGS`).
+- **Drawn content** (`.ts-frame`) is SVG: its text is in `aria-label`, not selectable. A drawing without text is hidden from assistive technology (`aria-hidden`): there is nothing to read out.
+- `enum(full: true)` with a pattern shows plain numbers; the `augment` line of a matrix is dropped by Typst's MathML export.
+- **Table** strokes other than the default or `none`, and `table.hline`/`table.vline`, are not drawn.
+- **fletcher 0.5.8** diagrams stay empty: its cetz 0.3.4 canvas calls `layout` inside `context`, within the package, where neither the prelude's `layout` nor its drawing detection reaches. CeTZ 0.5 canvases (cetz, cetz-plot, alchemist) become `.ts-frame` SVG and are in the matrix.
+
+## Tests
+
+The tests compile through `@typstream/engine-wasm` and compare with native `typst` 0.15.1 (paged text via pdf.js), so they need the engine built, `cargo` (for Typst's fonts) and `typst` on `PATH`. CI runs them in the `Engine (wasm)` job.
+
+- `coverage.test.ts`: the coverage matrix (`__tests__/support/matrix.ts`). Every entry compiles with no "ignored during HTML export" warning, and its HTML holds every letter and digit of its paged text, except documented gaps. Entries marked `nativeDrops` are checked to lose something without the prelude. The HTML must not put a `<div>` inside a `<p>` or `<span>`.
+- `corpus.test.ts`: every `corpus/edu` document, with each one's known gap (page numbers, headers, PDF text-layer artifacts) listed.
+- `paged.test.ts`: every SVG page is byte-identical with and without the prelude.
+
+Edit `typst/html-compat.typ` and `css/html-compat.css`, then `pnpm embed` (or `pnpm build`) to regenerate `src/assets.generated.ts`. A test fails when it's stale.
+
+## License
+
+MIT

package/css/html-compat.css

@@ -0,0 +1,558 @@
+/*
+ * @typstream/html-compat: styles for the HTML that html-compat.typ emits, and Typst-like
+ * defaults for the elements Typst's HTML export writes natively (tables, math).
+ *
+ * Everything is scoped to the renderer's root element, `.typstream`, and wrapped in
+ * :where() so an app's own rules win without !important. Inline `style` attributes
+ * carry the per-element values from the document (sizes, colors, strokes).
+ */
+
+/* Top-level place() is positioned against the document. */
+:where(.typstream) {
+  position: relative;
+}
+
+/* Block elements inside a box are spans (a div would end the paragraph); this makes them blocks.
+   Rules below that set another display (grid, flex) come later and win. */
+:where(.typstream .ts-b) {
+  display: block;
+}
+
+/* Typst's text, as the engine's layout profile (#129) sets it on pages: Libertinus Serif at 11pt, lines a constant
+   1.3em apart, ragged right, no hyphenation. The fonts are the engine's own (dom's `registerTypstFonts`), registered
+   with the profile's line box as their ascent and descent (1.054em and 0.246em, no gap), so a line box 1.3em tall
+   has the baseline where Typst puts it, in any of them and any size. `line-height: normal` would be the same box,
+   but browsers round a font's ascent and descent to whole pixels: lines would drift from Typst's by a fraction of
+   a pixel each. Text the base font lacks falls back to the engine's script fonts, as in Typst. */
+:where(.typstream) {
+  font-family:
+    typstream-libertinus-serif, typstream-noto-naskh-arabic, typstream-noto-serif-bengali,
+    typstream-noto-serif-devanagari, "Libertinus Serif", serif;
+  font-size: 11pt;
+  font-weight: 400;
+  line-height: 1.3;
+  text-align: start;
+  hyphens: manual;
+  font-kerning: normal;
+  font-synthesis: none;
+  text-rendering: geometricPrecision;
+}
+:where(.typstream) p {
+  margin-block: 0.56em;
+}
+/* `par.first-line-indent` without `all`: only a paragraph right after another is indented. */
+:where(.typstream) p + p.ts-indent {
+  text-indent: var(--ts-indent);
+}
+:where(.typstream) :is(h1, h2, h3, h4, h5, h6) {
+  font-size: 1em;
+  font-weight: 700;
+  margin-block: var(--ts-above, 0.71em) var(--ts-below, 0.3em);
+}
+/* A block's own spacing (html-compat.typ's `.ts-sp`), reset for what it holds. */
+:where(.typstream) :is(h1, h2, h3, h4, h5, h6) > *,
+:where(.typstream .ts-sp) > * {
+  --ts-above: initial;
+  --ts-below: initial;
+}
+:where(.typstream .ts-sp) {
+  margin-block: var(--ts-above, 0.56em) var(--ts-below, 0.56em);
+}
+:where(.typstream) h2 {
+  font-size: 1.4em;
+}
+:where(.typstream) h3 {
+  font-size: 1.2em;
+}
+:where(.typstream) :is(code, pre, kbd, samp) {
+  font-family: typstream-dejavu-sans-mono, "DejaVu Sans Mono", monospace;
+  font-size: 0.8em;
+}
+:where(.typstream) pre {
+  margin-block: 0.56em;
+  white-space: pre;
+}
+/* Text with its own line box (html-compat.typ's `.ts-edges`): a strut as tall, its letters with none of theirs. */
+:where(.typstream .ts-strut) {
+  display: inline-block;
+  width: 0;
+}
+:where(.typstream .ts-edges) .typstream-t {
+  line-height: 0;
+}
+
+/* Text decorations from the font, as Typst draws them. */
+:where(.typstream) :is(u, s, [style*="text-decoration"]) {
+  text-decoration-thickness: from-font;
+  text-underline-offset: from-font;
+}
+/* Typst sets super- and subscripts with the font's own glyphs where it has them (Libertinus Serif does). */
+:where(.typstream) :is(sup, sub) {
+  font-size: 1em;
+  vertical-align: baseline;
+}
+:where(.typstream) sup {
+  font-variant-position: super;
+}
+:where(.typstream) sub {
+  font-variant-position: sub;
+}
+/* A highlight covers the font's ascender to its descender: the line box less 0.16em at the top. */
+:where(.typstream) mark {
+  background: linear-gradient(transparent 0.16em, var(--ts-mark, #fffd11a1) 0.16em);
+  color: inherit;
+}
+/* Links look like the text around them, as on pages. */
+:where(.typstream) a {
+  color: inherit;
+  text-decoration: none;
+}
+
+/* Lists (html-compat.typ): a marker column as wide as the widest marker, the bodies after it; the items' gap is on
+   the list. */
+:where(.typstream .ts-list) {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  align-items: baseline;
+  column-gap: 0.5em;
+  margin-block: 0.56em;
+  padding: 0;
+  list-style: none;
+}
+:where(.typstream .ts-list) > li {
+  display: contents;
+}
+:where(.typstream .ts-list) > li > .ts-marker {
+  justify-self: end;
+}
+:where(.typstream .ts-terms) {
+  display: grid;
+  margin-block: 0.56em;
+}
+:where(.typstream .ts-terms) :is(dt, dd) {
+  display: inline;
+  margin: 0;
+}
+
+/* Math: Typst's own math font. Without a math font, browsers can't stretch delimiters
+   and fall back to whatever has the math alphanumerics (PLAN.md §6.5). */
+:where(.typstream) math {
+  /* biome-ignore lint/a11y/useGenericFontNames: `math` is the generic family (CSS Fonts 4). */
+  font-family: "New Computer Modern Math", math;
+}
+/* Equations (html-compat.typ) are Typst's drawings; their MathML is for screen readers only. A display equation is
+   centred on its line, its number at the end, both vertically centred. */
+:where(.typstream .ts-sr) {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+/* Typst writes `display: block` on a frame it finds at a block's start; an equation is in its line. */
+:where(.typstream .ts-math) svg {
+  display: inline !important;
+  /* Its bottom edge is its baseline: the equation's depth below the text's (html-compat.typ measures it). */
+  vertical-align: var(--ts-depth, baseline);
+}
+/* An equation no deeper than the line: from the bottom of the text's line box, as Typst's line holds it, raised by
+   what the line is deeper (0.246em less its depth). From the baseline, it would stick out of a line as tall as it:
+   browsers round the font's ascent and descent to pixels, which moves the baseline in the line box. */
+:where(.typstream .ts-math.ts-flat) svg {
+  vertical-align: text-bottom;
+  margin-block-end: var(--ts-lift);
+}
+:where(.typstream .ts-equation) {
+  display: grid;
+  grid-template-columns: 1fr auto 1fr;
+  align-items: center;
+  margin-block: 0.56em;
+  padding-top: 0.02px;
+}
+:where(.typstream .ts-equation-body) {
+  grid-column: 2;
+}
+:where(.typstream .ts-equation-number) {
+  grid-column: 3;
+  justify-self: end;
+}
+
+/* Strokes (html-compat.typ's `_box-props`): centred on the element's edge, half outside, taking no room, as Typst
+   draws them. Each side's border and width come from custom properties, reset on every stroked element so they
+   aren't inherited from one around it. */
+:where(.typstream .ts-stroked) {
+  --ts-bt: none;
+  --ts-br: none;
+  --ts-bb: none;
+  --ts-bl: none;
+  --ts-wt: 0pt;
+  --ts-wr: 0pt;
+  --ts-wb: 0pt;
+  --ts-wl: 0pt;
+  position: relative;
+}
+:where(.typstream .ts-stroked)::before {
+  content: "";
+  position: absolute;
+  inset: calc(var(--ts-wt) / -2) calc(var(--ts-wr) / -2) calc(var(--ts-wb) / -2) calc(var(--ts-wl) / -2);
+  border-top: var(--ts-bt);
+  border-right: var(--ts-br);
+  border-bottom: var(--ts-bb);
+  border-left: var(--ts-bl);
+  border-radius: inherit;
+  pointer-events: none;
+}
+
+/* Figures: centred, their caption 0.65em under them (`figure.gap`), as on pages. */
+:where(.typstream) figure {
+  margin: 0.56em 0;
+  text-align: center;
+}
+/* A figure with its own gap to its caption (html-compat.typ's `.ts-figure`, around it) is spaced by that. */
+:where(.typstream .ts-figure) {
+  margin: 0.56em 0;
+}
+:where(.typstream .ts-figure) > figure {
+  margin: 0;
+}
+:where(.typstream) figure > :not(figcaption) {
+  margin-inline: auto;
+}
+:where(.typstream) figcaption {
+  margin-block-start: var(--ts-gap, 0.65em);
+  color: inherit;
+}
+
+/* An outline (html-compat.typ): a line per entry, its dots filling the room to the page number. */
+:where(.typstream .ts-outline-entry) {
+  display: flex;
+  align-items: baseline;
+}
+:where(.typstream .ts-outline-entry) > a {
+  display: contents;
+}
+:where(.typstream .ts-outline-prefix) {
+  flex-shrink: 0;
+}
+:where(.typstream .ts-outline-fill) {
+  flex: 1 1 0;
+  min-width: 1em;
+  margin-inline: 0.25em;
+  overflow: hidden;
+  white-space: nowrap;
+  letter-spacing: 0.15em;
+  text-align: justify;
+  text-align-last: justify;
+}
+
+/* A block quote (html-compat.typ): padded by 1em, 2.4em above and 1.8em below, its attribution 0.9em under it. */
+:where(.typstream .ts-quote) {
+  margin: 2.4em 1em 1.8em;
+}
+:where(.typstream .ts-attribution) {
+  margin-block-start: 0.9em;
+  text-align: end;
+}
+
+/* Layout containers. Blocks inside an align() move like its text. An align() is spaced by what it holds (its
+   margins collapse through it); a pad's content, or what a vertical align() holds, is spaced as one paragraph. */
+:where(.typstream) :is(.ts-align-v, .ts-pad) {
+  margin-block: 0.56em;
+}
+:where(.typstream .ts-align-center) > * {
+  margin-inline: auto;
+}
+:where(.typstream) :is(.ts-align-end, .ts-align-right) > * {
+  margin-inline-start: auto;
+}
+:where(.typstream .ts-align-v) {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+:where(.typstream .ts-grid) {
+  display: grid;
+}
+/* A table's rows hold its semantics (ARIA roles); its cells are the grid's items. Tables are spaced as blocks. */
+:where(.typstream .ts-row) {
+  display: contents;
+}
+:where(.typstream) :is(.ts-grid, .ts-columns, .ts-stack) {
+  margin-block: 0.56em;
+}
+:where(.typstream .ts-cell) {
+  min-width: 0;
+  box-sizing: border-box;
+}
+:where(.typstream .ts-valign) {
+  display: flex;
+  flex-direction: column;
+}
+:where(.typstream .ts-stack) {
+  display: flex;
+}
+:where(.typstream .ts-columns) {
+  column-fill: balance;
+}
+:where(.typstream .ts-colbreak) {
+  break-after: column;
+}
+:where(.typstream .ts-pagebreak) {
+  break-after: page;
+}
+/* On the renderer's pages a page break is where a page ends, nothing to see. */
+:where(.typstream .typstream-flow .ts-pagebreak) {
+  height: 0;
+}
+
+/* Boxes and blocks. Typst draws strokes centred on the edge and counts them in the size. */
+:where(.typstream) :is(.ts-block, .ts-shape, .ts-box, .ts-place) {
+  box-sizing: border-box;
+}
+:where(.typstream) :is(.ts-block, .ts-shape) {
+  position: relative;
+  margin-block: var(--ts-above, 0.56em) var(--ts-below, 0.56em);
+}
+/* A block is as wide as its content unless it has a width. */
+:where(.typstream .ts-block) {
+  width: fit-content;
+}
+:where(.typstream .ts-box) {
+  display: inline-block;
+  position: relative;
+  vertical-align: baseline;
+}
+/* box(width: 1fr) takes the rest of a line in Typst; HTML has no inline equivalent. */
+:where(.typstream .ts-box.ts-fr) {
+  min-width: 4em;
+  overflow: hidden;
+  white-space: nowrap;
+  vertical-align: bottom;
+}
+/* repeat() fills its box in Typst: its copies stop at the box's edge (or the line's) instead of
+   spilling past it. Clipped by `clip-path`, which leaves its baseline on its text's, as Typst's;
+   `overflow` would move it to the box's bottom edge (WebKit's even with `overflow: clip`). */
+:where(.typstream .ts-repeat) {
+  display: inline-block;
+  max-width: 100%;
+  clip-path: inset(0);
+  white-space: nowrap;
+}
+/* Empty shapes are drawings of a size; with content they size to it. */
+:where(.typstream .ts-shape:empty) {
+  min-height: 1em;
+}
+:where(.typstream .ts-line) {
+  height: 0;
+  margin: 0.56em 0;
+  /* Not empty: Typst spaces it from both neighbours, where CSS would collapse its margins through it. */
+  padding-top: 0.02px;
+}
+:where(.typstream .ts-empty-line) {
+  display: block;
+  height: 0.658em;
+}
+:where(.typstream .ts-transform) {
+  width: fit-content;
+}
+:where(.typstream .ts-hide) {
+  visibility: hidden;
+}
+
+/* place(): absolute, against the nearest block, shape or box (or the document), inside its inset.
+   A container with an inset writes it as these properties (html-compat.typ's `_inset-vars`); every
+   element a .ts-place can be positioned against resets them, so they never come from further out.
+   A place resets them for what it holds, not for itself: its own offsets read them. */
+:where(.typstream),
+:where(.typstream) :is(.ts-block, .ts-shape, .ts-box, .ts-transform, .ts-place > *) {
+  --ts-inset-top: 0pt;
+  --ts-inset-right: 0pt;
+  --ts-inset-bottom: 0pt;
+  --ts-inset-left: 0pt;
+}
+:where(.typstream .ts-place) {
+  position: absolute;
+}
+/* Placed text with a vertical alignment: its box runs from 1.054em above the baseline to 0.246em
+   below it, the text edges of the engine's layout profile (#129), not over the whole line, so it
+   lands where paged output puts it: trimmed to the cap height and the baseline, then padded out.
+   Only text: an image or tall math in a trimmed line would stick out above it. */
+:where(.typstream .ts-place-text) {
+  text-box: trim-both cap alphabetic;
+  padding-block: calc(1.054em - 1cap) 0.246em;
+}
+:where(.typstream .ts-place.ts-float) {
+  position: static;
+}
+
+/* Spacing. */
+:where(.typstream .ts-h) {
+  display: inline-block;
+}
+/* h(1fr) takes the rest of the line: the renderer's pages give one in a run of inline content
+   (`.typstream-fill`) what its line leaves, and make a run with more a row of its pieces (`.typstream-row`,
+   `.typstream-seg`), the spacing growing between them. */
+:where(.typstream .ts-hfill) {
+  flex-basis: 0;
+}
+
+/* Drawings (html.frame): inline SVG, scaled down to fit narrow containers. */
+:where(.typstream .ts-frame) svg {
+  max-width: 100%;
+  height: auto;
+}
+/* Typst writes `display: block` on every picture's SVG (typst-html's make_block_level); one in a line (a box, a
+   polygon) sits on the baseline as on pages, and the line's alignment moves it. */
+:where(.typstream) span.ts-frame:not(.ts-b) {
+  display: inline-block;
+}
+:where(.typstream) :is(div.ts-frame, span.ts-frame.ts-b) {
+  width: fit-content;
+  margin-block: 0.56em;
+  padding-top: 0.02px;
+}
+
+/* Last, to win over the margins above. */
+/* Typst spaces blocks apart, not from the edges of what contains them. */
+:where(.typstream)
+  :is(
+    .ts-cell,
+    .ts-valign-body,
+    .ts-align-body,
+    .ts-block,
+    .ts-shape,
+    .ts-box,
+    .ts-stack-item,
+    .ts-place,
+    .ts-align-v,
+    .ts-pad,
+    .ts-item-body,
+    .ts-columns,
+    .ts-marginal,
+    figure
+  )
+  > :is(:first-child, .ts-place:first-child + *),
+:where(.typstream)
+  :is(
+    .ts-cell,
+    .ts-valign-body,
+    .ts-align-body,
+    .ts-block,
+    .ts-shape,
+    .ts-box,
+    .ts-stack-item,
+    .ts-place,
+    .ts-align-v,
+    .ts-pad,
+    .ts-item-body,
+    .ts-columns,
+    .ts-marginal,
+    figure
+  )
+  > .ts-align:first-child
+  > :first-child {
+  margin-block-start: 0;
+}
+:where(.typstream)
+  :is(
+    .ts-cell,
+    .ts-valign-body,
+    .ts-align-body,
+    .ts-block,
+    .ts-shape,
+    .ts-box,
+    .ts-stack-item,
+    .ts-place,
+    .ts-align-v,
+    .ts-pad,
+    .ts-item-body,
+    .ts-columns,
+    .ts-marginal,
+    figure
+  )
+  > :last-child,
+:where(.typstream)
+  :is(
+    .ts-cell,
+    .ts-valign-body,
+    .ts-align-body,
+    .ts-block,
+    .ts-shape,
+    .ts-box,
+    .ts-stack-item,
+    .ts-place,
+    .ts-align-v,
+    .ts-pad,
+    .ts-item-body,
+    .ts-columns,
+    .ts-marginal,
+    figure
+  )
+  > .ts-align:last-child
+  > :last-child {
+  margin-block-end: 0;
+}
+/* A column starts at its top, as a page does. */
+:where(.typstream) .ts-colbreak + * {
+  margin-block-start: 0;
+}
+:where(.typstream) :has(+ .ts-colbreak) {
+  margin-block-end: 0;
+}
+/* Spacing between blocks collapses as Typst's does (typst-layout's flow, distribute.rs): the larger of two gaps wins,
+   unless one is stronger. A block's own `above` and `below` (a heading's; html-compat.typ's `.ts-sp-a`, `.ts-sp-b`)
+   beat the paragraph spacing that blocks get by default (`auto`), even when smaller. */
+:where(.typstream) :is(h1, h2, h3, h4, h5, h6, .ts-sp-b) + :not(h1, h2, h3, h4, h5, h6, .ts-sp-a) {
+  margin-block-start: 0;
+}
+:where(.typstream) :not(h1, h2, h3, h4, h5, h6, .ts-sp-b):has(+ :is(h1, h2, h3, h4, h5, h6, .ts-sp-a)) {
+  margin-block-end: 0;
+}
+/* A tight list right after a paragraph (or text) is attached to it: its items' gap, `par.leading`, 0 on pages,
+   replaces the spacing between them (typst-layout's LIST_RULE, an attached weak `v`). Not after a blank line, which
+   ends the paragraph first: the renderer marks the blocks that start there (`data-typstream-start`). */
+:where(.typstream)
+  :is(p, span, strong, em, b, i, a, code, mark, sub, sup, u, s)
+  + .ts-tight:not([data-typstream-start]) {
+  margin-block-start: 0;
+}
+:where(.typstream) p:has(+ .ts-tight:not([data-typstream-start])) {
+  margin-block-end: 0;
+}
+/* In a container, html-compat.typ marks the blank line itself (`.ts-start`). */
+:where(.typstream .ts-start) {
+  display: none;
+}
+/* Spacing (`v`): Typst adds it to the gap its neighbours' spacing collapses to (distribute.rs, keep_spacing): the
+   stronger of the spacing below the block before it and above the one after (a block's own, a heading's, beats
+   paragraph spacing), or, when they are alike, the larger (here the one before). Weak spacing replaces that gap, as
+   fractional spacing does (distribute.rs trims weak spacing next to it). */
+:where(.typstream) .ts-v:not(.ts-v-both) + :not(h1, h2, h3, h4, h5, h6, .ts-sp-a),
+:where(.typstream) :is(h1, h2, h3, h4, h5, h6, .ts-sp-b) + .ts-v + :not(h1, h2, h3, h4, h5, h6, .ts-sp-a) {
+  margin-block-start: 0;
+}
+/* Between two blocks' own spacings both stay here, and between two paragraph spacings where the renderer marks the
+   `v` (`.ts-v-both`): Typst's is the larger, which @typstream/dom's pages keep (`collapseSpacing`). */
+:where(.typstream) :not(h1, h2, h3, h4, h5, h6, .ts-sp-b):has(+ .ts-v + :is(h1, h2, h3, h4, h5, h6, .ts-sp-a)) {
+  margin-block-end: 0;
+}
+:where(.typstream) :has(+ :is(.ts-v-weak, .ts-vfill)) {
+  margin-block-end: 0;
+}
+/* Text that isn't in a paragraph element (a tight list item's, the renderer's `.typstream-t`) is one in Typst, spaced
+   from spacing after it as a paragraph is. */
+:where(.typstream)
+  :is(.typstream-t, span, strong, em, b, i, a, code, mark, sub, sup, u, s)
+  + .ts-v:not(.ts-v-weak, .ts-vfill, :last-child) {
+  margin-block-start: 0.56em;
+}
+/* Spacing that ends what holds it: the weak spacing before it goes, as at the end of any region. */
+:where(.typstream) :has(+ .ts-v:last-child) {
+  margin-block-end: 0;
+}
+/* Typst drops the spacing above the first block of a page (the renderer's pages, below a break too). */
+:where(.typstream .typstream-flow) > :first-child,
+:where(.typstream .typstream-flow) > .ts-align:first-child > :first-child {
+  margin-block-start: 0;
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { TypstreamPlugin } from '@typstream/core';
+
+/** Where the engine mounts the prelude in its virtual file system. */
+declare const HTML_COMPAT_PATH = "/@typstream/html-compat.typ";
+/** The prelude's Typst source. Mount it at {@link HTML_COMPAT_PATH}. */
+declare const htmlCompatSource: string;
+/**
+ * The stylesheet for the prelude's HTML and Typst-like defaults for tables and math. Its rules
+ * are scoped to an element with class `typstream` (the renderer's root) and have zero
+ * specificity (`:where`), so an app's own rules win.
+ *
+ * Math needs the "New Computer Modern Math" font (the engine's math font) registered as a web
+ * font; without a math font browsers can't stretch delimiters.
+ */
+declare const htmlCompatCss: string;
+/**
+ * Typst to put before a document: imports the prelude and applies it. It also replaces
+ * `layout`, which HTML export would drop, with one that reports a fixed text width in HTML.
+ * The rules act only on the HTML target, so the same preamble is safe for paged output.
+ */
+declare const htmlCompatPreamble: string;
+/**
+ * Warnings the prelude can't prevent, as message substrings. A `#set page(...)` rule has no
+ * HTML equivalent (no pages); its header, footer and page numbers aren't in the HTML output.
+ */
+declare const KNOWN_HTML_WARNINGS: readonly string[];
+/**
+ * html-compat as a typstream plugin: the prelude file, the preamble, what the sanitizer must let
+ * through, and the stylesheet.
+ */
+declare const htmlCompat: TypstreamPlugin;
+
+export { HTML_COMPAT_PATH, KNOWN_HTML_WARNINGS, htmlCompat, htmlCompatCss, htmlCompatPreamble, htmlCompatSource };