# Todo

## 0.2.0

- **36 — Move every decision into `docs/decisions.md`, indexed from `AGENTS.md`.** Each entry states
  the decision, its date, who made it, the README goal it serves and the premise it is valid while;
  one no goal serves is proposed as a goal and asked. Sources: `AGENTS.md`'s body, the settled text
  in this file's items, and `todo-history.md`, deleted with the bare `(28)` citations into it once
  nothing cites it. Split by `AGENTS.md` section where one chunk is too big.
  - **36d — Move the settled text in `todo.md`'s items and §15's dated rules, and point §15's
    "the rule that closes it, landing here" at `docs/decisions.md`.** `AGENTS.md`'s sections are
    renumbered once only working rules remain, their citations with them.
  - **36e — Move `todo-history.md`'s decisions, re-point its citations and delete it.**
- **35 — Read and write plain markdown as a flavour of the markdown grammar.** Per Goal 2 and
  `docs/decisions.md` §Plain markdown is a flavour of the grammar, `plainMarkdownToAdf` is
  `markdownToAdf`'s parser and `adfToPlainMarkdown` `adfToMarkdown`'s writer, each with the plain
  flavour set; 10's rows are read and written there, and the lift goes (the maintainer, 2026-09-27).
  The exports, their refusals and 10's rows stay as they are.
  - **35a — Read the plain flavour in the parser and delete the lift.** 10's rows are read while
    parsing, and `plain-lift.ts` is deleted, its tests reading through `plainMarkdownToAdf`. `>
    [!faq]- Why?` with the body on the next `>` line reads to an expand titled `Why?` whose body
    keeps the next lines' link targets and marks, and `> [!tip] Title` then `> body` to a panel
    whose paragraphs are `Title` and `body`: the rest of the marker's line is the title (an expand)
    or the first body paragraph (a panel). A CommonMark backslash keeps a marker literal — `\==x==`,
    `> \[!NOTE]`, `- \[x]`.
  - **35b — Spell the plain flavour in the writer.** Panels, expands, task lists and highlights are
    written by the writer, which escapes text that would read back as one, so
    `plainMarkdownToAdf(adfToPlainMarkdown(doc))` keeps a literal `==x==`, a quote opening `[!NOTE]`
    and a list whose items all open `[x] ` as text. A highlighted `=` (today `=====`) and `a==b`
    (today `==a==b==`, highlighting `a` alone) come back highlighted whole, or lose the highlight
    where no spelling holds them; 10c's byte-for-byte property misses both, since the wrong document
    re-spells to the same bytes. The reduction keeps only degrading what the flavour cannot spell.
- **10f — Give task nodes read from plain markdown position ids.** `plainMarkdownToAdf` gives each
  `taskList`, `taskItem` and `blockTaskItem` a deterministic `localId` from its position in document
  order, so a site that rejects a missing `localId` takes the document and the same markdown reads
  to the same ids every run; README §Plain markdown's `localId` bullet says so (the maintainer,
  2026-09-26). The id spelling — unique within the document, no host API — is part of the chunk.
- **6 — Specify the HTML dialect.** Element-by-element mapping, the `data-*` fidelity scheme, the
  opaque-carry form, and the documented foreign-element set `htmlToAdf` accepts — the set
  `markdownToAdf` shares (`spec/flavour.md` §Raw HTML in input; 29).
  **Settled** (the maintainer, 2026-09-20), the four answers that shape the set:
  - A container ADF has no node for unwraps to its children, its own attributes dropped, so `<div
    align="center">text</div>` keeps `text` and loses the box and the alignment ADF cannot hold.
  - `<details><summary>Title</summary>…</details>` is an `expand`, the summary its `title`; one
    inside another is a `nestedExpand`, as 10 already spells for the lossy pair. An empty
    `<details>` is still refused — `expand` requires content, so there is nothing to build.
  - A comment stays an error result. Neither schema holds a comment node: across 84 and 98
    definitions the only "comment" in either file is `annotationType: "inlineComment"` on the
    `annotation` mark, which carries an `id` and no text, the words living behind an Atlassian API.
    `placeholder` is the editor's own visible hint, and `extension` demands an `extensionKey` naming
    a vendor app. Nothing can hold the words, so nothing accepts them.
  - `<script>` and `<style>` drop whole, their text with them. Neither holds anything a reader of
    the document ever saw, so nothing is lost; unwrapping them would put `alert(1)` on the page as
    prose. A `style` attribute is a separate question — `textColor` and `backgroundColor` are the
    marks it could reach — and is not read at `0.2.0`, the work outweighing what it buys.
  So the set sorts every element three ways, and that is what `docs/decisions.md` §Foreign HTML is
  refused by name becomes in place of "error result naming the element": a container around document
  content unwraps, content ADF cannot hold is an error result naming it, and what is not document
  content at all drops whole. A comment sorts into the second rather than the third because a person
  wrote those words on purpose. 10's "Rejected in the survey" line names raw HTML and comments and
  does not contradict this: it rejects them as spellings the lossy pair writes and reads back, where
  `plainMarkdownToAdf` reads through `markdownToAdf`'s parser and so inherits whatever this set
  accepts.
- **7 — Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed
  through ADF.** CommonMark spec suite runs against `markdownToHtml` from here (`docs/decisions.md` §The corpus). The README's
  tagline and `package.json`'s `description` regain HTML (5g).
- **31 — Make the branch figure the coverage floor is read against repeatable.** Three Node test
  legs over one unchanged tree reported `emit/inline-line.ts` at 95.83%, 96.23% and 96.23%, and the
  total at 98.80%, 98.84% and 98.84% (2026-09-21). `--experimental-test-coverage` counts branches
  off V8's own coverage, which the runner's parallel files and V8's optimization make run-dependent,
  so the number the floor is read against is not the code's alone. The floor of 98 holds today on
  0.8 points of slack and `docs/decisions.md` §The coverage floors says it only ever moves upward, so the first raise to the measured
  figure reddens a run that changed nothing. Make the measurement repeatable, or state the number
  the floor may be raised to and why it is not the measured one.
- **33 — Make a carried mark run cost the line one re-emit.** `adfToMarkdown` spends 23 s on one
  paragraph of 2000 × `un` plus `**-r**`: each run its flanking cannot spell re-emits the whole line
  before riding the carry, quadratic in the runs (Goal 9), and the plain reduction's
  `spellableLine` drops one mark per re-emit the same way. Make both linear.
- **34 — Read emphasis flanking by the whole character beside an astral symbol.** Check whether
  `line-escaping.ts`'s `charAt` and the parser's flanking read one UTF-16 unit beside an astral
  symbol — a lone surrogate is neither punctuation nor symbol, where CommonMark reads `😀` as
  punctuation — and, where they do, read the code point, with a fixture per direction.
- **5f — Publish the bundle size, after 7 changes it.** Measure the shipped artifact and put the
  number in the README, kept honest by the release pipeline rather than by a human re-reading it.
  The quantity is what a consumer downloads and loads: the tarball `npm pack` produces, its unpacked
  `dist`, and the built JavaScript minified + gzipped — the figure the competitors advertise
  (marklassian's "12kb") and the only apple-to-apple one, since ours ships tsc's unminified output
  and no minifier yet (decide here whether to minify for the build or report the unminified gzip). A
  publish/pipeline leg measures it and fails when the README figure drifts, so the number can't rot;
  the figure lands in README §The package beside the "no runtime dependencies" claim. Measured
  today, unminified: tarball 60.4 kB, unpacked 221.5 kB, JS gzipped 45.6 kB.
- **5g — Reweight the README for the reader.** It opens with the pre-launch rationale — Atlassian's
  REST APIs, `pf-editor-service/convert` being decommissioned, a link to JRACLOUD-77436 — where a
  shipped package should answer what it is, what it does and for whom first, then the shortest
  runnable example.
  **Settled** (the maintainer, 2026-09-13): the background goes entirely, no endpoint, ticket or
  "why" note left. The top follows the package-README order: an npm version badge and the Gitea
  Actions badge, a tagline that is also `package.json`'s `description`, a feature list and a
  one-line table of contents, then install and the shortest runnable example; a table of everything
  exported sits near the bottom. The HTML directions were to stay an aside until a later release
  shipped them; 7 now ships in this one and reads ahead of this item, so the README documents HTML
  as it documents markdown, the tagline and `description` naming both (the maintainer, 2026-09-13,
  revised 2026-09-18). They name the lossy pair too, and the flavours it writes and reads by name —
  GitHub Flavored Markdown's alerts and task lists, Obsidian Flavored Markdown's callouts — so a
  search for either finds the package (the maintainer, 2026-09-26).

## 0.3.0

- **5e — Keep the release path publishing past npm's bypass-2FA token retirement.** `0.1.0`
  published only once the npm token carried **Bypass 2FA**: the account requiring no 2FA on writes
  was not enough, and npm answered `EOTP` until the token itself bypassed. npm retires bypass-2FA
  tokens for direct publishing around January 2027, leaving them `npm stage publish`, which a
  maintainer approves with 2FA; its replacement — trusted publishing over OIDC — supports
  GitHub-hosted Actions, GitLab.com's shared runners and CircleCI's cloud, self-hosted runners
  planned without a date. So the release path has an expiry date and no drop-in successor yet.
  Revisit: whether npm has added Gitea or self-hosted OIDC, and otherwise whether the release moves
  to the staged publish — which fits badly with publish-on-merge, and is the trade to weigh rather
  than discover on a red release run.
  **Settled** (the maintainer, 2026-09-13, placed in `0.3.0` 2026-09-27): clear of `0.2.0`, knowing
  the cutoff may land before `0.2.0` ships.
- **8 — Ship a CLI, shaped around the personas.**
- **9 — Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on
  the library's browser build.**