docs: update CLAUDE.md + CONTRIBUTING.md for the node-registry architecture#80
Merged
docs: update CLAUDE.md + CONTRIBUTING.md for the node-registry architecture#80
Conversation
…ecture The renderer monolith was split in PRs #77 / #78 / #79; both files still described the pre-split flow ("add a case to html-renderer.ts, react-renderer.ts, tailwind-renderer.ts" — three switches that no longer exist). New contributors following the old checklist would land in the wrong place. CLAUDE.md - Architecture tree shows the new `nodes/<type>/` layout, the registry + contract files, and the per-theme styles split. - New "Render flow (Strategy + Registry)" paragraph explains the dispatcher → registry → node module flow and the "Unknown node" fall-through (intentional behavior for nodes without per-target renderers). - New "Adding a new component" pointer. - Classic tests list adds registry.test.ts and styles-split.test.ts. CONTRIBUTING.md "Feature Development Checklist" - Replaced the three "add a case" bullets (HTML/React/Tailwind) with one "Node module" bullet pointing at `src/nodes/<your-type>/`. - Notes that React and Tailwind targets are optional (dispatcher falls through cleanly). - CSS bullet points at `renderer/styles/_structural.ts` and the per-theme files instead of the old monolithic `styles.ts`. - Removed "Renderer index" bullet — `renderer/index.ts` no longer needs per-component plumbing. No code change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 tasks
teezeit
added a commit
that referenced
this pull request
May 1, 2026
## Summary Self-contained brief for the next architectural beat after the renderer split. **No code change** — just the planning doc at `.github/dev-docs/parser-contract-plan.md`. The renderer monolith is split (#77 #78 #79 #80). The next high-leverage move is **not** splitting `parser/transformer.ts` per file — it's fixing the contract: explicit `TransformContext` with `peekNext`/`consumeNext`, plus isolated per-node parse tests that don't go through the full markdown→AST→render pipeline. The doc explains why (the file split is cosmetic; the leverage is the contract), what to build (`_context.ts` + test helpers + per-node tests), and what NOT to do (no file split in this PR, no syntax change, no bug fix). It also captures the user's pending syntax direction (`((pill))` over `|pill|`, `:::columns` over `:::grid`, etc.) so the next session has the destination clear before starting work. Two syntax ideas got pushed back during discussion and are flagged for design calls before any code: - Free-floating `{.right}/{.center}/{.left}` "applies until resolved" — stateful-parsing trap; counter-proposed "applies to nearest element only." - Navbar `[[ a | b | c ]]` `|` separators — collides with table syntax, new escape rules; counter-proposed alignment classes on items. ## Test plan - [x] No code touched. - [ ] Skim the doc for accuracy. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Both files still described the pre-split flow ("add a case to html-renderer.ts, react-renderer.ts, tailwind-renderer.ts") even though those switches were deleted in #77 / #78 / #79. New contributors following the old checklist would land in the wrong place.
No code change — pure docs.
CLAUDE.md
nodes/<type>/layout, the registry + contract files, and the per-theme styles split.registry.test.tsandstyles-split.test.ts(added in refactor(core): scaffold node-registry + split styles.ts into per-theme files #77).CONTRIBUTING.md "Feature Development Checklist"
src/nodes/<your-type>/.renderer/styles/_structural.tsand the per-theme files instead of the old monolithicstyles.ts.renderer/index.tsno longer needs per-component plumbing.Test plan
🤖 Generated with Claude Code