@samva/markup 0.6.0 → 0.8.0

package/AGENTS.md

@@ -1,47 +1,94 @@
-# Samva Markup consumer guide
-
-This package is plain TypeScript. It depends on no application runtime, so a template project
-installs the compiler and nothing that comes with one. The structured SML surface — `parseSml`,
-`compileSml`, `compileSource` — returns a better-result `Result` you branch on with `Result.isOk`
-/ `Result.isErr`, carrying a `TaggedError` such as `SmlParseError` or `SmlCompileError` that you
-discriminate by `_tag`. Email compilation reports through `EmailDiagnostic` values instead. A
-declaration the compiler cannot accept at all throws a `TypeError`: a template id or fixture key
-that is not one plain path segment, a nonportable input schema, a project holding a reserved
-compiler path.
-
-Markup's own data models are types and interfaces, not schema declarations, so there is no schema
-library to adopt to consume them. Their unions discriminate on `type`: an `EmailNode` is `Text`,
-`Element`, `Fragment` or `Raw`, and an `SmlOp` names its edit the same way.
-Only the better-result error classes carry `_tag`. A template's JSON input contract is the one
-exception to the no-schema rule, because it has to be checked against real input: `inputSchema`
-accepts any Standard Schema through the `@standard-schema/spec` types and returns a portable JSON
-Schema with its validator, so which schema library an author reaches for stays theirs.
-
-Email entries default-export `defineEmail` definitions. SMS and WhatsApp use the structured
-channel runtime at `@samva/markup` and components at `@samva/markup/components`.
-Use documented package subpaths only. Template entry discovery is `.tsx` only.
-`presets/sources.gen.ts` is generated: run `bun run codegen:presets` from this package, never hand-edit
-it.
-
-Object email templates use `jsxImportSource: "@samva/markup/email"` and
-`defineEmail` from `@samva/markup/template`. Their render function receives actual validated
-JSON input and returns subject, optional preheader, body, and optional text. A template id and a
-fixture key are both written into file paths, so each must match `TEMPLATE_NAME_PATTERN` — one
-plain path segment — and `defineEmail` refuses anything else where the name is declared. A consumer
-that resolves a path from those names imports that pattern; it never restates it. The derived
-semantic tree lowers directly to HTML/text via `@samva/markup/email/render`; do not route object
-templates through recording proxies or textual SML. Authoring-source provenance belongs to semantic
-nodes.
-
-Ordinary HTML is typed. `@samva/markup/email/elements` is the one table behind both the JSX
-intrinsic prop types and the serializer's allowlist, so an unsupported element or attribute fails at
-typecheck and again at compile with a source location. Email primitives — `Email`, `Section`,
-`Columns`/`Column`, `Button`, `Spacer`, `Divider`, `Image`, `Link` — come from
-`@samva/markup/email/components`; they generate table markup and classic-Outlook fallbacks, and
-every wrapper they generate carries the authoring call site as its origin. Findings are
-`EmailDiagnostic` values from `@samva/markup/email/diagnostics`: errors throw `EmailCompileError`,
-warnings ride back on the render result. Nothing an author passes as a string becomes markup.
-
-`@samva/markup/compiler` is the bundler-agnostic compiler boundary. `@samva/vite` and
-`apps/agents/src/editor` are adapters over it — they own resolution, watching and transport, never
-compilation semantics — and the module imports no Vite, esbuild or Node builtins.
+# @samva/markup agent guide
+
+`@samva/markup` is the authoring language and compiler for Samva templates. Email templates are
+TSX modules that default-export a `defineEmail` definition and render through a JSX runtime that
+lowers to email-safe HTML and plain text. SMS and WhatsApp templates use the structured SML runtime.
+The package is plain TypeScript with no application runtime; the local editor, project builds, and
+exports live in `@samva/vite`.
+
+## Entry points
+
+- `@samva/markup/template` — `defineEmail`, `TemplateDefinition`, `TemplateInput`, and
+  `TEMPLATE_NAME_PATTERN`.
+- `@samva/markup/email` — the JSX runtime. Set `jsxImportSource: "@samva/markup/email"` for email
+  entries.
+- `@samva/markup/email/components` — email primitives (`Email`, `Section`, `Columns`, `Button`,
+  and the rest of its exports). They generate table layout and classic-Outlook fallbacks.
+- `@samva/markup/email/render` — `renderEmail(template, data)`, which validates input and returns
+  subject, preheader, HTML, text, and the derived tree.
+- `@samva/markup/email/diagnostics` — `EmailDiagnostic` and `EmailCompileError`.
+- `@samva/markup/email/assets` — `isAssetPath` and `ASSET_CONTENT_TYPES`: which imported files
+  become content-addressed assets, without loading the compiler.
+- `@samva/markup/input-schema` — `inputSchema`, which turns any Standard JSON Schema into the
+  portable JSON Schema and validator a template's input is checked against.
+- `@samva/markup/compiler` — `compileEmailProject`, the bundler-agnostic compile step. It imports no
+  Vite, esbuild, or Node builtins, so it runs in any JavaScript host.
+- `samva:brand` — `BrandLogo` (light logo, swapped for the dark one where the client honors dark
+  mode) and `BrandFooter` (company, postal address, social links and the unsubscribe row the send
+  path fills). The compiler binds them to the brand the build resolves; add
+  `"types": ["@samva/markup/samva-brand"]` to the project's tsconfig for `tsc`. In `theme.css`,
+  `@import "samva:brand";` layers the brand theme; `samva:brand/<slug>` names one brand.
+- `jsxImportSource: "@samva/markup"` and `@samva/markup/components` — the structured SMS and
+  WhatsApp runtime and components. `parseSml` (`@samva/markup/parser`) and `compileSml` /
+  `compileSource` (`@samva/markup/compile`) work on SML source.
+
+The package's `generated/` directory ships the SML and email language references and agent
+contracts; read those before authoring. Import only subpaths declared in `package.json` `exports`.
+
+## How you hurt yourself here
+
+- **Passing a string where you want markup.** Nothing an author passes as a string becomes markup;
+  strings render as escaped text. There is no raw-HTML escape hatch: compatibility markup comes only
+  from the email primitives.
+- **Using an element or attribute the serializer does not allow.** `@samva/markup/email/elements` is
+  the one table behind both the JSX intrinsic prop types and the serializer's allowlist, so an
+  unsupported element or attribute fails at typecheck and again at compile with a source location.
+- **Naming a template or fixture like a path.** A template id and a fixture key are both written
+  into file paths, so each must match `TEMPLATE_NAME_PATTERN`, one plain path segment.
+  `defineEmail` throws a `TypeError` where the name is declared. Code that builds a path from these
+  names imports the pattern instead of restating it.
+- **Reading the clock or randomness in a template.** Samva's hosted render has no ambient clock and
+  no entropy source: reading the current instant or a random value there throws unless the
+  definition declares the fixed value in its `runtime` (`TemplateRuntime`). A local render does not
+  enforce this, so a template that reads `Date.now()` can pass locally and fail once published. Take
+  times from validated input, or declare them.
+- **Declaring a webfont as if every client loads it.** A project font is an ordinary `@font-face`
+  in the project's CSS (usually `theme.css`) whose `src` is a `.woff2` file in the project, named
+  by a path relative to that stylesheet; the compiler serves it as a content-addressed asset and
+  hides the rule from classic Outlook. Gmail and Outlook never load it, so a `font-family` stack
+  that names a project font must end in a generic (`sans-serif`, `serif`, `monospace`) or the
+  render fails with `email-font-fallback`. Only WOFF2 is accepted; an `https:` `src` stays an
+  external reference.
+- **Treating `renderEmail` as a sandbox.** It executes the template's TypeScript in the calling
+  process. Run untrusted template source in an isolated host.
+- **Expecting the schema library to do the validation.** A template's input schema is converted to
+  a portable JSON Schema and validated by that document, not by the library that produced it. A
+  refinement that the converter cannot export is refused, and defaults are never inserted or values
+  coerced. The README lists the supported keywords.
+
+## Rules
+
+- **Email entries default-export a `defineEmail` definition** from a `.tsx` file. The definition
+  owns a stable, project-unique `id`, an input schema, named fixtures, and a synchronous `render`
+  that receives the validated JSON input unchanged. Helper modules are ordinary imports, not
+  catalog entries.
+- **Email templates have no textual SML form.** The derived semantic tree lowers directly to HTML
+  and text through `@samva/markup/email/render`; SML is the SMS and WhatsApp language.
+- **Structured SML is a closed grammar.** `parseSml` and `compileSml` reject anything outside it
+  rather than passing it through.
+- **Failures are typed.** The SML surface returns a better-result `Result`; branch with
+  `Result.isOk` / `Result.isErr` and discriminate the `TaggedError` (`SmlParseError`,
+  `SmlCompileError`) by `_tag`. Email compilation reports `EmailDiagnostic` values: errors throw
+  `EmailCompileError`, warnings ride back on the render result. A declaration the compiler cannot
+  accept at all, such as an invalid name or a nonportable input schema, throws a `TypeError`.
+- **Data models are plain types.** Markup's data models are TypeScript types, not schema
+  declarations, so there is no schema library to adopt to consume them. Unions discriminate on
+  `type` (an `EmailNode`, an `SmlOp`); only error classes carry `_tag`. The input schema is the one
+  place a Standard Schema is accepted, and which library produces it is yours to choose.
+
+## Proving your setup
+
+- `tsc --noEmit` over the template project catches unsupported elements, attributes, and props.
+- `samva templates check` (from `@samva/cli`) compiles every entry and renders every fixture,
+  reporting findings with source locations.
+- `renderEmail(template, fixture)` in a unit test proves one template's output without a build.

package/README.md

@@ -101,7 +101,7 @@ a value at import. `new Date(value)` with an explicit argument always works, so
 takes its time from validated input or states it once as configuration. Locale (`en-US`) and time
 zone (UTC) are publication-wide and back every `Intl` constructor and `toLocale*` call.
 
-Portable validation uses `@cfworker/json-schema` 4.1.1 without runtime code generation. The
+Portable validation uses `@cfworker/json-schema` without runtime code generation. The
 2020-12 meta-schema is checked at every supported schema position, and the explicit profile rejects
 keywords outside its contract before interpretation. The AJV dependency supplies static meta-schema
 JSON; its code generator is not invoked in a loaded template.

package/dist/brand-DcoVkh_S.d.ts

@@ -0,0 +1,88 @@
+import { m as EmailNode } from "./elements-BzjjnoCS.js";
+//#region src/internal/unsubscribe-link.d.ts
+/**
+ * The per-recipient unsubscribe URL is not known at render: the send path
+ * substitutes each delivery's link for this placeholder, or removes the
+ * unsubscribe row when the send resolved no unsubscribe group.
+ */
+declare const UNSUBSCRIBE_URL_PLACEHOLDER = "%samva:unsubscribe-url%";
+//#endregion
+//#region src/email/brand.d.ts
+interface EmailBrandAddress {
+  readonly street1: string;
+  readonly street2?: string | undefined;
+  readonly city: string;
+  readonly region: string;
+  readonly postalCode: string;
+  readonly country: string;
+}
+interface EmailBrandSocialLink {
+  readonly label: string;
+  readonly url: string;
+}
+interface EmailBrandAssets {
+  readonly logoUrl?: string | undefined;
+  readonly logoDarkUrl?: string | undefined;
+  readonly iconUrl?: string | undefined;
+}
+interface EmailBrandFooter {
+  readonly companyName?: string | undefined;
+  readonly address?: EmailBrandAddress | undefined;
+  readonly socialLinks?: readonly EmailBrandSocialLink[] | undefined;
+}
+interface EmailBrand {
+  /** The brand's slug; `samva:brand/<slug>` must name it. */
+  readonly slug: string;
+  /** Brand theme CSS in the closed grammar `parseBrandCss` accepts. */
+  readonly css: string;
+  readonly assets?: EmailBrandAssets | undefined;
+  readonly footer?: EmailBrandFooter | undefined;
+}
+/** Marks the block the send path recognizes as the template's own footer. */
+declare const FOOTER_ATTRIBUTE = "data-samva-footer";
+/** Marks the footer row that carries the unsubscribe link. */
+declare const UNSUBSCRIBE_ROW_ATTRIBUTE = "data-samva-unsubscribe";
+/** Every class the brand components use, compiled for any project that imports them. */
+declare const BRAND_COMPONENT_CLASSES: readonly ["dark:hidden!", "hidden", "dark:block!", "text-xs", "text-gray-500", "text-center", "font-semibold", "underline"];
+interface BrandLogoProps {
+  /** Rendered width in pixels; the height follows the image. */
+  readonly width?: number | undefined;
+  /** Defaults to the brand footer's company name. */
+  readonly alt?: string | undefined;
+  readonly align?: "left" | "center" | "right" | undefined;
+  readonly className?: string | undefined;
+}
+interface BrandFooterProps {
+  /** Text of the unsubscribe link. */
+  readonly unsubscribeLabel?: string | undefined;
+  readonly className?: string | undefined;
+}
+interface BrandComponents {
+  readonly BrandLogo: (props: BrandLogoProps) => EmailNode | null;
+  readonly BrandFooter: (props: BrandFooterProps) => EmailNode | null;
+}
+/** Bind `BrandLogo` and `BrandFooter` to one brand. */
+declare const brandComponents: (brand: EmailBrand) => BrandComponents;
+/** What a rendered message says about the footer it carries. */
+interface RenderedFooterMarkers {
+  /** The message renders `BrandFooter` (or claims to, with the marker). */
+  readonly footer: boolean;
+  /** The message carries the unsubscribe placeholder link only `BrandFooter` can write. */
+  readonly unsubscribeLink: boolean;
+}
+/** Read the footer markers from rendered HTML. */
+declare const renderedFooterMarkers: (html: string) => RenderedFooterMarkers;
+/**
+ * Drop the unsubscribe row from a rendered message, for a send that resolved
+ * no unsubscribe group: there is no link to put there, so the row goes.
+ */
+declare const withoutUnsubscribeRow: (rendered: {
+  readonly html?: string | undefined;
+  readonly text?: string | undefined;
+}) => {
+  readonly html: string | undefined;
+  readonly text: string | undefined;
+};
+//#endregion
+export { EmailBrand as a, EmailBrandFooter as c, RenderedFooterMarkers as d, UNSUBSCRIBE_ROW_ATTRIBUTE as f, UNSUBSCRIBE_URL_PLACEHOLDER as g, withoutUnsubscribeRow as h, BrandLogoProps as i, EmailBrandSocialLink as l, renderedFooterMarkers as m, BrandComponents as n, EmailBrandAddress as o, brandComponents as p, BrandFooterProps as r, EmailBrandAssets as s, BRAND_COMPONENT_CLASSES as t, FOOTER_ATTRIBUTE as u };
+//# sourceMappingURL=brand-DcoVkh_S.d.ts.map

package/dist/{catalog-60eaYC7b.d.ts → catalog-CKuOooB8.d.ts}

@@ -1,16 +1,15 @@
 import { l as Channel } from "./ast-BrDtApwS.js";
-import { o as TokenOverrides } from "./theme-6ApjjiBo.js";
-//#region presets/catalog.d.ts
-type PresetCategory = "transactional" | "digest" | "marketing" | "lifecycle";
-interface PresetMeta {
+//#region starters/catalog.d.ts
+type StarterCategory = "transactional" | "digest" | "marketing" | "lifecycle";
+interface StarterMeta {
   /** Stable id and source filename stem (`${id}.tsx`). */
   readonly id: string;
   /** The source's root-tag channel; the gallery filters by it. */
   readonly channel: Channel;
-  readonly category: PresetCategory;
+  readonly category: StarterCategory;
   /** Human title for the gallery card. */
   readonly name: string;
-  /** One-line description of when to reach for this preset. */
+  /** One-line description of when to reach for this starter. */
   readonly description: string;
   /**
    * Every input property declared by the template schema, sorted.
@@ -18,8 +17,7 @@ interface PresetMeta {
    */
   readonly variables: ReadonlyArray<string>;
 }
-declare const RECOMMENDED_THEME: TokenOverrides;
-declare const presetCatalog: readonly [{
+declare const starterCatalog: readonly [{
   readonly id: "linear-login-code";
   readonly channel: "email";
   readonly category: "transactional";
@@ -342,15 +340,15 @@ declare const presetCatalog: readonly [{
   readonly description: "Marketing template: limited-time offer with a copyable promo code and a shop button.";
   readonly variables: readonly ["endsToday", "firstName", "offerDetails", "offerHeadline", "promoCode", "shopUrl"];
 }];
-type PresetId = (typeof presetCatalog)[number]["id"];
-type PresetVariable = (typeof presetCatalog)[number]["variables"][number];
-type EmailPreset = Extract<(typeof presetCatalog)[number], {
+type StarterId = (typeof starterCatalog)[number]["id"];
+type StarterVariable = (typeof starterCatalog)[number]["variables"][number];
+type EmailStarter = Extract<(typeof starterCatalog)[number], {
   channel: "email";
 }>;
-type EmailPresetId = EmailPreset["id"];
-type EmailPresetVariable = EmailPreset extends (infer Preset) ? Preset extends {
+type EmailStarterId = EmailStarter["id"];
+type EmailStarterVariable = EmailStarter extends (infer Starter) ? Starter extends {
   readonly variables: ReadonlyArray<infer Variable>;
 } ? Variable : never : never;
 //#endregion
-export { PresetMeta as a, presetCatalog as c, PresetId as i, EmailPresetVariable as n, PresetVariable as o, PresetCategory as r, RECOMMENDED_THEME as s, EmailPresetId as t };
-//# sourceMappingURL=catalog-60eaYC7b.d.ts.map
+export { StarterMeta as a, StarterId as i, EmailStarterVariable as n, StarterVariable as o, StarterCategory as r, starterCatalog as s, EmailStarterId as t };
+//# sourceMappingURL=catalog-CKuOooB8.d.ts.map