Tutorial: preview the unreleased kolay (docs() plugin rework)

[NullVoxPopuli-ai-agent]

Previews the unreleased kolay (the plugin rework, universal-ember/kolay#323) on the tutorial app before the release — same mechanism as universal-ember/ember-primitives#794: a root pnpm.overrides entry resolves kolay to github:universal-ember/kolay#dist (the built package contents kolay pushes on every commit to main), so apps/tutorial keeps its declared range. When kolay releases, the override goes away and the range gets bumped instead.

Migration (kolay 4.x → next)

• vite: kolay({ src, exclude, onlyDirectories, packages }) → docs('docs', { src: import.meta.resolve('./public/docs') }). The manifest is file-based now (each lesson's prose.md is the page; the app already normalized /prose.md off paths). import.meta.resolve is required — a relative src produces broken /@fs imports (noted on Top-level scoped mounts register the real route name ('page', not 'application.page') universal-ember/kolay#350).
• router: addRoutes(this, 'docs') — a scoped mount serving the group from the root URL space, so all tutorial URLs are unchanged (/1-introduction/1-basics, …).
• optimizeDeps.exclude: ['kolay']: the scoped-route registry is stateful, so the router and the docs service must share one module instance (kolay's own docs-app does the same).
• paths: one lessonPath() util maps manifest paths (/docs/**/prose.md) to lesson URLs; selection, docs, selected, and nextPage go through it.
• hidden chapters: the plugin-level exclude option is gone. x-* chapters were already hidden app-side (isHidden, with the ?showHidden escape hatch); the check is segment-based now so x-* files inside chapters stay hidden too, and keyed-each-blocks keeps its dev-only visibility via import.meta.env.PROD in the same place. Net behavior change: hidden chapters are now routable by direct URL in prod (they 404'd via manifest-absence before) — their content was always fetchable from /docs/** anyway.
• lesson-only nav: onlyDirectories is gone too, so the stray .md notes sitting next to lesson directories (8 of them under 7-form-data/) would become broken nav entries (no prompt.gjs/prose.md beneath them). isHidden now admits only lesson directories (via their prose.md), matching the old manifest exactly: 14 chapters / 68 lessons in prod, +keyed-each-blocks in dev.
• setupKolay: the empty resolve: {} option is gone (it's modules now).
• cssTarget: vite 8's default downlevels light-dark() into space-toggle vars whose :root definitions don't survive chunking, invalidating kolay's colors (found on ember-primitives#794); target browsers that support it natively.

Depends on

⚠️ universal-ember/kolay#350 — top-level scoped mounts register as 'application.page' instead of 'page' (ember's DSL reports the map root's parent as 'application'), so the mount is never detected. Verified locally with that fix applied to the resolved dist copy; once #350 merges, pnpm update kolay here re-pins dist and this PR goes green.

Verification

• dev server: root redirect, chapter/lesson select (14 chapters — the 5 x-* hidden, keyed-each-blocks visible in dev), prev/next navigation, prose + editor + live output all work; URLs identical to production today
• lint:types passes; the visitable application test suite passes locally
• prod build: light-dark() preserved in CSS; keyed-each-blocks hidden

🤖 Generated with Claude Code

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[NullVoxPopuli-ai-agent]

CI confirms the dependency called out above: the only failures are the tutorial "Visiting" tests (the scoped root mount), against a dist kolay that predates universal-ember/kolay#350. Every other suite passes. Once #350 merges and dist updates, I'll re-pin with pnpm update kolay here.

[github-actions]

Project	Preview URL1	Manage
Limber	https://tutorial-kolay-preview.limber-glimdown.pages.dev	on Cloudflare
Tutorial	https://tutorial-kolay-preview.limber-glimmer-tutorial.pages.dev	on Cloudflare

Logs

Footnotes

1. if these branch preview links are not working, please check the logs for the commit-based preview link. There is a character limit of 28 for the branch subdomain, as well as some other heuristics, described here for the sake of implementation ease in deploy-preview.yml, that algo has been omitted. The URLs are logged in the wrangler output, but it's hard to get outputs from a matrix job. ↩