# ADR-0003 — HTML and Markdown representation contract

- **Status:** accepted
- **Date:** 2026-07-09
- **Workplan:** ESRC-WP-0002 (T01)

## Context

ESRC-WP-0001 established the PDF ingest boundary. ESRC-WP-0002 extends ingest to
HTML and Markdown while reusing engine-owned contracts from
`@citation-evidence/engine/shared`.

`RepresentationType` already reserves `html-dom` and `markdown-rendered` in
`citation-engine`; no engine schema change is required for this slice.

## Decision

### Representation types

| Source format | `mediaType`        | `representationType`   |
| ------------- | ------------------ | ---------------------- |
| HTML          | `text/html`        | `html-dom`             |
| Markdown      | `text/markdown`    | `markdown-rendered`    |

### Pageless offset semantics

Reflowable formats have no fixed pages:

- `pageMap` is **omitted** (undefined).
- `offsetMap` is a **single synthetic range** on page 1 covering
  `[0, canonicalText.length)` with no gaps. This keeps
  `TextPositionSelector` usable without inventing physical page geometry.
- `structureMap` is omitted by ingest; viewer adapters in `evidence-anchor`
  may populate it at selection time (see `SharedContracts.md` §3).

### Canonical text

Both pipelines decode source bytes as UTF-8, derive plain text from the format,
then apply `normalize()` from `@citation-evidence/engine/shared`. HTML strips
active content (`script`, `style`, `iframe`, `object`, `embed`, `noscript`)
before text extraction.

### Content hash

`contentHash` is the SHA-256 fingerprint of the **source bytes** (same rule as
PDF ingest), not a hash of canonical text.

### Fixtures

HTML/Markdown contract tests use small inline fixtures owned by this repo. They
contain no PII and do not duplicate the upstream PDF corpus (ADR-0002).

## Consequences

- `ingestHtml` and `ingestMarkdown` mirror the PDF `{ document, representation }`
  shape.
- Anchoring layers may add DOM/structural selectors later; this slice delivers
  canonical text and position offsets only.
- Sanitization is extraction-time stripping, not a sandboxed renderer.