Add internals architecture documentation page

[berendkleinhaneveld]

Summary

Adds an Internals → Architecture page to the docs, modelled after observ's architecture page. It explains how Collagraph's internals fit together and — as specifically requested — gives a visual representation of how elements and fragments relate to each other.

The page centres on the Fragment/element relationship and covers:

• The four cooperating pieces: the SFC compiler, Fragments, Renderers, and observ
• Fragments vs. elements — the persistent Python-side description driving a disposable toolkit-side element
• The Fragment family (Fragment, ControlFlowFragment, ListFragment, ComponentFragment, SlotFragment, DynamicFragment)
• The template tree vs. render tree distinction (template_children / render_children() / iter_all_children())
• Compilation — real, compiled render() output for a counter and a v-for list
• Mounting, anchors and first()
• Reactivity — how a state change flows to a targeted element update
• The fragment lifecycle (create / mount / unmount(destroy=…))
• How renderers close the loop

The prose is grounded in the actual source — the compiled snippets and the directive/fragment tables were produced by compiling real .cgx examples, so they match what the compiler emits.

Visuals

Nine Mermaid diagrams serve as the visual representation, including the big-picture flow, a fragments-vs-elements diagram, the fragment class hierarchy, template-vs-render tree, the template→fragment mapping, the mount sequence, the reactive update flow, and a lifecycle state diagram.

Changes

• docs/internals/architecture.md — new page
• mkdocs.yml — add a pymdownx.superfences custom fence so Material renders Mermaid diagrams, and add the Internals: Architecture nav section

Verification

• mkdocs build --strict passes
• Confirmed all 9 diagrams emit class="mermaid" in the built HTML and the nav link appears

🤖 Generated with Claude Code

---

Generated by Claude Code