@samva/markup 0.1.0

package/generated/sml-email-language-reference.md

@@ -0,0 +1,160 @@
+<!-- GENERATED by apps/api/scripts/generate-sml-reference.ts — do not edit by hand. -->
+
+# SML email language reference
+
+SML is JSX-strict markup: every tag is closed, every attribute is quoted (or
+`{numeric}`), and the vocabulary is closed. One email document has one
+`<Email>` root and compiles to email-safe table HTML.
+
+## Email primitives
+
+Styling is an email-safe subset of Tailwind utility classes on the `class`
+attribute. The compiler lowers this to table-based HTML with Outlook/Gmail
+fallbacks — you never write raw HTML.
+
+| Tag           | Attributes                                                    | Children                      | Notes                                                                                                                                                               |
+| ------------- | ------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Email>`     | lang, dir, width (1-10000), class                             | Subject?, Preview?, blocks    | Email document root. Exactly one root per template; wraps the whole message.                                                                                        |
+| `<Subject>`   | —                                                             | text, {{vars}}                | Email subject line. Text and interpolations only; must appear before body blocks.                                                                                   |
+| `<Preview>`   | —                                                             | text, {{vars}}                | Inbox preview text (hidden in the body). Text and interpolations only.                                                                                              |
+| `<Container>` | class, backgroundImage, backgroundPosition, backgroundSize    | blocks                        | Centered 600px max-width wrapper. Compiles to a table on the outlook-safe base.                                                                                     |
+| `<Section>`   | class, backgroundImage, backgroundPosition, backgroundSize    | blocks                        | Full-width band. Padding splits onto the inner cell for Outlook/Klaviyo.                                                                                            |
+| `<Row>`       | class                                                         | Column+                       | Horizontal layout. Children must be <Column>. Use instead of flex/grid.                                                                                             |
+| `<Column>`    | class, width, valign                                          | blocks                        | A cell inside a <Row>. `width` is an HTML width (e.g. "50%", "300").                                                                                                |
+| `<Heading>`   | level (1-6), class                                            | text, {{vars}}, strong, em, a | Renders <h1>-<h6> by `level` (default 1).                                                                                                                           |
+| `<Text>`      | class                                                         | text, {{vars}}, strong, em, a | Paragraph. Ships sane font-size/line-height/margin defaults.                                                                                                        |
+| `<Button>`    | href (required), class                                        | text, {{vars}}, strong, em    | Link styled as a button. Set padding via classes; the compiler injects the Outlook mso hack.                                                                        |
+| `<Image>`     | src (required), alt, width (0-10000), height (0-10000), class | Source?                       | Responsive image. Always set `alt` for accessibility. Add a <Source scheme="dark"> child to swap the asset in dark mode.                                            |
+| `<Source>`    | scheme (required), src (required)                             | void                          | Image source variant. Inside <Image>, `scheme="dark"` swaps the asset when dark-mode media queries are honored.                                                     |
+| `<Divider>`   | class                                                         | void                          | Horizontal rule (border-top).                                                                                                                                       |
+| `<Spacer>`    | height (required, 1-2000)                                     | void                          | Vertical gap of `height` px.                                                                                                                                        |
+| `<List>`      | type, class                                                   | ListItem+                     | Bulleted or numbered list. `type` is "unordered" (default) or "ordered". Children must be <ListItem>.                                                               |
+| `<ListItem>`  | class                                                         | text, {{vars}}, strong, em, a | A single list row. Inline content only (text, {{vars}}, strong/em/a).                                                                                               |
+| `<If>`        | test (required)                                               | blocks, Else?                 | Send-time conditional block. `test` is a predicate over declared variables (see "Send-time conditionals" below). Content: blocks, then an optional trailing <Else>. |
+| `<Else>`      | —                                                             | blocks                        | The false branch of an <If>. Valid only as the last direct child of <If>.                                                                                           |
+| `<a>`         | href (required), class                                        | text, {{vars}}, strong, em    | Inline link. It has deterministic theme-brand color and underline defaults; use safe classes to override either.                                                    |
+| `<strong>`    | —                                                             | text, {{vars}}, strong, em    | Bold inline text.                                                                                                                                                   |
+| `<em>`        | —                                                             | text, {{vars}}, strong, em    | Italic inline text.                                                                                                                                                 |
+
+- Interpolate variables with `{{name}}` (or `${name}`) inside text content.
+- Only `sm:` (min-width 640px, progressive enhancement) and `dark:` (color
+  families only) class variants are supported. `hover:`/`focus:`/`md:`/`lg:`/etc.
+  are rejected.
+
+## Send-time conditionals
+
+`<If test="...">...<Else>...</Else></If>` renders one branch per recipient at
+send time. Both branches compile into the email artifact behind hidden markers;
+the send-time interpolation step selects one branch and strips the markers before
+`{{}}` substitution.
+
+- `<Else>` is optional and, when present, must be the last direct child of
+  `<If>`. There is no `<ElseIf>` — nest another `<If>` inside `<Else>` instead.
+  Both elements accept the same email blocks as any other conditional section.
+- `test` is a closed predicate grammar over flat variable names and literals:
+  - Comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=`.
+  - Boolean keywords: `and`, `or`, `not`, plus
+    `( )` grouping.
+  - Literals: `'single-quoted strings'` or bare numbers. No arithmetic, function
+    calls, method calls, or dotted paths.
+  - A bare variable name means "present and non-empty"; a missing variable makes
+    every comparison false, including `!=`.
+
+## Utility classes
+
+Email styling uses this Tailwind subset. Arbitrary values (`w-[600px]`,
+`text-[#374151]`, `bg-[#0088cc]`) are allowed where noted.
+
+| Class           | What it sets                                                                                                                                                                                                                                                                                          |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `p-*`           | Padding on all sides (p-4 = 16px). Compiles onto table cells for Outlook.                                                                                                                                                                                                                             |
+| `px-*`          | Horizontal padding.                                                                                                                                                                                                                                                                                   |
+| `py-*`          | Vertical padding.                                                                                                                                                                                                                                                                                     |
+| `pt-*`          | Top padding.                                                                                                                                                                                                                                                                                          |
+| `pr-*`          | Right padding.                                                                                                                                                                                                                                                                                        |
+| `pb-*`          | Bottom padding.                                                                                                                                                                                                                                                                                       |
+| `pl-*`          | Left padding.                                                                                                                                                                                                                                                                                         |
+| `m-*`           | Margin on all sides. Warn tier — some clients strip margins. (warn: some clients strip it)                                                                                                                                                                                                            |
+| `mx-*`          | Horizontal margin; mx-auto centers block elements. (warn: some clients strip it)                                                                                                                                                                                                                      |
+| `my-*`          | Vertical margin. (warn: some clients strip it)                                                                                                                                                                                                                                                        |
+| `mt-*`          | Top margin. (warn: some clients strip it)                                                                                                                                                                                                                                                             |
+| `mr-*`          | Right margin. (warn: some clients strip it)                                                                                                                                                                                                                                                           |
+| `mb-*`          | Bottom margin. (warn: some clients strip it)                                                                                                                                                                                                                                                          |
+| `ml-*`          | Left margin. (warn: some clients strip it)                                                                                                                                                                                                                                                            |
+| `w-*`           | Width from the spacing scale (w-32 = 128px), w-full, or w-[600px]/w-[50%].                                                                                                                                                                                                                            |
+| `max-w-*`       | Max width from the container scale (max-w-lg = 512px) or max-w-[600px].                                                                                                                                                                                                                               |
+| `h-*`           | Height from the spacing scale (h-12 = 48px) or h-[80px].                                                                                                                                                                                                                                              |
+| `text-*`        | Font size with paired line-height (text-sm = 14px/20px) or bounded px value (text-[15px] = 15px/22.5px). Put an explicit leading-* after it to override line-height. Text alignment: text-left, text-center, text-right, text-justify. Text color from the palette (text-gray-700) or text-[#374151]. |
+| `leading-*`     | Line height: named ratios (leading-relaxed) or spacing steps (leading-6 = 24px).                                                                                                                                                                                                                      |
+| `font-*`        | Font weight: font-normal, font-medium, font-semibold, font-bold, ... Font stack: font-sans, font-serif, font-mono.                                                                                                                                                                                    |
+| `tracking-*`    | Letter spacing: tracking-tighter … tracking-widest (em-based; inlines fine in Outlook). Pair tracking-wide/wider with uppercase for eyebrows.                                                                                                                                                         |
+| `uppercase`     | Uppercase text transform.                                                                                                                                                                                                                                                                             |
+| `underline`     | Underlined text.                                                                                                                                                                                                                                                                                      |
+| `no-underline`  | Removes the underline (links render underlined by default in most clients).                                                                                                                                                                                                                           |
+| `bg-*`          | Background color from the palette (bg-white, bg-blue-600) or bg-[#0088cc].                                                                                                                                                                                                                            |
+| `bg-gradient-*` | Linear gradient background for hero sections: bg-gradient-to-b/t/l/r with from-{color} and to-{color}. Modern base compiles a CSS linear-gradient (plus a solid from-color fallback); the outlook-safe base degrades to the solid from-color — Outlook for Windows never renders the gradient.        |
+| `from-*`        | Gradient start color (from-indigo-600). Doubles as the solid fallback color on clients without gradient support (Outlook for Windows).                                                                                                                                                                |
+| `to-*`          | Gradient end color (to-purple-600).                                                                                                                                                                                                                                                                   |
+| `border-*`      | Solid border width: border (1px), border-2, border-0. Border color from the palette (border-gray-200).                                                                                                                                                                                                |
+| `rounded-*`     | Border radius (rounded-md = 6px). Ignored by Outlook for Windows — buttons degrade to square corners.                                                                                                                                                                                                 |
+| `rounded-t-*`   | Top border radius for card/header blocks (rounded-t-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                           |
+| `rounded-r-*`   | Right-side border radius (rounded-r-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                                           |
+| `rounded-b-*`   | Bottom border radius for card/footer blocks (rounded-b-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                        |
+| `rounded-l-*`   | Left-side border radius (rounded-l-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                                            |
+| `block`         | display: block.                                                                                                                                                                                                                                                                                       |
+| `inline-block`  | display: inline-block.                                                                                                                                                                                                                                                                                |
+| `hidden`        | display: none. Pair with sm:block for mobile-only content.                                                                                                                                                                                                                                            |
+
+Palette color families (each with the usual `50`-`950` steps, plus `white`,
+`black`, `transparent`): `amber`, `black`, `blue`, `brand`, `brand-foreground`, `cyan`, `emerald`, `fuchsia`, `gray`, `green`, `indigo`, `lime`, `mauve`, `mist`, `neutral`, `olive`, `orange`, `pink`, `purple`, `red`, `rose`, `sky`, `slate`, `stone`, `taupe`, `teal`, `violet`, `white`, `yellow`, `zinc`.
+
+## Rejected utilities
+
+These compile to hard errors — the message names the failing client and the
+supported alternative. Drop the feature rather than break a client.
+
+| Class / prefix | Why it is rejected                                                                           |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `flex`         | display:flex is unsupported in Outlook for Windows (Word engine) — use <Row>/<Column>        |
+| `inline-flex`  | display:inline-flex is unsupported in Outlook for Windows — use <Row>/<Column>               |
+| `grid`         | display:grid is unsupported in Outlook for Windows and Gmail — use <Row>/<Column>            |
+| `inline-grid`  | display:inline-grid is unsupported in Outlook for Windows — use <Row>/<Column>               |
+| `gap-`         | gap requires flex/grid, unsupported in Outlook for Windows — use padding on <Column>         |
+| `space-`       | space-* margins require selectors Gmail strips — use padding or <Spacer>                     |
+| `items-`       | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `justify-`     | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column> and text-center |
+| `self-`        | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `content-`     | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `order-`       | flex order is unsupported in Outlook for Windows — reorder the source instead                |
+| `absolute`     | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `relative`     | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `fixed`        | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `sticky`       | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `static`       | CSS position is ignored by Gmail and Outlook — remove it                                     |
+| `inset-`       | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `top-`         | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `right-`       | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `bottom-`      | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `left-`        | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `z-`           | z-index is ignored by Gmail and Outlook — remove it                                          |
+| `float-`       | float is unreliable across email clients — use <Row>/<Column>                                |
+| `shadow`       | box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead            |
+| `shadow-`      | box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead            |
+| `opacity-`     | opacity is unsupported in Outlook for Windows — bake the tint into the color                 |
+| `transform`    | CSS transforms are unsupported in email clients — remove them                                |
+| `rotate-`      | CSS transforms are unsupported in email clients — remove them                                |
+| `scale-`       | CSS transforms are unsupported in email clients — remove them                                |
+| `translate-`   | CSS transforms are unsupported in email clients — remove them                                |
+| `skew-`        | CSS transforms are unsupported in email clients — remove them                                |
+| `transition`   | transitions don't run in email — remove them                                                 |
+| `transition-`  | transitions don't run in email — remove them                                                 |
+| `duration-`    | transitions don't run in email — remove them                                                 |
+| `animate-`     | animations don't run in email — remove them                                                  |
+| `blur-`        | CSS filters are unsupported in most email clients — remove them                              |
+| `brightness-`  | CSS filters are unsupported in most email clients — remove them                              |
+| `grayscale`    | CSS filters are unsupported in most email clients — remove them                              |
+| `grayscale-`   | CSS filters are unsupported in most email clients — remove them                              |
+| `truncate`     | text truncation is unsupported in Outlook for Windows — shorten the copy                     |
+| `line-clamp-`  | line clamping is unsupported in email clients — shorten the copy                             |
+| `aspect-`      | aspect-ratio is unsupported in Outlook and Gmail — set width/height on <Image>               |
+| `overflow-`    | overflow is unreliable across email clients — restructure the layout                         |

package/generated/sml-language-reference.md

@@ -0,0 +1,220 @@
+<!-- GENERATED by apps/api/scripts/generate-sml-reference.ts — do not edit by hand. -->
+
+# SML language reference
+
+SML is JSX-strict markup: every tag is closed, every attribute is quoted (or
+`{numeric}`), and the vocabulary is closed. One document targets exactly one
+channel, declared by the root tag: `<Email>` compiles to email-safe table
+HTML, `<Sms>` to a plain-text message body, `<WhatsApp>` to a Meta template
+payload. Cross-channel compilation does not exist — one `.samva` file is one
+channel's template.
+
+## Email primitives
+
+Styling is an email-safe subset of Tailwind utility classes on the `class`
+attribute (email only). The compiler lowers this to table-based HTML with
+Outlook/Gmail fallbacks — you never write raw HTML.
+
+| Tag           | Attributes                                                    | Children                      | Notes                                                                                                                                                               |
+| ------------- | ------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Email>`     | lang, dir, width (1-10000), class                             | Subject?, Preview?, blocks    | Email document root. Exactly one root per template; wraps the whole message.                                                                                        |
+| `<Subject>`   | —                                                             | text, {{vars}}                | Email subject line. Text and interpolations only; must appear before body blocks.                                                                                   |
+| `<Preview>`   | —                                                             | text, {{vars}}                | Inbox preview text (hidden in the body). Text and interpolations only.                                                                                              |
+| `<Container>` | class, backgroundImage, backgroundPosition, backgroundSize    | blocks                        | Centered 600px max-width wrapper. Compiles to a table on the outlook-safe base.                                                                                     |
+| `<Section>`   | class, backgroundImage, backgroundPosition, backgroundSize    | blocks                        | Full-width band. Padding splits onto the inner cell for Outlook/Klaviyo.                                                                                            |
+| `<Row>`       | class                                                         | Column+                       | Horizontal layout. Children must be <Column>. Use instead of flex/grid.                                                                                             |
+| `<Column>`    | class, width, valign                                          | blocks                        | A cell inside a <Row>. `width` is an HTML width (e.g. "50%", "300").                                                                                                |
+| `<Heading>`   | level (1-6), class                                            | text, {{vars}}, strong, em, a | Renders <h1>-<h6> by `level` (default 1).                                                                                                                           |
+| `<Text>`      | class                                                         | text, {{vars}}, strong, em, a | Paragraph. Ships sane font-size/line-height/margin defaults.                                                                                                        |
+| `<Button>`    | href (required), class                                        | text, {{vars}}, strong, em    | Link styled as a button. Set padding via classes; the compiler injects the Outlook mso hack.                                                                        |
+| `<Image>`     | src (required), alt, width (0-10000), height (0-10000), class | Source?                       | Responsive image. Always set `alt` for accessibility. Add a <Source scheme="dark"> child to swap the asset in dark mode.                                            |
+| `<Source>`    | scheme (required), src (required)                             | void                          | Image source variant. Inside <Image>, `scheme="dark"` swaps the asset when dark-mode media queries are honored.                                                     |
+| `<Divider>`   | class                                                         | void                          | Horizontal rule (border-top).                                                                                                                                       |
+| `<Spacer>`    | height (required, 1-2000)                                     | void                          | Vertical gap of `height` px.                                                                                                                                        |
+| `<List>`      | type, class                                                   | ListItem+                     | Bulleted or numbered list. `type` is "unordered" (default) or "ordered". Children must be <ListItem>.                                                               |
+| `<ListItem>`  | class                                                         | text, {{vars}}, strong, em, a | A single list row. Inline content only (text, {{vars}}, strong/em/a).                                                                                               |
+| `<If>`        | test (required)                                               | blocks, Else?                 | Send-time conditional block. `test` is a predicate over declared variables (see "Send-time conditionals" below). Content: blocks, then an optional trailing <Else>. |
+| `<Else>`      | —                                                             | blocks                        | The false branch of an <If>. Valid only as the last direct child of <If>.                                                                                           |
+| `<a>`         | href (required), class                                        | text, {{vars}}, strong, em    | Inline link. It has deterministic theme-brand color and underline defaults; use safe classes to override either.                                                    |
+| `<strong>`    | —                                                             | text, {{vars}}, strong, em    | Bold inline text.                                                                                                                                                   |
+| `<em>`        | —                                                             | text, {{vars}}, strong, em    | Italic inline text.                                                                                                                                                 |
+
+- Interpolate variables with `{{name}}` (or `${name}`) inside text content.
+- Only `sm:` (min-width 640px, progressive enhancement) and `dark:` (color
+  families only) class variants are supported. `hover:`/`focus:`/`md:`/`lg:`/etc.
+  are rejected.
+
+## SMS documents
+
+| Tag      | Attributes      | Children                           | Notes                                                                                                           |
+| -------- | --------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `<Sms>`  | category        | verbatim text, {{vars}}, If        | SMS document root. The body is VERBATIM text — newlines and space runs are content. No layout tags, no classes. |
+| `<If>`   | test (required) | verbatim text, {{vars}}, If, Else? | Send-time conditional inline in the body. Content is verbatim text/{{vars}}, then an optional trailing <Else>.  |
+| `<Else>` | —               | verbatim text, {{vars}}, If        | The false branch of an <If>; must be its last child. Nothing may follow it, whitespace included.                |
+
+- The body is VERBATIM: newlines and runs of spaces are content and are
+  preserved exactly. There is no whitespace collapsing and no `class`
+  attribute anywhere — SMS has no styling.
+- `category` is optional authoring intent: `transactional`, `promotional`,
+  or `service_implicit`.
+- The compiler reports GSM-7/UCS-2 encoding and segment estimates (variables
+  count at a 16-character worst case) and warns on multi-segment bodies and
+  missing opt-out language (e.g. "Reply STOP to unsubscribe").
+- Example: `<Sms category="transactional">{{workspace}}: {{code}} is your
+code. Reply STOP to opt out.</Sms>`
+
+## WhatsApp documents
+
+| Tag          | Attributes                          | Children                                    | Notes                                                                                                                                                                              |
+| ------------ | ----------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<WhatsApp>` | name, language, category (required) | Header?, Body, Footer?, Buttons? (in order) | WhatsApp template root. Children are Meta's template anatomy in order: Header?, Body, Footer?, Buttons?. `name`/`language` default from the template slug/locale at the API layer. |
+| `<Header>`   | type                                | verbatim text, {{vars}}, If                 | Optional template header. `type` is "text" (default, ≤60 chars) or "image"/"video"/"document" (content is the media URL/handle).                                                   |
+| `<Body>`     | —                                   | verbatim text, {{vars}}, If                 | Required template body (≤1024 chars). Verbatim text, {{vars}}, and <If> conditionals.                                                                                              |
+| `<Footer>`   | —                                   | verbatim text, {{vars}}, If                 | Optional template footer (≤60 chars).                                                                                                                                              |
+| `<Buttons>`  | —                                   | Button+                                     | Interactive buttons container. Meta limits: ≤10 total, ≤2 url, ≤1 phone.                                                                                                           |
+| `<Button>`   | type (required), url, phone         | verbatim text, {{vars}}, If                 | `type` is "quick-reply" (label only), "url" (requires `url`, ≤2), "phone" (requires `phone`, ≤1), or "copy-code" (content is the code to copy). Label text ≤25 chars.              |
+| `<If>`       | test (required)                     | verbatim text, {{vars}}, If, Else?          | Send-time conditional inline in a text slot. Content is verbatim text/{{vars}}, then an optional trailing <Else>.                                                                  |
+| `<Else>`     | —                                   | verbatim text, {{vars}}, If                 | The false branch of an <If>; must be its last child. Nothing may follow it, whitespace included.                                                                                   |
+
+- Components follow Meta's template anatomy in order — `Header?`, `Body`
+  (required), `Footer?`, `Buttons?` — each at most once. Text slots are
+  verbatim like SMS; no `class` attributes.
+- `category` is required: `marketing`, `utility`, `authentication`, or
+  `service`. `name`/`language` are optional (defaulted from the template
+  slug and variant locale).
+- Meta limits compile as diagnostics: header/footer ≤60 chars, body ≤1024,
+  button labels ≤25 (warnings); button counts and missing `url`/`phone`
+  attributes are errors. Don't mix positional `{{1}}` and named `{{var}}`
+  placeholders.
+
+## Send-time conditionals
+
+`<If test="...">...<Else>...</Else></If>` renders one branch per recipient at
+send time, selected by the per-recipient variables. It works on every channel:
+both branches compile into the artifact (email HTML/text, sms body, whatsapp
+component text) behind hidden markers; the send-time interpolation step picks
+a branch and strips the markers before `{{}}` substitution — sent messages
+never contain markers or the untaken branch.
+
+- `<Else>` is optional and, when present, must be the last direct child of
+  `<If>`. There is no `<ElseIf>` — nest another `<If>` inside `<Else>` instead.
+  In email, both `<If>` and `<Else>` accept the same children as any other
+  block (Container, Section, Row, Heading, Text, Button, Image, Divider,
+  Spacer, and nested If). In sms/whatsapp text slots they carry verbatim text,
+  `{{vars}}`, and nested `<If>` inline.
+- `test` is a closed predicate grammar — comparisons and boolean combinators
+  over flat variable names and literals, nothing else:
+  - Comparison operators: `==`, `!=`, `>`, `>=`, `<`, `<=`.
+  - Boolean keywords: `and`, `or`, `not`, plus
+    `( )` grouping.
+  - Literals: `'single-quoted strings'` or bare numbers. No arithmetic, no
+    function calls, no method calls, no dotted paths — variable names are flat
+    (`plan`, not `user.plan`).
+  - A bare variable name (`seats`) means "present and non-empty"; a missing
+    variable makes every comparison false, including `!=`.
+  - Examples: `test="plan == 'pro'"`, `test="seats > 5 and plan != 'free'"`,
+    `test="not (region == 'eu' or region == 'uk')"`.
+- Full grammar and evaluation semantics live in `packages/markup/src/predicate.ts`
+  (parse / evaluate / print / collectPredicateVariables) — the same module the
+  compiler, checks, send-time evaluator, and canvas all share, so predicate
+  semantics cannot fork between them.
+
+## Utility classes (email only)
+
+Email styling uses this Tailwind subset. Arbitrary values (`w-[600px]`, `text-[#374151]`,
+`bg-[#0088cc]`) are allowed where noted in each family's description. Sms and
+whatsapp documents have no `class` attribute anywhere.
+
+| Class           | What it sets                                                                                                                                                                                                                                                                                          |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `p-*`           | Padding on all sides (p-4 = 16px). Compiles onto table cells for Outlook.                                                                                                                                                                                                                             |
+| `px-*`          | Horizontal padding.                                                                                                                                                                                                                                                                                   |
+| `py-*`          | Vertical padding.                                                                                                                                                                                                                                                                                     |
+| `pt-*`          | Top padding.                                                                                                                                                                                                                                                                                          |
+| `pr-*`          | Right padding.                                                                                                                                                                                                                                                                                        |
+| `pb-*`          | Bottom padding.                                                                                                                                                                                                                                                                                       |
+| `pl-*`          | Left padding.                                                                                                                                                                                                                                                                                         |
+| `m-*`           | Margin on all sides. Warn tier — some clients strip margins. (warn: some clients strip it)                                                                                                                                                                                                            |
+| `mx-*`          | Horizontal margin; mx-auto centers block elements. (warn: some clients strip it)                                                                                                                                                                                                                      |
+| `my-*`          | Vertical margin. (warn: some clients strip it)                                                                                                                                                                                                                                                        |
+| `mt-*`          | Top margin. (warn: some clients strip it)                                                                                                                                                                                                                                                             |
+| `mr-*`          | Right margin. (warn: some clients strip it)                                                                                                                                                                                                                                                           |
+| `mb-*`          | Bottom margin. (warn: some clients strip it)                                                                                                                                                                                                                                                          |
+| `ml-*`          | Left margin. (warn: some clients strip it)                                                                                                                                                                                                                                                            |
+| `w-*`           | Width from the spacing scale (w-32 = 128px), w-full, or w-[600px]/w-[50%].                                                                                                                                                                                                                            |
+| `max-w-*`       | Max width from the container scale (max-w-lg = 512px) or max-w-[600px].                                                                                                                                                                                                                               |
+| `h-*`           | Height from the spacing scale (h-12 = 48px) or h-[80px].                                                                                                                                                                                                                                              |
+| `text-*`        | Font size with paired line-height (text-sm = 14px/20px) or bounded px value (text-[15px] = 15px/22.5px). Put an explicit leading-* after it to override line-height. Text alignment: text-left, text-center, text-right, text-justify. Text color from the palette (text-gray-700) or text-[#374151]. |
+| `leading-*`     | Line height: named ratios (leading-relaxed) or spacing steps (leading-6 = 24px).                                                                                                                                                                                                                      |
+| `font-*`        | Font weight: font-normal, font-medium, font-semibold, font-bold, ... Font stack: font-sans, font-serif, font-mono.                                                                                                                                                                                    |
+| `tracking-*`    | Letter spacing: tracking-tighter … tracking-widest (em-based; inlines fine in Outlook). Pair tracking-wide/wider with uppercase for eyebrows.                                                                                                                                                         |
+| `uppercase`     | Uppercase text transform.                                                                                                                                                                                                                                                                             |
+| `underline`     | Underlined text.                                                                                                                                                                                                                                                                                      |
+| `no-underline`  | Removes the underline (links render underlined by default in most clients).                                                                                                                                                                                                                           |
+| `bg-*`          | Background color from the palette (bg-white, bg-blue-600) or bg-[#0088cc].                                                                                                                                                                                                                            |
+| `bg-gradient-*` | Linear gradient background for hero sections: bg-gradient-to-b/t/l/r with from-{color} and to-{color}. Modern base compiles a CSS linear-gradient (plus a solid from-color fallback); the outlook-safe base degrades to the solid from-color — Outlook for Windows never renders the gradient.        |
+| `from-*`        | Gradient start color (from-indigo-600). Doubles as the solid fallback color on clients without gradient support (Outlook for Windows).                                                                                                                                                                |
+| `to-*`          | Gradient end color (to-purple-600).                                                                                                                                                                                                                                                                   |
+| `border-*`      | Solid border width: border (1px), border-2, border-0. Border color from the palette (border-gray-200).                                                                                                                                                                                                |
+| `rounded-*`     | Border radius (rounded-md = 6px). Ignored by Outlook for Windows — buttons degrade to square corners.                                                                                                                                                                                                 |
+| `rounded-t-*`   | Top border radius for card/header blocks (rounded-t-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                           |
+| `rounded-r-*`   | Right-side border radius (rounded-r-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                                           |
+| `rounded-b-*`   | Bottom border radius for card/footer blocks (rounded-b-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                        |
+| `rounded-l-*`   | Left-side border radius (rounded-l-lg). Degrades to square corners in Outlook for Windows.                                                                                                                                                                                                            |
+| `block`         | display: block.                                                                                                                                                                                                                                                                                       |
+| `inline-block`  | display: inline-block.                                                                                                                                                                                                                                                                                |
+| `hidden`        | display: none. Pair with sm:block for mobile-only content.                                                                                                                                                                                                                                            |
+
+Palette color families (each with the usual `50`-`950` steps, plus `white`,
+`black`, `transparent`): `amber`, `black`, `blue`, `brand`, `brand-foreground`, `cyan`, `emerald`, `fuchsia`, `gray`, `green`, `indigo`, `lime`, `mauve`, `mist`, `neutral`, `olive`, `orange`, `pink`, `purple`, `red`, `rose`, `sky`, `slate`, `stone`, `taupe`, `teal`, `violet`, `white`, `yellow`, `zinc`.
+
+## Rejected utilities
+
+These compile to hard errors — the message names the failing client and the
+supported alternative. Drop the feature rather than break a client.
+
+| Class / prefix | Why it is rejected                                                                           |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `flex`         | display:flex is unsupported in Outlook for Windows (Word engine) — use <Row>/<Column>        |
+| `inline-flex`  | display:inline-flex is unsupported in Outlook for Windows — use <Row>/<Column>               |
+| `grid`         | display:grid is unsupported in Outlook for Windows and Gmail — use <Row>/<Column>            |
+| `inline-grid`  | display:inline-grid is unsupported in Outlook for Windows — use <Row>/<Column>               |
+| `gap-`         | gap requires flex/grid, unsupported in Outlook for Windows — use padding on <Column>         |
+| `space-`       | space-* margins require selectors Gmail strips — use padding or <Spacer>                     |
+| `items-`       | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `justify-`     | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column> and text-center |
+| `self-`        | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `content-`     | flexbox alignment is unsupported in Outlook for Windows — use <Row>/<Column>                 |
+| `order-`       | flex order is unsupported in Outlook for Windows — reorder the source instead                |
+| `absolute`     | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `relative`     | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `fixed`        | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `sticky`       | CSS position is ignored by Gmail and Outlook — use nested <Section>s                         |
+| `static`       | CSS position is ignored by Gmail and Outlook — remove it                                     |
+| `inset-`       | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `top-`         | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `right-`       | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `bottom-`      | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `left-`        | position offsets are ignored by Gmail and Outlook — use padding                              |
+| `z-`           | z-index is ignored by Gmail and Outlook — remove it                                          |
+| `float-`       | float is unreliable across email clients — use <Row>/<Column>                                |
+| `shadow`       | box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead            |
+| `shadow-`      | box-shadow is unsupported in Outlook for Windows and Gmail — use a border instead            |
+| `opacity-`     | opacity is unsupported in Outlook for Windows — bake the tint into the color                 |
+| `transform`    | CSS transforms are unsupported in email clients — remove them                                |
+| `rotate-`      | CSS transforms are unsupported in email clients — remove them                                |
+| `scale-`       | CSS transforms are unsupported in email clients — remove them                                |
+| `translate-`   | CSS transforms are unsupported in email clients — remove them                                |
+| `skew-`        | CSS transforms are unsupported in email clients — remove them                                |
+| `transition`   | transitions don't run in email — remove them                                                 |
+| `transition-`  | transitions don't run in email — remove them                                                 |
+| `duration-`    | transitions don't run in email — remove them                                                 |
+| `animate-`     | animations don't run in email — remove them                                                  |
+| `blur-`        | CSS filters are unsupported in most email clients — remove them                              |
+| `brightness-`  | CSS filters are unsupported in most email clients — remove them                              |
+| `grayscale`    | CSS filters are unsupported in most email clients — remove them                              |
+| `grayscale-`   | CSS filters are unsupported in most email clients — remove them                              |
+| `truncate`     | text truncation is unsupported in Outlook for Windows — shorten the copy                     |
+| `line-clamp-`  | line clamping is unsupported in email clients — shorten the copy                             |
+| `aspect-`      | aspect-ratio is unsupported in Outlook and Gmail — set width/height on <Image>               |
+| `overflow-`    | overflow is unreliable across email clients — restructure the layout                         |