luna

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.

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/luna MoonBit code in this repo
• Adding or moving an example under luna/src/examples/ or luna_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.mjs chain in references/csr-app-scaffolding.md. For reactivity changes, use the console_log verification in references/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 components
• luna/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)