feat(remix_cli): add Sidebar and a preset tutorial

[tilucasoli]

Description

The default preset does not expose Sidebar through the CLI. This PR adds its recipe and a complete screenshot tutorial.
This PR targets #180, after the Open Code PR #177.

Sidebar destinations use the application's toggle recipe. The existing installer adds theme, toggle, and sidebar in dependency order.
The template uses the default registry path from #180. Both registries require Remix beta.9, which includes RemixSidebar.
The playground contains the installed recipe and generated adapter. The source describes ordinary Tab traversal.

The tutorial follows an empty Flutter project through installation, composition, customization, source preservation, and behavior checks.
It includes both presets, complete source, eight application screenshots, and downloadable sample projects.
It explains application ownership, generated adapters, scope placement, and CI. The existing reference guide links to the tutorial.
The tutorial uses the reviewed checkout because the required package versions await publication.

The tutorial uses local fonts and syntax highlighting. It provides compact navigation, code wrapping, copy controls, and keyboard access to long examples.
An installation diagram identifies the files that the CLI, generator, and application own.
The instructions now identify the second terminal and the starting directory for the Fortal project.
The page requires no build step or remote asset service. The original screenshots and sample archive remain unchanged.

Related Issues

Related to #168, #177, and #180.

---

Checklist

• My PR includes unit or integration tests for all changed behaviors.
• I have updated the relevant documentation.
• I am prepared to follow up on review comments.

Validation

• The complete CLI suite passed 86 tests before the documentation changes.
• A fresh tutorial replay completed 36 commands with no failures.
• Both fresh presets passed analysis, four behavior tests each, and release web builds.
• Both archived sample projects passed dependency resolution, analysis, and four tests each.
• The replay verified installation, first render, composition, recipe customization, and source preservation.
• All 64 URL references resolve. All 39 IDs are unique. The eight application screenshots and sample archive retain their digests.
• Of 35 code blocks, 34 match the previous verified tutorial. The Fortal setup adds the required directory change.
• Chrome checks passed for navigation, source disclosure, syntax highlighting, copy feedback, code wrapping, and keyboard scrolling.
• Chrome displayed the desktop layout and narrow layouts in 390-pixel and 320-pixel frames without page overflow.
• Chrome reported no tutorial console warnings or errors. Syntax colors have contrast ratios of at least 8.52 against the code surface.
• Browser policy blocks automated file URL access. The HTTP preview was checked; all 28 files in the Downloads copy match the repository.
• GitHub CI for the current commit records the automated results.

Visual evidence

The tutorial shows the first render with highlighted Dart source, file labels, and the current section.

The default sample uses the installed Sidebar and a local Button customization.
The application supplies its screen and callbacks. The CLI installs the theme and recipes.

Breaking Change

• Yes.
• No. This PR adds one registry item and its tutorial.

[leoafarias]

The recipe and the integration are good — I arrived at nearly the same design independently, so I want to be clear that the craft here is not the issue. registryDependencies: [theme, toggle], the destination styled through the application's own toggle recipe rather than loose box properties, no panel width set, header and section left at their defaults: all correct, and the reasoning in the comments is right.

The blocker is timing, and it is reproducible. I ran dart run tool/check_open_code.dart against this branch. It fails, exit 1:

E mix_generator:mix_widget_generator on lib/ui/components/sidebar.dart:
  @MixWidget target must resolve to a Style<S> subtype, but got `InvalidType`.
  48 │ SidebarStyler acmeSidebarStyle({

open-code check failed: remix add sidebar failed in the fresh app

It installs 24 items successfully and dies on the 25th. 1.0.0-beta.7 is the highest published remix and it has no RemixSidebar, so the item cannot generate against the floor the registry declares.

One consequence that is worse than it first looks. The installer unions every already-installed adapter into one generation batch, so the failure is not scoped to sidebar:

--build-filter=...toggle.g.dart --build-filter=...sidebar.g.dart --build-filter=...button.g.dart  (23 adapters)
→ 21 skipped, 1 output

remix add sidebar therefore aborts generation for every component already installed, and leaves authored source on disk with generation incomplete. For a consumer that is a bad failure mode rather than a no-op.

Why CI is green here. ci.yaml triggers on pull_request: branches: [main]. This PR targets feat/open-code, so only the PR-title validator ran — the end-to-end gate never executed. The failure will surface on #177 (feat/open-code → main) instead of here.

Suggested paths, either is fine:

1. Release a remix carrying Sidebar, run dart run tool/sync_registry_remix.dart to raise the floor, then merge this as-is. Cleanest, nothing to undo.
2. Drop the three registry references (registry.yaml, _registryItems, registry_test.dart) and keep the template, tests, playground install, and docs. Restore them after that release.

Two smaller things noted inline. Leaving this as a comment rather than a block, in case landing ahead of the release is already the agreed plan.

[leoafarias]

This entry is what turns tool/check_open_code.dart red. The registry floors at remix: ^1.0.0-beta.7, and I confirmed against the pub.dev API that beta.7 is the highest published version — it predates RemixSidebar, so remix add sidebar cannot generate in a consumer app.

The rest of the item is right: [theme, toggle] is a real dependency, not a convenience, because the destination is a nested StyleSpec<ToggleSpec> that RemixSidebar resolves inside each destination's own state context. Worth keeping exactly as written for when the floor moves.

[leoafarias]

This note is accurate and I appreciate it being explicit — it is how I confirmed the constraint was known rather than missed.

The thing it cannot do is prevent the breakage. A registry is a distribution surface, so a consumer who runs remix add sidebar today gets @MixWidget target must resolve to a Style<S> subtype, but got InvalidType — a message that names neither SidebarStyler nor the version cause. Most people will not connect that to a changelog line.

After sync_registry_remix.dart raises the floor this paragraph can go away entirely, which is another argument for landing the item with the release rather than ahead of it.

[leoafarias]

Two notes on this one line.

First, the count above is now stale — the section still reads "29 core components" while the table lists 30.

Second, and this one is my fault rather than yours: this file is generated from a build pipeline that currently lives in a gitignored directory on my machine, so there is no way for you to know that hand-editing the built HTML is not the intended path. My next rebuild would silently drop this row. I will either commit the pipeline or convert the file to hand-maintained so it stops being a trap.

[leoafarias]

Correct placement, and this line is doing its job: _verifyRegistryCoverage requires this list and the registry to agree, so the item cannot be added in one place and forgotten in the other.

It is also the line that makes the end-to-end gate attempt the install, which is how the version blocker surfaces. If you take path 2 above, this comes out with the registry entry and goes back with it.