feat(mix_markdown): add Markdown renderer styled with Mix

[leoafarias]

Related issue

Not linked to an open issue.

Description

Adds mix_markdown, a new package that renders Markdown through generated Mix Specs and Stylers, and fixes one mix_generator bug that the package surfaced.

MixMarkdown is a StyleWidget<MarkdownSpec>, so every text slot is a TextStyler and inherits the rest of Mix: tokens, onDark and other variants, widget modifiers, animation, and the generated call(). It parses a document once and reuses the parsed nodes across style, theme, and text-scale changes.

The supported subset is paragraphs, h1–h6, nested inline formatting, and GitHub alerts (including nested alerts and shared link references). Links are styled but not activated, and inline images contribute their alt text. A document containing any other block goes to unsupportedBuilder, or shows a diagnostic, rather than being silently flattened.

The package started from an external handoff bundle that had never compiled. It was rebuilt against this repo's conventions rather than imported: the copied alert syntax was dropped in favour of the markdown package's own AlertBlockSyntax, the handwritten style classes and ProbeSpec aliases were replaced with generated Specs and Stylers, and the SuperDeck-specific hero handling, Python validation tooling, and review documents were left out.

Changes

New package packages/mix_markdown (version 0.0.1-beta.0)

• MixMarkdown widget with syntax, wrapBlock, and unsupportedBuilder hooks.
• Generated MarkdownSpec, MarkdownAlertSpec, and MarkdownAlertTypeSpec, with a slot per block, inline run, and alert type.
• MarkdownSyntax value object for parser configuration; equal configurations do not trigger a reparse.
• Pure-function unsupported-node scan under lib/src/parsing/, unit tested separately from the widgets.
• 43 package tests plus an example smoke test, covering parse counts, brightness and scale changes, heading fallback, alert slots, inline span composition and text directives, semantics, RTL wrapping, and selection.
• Example app with a theme toggle, README, CHANGELOG, LICENSE, and light/dark screenshots.
• Publish-contract and public-API tests mirroring mix_chart.

mix_generator fix

• firstInvisibleTypeName recursed into a type alias's expansion, so a visible typedef whose parameters name types the annotated library does not import was rejected. Generated code only ever writes the alias name, so the expansion does not need to be visible. Added a regression test.

Wiring and docs

• melos.yaml: register the package and its example under flutter_projects.
• .github/workflows/publish.yml: add the mix_markdown-v* tag pattern and publish job.
• README.md, AGENTS.md, llms.txt, and the mix skill: list the package (the structure block in AGENTS.md now lists every package, not just the original four).

Review Checklist

• Testing: Have you tested your changes, including unit tests and integration tests for affected code?
• Breaking Changes: Does this change introduce breaking changes affecting existing code or users? — No. The package is new, and the generator fix only widens what the generator accepts.
• Documentation Updates: Are all relevant documentation files (e.g. README, API docs) updated to reflect the changes in this PR?
• Website Updates: Is the website containing the updates you make on documentation? — Not included. The package is experimental, and btwld/mix-docs lives outside this repo.

Additional Information (optional)

Verification on the current head (branch is merged up to date with main):

Check	Result
melos run format:check	SUCCESS
melos run analyze:dart	No issues, every package
mix_markdown tests	43 pass
mix_markdown/example test	1 pass
mix_generator tests	379 pass
dart pub publish --dry-run	Passes, only the expected melos-override hints
pana	140/160 locally; the missing points are sandbox artifacts (no cwebp, no network for URL checks, shared lint file excluded from the archive by .pubignore, exactly as mix_chart does)

DCM could not run in the environment used to prepare this, since it has no licence there. CI skips it too, so its rules were applied by hand (member ordering, newline-before-return, named booleans).

Where a reviewer should start:

1. lib/src/specs/markdown_spec.dart for the public style contract. The main open design question is whether the slot set is the right one, particularly that inline slots contribute only their resolved TextStyle (inline runs are spans, not widgets, so modifiers and animation cannot apply to them).
2. lib/src/widgets/markdown_document.dart for the parse lifecycle. The state parses in initState and didUpdateWidget only, never in build, which is what keeps style changes free. Parse counts are asserted in the widget tests.
3. lib/src/parsing/unsupported_nodes.dart for the subset boundary. Worth checking the policy is the one the project wants: a paragraph holding only an image reports standalone-image rather than rendering alt text, and unsupported blocks anywhere, including inside an alert, reject the whole document.
4. packages/mix_generator/lib/src/core/helpers/library_scope.dart for the one-line behavioural change outside the new package.

Decisions worth a second opinion:

• The version is 0.0.1-beta.0 with publish metadata, matching how mix_chart entered the repo. Say if this should ship with publish_to: none until the API settles.
• Dependency floors are mix: ^2.2.0-beta.5 and mix_annotations: ^2.2.0-beta.1, following mix_chart in not tracking every release bump.
• Missing heading slots fall back to paragraph, and blockSpacing defaults to zero. No theme-derived typography defaults, matching Mix's explicit-style approach.
• Active links, lists, tables, and fenced code are deliberately out of scope for this first cut.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QnNfDRXutaME1C2FAGBYKv