FE-1447: Emit layer facts and relations as structured data

[kube]

🌟 What is the purpose of this PR?

Generated layer pages baked their facts into MDX prose: the Package/Layer id/Files/Lines line, "Declared in", and the "Depends on" / "Depended on by" heading-plus-table blocks. A host could not restyle any of it. The pages now render components shipped in the bundle, which receive the same facts as structured props.

In stack #9280, FE-1443 (#9263) sits below and FE-1415 (#9265) above.

🔗 Related links

• FE-1447 (internal): this PR
• FE-1443 (internal): the declared edges the relations component renders

🔍 What does this change?

libs/@local/petrinaut-arch-docs:

• Four shipped components, emitted into the bundle's components/ beside authored ones:
  • LayerFacts renders the Package / Layer id / Files / Lines grid with a Declared-in link. The role renders as the page's plain lead paragraph above it.
  • LayerRelations renders both edge directions side by side, in one column under 640px, with import counts and package badges. A declared edge shows its protocol on a dashed label.
  • LayerSource renders the file count and the source root, replacing the old "Source" heading and sentence.
  • LayerLinks renders a titled list of links: sub-layers, attached guides, and further reading.
• Styling: plain CSS, with colours derived from currentColor via color-mix, so both Starlight themes work without theme-specific rules.
• Emission (mdx.ts): pages import the components by page-relative path and pass props as JSON expressions, because a JSX string attribute cannot escape a " in a role. A page with no edges renders no relations section, and architecture.md keeps plain text.
• The generator's tsconfig excludes the component sources; the Astro build compiles them, the same as authored content/components/.
• The README records the new contract: hosts need a React-capable MDX pipeline for generated layer pages as well as authored ones.

Review fixes

• All four component imports are emitted unconditionally. Whether a component renders is decided where it is emitted, and an unused import is tree-shaken. The test that asserted the conditional import now asserts the element.
• Comments tie the components' import.meta.url asset resolution to the tsconfig exclude.
• A comment names --arch-accent as the one fixed colour; everything else derives from currentColor.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies a workspace but not a publishable library

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🛡 What tests cover this?

• mdx.test.ts: import-path depth per page, the structured props, declared-edge entries in the relations props, the element-level assertion for a page with no edges, and the removal of the old heading-plus-table sections.
• lint:arch-docs and turbo run build --filter @apps/petrinaut-docs prove the emitted MDX compiles and renders.

❓ How to test this?

1. turbo run dev --filter @apps/petrinaut-docs
2. Open any layer page (for example architecture/python-bindings): LayerFacts replaces the header prose, LayerRelations shows both directions, and the declared edge to cli renders with its dashed protocol label.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 21, 2026 3:30pm
petrinaut	Ready	Preview	Aug 21, 2026 3:30pm
petrinaut-docs	Ready	Preview	Aug 21, 2026 3:30pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 21, 2026 3:30pm

[cursor]

PR Summary

Medium Risk
Changes the portable bundle contract: generated layer pages now require a React-capable MDX pipeline, so other hosts (e.g. hash.dev) must compile the new components.

Overview
Generated layer pages no longer bake package/id/size, dependency tables, source, and link lists into Markdown. They import four shipped React cards (LayerFacts, LayerRelations, LayerSource, LayerLinks) and pass the same data as JSON props so a host can restyle without re-parsing prose. architecture.md stays plain text.

The generator copies those components (plus shared currentColor-based CSS) into every bundle’s components/ next to authored diagram components, and fails if an authored file would overwrite a shipped name. Import edges still sort by count; @talksTo edges show a dashed protocol label instead of a separate “Declared” table.

Hosts now need a React MDX pipeline for generated layer pages, not only authored diagram pages. The Starlight site already had react(); comments and the README record the new contract.

^{Reviewed by Cursor Bugbot for commit 7092784. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0c71119. Configure here.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.