mizchi luna (luna.mbt project skill)
Purpose
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.
When to use
- Writing or modifying any
mizchi/lunaMoonBit code in this repo - Adding or moving an example under
luna/src/examples/orluna_components/src/examples/ - A luna effect / route / component re-renders on signal changes that should be local
- Onboarding to luna for the first time, or coming back after a long break
- Reviewing a PR that touches luna's public API or examples
Step 1 — orient (only on first encounter)
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.
Step 2 — pick the reference page
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.
Step 3 — verify before claiming done
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.mjschain inreferences/csr-app-scaffolding.md. For reactivity changes, use theconsole_logverification inreferences/signal-tracking.md.
Related
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 helpers- Sibling skills:
sol-cloudflare-deploy,playwright-pnpm-workspace(when the work crosses into sol or e2e tests)