@marianmeres/safe-html 0.2.0

package/AGENTS.md

@@ -0,0 +1,92 @@
+# @marianmeres/safe-html — Agent Guide
+
+## Quick Reference
+
+- **What**: `html` tagged template with contextual escaping + helpers (`attrs`, `url`,
+  `srcset`, `jsonScript`, `scriptText`, `styleText`, `join`, `unsafeRaw`, `createHtml`).
+- **Stack**: TypeScript, Deno (primary), npm via `@marianmeres/npmbuild`. Zero runtime deps.
+- **Test**: `deno task test` | **Types**: `deno task check` | **Bench**: `deno task bench` |
+  **npm build**: `deno task npm:build`
+- **Dev-only dep**: `npm:parse5` (tests only; parses rendered output as a browser would).
+- **Status**: `0.x`; stay there until a real page has been ported onto it.
+
+## Project Structure
+
+```
+src/mod.ts       public exports only
+src/types.ts     public types (Trusted, Renderable, SlotContext, HtmlKit, …)
+src/trusted.ts   TrustedValue (brand via Symbol.for keys, private fields), isTrusted
+src/escape.ts    escapeHtml
+src/url.ts       URL policy: urlScheme (URL-parser-accurate), vetUrl, createPolicy
+src/scanner.ts   context analysis: tokenizer model, slot rules, neutrality, WeakMap cache
+src/render.ts    value × context rules (renderValue)
+src/helpers.ts   policy-free helpers: jsonScript, scriptText, styleText, unsafeRaw, join
+src/kit.ts       createHtml (html, attrs, url, srcset bound to a policy) + default kit
+tests/           golden scanner tests, render table, helpers, SVG/MathML, parse5 invariance
+bench/           deno bench vs hand-written concatenation
+docs/design.md   normative rules (read before changing scanner or render behavior)
+```
+
+## Critical Conventions
+
+1. **Safety invariants** (see [docs/design.md](./docs/design.md) §2): given templates that
+   pass analysis and no `unsafeRaw()`, no string value may change document structure. Every
+   change must keep `tests/invariance.test.ts` green.
+2. **Errors depend on the template or the value's type/kind, never on string content.**
+   Blocked URLs are replaced, `</script` is rewritten — never thrown.
+3. **Error messages never contain interpolated values** (attribute names in `attrs()` too:
+   refer to them by index). Template excerpts contain static text only.
+4. **Strictness**: anything the scanner does not model is an `HtmlTemplateError`, never a
+   guess. Relaxing a rule is a minor change; tightening one breaks users.
+5. **Analysis is kit-independent** (one shared cache). Kit-dependent checks (static URL
+   scheme) run at render from `SlotInfo.scheme`.
+6. **`SlotInfo` objects always have the same shape** (create via `slotInfo()`); rendering is
+   hot and relies on monomorphic property access.
+7. **No `Object.freeze` on trusted values** (costs more than a small render); immutability
+   comes from private fields.
+8. **`deno fmt` rewrites the contents of `html`-tagged templates.** Every file whose `html`
+   templates must stay byte-exact (all tests, bench, API.md) starts with
+   `// deno-fmt-ignore-file` (`<!-- deno-fmt-ignore-file -->` in Markdown). Keep it when
+   adding such files.
+9. **No `console.*`** in `src/` (visibility goes through `onBlockedUrl`).
+10. **U+2028 / U+2029 in source**: always write them as `\u` escapes. Some tools turn escapes
+    into the literal characters, which are line terminators and break regex literals.
+
+## Common Tasks
+
+### Add a URL attribute
+
+1. Add the lowercased name to `URL_ATTRIBUTES` in `src/scanner.ts` (also used by `attrs()`).
+2. Add a golden case to `tests/scanner.test.ts` ("URL attributes") and to `URL_ATTRS` in
+   `tests/invariance.test.ts`.
+3. Update docs/design.md §3.4, API.md (`attrs`).
+
+### Change a scanner rule
+
+1. Read docs/design.md §3; locate the state in `Scanner.chunk()`, the slot rule in
+   `Scanner.slot()` / `valueSlot()`, tag effects in `emitTag()` / `endTag()`.
+2. Add golden tests (context or exact error substring), and a corpus template in
+   `tests/invariance.test.ts` if a new context shape is involved.
+3. Consider the neutrality scan (`new Scanner(strings, true)`): a rule that differs between
+   HTML and foreign content must make the two scans disagree, not silently match.
+4. Update docs/design.md (and §8 if it departs from earlier behavior).
+
+### Change the value × context table
+
+Edit `renderValue` / `renderTrusted` in `src/render.ts`, the table test in
+`tests/render.test.ts`, and docs/design.md §4 plus the table in API.md.
+
+## Before Making Changes
+
+- [ ] Read docs/design.md for the rule you touch
+- [ ] `deno task test` (includes parse5 invariance and round-trips) and `deno task check`
+- [ ] `deno lint` and `deno fmt --check`
+- [ ] `deno task bench` if touching `render.ts`, `kit.ts`, `trusted.ts`, `escape.ts`, `url.ts`
+- [ ] Update README / API.md / docs/design.md for user-visible behavior
+
+## Documentation Index
+
+- [README.md](./README.md) — overview, safety lists, usage, porting from Svelte
+- [API.md](./API.md) — full API reference
+- [docs/design.md](./docs/design.md) — normative analysis and rendering rules, algorithms,
+  changes from the original draft

package/API.md

@@ -0,0 +1,404 @@
+<!-- deno-fmt-ignore-file -->
+<!-- (deno fmt would rewrite the html`…` templates in the examples) -->
+
+# API
+
+All exports come from the package root:
+
+```ts
+import { html, attrs, url, srcset, createHtml, jsonScript, scriptText, styleText,
+	join, unsafeRaw, escapeHtml, isTrusted, HtmlTemplateError, HtmlValueError,
+	DEFAULT_URL_SCHEMES } from "@marianmeres/safe-html";
+```
+
+The rules for which value may go where are in [docs/design.md](docs/design.md) (§3 analysis,
+§4 value × context table).
+
+## Template tag
+
+### `` html`…` ``
+
+```ts
+function html(strings: TemplateStringsArray, ...values: Renderable[]): SafeHtml;
+```
+
+The template tag. Returns a trusted, immutable `SafeHtml`. Each interpolated value is rendered
+for the context its slot sits in, as worked out once per call site from the static markup:
+
+| Context      | Where                                   | Accepts                                                        |
+| ------------ | --------------------------------------- | -------------------------------------------------------------- |
+| `text`       | element content                         | strings and numbers (escaped), `html`/`join()` fragments, `url()`, arrays |
+| `rcdata`     | `<title>`, `<textarea>` content         | strings and numbers (escaped), `url()`, arrays                 |
+| `attr-list`  | `<tag ${…}>`                            | `attrs()`, arrays of them                                      |
+| `attr-value` | inside a quoted attribute value         | strings and numbers (escaped), `url()`, `srcset()`             |
+| `url`        | a URL attribute value the slot starts   | strings and numbers (URL policy, then escaped), `url()`        |
+| `srcset`     | a whole `srcset`/`imagesrcset` value    | `srcset()`                                                     |
+| `script`     | `<script>` content                      | `jsonScript()`, `scriptText()`                                 |
+| `style`      | `<style>` content                       | `styleText()`                                                  |
+
+Everywhere: `null`, `undefined`, `false` and `true` render nothing; `unsafeRaw()` is inserted
+verbatim. Anything else throws `HtmlValueError`.
+
+**Throws:** `HtmlTemplateError` if the template is refused (slot in an unquoted attribute,
+event handler, tag name, comment, …) or `html` is not called as a tagged template;
+`HtmlValueError` if a value has no rendering in its context.
+
+**Example:**
+
+```ts
+const Card = (c: { title: string; href: string; tags: string[] }) =>
+	html`<article>
+	<h2><a href="${c.href}">${c.title}</a></h2>
+	${c.tags.length > 0 && html`<p>${join(c.tags, ", ")}</p>`}
+</article>`;
+
+String(Card({ title: "<Hi>", href: "javascript:x", tags: [] }));
+// <article>
+// 	<h2><a href="about:invalid#blocked">&lt;Hi&gt;</a></h2>
+// 	
+// </article>
+```
+
+---
+
+## Kit (URL policy)
+
+### `createHtml(options?)`
+
+```ts
+function createHtml(options?: HtmlOptions): HtmlKit;
+```
+
+Creates a kit whose `html`, `attrs`, `url` and `srcset` use the given URL policy. The default
+exports (`html`, `attrs`, `url`, `srcset`) are `createHtml()` with default options. Analyses are
+cached per call site and shared by all kits.
+
+**Parameters:**
+- `options.urlSchemes` (`readonly string[]`, optional) — allowed schemes, case-insensitive, with
+  or without the colon. Default: `DEFAULT_URL_SCHEMES` (`http`, `https`, `mailto`, `tel`).
+- `options.blockedUrl` (`string`, optional) — what a blocked URL renders as. Default:
+  `"about:invalid#blocked"`.
+- `options.onBlockedUrl` (`(info: BlockedUrlInfo) => void`, optional) — called once per blocked
+  URL (e.g. to log a probe). If it throws, the render throws.
+
+**Returns:** `HtmlKit` — `{ html, attrs, url, srcset }` (frozen; the functions need no `this`).
+
+**Throws:** `TypeError` on malformed options.
+
+**Example:**
+
+```ts
+export const { html, attrs, url, srcset } = createHtml({
+	urlSchemes: [...DEFAULT_URL_SCHEMES, "sms"],
+	onBlockedUrl: ({ tag, attribute }) => console.warn("blocked URL", tag, attribute),
+});
+```
+
+A template whose static URL text writes a scheme (`href="mailto:${a}"`) is checked against the
+kit's list at render: a scheme outside it (`href="javascript:go('${id}')"`) is an
+`HtmlTemplateError`.
+
+### `attrs(record)`
+
+```ts
+function attrs(record: Readonly<Record<string, AttrValue>>): SafeAttrs;
+```
+
+An attribute list for an `attr-list` slot: `<button ${attrs({ type: "submit", disabled })}>`.
+
+- Each attribute renders as ` name="value"` (leading space, value escaped), in key order.
+- `true` → ` name` (boolean attribute); `false`, `null`, `undefined` → omitted.
+- URL attributes (`href`, `src`, `action`, `formaction`, `poster`, `cite`, `background`,
+  `longdesc`, `manifest`, `codebase`, `icon`, `xlink:href`, `data`) go through the URL policy
+  unless the value is `url()` or `unsafeRaw()`.
+- `srcset` / `imagesrcset` take `srcset()` (or `unsafeRaw()`).
+- Values may also be `url()` / `srcset()` (escaped) or `unsafeRaw()` (verbatim) anywhere.
+
+**Throws:** `HtmlValueError` for a name not matching `/^[A-Za-z_][A-Za-z0-9_.:-]*$/`, an `on*`
+name, `srcdoc` or `ping`, or a value with no attribute rendering (object, `html`, …). Names
+are expected to come from code.
+
+**Example:**
+
+```ts
+html`<input ${attrs({ type: "email", name: "email", required: true, value: draft })}>`;
+// <input  type="email" name="email" required value="…">
+```
+
+### `url(value, options?)`
+
+```ts
+function url(value: string, options?: { schemes?: readonly string[] }): SafeUrl;
+```
+
+Checks `value` against the scheme allowlist and returns a `SafeUrl`: vetted, **not escaped**
+(it is escaped wherever it is rendered). A blocked value becomes the kit's `blockedUrl`
+(and `onBlockedUrl` is called); it never throws on content. `options.schemes` replaces the
+kit's list for this one value.
+
+Relative URLs (`/x`, `./x`, `?q`, `#f`, `//host`, `x/y`) are allowed. Scheme detection
+follows the URL parser: leading control characters and spaces are skipped and tab/LF/CR are
+ignored, so `" java\tscript:"` is caught.
+
+**Example:**
+
+```ts
+html`<img src="${url(`data:image/png;base64,${b64}`, { schemes: ["data"] })}">`;
+```
+
+### `srcset(candidates)`
+
+```ts
+function srcset(candidates: readonly SrcsetCandidate[]): SafeSrcset;
+```
+
+A `srcset` value. Each candidate's URL goes through the URL policy unless it is a `SafeUrl`;
+blocked and empty candidates are **dropped**. ASCII whitespace and leading/trailing commas in
+a URL are percent-encoded. Returns an unescaped, vetted value (escaped where rendered).
+
+**Throws:** `HtmlValueError` for a descriptor not matching `/^\d+(\.\d+)?x$|^\d+w$/` (e.g.
+`"2x"`, `"1.5x"`, `"800w"`), or a malformed candidate.
+
+**Example:**
+
+```ts
+html`<img src="${img.src}" srcset="${srcset([
+	{ url: img.src },
+	{ url: img.src2x, descriptor: "2x" },
+])}" alt="${img.alt}">`;
+```
+
+---
+
+## Policy-free helpers
+
+### `jsonScript(value, space?)`
+
+```ts
+function jsonScript(value: unknown, space?: number): Trusted<"json">;
+```
+
+`JSON.stringify(value, null, space)` with `<`, `>`, `&`, U+2028 and U+2029 written as `\uXXXX`
+escapes: valid JSON of the same value, a valid JS expression, and unable to end a `<script>`.
+Accepted in `script` context only. Use it for `application/ld+json`, `application/json` data
+islands, or `const x = ${jsonScript(v)};`. `SafeHtml` values inside serialize as their string.
+
+**Throws:** `HtmlValueError` when there is no JSON representation (`undefined`, a function or
+a symbol at the root). `JSON.stringify`'s own `TypeError`s (cycles, `BigInt`) propagate.
+
+**Example:**
+
+```ts
+html`<script type="application/ld+json">${jsonScript({ "@type": "Article", headline })}</script>`;
+```
+
+### `scriptText(source)`
+
+```ts
+function scriptText(source: string): Trusted<"js">;
+```
+
+Inline JavaScript that is code, not data (typically a constant). Every case-insensitive
+`</script` becomes `<\/script`, every `<!--` becomes `\x3C!--`, and a `<` that ends the source
+(alone or followed by the start of `/script` or `!--`) becomes `\x3C`. These keep the meaning
+inside strings, template literals and regexes. Accepted in `script` context only. Never throws
+on content.
+
+**Example:**
+
+```ts
+html`<script>${scriptText(`document.documentElement.dataset.theme = "dark";`)}</script>`;
+```
+
+### `styleText(source)`
+
+```ts
+function styleText(source: string): Trusted<"css">;
+```
+
+Inline CSS. Every case-insensitive `</style` becomes `<\/style`, and a `<` that ends the source
+(alone or followed by the start of `/style`) becomes `\00003C`. Other `<` are kept
+(media-query ranges use them). Accepted in `style` context only. Prevents breakout, **not**
+CSS injection: build dynamic CSS from validated tokens.
+
+**Example:**
+
+```ts
+html`<style>${styleText(`:root { --accent: ${validatedHexColor}; }`)}</style>`;
+```
+
+### `unsafeRaw(value)`
+
+```ts
+function unsafeRaw(value: string): Trusted<"unsafe">;
+```
+
+The escape hatch: inserted verbatim in **any** context, with no checks. It means *trusted*,
+never *cleaned*; this package is not an HTML sanitizer. The name is loud on purpose so every
+use is greppable.
+
+**Example:**
+
+```ts
+html`<article>${unsafeRaw(sanitizedByYourSanitizer)}</article>`;
+```
+
+### `join(values, separator?)`
+
+```ts
+function join(values: readonly Renderable[], separator?: string | SafeHtml): SafeHtml;
+```
+
+Renders each value under the `text` rules, separated by `separator` (default `""`; a string is
+escaped, `html` is inserted as is). `null`, `undefined` and booleans are skipped, so
+conditional items leave no stray separator. The result is `html`, so `<title>` and
+`<textarea>` refuse it: pass a plain string there (`parts.join(" | ")`).
+
+**Example:**
+
+```ts
+html`<p>${join([author, date, isDraft && html`<em>draft</em>`], " · ")}</p>`;
+```
+
+### `escapeHtml(value)`
+
+```ts
+function escapeHtml(value: string): string;
+```
+
+Escapes `&`, `<`, `>`, `"`, `'` (as `&amp;`, `&lt;`, `&gt;`, `&quot;`, `&#39;`). Returns the input
+unchanged when there is nothing to escape. For use outside templates.
+
+### `isTrusted(v, kind?)`
+
+```ts
+function isTrusted<K extends TrustedKind>(v: unknown, kind?: K): v is Trusted<K>;
+```
+
+Whether `v` is a value produced by this package (optionally of the given kind). Recognizes
+values from other copies of the package in the same process; never true for parsed JSON.
+
+---
+
+## Errors
+
+### `HtmlTemplateError`
+
+```ts
+class HtmlTemplateError extends Error {
+	readonly slot?: number; // offending slot, when the error is about a slot
+	readonly excerpt: string; // static text, slots as ${…}, the error at ⟨here⟩
+}
+```
+
+A refused template, or a call that is not a genuine tagged template. Depends on the template
+only (and, for a static URL scheme, on the kit's allowlist). A failed analysis is cached and
+rethrown on every render of that call site. The excerpt contains only developer-written text,
+so it is safe to log:
+
+```
+HtmlTemplateError: unquoted attribute value: quote it, e.g. name="${…}"
+    slot 0 in: <a href=${⟨here⟩}>
+```
+
+### `HtmlValueError`
+
+```ts
+class HtmlValueError extends TypeError {
+	readonly slot?: number; // when raised while rendering a template
+	readonly context?: SlotContext; // when raised while rendering a template or join()
+	readonly received: string; // type or kind, e.g. "object", "Promise", "Trusted<html>"
+}
+```
+
+A value with no rendering in its context (depends on the value's type or kind), an invalid
+attribute name in `attrs()` or descriptor in `srcset()` (content expected from code), or
+arrays nested deeper than 100 (a cycle). Messages never include values.
+
+---
+
+## Constants
+
+### `DEFAULT_URL_SCHEMES`
+
+`readonly ["http", "https", "mailto", "tel"]` — the default scheme allowlist (frozen).
+
+---
+
+## Types
+
+### `Trusted`, `TrustedKind`
+
+```ts
+type TrustedKind = "html" | "attrs" | "url" | "srcset" | "json" | "js" | "css" | "unsafe";
+
+interface Trusted<K extends TrustedKind = TrustedKind> {
+	readonly kind: K;
+	toString(): string; // also String(v), `${v}`
+	toJSON(): string; // JSON.stringify(v) gives the string
+}
+
+type SafeHtml = Trusted<"html">;
+type SafeAttrs = Trusted<"attrs">;
+type SafeUrl = Trusted<"url">;
+type SafeSrcset = Trusted<"srcset">;
+```
+
+Immutable, branded values. `SafeUrl` and `SafeSrcset` hold the vetted, unescaped value.
+
+### `Renderable`
+
+```ts
+type Renderable =
+	| Trusted | string | number | bigint | boolean | null | undefined
+	| readonly Renderable[];
+```
+
+What `html` accepts. Objects, functions, symbols, dates and promises are type errors.
+
+### `AttrValue`
+
+```ts
+type AttrValue =
+	| string | number | bigint | boolean | null | undefined
+	| Trusted<"url" | "srcset" | "unsafe">;
+```
+
+### `SrcsetCandidate`
+
+```ts
+interface SrcsetCandidate {
+	url: string | SafeUrl;
+	descriptor?: string; // "2x", "1.5x", "800w"; omitted = 1x
+}
+```
+
+### `HtmlOptions`, `HtmlKit`, `BlockedUrlInfo`
+
+```ts
+interface HtmlOptions {
+	urlSchemes?: readonly string[];
+	blockedUrl?: string;
+	onBlockedUrl?: (info: BlockedUrlInfo) => void;
+}
+
+interface HtmlKit {
+	html(strings: TemplateStringsArray, ...values: Renderable[]): SafeHtml;
+	attrs(record: Readonly<Record<string, AttrValue>>): SafeAttrs;
+	url(value: string, options?: { schemes?: readonly string[] }): SafeUrl;
+	srcset(candidates: readonly SrcsetCandidate[]): SafeSrcset;
+}
+
+interface BlockedUrlInfo {
+	url: string; // as given
+	tag?: string; // lowercased, when known
+	attribute?: string; // lowercased, when known
+}
+```
+
+### `SlotContext`
+
+```ts
+type SlotContext =
+	| "text" | "rcdata" | "attr-list" | "attr-value" | "url" | "srcset" | "script" | "style";
+```

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Instructions
+
+See [AGENTS.md](./AGENTS.md) for complete project documentation and AI agent instructions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marian Meres
+
+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.