@c9up/nebula 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# @c9up/nebula
+
+> shadcn/ui, ported to Aurora, organised as atomic design. Zero runtime dependencies, copy-the-source registry, swappable CSS engine.
+
+Part of **[Ream](https://github.com/C9up/ream)** — a Rust-powered, AdonisJS-compatible Node.js framework. Independent, publishable package.
+
+## What this is
+
+shadcn/ui is React. [Aurora](https://github.com/C9up/aurora) is a tagged-template DOM runtime with signals and no build step. nebula is the shadcn component set — the same markup, the same Tailwind classes, the same behaviour — written for Aurora.
+
+Sixty-nine components across four atomic layers, plus the headless behaviour layer Radix would otherwise provide. Every component in shadcn's registry has a counterpart; several are deliberately narrower, and the [parity section](#parity-with-shadcn) says exactly which.
+
+## Installation
+
+```bash
+ream add @c9up/nebula --adapter tailwind
+```
+
+The same one-step install as every other ream package: it installs the package and dispatches to nebula's `configure()` hook, which writes `config/nebula.ts` and the stylesheet for your chosen engine, then prints the packages to install and the build command to register. It installs nothing itself and edits no `package.json` of yours.
+
+Changing the adapter later is `ream configure @c9up/nebula --adapter unocss`.
+
+## Two ways to use it
+
+```ts
+// Import it — quickest to try
+import { Button, Card, CardHeader } from '@c9up/nebula'
+
+// Or take the source — what the library is really for
+// $ ream nebula:add button card
+import { Button } from '#pages/atoms/Button.js'
+```
+
+`ream nebula:add` copies the component's source into your project and hands it over. No version, no upgrade path, no wrapper to fight when a design needs one class changed. That is shadcn's premise and nebula keeps it.
+
+```bash
+ream nebula:list                    # everything in the registry
+ream nebula:list --layer organisms
+ream nebula:add dialog data-table   # copies both, plus what they depend on
+ream nebula:add button --force      # overwrite your edited copy
+```
+
+Subcommands on the ream binary, not a CLI of nebula's own — the same place
+`ream nova:vapid:generate` lives. The registry logic stays in this package; the
+binary dispatches to it.
+
+Copies mirror the package's own layout, so `atoms/Button` finds `../lib/cva.js` for the same reason it does inside nebula. **No import is ever rewritten** — that is where a copy-the-source CLI usually accumulates its edge cases.
+
+**JavaScript by default.** An Aurora app serves `resources/pages` to the browser unbuilt — that zero-build-step promise is the framework's premise — so TypeScript dropped into that tree does not run. `ream nebula:add` copies the compiled output instead: valid ESM, `.js` specifiers already correct, and every doc comment intact, so what you own is still readable source. The language is inferred from what your components directory already holds; `--ts` and `--js` override it.
+
+## Zero runtime dependencies
+
+shadcn stands on Radix, `clsx`, `tailwind-merge`, `class-variance-authority`, `lucide-react`, `@floating-ui/dom`, `cmdk`, `sonner`, `recharts`, `@tanstack/react-table` and `react-day-picker`. None are React-agnostic, and this workspace had already decided `cn` was worth writing by hand rather than installing two packages. So:
+
+| shadcn dependency | nebula |
+| --- | --- |
+| `clsx` + `tailwind-merge` | `cn` from `@c9up/aurora` — already written from scratch there |
+| `class-variance-authority` | `lib/cva.ts` — reimplemented, and it runs its result through `cn` |
+| Radix UI | `primitives/` — focus trap, dismissable layers, roving focus, type-ahead, presence, portals |
+| `@floating-ui/dom` | `primitives/floating.ts` — offset, flip, shift, arrow, available height |
+| `lucide-react` | `lib/icons.ts` — the eighteen glyphs the set needs, inlined |
+| `cmdk` | `organisms/Command.ts` |
+| `sonner` | `organisms/Toaster.ts` |
+| `react-day-picker` + `date-fns` | `organisms/Calendar.ts` — `Date` and `Intl` |
+| `@tanstack/react-table` | `organisms/DataTable.ts` — sort, filter, page, select |
+| `recharts` | `organisms/Chart.ts` — line, area and bar, as inline SVG |
+| `react-hook-form` | `form()` from `@c9up/aurora`, bound by `organisms/Form.ts` |
+| `tw-animate-css` | four keyframes in `theme.css` |
+
+Several of those are narrower than what they replace — see [parity with shadcn](#parity-with-shadcn) for the full list rather than a reassuring summary.
+
+## Parity with shadcn
+
+Checked against shadcn's published component list, not from memory. Every one of its components has a counterpart here — including the conversational set (`Bubble`, `Message`, `MessageScroller`, `Attachment`, `Marker`), `NativeSelect` and `Questionnaire` — and the ~40 simple ones are faithful down to the class strings, the variants and the ARIA attributes.
+
+Two of shadcn's entries have no direct counterpart on purpose. `DirectionProvider` is React context; Aurora has none, and the direction belongs on `<html dir>` — what it was really buying is [RTL support](#right-to-left), which is handled in the placement engine instead. `Form` has been folded into `Field` upstream; nebula ships both, with `Form` binding Aurora's own form controller. The components shadcn builds by wrapping a third-party library are reimplementations, and they are narrower. Stated plainly, because "complete port" would not be true:
+
+| Component | shadcn | nebula |
+| --- | --- | --- |
+| Chart | Recharts, in full | line, area and bar over one categorical axis |
+| DataTable | TanStack Table (column grouping, virtualisation, pinning, faceted filters, server-side) | sort, filter, page, select — in memory |
+| Sidebar | ~15 parts | the parts that are not re-skinned atoms — see below |
+| Carousel | embla (loop, autoplay, N slides per view) | scroll-snap, one slide per view, no loop or autoplay |
+| Toaster | sonner (promise toasts, arbitrary JSX, multiple positions) | four variants, action, pause on hover |
+| Resizable | arbitrary nesting, persisted layouts, collapse-to-zero | two panes, one handle |
+| Combobox | single, multi-select and creatable recipes | single-select |
+| ScrollArea | scrollbars redrawn by Radix | native scrollbars, styled |
+| Calendar | react-day-picker, every selection mode | single date and range; no multi-month, no multi-select |
+| Questionnaire | branching logic, validation schemas | linear steps; single, multiple, freeform, skippable |
+| Bubble / Message | rich composition slots | the parts nebula's own layout needs |
+
+Two API-wide differences, both consequences of the runtime rather than choices about scope: there is no `asChild` (a compiled template has no element to clone), and compound components take data rather than children (Aurora has no React context).
+
+**The Sidebar deserves its own note**, because porting it part-for-part would have fought the atomic taxonomy rather than following it. `SidebarInput`, `SidebarSeparator` and `SidebarMenuSkeleton` are the existing `Input`, `Separator` and `Skeleton` atoms with a prefix — redeclaring them would break the composition rule the whole library is organised on. `SidebarProvider` is React context, and nebula's sidebar owns its own shared signal instead. `SidebarInset` is the content column beside the rail, which is `AppShell`, a template. What was genuinely missing and has been added: `SidebarMenuSub`, `SidebarMenuSubItem`, `SidebarMenuAction`, a badge slot, and tooltips when the rail is collapsed.
+
+## Right to left
+
+The placement engine mirrors itself. Placements are written physically —
+`"right-start"` for a submenu — because that is what reads clearly at the call
+site, and `resolvePosition` flips them when the anchor computes to
+`direction: rtl`. `autoPosition` reads that off the anchor on every update, so
+no component passes a flag and a language switcher flipped mid-session moves
+open surfaces with it.
+
+The mirror is not symmetric, which is the part worth knowing: for `left`/`right`
+the *side* swaps and the alignment is untouched; for `top`/`bottom` the side
+stays and the *alignment* swaps. Mirroring both halves of `bottom-start` would
+land it back where it started.
+
+Components use logical properties (`ms-*`, `me-*`, `start-*`, `end-*`) wherever
+a side is meant relative to the text, so a `Bubble` aligned to the end sits
+right in English and left in Arabic. Where a side is a genuine layout choice —
+which edge a `Sheet` enters from, which side a `Sidebar` occupies — it stays
+physical, because that is what the caller means.
+
+## Choose your CSS engine
+
+nebula declares **no CSS dependency at all**, not even a peer one. You install the engine you want; `config/nebula.ts` names it; nebula generates the matching stubs and build command. Same arrangement AdonisJS uses for its asset bundler.
+
+```ts
+// config/nebula.ts
+import { defineConfig } from '@c9up/nebula'
+
+export default defineConfig({
+  adapter: 'tailwind',              // 'tailwind' | 'unocss' | 'css'
+  paths: {
+    components: 'resources/pages',
+    css: 'resources/css/app.css',
+    output: 'public/app.css',
+  },
+})
+```
+
+| Adapter | What it does | You install |
+| --- | --- | --- |
+| `tailwind` | Tailwind v4, configured in CSS. What shadcn itself targets. | `tailwindcss @tailwindcss/cli` |
+| `unocss` | `presetWind4` — same class syntax, no PostCSS, faster. | `unocss @unocss/cli` |
+| `css` | Nothing. nebula ships a prebuilt stylesheet. | — |
+
+All three consume the same class names, which is what lets one set of components serve all of them. Switching is a one-word change plus `ream configure @c9up/nebula`.
+
+**The `css` adapter's limit, stated plainly.** `nebula.css` is compiled at nebula's release time and covers the components as published. Edit a copied component to add a utility nebula never used and nothing emits it — the class silently does nothing. Use it when you take the components as they are; use `tailwind` or `unocss` when you intend to retune them.
+
+An engine with a different authoring model — Panda's recipes, StyleX — cannot go behind this interface. It would need a second version of every component.
+
+## Atomic design
+
+shadcn is a flat `ui/` directory. nebula sorts the same components into layers, and the layer is a property of the component: `nebula add button` knows Button is an atom.
+
+```
+resources/pages/
+├── lib/          cn, cva, icons, ids, reactive props
+├── primitives/   the headless layer — focus, dismissal, placement, presence
+├── atoms/        one element, composing nothing from nebula
+├── molecules/    assembles atoms, or owns state across several elements
+├── organisms/    portals, traps focus, floats, or coordinates molecules
+└── templates/    page skeletons
+```
+
+The rule is composition, not complexity. Slider is an atom though it is interactive, because it is one input. Card is a molecule though it is trivial, because it assembles parts.
+
+<details>
+<summary><strong>All 69 components</strong></summary>
+
+**atoms (19)** — AspectRatio, Avatar, Badge, Button, Checkbox, Input, Kbd, Label, Marker, NativeSelect, Progress, ScrollArea, Separator, Skeleton, Slider, Spinner, Switch, Textarea, Toggle
+
+**molecules (21)** — Accordion, Alert, Attachment, Breadcrumb, Bubble, ButtonGroup, Card, Collapsible, Empty, Field, InputGroup, InputOTP, Item, Message, Pagination, RadioGroup, Resizable, Table, Tabs, ToggleGroup, Typography
+
+**organisms (26)** — AlertDialog, Calendar, Carousel, Chart, Combobox, Command, CommandDialog, ContextMenu, DataTable, DatePicker, DateRangePicker, Dialog, Drawer, DropdownMenu, Form, HoverCard, Menubar, MessageScroller, NavigationMenu, Popover, Questionnaire, Select, Sheet, Sidebar, Toaster, Tooltip
+
+**templates (3)** — AppShell, AuthLayout, SettingsLayout
+
+</details>
+
+## The API difference
+
+shadcn composes through React context:
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList><TabsTrigger value="account">Account</TabsTrigger></TabsList>
+  <TabsContent value="account">…</TabsContent>
+</Tabs>
+```
+
+Aurora has no context, and the workarounds — a factory returning bound parts, a handle threaded through props — are more machinery for less clarity. So compound components take data:
+
+```ts
+Tabs({
+  defaultValue: 'account',
+  items: [
+    { value: 'account', label: 'Account', content: html`…` },
+    { value: 'password', label: 'Password', content: html`…` },
+  ],
+})
+```
+
+The rendered markup is unchanged, so shadcn's CSS and its examples still read across. Free-form containers take named slots instead:
+
+```ts
+Dialog({
+  trigger: 'Edit profile',
+  title: 'Edit profile',
+  description: "Make changes here. Click save when you're done.",
+  children: [TextField({ bind: bind(profile, 'name'), label: 'Name' })],
+  footer: SubmitButton({ form: profile, label: 'Save' }),
+})
+```
+
+There is no `asChild`. React's Slot clones an element and merges props into it; Aurora templates are compiled markup with nothing to clone. Where shadcn writes `<Button asChild><a/></Button>`, nebula exports the variants:
+
+```ts
+html`<a href="/docs" class="${buttonVariants({ variant: 'outline' })}">Docs</a>`
+```
+
+## Reactive props
+
+Aurora never re-renders. Any prop that can change is `Reactive<T>` — pass a constant when it never moves, an accessor when it does:
+
+```ts
+Button({ disabled: true })                  // static
+Button({ disabled: () => form.submitting() }) // live
+```
+
+A value read once at setup is frozen for the lifetime of the node, so `disabled: form.submitting()` is a bug that only shows after the first submit.
+
+## Accessibility
+
+The headless layer is most of this package, and it is where shadcn's behaviour actually lives. What is implemented, rather than approximated:
+
+- **Focus trap** — Tab wraps, focus returns to the trigger, and a `focusin` handler catches focus arriving by any other route.
+- **Modal** — the page behind is `aria-hidden`, not merely unreachable by Tab. Trapping keyboard focus does nothing for a reader navigating by landmark.
+- **Dismissable layers** — one stack. Escape reaches the topmost layer that accepts it; a pointer outside closes layers above the one it landed in and no further.
+- **Roving focus** — a menu, tab list or toolbar is one tab stop.
+- **Type-ahead** — accumulating buffer, and a repeated letter cycles.
+- **Charts** — the same data is emitted as a visually hidden `<table>`. No ARIA makes an SVG readable.
+- **Live regions** — `polite` for toasts, `assertive` for errors, mounted empty before anything arrives.
+
+## Development
+
+```bash
+pnpm test        # 391 unit tests
+pnpm typecheck
+pnpm lint
+pnpm registry    # regenerate registry.json from the source tree
+pnpm css         # freeze nebula.css for the `css` adapter
+pnpm build
+```
+
+`registry.json` is derived from the imports rather than maintained by hand, and a test asserts that every file an item ships actually resolves — the failure it guards is otherwise silent, showing up in a user's build rather than here.
+
+Coverage sits around 83% of statements. The shape matters more than the number: every component is mounted and unmounted by `render-smoke.test.ts`, the shared surfaces and the headless primitives are tested directly, and the overlays are opened rather than only rendered closed. What the suite cannot reach is pointer-drag — happy-dom has no `setPointerCapture`, so Drawer's swipe-to-dismiss and Resizable's drag are covered by their keyboard paths only.
+
+## Licence
+
+MIT

package/dist/adapters/css.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The engine-free adapter.
+ *
+ * No Tailwind, no UnoCSS, no build step in the app at all: nebula ships a
+ * prebuilt `nebula.css` holding exactly the utilities its own components
+ * reference, and the app imports it.
+ *
+ * **Where the compilation actually happens.** nebula's own release build runs
+ * Tailwind over `src/**` and freezes the result (`scripts/build-css.ts`).
+ * Tailwind is therefore a devDependency *of nebula* and never reaches the
+ * app's dependency tree — which is the whole point. The set of utilities is
+ * knowable ahead of time because the components are nebula's, and they do not
+ * change between one app's install and another's.
+ *
+ * **The limitation, stated plainly.** The frozen stylesheet covers the
+ * components as nebula wrote them. The registry copies those sources into the
+ * app for the user to edit, and the moment an edit introduces a utility nebula
+ * never used — `bg-emerald-500`, `grid-cols-7` — nothing emits it, and the
+ * class silently does nothing.
+ *
+ * So this adapter suits an app that takes the components as they are and
+ * writes its own hand-rolled CSS around them. An app that intends to retune
+ * components through their class strings wants `tailwind` or `unocss`, where
+ * the scanner sees the edits.
+ *
+ * Lifting that limitation means compiling the app's copied sources too — a
+ * utility scanner and a CSS emitter over the finite surface nebula uses. That
+ * is a build-time, string-heavy, run-on-every-build job, which is the profile
+ * where moving it into `ream-cli` (Rust) pays; it is the one part of nebula
+ * where Rust would earn its place.
+ */
+import type { StyleAdapter } from "./types.js";
+export declare const cssAdapter: StyleAdapter;

package/dist/adapters/css.js

@@ -0,0 +1,67 @@
+/**
+ * The engine-free adapter.
+ *
+ * No Tailwind, no UnoCSS, no build step in the app at all: nebula ships a
+ * prebuilt `nebula.css` holding exactly the utilities its own components
+ * reference, and the app imports it.
+ *
+ * **Where the compilation actually happens.** nebula's own release build runs
+ * Tailwind over `src/**` and freezes the result (`scripts/build-css.ts`).
+ * Tailwind is therefore a devDependency *of nebula* and never reaches the
+ * app's dependency tree — which is the whole point. The set of utilities is
+ * knowable ahead of time because the components are nebula's, and they do not
+ * change between one app's install and another's.
+ *
+ * **The limitation, stated plainly.** The frozen stylesheet covers the
+ * components as nebula wrote them. The registry copies those sources into the
+ * app for the user to edit, and the moment an edit introduces a utility nebula
+ * never used — `bg-emerald-500`, `grid-cols-7` — nothing emits it, and the
+ * class silently does nothing.
+ *
+ * So this adapter suits an app that takes the components as they are and
+ * writes its own hand-rolled CSS around them. An app that intends to retune
+ * components through their class strings wants `tailwind` or `unocss`, where
+ * the scanner sees the edits.
+ *
+ * Lifting that limitation means compiling the app's copied sources too — a
+ * utility scanner and a CSS emitter over the finite surface nebula uses. That
+ * is a build-time, string-heavy, run-on-every-build job, which is the profile
+ * where moving it into `ream-cli` (Rust) pays; it is the one part of nebula
+ * where Rust would earn its place.
+ */
+function stylesheet() {
+    return `/*
+ * nebula, engine-free.
+ *
+ * \`nebula.css\` is prebuilt and shipped with the package — no scanner runs in
+ * this project, so nothing here needs a build step.
+ *
+ * It covers nebula's components as published. A utility you add to a copied
+ * component will not be emitted; write the rule below by hand, or switch the
+ * adapter in \`config/nebula.ts\` to \`tailwind\` or \`unocss\`.
+ */
+@import "@c9up/nebula/nebula.css";
+
+/* Your own styles go here. */
+`;
+}
+export const cssAdapter = {
+    name: "css",
+    summary: "No engine and no build step — nebula's prebuilt stylesheet, imported as-is.",
+    packages: [],
+    files(config) {
+        return [
+            { path: config.paths.css, contents: stylesheet(), skipIfExists: true },
+        ];
+    },
+    /**
+     * Nothing to compile.
+     *
+     * `null` rather than a copy command: the app serves the stylesheet straight
+     * from the package, so there is no compile step for `ream build` to run and
+     * none should be registered.
+     */
+    commands() {
+        return null;
+    },
+};

package/dist/adapters/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The three style adapters.
+ *
+ * All three consume the same utility class names, which is what lets one set
+ * of components serve all of them. Switching is a one-word change in
+ * `config/nebula.ts` followed by `ream nebula:init`.
+ */
+import type { AdapterName } from "../config.js";
+import type { StyleAdapter } from "./types.js";
+export { cssAdapter } from "./css.js";
+export { tailwindAdapter } from "./tailwind.js";
+export type { AdapterCommand, GeneratedFile, StyleAdapter, } from "./types.js";
+export { unocssAdapter } from "./unocss.js";
+export declare function adapterFor(name: AdapterName): StyleAdapter;
+export declare function adapterNames(): readonly AdapterName[];
+export declare function isAdapterName(value: string): value is AdapterName;

package/dist/adapters/index.js

@@ -0,0 +1,27 @@
+/**
+ * The three style adapters.
+ *
+ * All three consume the same utility class names, which is what lets one set
+ * of components serve all of them. Switching is a one-word change in
+ * `config/nebula.ts` followed by `ream nebula:init`.
+ */
+import { cssAdapter } from "./css.js";
+import { tailwindAdapter } from "./tailwind.js";
+import { unocssAdapter } from "./unocss.js";
+export { cssAdapter } from "./css.js";
+export { tailwindAdapter } from "./tailwind.js";
+export { unocssAdapter } from "./unocss.js";
+const adapters = {
+    tailwind: tailwindAdapter,
+    unocss: unocssAdapter,
+    css: cssAdapter,
+};
+export function adapterFor(name) {
+    return adapters[name];
+}
+export function adapterNames() {
+    return Object.keys(adapters).filter(isAdapterName);
+}
+export function isAdapterName(value) {
+    return value === "tailwind" || value === "unocss" || value === "css";
+}

package/dist/adapters/tailwind.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tailwind CSS v4 adapter.
+ *
+ * The default, and the one shadcn itself targets — so the class strings in
+ * nebula's components are exactly the ones upstream uses, and a shadcn example
+ * pasted into a nebula project renders the same.
+ *
+ * v4 is configured in CSS rather than a JS config file, which is why this
+ * emits a stylesheet and no `tailwind.config.js`. Three directives do the
+ * work:
+ *
+ * - `@source` points the scanner at the copied components. Without it Tailwind
+ *   never sees `bg-primary` and emits none of it — the single most common way
+ *   a v4 setup produces an unstyled page.
+ * - `@custom-variant dark` makes `dark:` respond to a `.dark` class rather
+ *   than the system preference, so a theme toggle can override the OS.
+ * - `@theme inline` maps nebula's plain custom properties onto Tailwind's
+ *   colour namespace, which is what turns `--primary` into a `bg-primary`
+ *   utility.
+ *
+ * The build runs through `@tailwindcss/cli`, matching the aurora apps already
+ * in this workspace.
+ */
+import type { StyleAdapter } from "./types.js";
+export declare const tailwindAdapter: StyleAdapter;

package/dist/adapters/tailwind.js

@@ -0,0 +1,122 @@
+/**
+ * Tailwind CSS v4 adapter.
+ *
+ * The default, and the one shadcn itself targets — so the class strings in
+ * nebula's components are exactly the ones upstream uses, and a shadcn example
+ * pasted into a nebula project renders the same.
+ *
+ * v4 is configured in CSS rather than a JS config file, which is why this
+ * emits a stylesheet and no `tailwind.config.js`. Three directives do the
+ * work:
+ *
+ * - `@source` points the scanner at the copied components. Without it Tailwind
+ *   never sees `bg-primary` and emits none of it — the single most common way
+ *   a v4 setup produces an unstyled page.
+ * - `@custom-variant dark` makes `dark:` respond to a `.dark` class rather
+ *   than the system preference, so a theme toggle can override the OS.
+ * - `@theme inline` maps nebula's plain custom properties onto Tailwind's
+ *   colour namespace, which is what turns `--primary` into a `bg-primary`
+ *   utility.
+ *
+ * The build runs through `@tailwindcss/cli`, matching the aurora apps already
+ * in this workspace.
+ */
+function stylesheet(config) {
+    return `@import "tailwindcss";
+@import "@c9up/nebula/theme.css";
+
+/* Scan the component tree so the utilities they use are emitted. */
+@source "${relativeFromCss(config)}";
+
+/* Class-based dark mode: \`dark:\` applies under any \`.dark\` ancestor. */
+@custom-variant dark (&:is(.dark *));
+
+/*
+ * Map nebula's tokens onto Tailwind's namespaces.
+ *
+ * \`inline\` matters: without it Tailwind copies the *values* at build time and
+ * the \`.dark\` overrides never reach the utilities, so dark mode changes the
+ * custom properties and nothing else.
+ */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+`;
+}
+/**
+ * `@source` is resolved relative to the stylesheet, not the project root.
+ *
+ * The two are rarely the same — `resources/css/app.css` scanning
+ * `resources/pages` needs `../pages` — and getting it wrong fails silently:
+ * Tailwind finds no files, emits no utilities, and the page renders unstyled
+ * with no error anywhere.
+ */
+function relativeFromCss(config) {
+    const cssDirectory = config.paths.css.split("/").slice(0, -1);
+    const target = config.paths.components.split("/");
+    let shared = 0;
+    while (shared < cssDirectory.length &&
+        shared < target.length &&
+        cssDirectory[shared] === target[shared]) {
+        shared += 1;
+    }
+    const up = new Array(cssDirectory.length - shared).fill("..");
+    return [...up, ...target.slice(shared)].join("/");
+}
+export const tailwindAdapter = {
+    name: "tailwind",
+    summary: "Tailwind CSS v4, configured in CSS. What shadcn/ui itself targets.",
+    packages: ["tailwindcss", "@tailwindcss/cli"],
+    files(config) {
+        return [
+            {
+                path: config.paths.css,
+                contents: stylesheet(config),
+                skipIfExists: true,
+            },
+        ];
+    },
+    commands(config) {
+        const base = ["-i", config.paths.css, "-o", config.paths.output];
+        return {
+            build: { command: "tailwindcss", args: base },
+            dev: { command: "tailwindcss", args: [...base, "--watch"] },
+        };
+    },
+};

package/dist/adapters/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The style-adapter contract.
+ *
+ * An adapter answers three questions and nothing else:
+ *
+ * 1. What does the app need to install? nebula never installs it — the app
+ *    owns its dependencies, and a UI library quietly adding a build tool to
+ *    someone's `package.json` is how a dependency tree gets away from them.
+ * 2. What files should exist? The stylesheet entry, and any engine config.
+ * 3. What command compiles them? Handed to ream's `assets` config, which
+ *    `ream dev` and `ream build` already run — the same hook AdonisJS uses for
+ *    its bundler.
+ *
+ * Deliberately not in the contract: anything that would change how a component
+ * is written. All three adapters consume the same utility class names, which
+ * is what keeps one set of fifty-odd components serving all of them. An engine
+ * with a different authoring model — Panda's recipes, StyleX's compile-time
+ * API — cannot be added behind this interface, and pretending otherwise would
+ * mean a second version of every component.
+ */
+import type { ResolvedNebulaConfig } from "../config.js";
+export interface GeneratedFile {
+    /** Path relative to the project root. */
+    path: string;
+    contents: string;
+    /**
+     * Leave an existing file alone. True for anything the user is expected to
+     * edit — their stylesheet is theirs once it exists.
+     */
+    skipIfExists: boolean;
+}
+export interface AdapterCommand {
+    command: string;
+    args: readonly string[];
+}
+export interface StyleAdapter {
+    readonly name: string;
+    /** One-line summary, printed by `nebula init`. */
+    readonly summary: string;
+    /** Packages the app must add itself. Empty for an engine-free adapter. */
+    readonly packages: readonly string[];
+    /** Stubs to write. */
+    files(config: ResolvedNebulaConfig): readonly GeneratedFile[];
+    /** Build and watch commands, or `null` when there is nothing to compile. */
+    commands(config: ResolvedNebulaConfig): {
+        build: AdapterCommand;
+        dev: AdapterCommand;
+    } | null;
+}

package/dist/adapters/types.js

@@ -0,0 +1,21 @@
+/**
+ * The style-adapter contract.
+ *
+ * An adapter answers three questions and nothing else:
+ *
+ * 1. What does the app need to install? nebula never installs it — the app
+ *    owns its dependencies, and a UI library quietly adding a build tool to
+ *    someone's `package.json` is how a dependency tree gets away from them.
+ * 2. What files should exist? The stylesheet entry, and any engine config.
+ * 3. What command compiles them? Handed to ream's `assets` config, which
+ *    `ream dev` and `ream build` already run — the same hook AdonisJS uses for
+ *    its bundler.
+ *
+ * Deliberately not in the contract: anything that would change how a component
+ * is written. All three adapters consume the same utility class names, which
+ * is what keeps one set of fifty-odd components serving all of them. An engine
+ * with a different authoring model — Panda's recipes, StyleX's compile-time
+ * API — cannot be added behind this interface, and pretending otherwise would
+ * mean a second version of every component.
+ */
+export {};

package/dist/adapters/unocss.d.ts

@@ -0,0 +1,17 @@
+/**
+ * UnoCSS adapter.
+ *
+ * `presetWind4` implements Tailwind v4's utility syntax, so nebula's component
+ * sources are unchanged between this adapter and the Tailwind one — the whole
+ * reason both can be offered without a second set of components.
+ *
+ * What differs is the config format. UnoCSS is configured in JavaScript rather
+ * than CSS, so the theme mapping that `@theme inline` expresses for Tailwind
+ * is a `theme` object here, and the token definitions come in through
+ * `preflights` since UnoCSS has no `@import` of its own.
+ *
+ * The tokens still come from `theme.css`. One file remains the source of truth
+ * for the palette; only the plumbing around it changes.
+ */
+import type { StyleAdapter } from "./types.js";
+export declare const unocssAdapter: StyleAdapter;