// Use whenever working with `mizchi/luna` in the luna.mbt repo — writing CSR examples, fixing reactivity bugs (effects re-running on unrelated signal changes), adding new luna features, or onboarding to luna's mental model. This is the unified entry point; pick the right reference page below for the specific situation.
Use when running `sol new` for the first time, when `sol <subcommand>` fails with `failed to resolve path mizchi/sol/cmd/sol_js` / `Run this command inside a MoonBit project that depends on mizchi/sol.`, or when moving from `sol dev` to `sol build` / `sol serve` for the first time. Covers (a) the bootstrap rules — `sol new <name> --user <ns>` works in an empty directory as of sol 0.22.2, but `--cloudflare` / `--doc` / `--dev` still need a host moon project, and every non-new subcommand needs `.mooncakes/mizchi/sol/` locally (= `moon install` after `sol new`) — (b) the sol 0.22.x scaffold layout (`app/server/routes.mbt` holds routes + page handlers; `app/layout/` is a separate package; `/` and `/about` are pre-registered) and (c) the production flow gotchas (`sol build` writes to two directories, `sol serve` does NOT rebuild, dev & prod both default to :7777).
Page description for <meta>
Use when running Playwright tests in this repo (luna.mbt) and either the test fails to discover specs ("did not expect test.describe()" / "two different versions of @playwright/test") or you're adding a new playwright config under astra/ or sol/. Captures the version-skew between root and per-package @playwright/test pins.
Use when deploying sol_app (or any sol-built MoonBit SSR worker) to Cloudflare Workers, debugging error 10021, or extending sol/examples/sol_app/scripts/patch-cloudflare-globals.mjs. Captures the global-scope I/O traps in MoonBit core + sol's generated bundle and the wrangler ASSETS binding URL layout.
| name | luna |
| description | Use whenever working with `mizchi/luna` in the luna.mbt repo — writing CSR examples, fixing reactivity bugs (effects re-running on unrelated signal changes), adding new luna features, or onboarding to luna's mental model. This is the unified entry point; pick the right reference page below for the specific situation. |
mizchi/luna is the fine-grained reactive UI primitive that sits under sol
and astra. It's small in surface but easy to misuse in two specific ways
(reactivity tracking, example-pipeline registration) that have already burned
real time in this repo. This skill collects the recovered knowledge as one
entry point so a luna task lands on the right page in one hop.
mizchi/luna MoonBit code in this repoluna/src/examples/ or luna_components/src/examples/Read luna/docs/onboarding.md once. It establishes the mental model
(fine-grained reactivity, abstract VNode, no server / routing / SSG inside
luna) and the directory map (luna/src/{core,dom,js,x}, luna_components/,
js/luna/, sol & astra siblings). Skip if you already have that model.
Match the situation to one of the pages under references/:
| Situation | Reference page |
|---|---|
"the route effect / a top-level effect re-runs on local state changes", "nested Show infinite loop", "I'm about to write a new top-level @resource.effect that builds DOM", "multiple signal.set() calls fire too many effect runs" | references/signal-tracking.md |
"add a new example under luna/src/examples/<name>/", "vite dev 404s on my new example", "pnpm build skips it", "deploy bundle is missing the new example" | references/csr-app-scaffolding.md |
If the situation is outside both pages (e.g. CSS extraction, web component
authoring, hydration internals), the existing per-module README in
luna/src/x/<area>/README.md and the ADRs in luna/spec/00*-*.md are the
canonical source — there is no skill page for those areas yet.
The reference pages each include a verification recipe. If the page you followed didn't, the minimum baseline for any luna change is:
moon check --target js # 0 errors (594 warnings is the current baseline)
moon test --target js # must stay 2794 PASS
For CSR example changes, also run the full moon build --target js --release
pnpm --filter ./luna dev + node luna/scripts/build-demo.mjs chain in
references/csr-app-scaffolding.md. For reactivity changes, use the
console_log verification in references/signal-tracking.md.luna/docs/onboarding.md — newcomer mental model + directory map (Step 1 above)luna/spec/00{1..5}-*.md — ADRs for signal system, CSS utility, VNode abstraction, hydration, web componentsluna/src/x/css/README.md — atomic CSS utility usage rules (string-literal extraction, SSR vs Island placement)luna/src/x/stella/README.md — Shard / Island fragment generator (sol/astra internal)luna/src/x/testing/README.md — DOM-less VNode unit-test helperssol-cloudflare-deploy, playwright-pnpm-workspace (when the work crosses into sol or e2e tests)