Gap analysis + ported remend conformity corpus

[jonathanKingston]

Addresses #12. Two commits: a decision record, and the follow-up code it prescribes.

1. Decision record — docs/streamdown-gap-analysis.md

Written comparison of @copse/streaming-markdown vs Vercel's streamdown and its streaming primitive remend, plus the policy for remend's test suite.

• They are not the same kind of tool. streamdown is a React component; remend is a string "self-healing" pre-processor; copse is a framework-agnostic renderer. remend competes with one internal step of copse, not the whole thing.
• Two philosophies. remend heals-then-reparses (append a guessed closing marker, re-parse each token); copse is natively incremental (holds/reveals partial tokens, patches the DOM). copse's hold-and-reveal never commits a wrong intermediate; remend's guess can.
• Pick copse for a framework-agnostic renderer with high partial-stream fidelity. Caveats recorded: hand-rolled tokenizer to maintain, no math today.

2. Ported conformity corpus — src/remend-corpus.test.ts

The conformity call from #12: adopt remend's input scenarios, not its assertions. remend asserts remend(str) === healedString; copse emits HTML/DOM with pending states, so those fixtures can't run verbatim, and matching remend's expected strings would regress us by design (e.g. remend heals [doc → [doc](streamdown:incomplete-link), a fake href; we reveal the label with no href until the real URL arrives — pinned by forbidHtml: [/streamdown:incomplete-link/]).

So each remend input runs through our own invariants:

Suite	Asserts
convergence	every prefix chunking converges to the fresh full render (chunk-invariance)
no-flash	held constructs never leak their raw marker mid-stream
literal-safe	lone ~, <, intraword _ stay literal — no tag/entity slip
completed forms	once markers close, streamed output equals the at-rest render
known-gap	unsupported constructs pinned to current behaviour

31 new tests; full suite 406 green (typecheck + build clean).

Findings (folded into the doc's checklist)

• ✅ Images already handled — forming [alt](partial reveals alt, hides [ + URL, paralleling revealFormingLink. Not a gap.
• ✅ single-tilde / comparison operators / snake_case underscores — all confirmed literal-safe while streaming.
• ⚠️ KaTeX / $$…$$ math — the one genuine gap. Passes through as literal text; pinned as a known-gap case so implementing math trips the test on purpose. Decision (implement vs. out-of-scope) left open.

Notes

• New file is test-only + a doc; dist//node_modules/ remain gitignored.
• Ran npm run typecheck, npm run build, npm test locally — all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R76iwh8Xoc2afkXfx8N4RP

[jonathanKingston]

Closing as a duplicate of #14, which addresses the same issue (#12) with a decision record + the ported remend conformity corpus. Consolidating on #14 to avoid two PRs adding the same src/remend-corpus.test.ts file. Reopen if you'd prefer this version instead.

---

Generated by Claude Code