# iftypeset v0.1 — Demo Acceptance Pack

This doc defines what “ship‑ready” means for `iftypeset` (pubstyle): a deterministic Markdown → HTML → PDF pipeline with enforceable quality gates and auditable artifacts.

## Goals

- Produce **consistently good-looking** outputs from plain Markdown without manual layout heroics.
- Provide **machine-verifiable QA gates** (layout/report JSON) suitable for CI.
- Keep the system **renderer-agnostic** via adapters (Playwright / WeasyPrint / Prince / Antenna House / Vivliostyle, etc.).
- Preserve legal constraints: **rules are paraphrases + pointers**, never book text.

## Definition of Done (v0.1)

“Done” means the following commands are boring and reliable:

- `lint` emits deterministic diagnostics and a manual checklist.
- `render-html` emits deterministic HTML + CSS for a profile.
- `qa` runs on HTML (always) and on PDF (when available) and fails builds when gates exceed thresholds.
- `report` shows rule coverage and doesn’t regress.

## Profiles to Support in v0.1

- `web_pdf` (screen-first): tolerant, readable, strong accessibility defaults.
- `dense_tech` (specs): tighter measure targets, code/tables common, strict numbering/citations.
- `memo` (internal): conservative, low typographic complexity.

## Fixture Set (minimum)

Create and maintain fixtures that represent real “pain” documents. v0.1 should ship with at least these:

1. **Memo (short, mixed content)** — bullets + links + a couple of headings
   - Stress: heading hierarchy, link wrapping, list spacing.
2. **Dense technical note** — headings, numbered sections, code blocks, small tables
   - Stress: code wrapping/overflow policy, table overflow policy, numbering monotonicity.
3. **Report with many links** — long URLs/DOIs/emails, references section
   - Stress: link wrap policy, footnote/reference formatting, readability.
4. **Table-heavy checklist** — 3–5 tables, some wide
   - Stress: table overflow handling, header repeat policy (HTML), clipping detection (PDF when possible).
5. **Degraded input** — hard-wrapped paragraphs + inconsistent headings
   - Stress: degraded-mode contract: unwrap/recover safely + emit degraded-mode report.

## Acceptance Gates (must pass)

### Lint gates (always on)

- No schema/spec validation failures.
- `lint-report.json` is produced and deterministic across two runs.
- `manual-checklist.md` is produced and contains only rules tagged `manual_checklist=true`.

### HTML render gates (always on)

- `render.html` and `render.css` produced deterministically.
- CSS tokens reflect chosen profile (page size, margins, font stacks, line-height).
- No external fetches in HTML (self-contained mode must embed local assets).

### QA gates (HTML fallback; PDF when available)

Minimum v0.1 gate set:

- `max_link_wrap_incidents` (catch “unbreakable” URLs / DOIs / emails).
- `max_table_overflow_incidents` (wide tables).
- `max_code_overflow_incidents` (wide code blocks).
- `max_stranded_headings` (keep-with-next heuristic).
- `max_heading_numbering_errors` (basic numbering monotonicity).

PDF-only gates (enable when a PDF engine is available):

- widows/orphans
- overfull lines (glyph boxes exceed text block)

## Multi-renderer Compatibility (design requirement)

v0.1 should treat the PDF engine as an adapter. Acceptance criteria:

- `render-pdf --engine auto`:
  - selects an available engine,
  - writes `render-log.json` including engine name + version,
  - fails clearly if no engine available (but keeps HTML artifacts).

Renderer capability differences must be explicit in `render-log.json` and `qa-report.json` (e.g., “widow/orphan detection unavailable for HTML-only run”).

## Demo Script (for humans)

For a convincing “this is real” demo:

1. Run `lint` + show `lint-report.json` and `manual-checklist.md`.
2. Run `render-html` + open `out/render.html` (show the profile look).
3. Run `qa` + show `qa-report.json` (pass/fail, counts).
4. If PDF engine exists, show the rendered PDF and the same QA gates on PDF.

## Release Checklist (v0.1)

- [ ] At least 30 fixtures exist and are exercised in CI.
- [ ] CI fails when QA thresholds are exceeded (no “green by vibes”).
- [ ] CI fails on spec regression (coverage floors, schema validation).
- [ ] Degraded mode emits its report artifacts and never silently “fixes” content.
- [ ] Renderer adapters are documented (how `auto` chooses, how to pin).