velloo 0.0.0 → 0.2.0

package/pkgs/shadcn-snapshot/src/components/ui/tabs.tsx

@@ -0,0 +1,84 @@
+// Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/tabs).
+// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
+// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
+// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Tabs as TabsPrimitive } from "radix-ui";
+import type * as React from "react";
+
+import { cn } from "../../lib/utils.ts";
+
+function Tabs({
+  className,
+  orientation = "horizontal",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      data-orientation={orientation}
+      className={cn("group/tabs flex gap-2 data-horizontal:flex-col", className)}
+      {...props}
+    />
+  );
+}
+
+const tabsListVariants = cva(
+  "group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
+  {
+    variants: {
+      variant: {
+        default: "bg-muted",
+        line: "gap-1 bg-transparent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+function TabsList({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.List> & VariantProps<typeof tabsListVariants>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      data-variant={variant}
+      className={cn(tabsListVariants({ variant }), className)}
+      {...props}
+    />
+  );
+}
+
+function TabsTrigger({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      data-slot="tabs-trigger"
+      className={cn(
+        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-1.5 py-0.5 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 dark:text-muted-foreground dark:hover:text-foreground group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
+        "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
+        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TabsContent({ className, ...props }: React.ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      data-slot="tabs-content"
+      className={cn("flex-1 text-sm outline-none", className)}
+      {...props}
+    />
+  );
+}
+
+export { Tabs, TabsContent, TabsList, TabsTrigger, tabsListVariants };

package/pkgs/shadcn-snapshot/src/components/ui/textarea.tsx

@@ -0,0 +1,24 @@
+// Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/textarea).
+// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
+// Canvas-safe: same contract as Input — designs ship a `value` with no handler
+// to show populated copy, and React warns about a controlled field it can never
+// update, so `value` without `onChange` opts into `readOnly`.
+import type * as React from "react";
+
+import { cn } from "../../lib/utils.ts";
+
+export function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  const isStaticControlled =
+    props.value !== undefined && props.onChange === undefined && props.readOnly === undefined;
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "flex field-sizing-content min-h-16 w-full rounded-lg border border-input bg-transparent px-2.5 py-2 text-base transition-colors outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className,
+      )}
+      {...props}
+      readOnly={isStaticControlled ? true : props.readOnly}
+    />
+  );
+}

package/pkgs/shadcn-snapshot/src/components/ui/toggle-group.tsx

@@ -0,0 +1,94 @@
+// Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/toggle-group).
+// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
+// Canvas-safe: the group's props are relaxed off Radix's `type`-discriminated
+// union, and `type` defaults, so a design that only names the items still
+// renders.
+"use client";
+
+import type { VariantProps } from "class-variance-authority";
+import { ToggleGroup as ToggleGroupPrimitive } from "radix-ui";
+import * as React from "react";
+
+import { cn } from "../../lib/utils.ts";
+import { toggleVariants } from "./toggle.tsx";
+
+const ToggleGroupContext = React.createContext<
+  VariantProps<typeof toggleVariants> & {
+    spacing?: number;
+    orientation?: "horizontal" | "vertical";
+  }
+>({
+  size: "default",
+  variant: "default",
+  spacing: 2,
+  orientation: "horizontal",
+});
+
+/**
+ * Radix discriminates the Root's props on `type` — `value` is a string for
+ * `"single"` and an array for `"multiple"` — which is user-hostile to thread
+ * through MCP. The wrapper takes a permissive passthrough instead: a
+ * design-mode group only has to render.
+ */
+export function ToggleGroup({
+  className,
+  variant,
+  size,
+  spacing = 2,
+  orientation = "horizontal",
+  type = "single",
+  children,
+  ...props
+  // biome-ignore lint/suspicious/noExplicitAny: discriminated radix props are user-hostile in design mode
+}: any) {
+  return (
+    <ToggleGroupPrimitive.Root
+      data-slot="toggle-group"
+      data-variant={variant}
+      data-size={size}
+      data-spacing={spacing}
+      data-orientation={orientation}
+      type={type as "single"}
+      style={{ "--gap": spacing } as React.CSSProperties}
+      className={cn(
+        "group/toggle-group flex w-fit flex-row items-center gap-[--spacing(var(--gap))] rounded-lg data-[size=sm]:rounded-[min(var(--radius-md),10px)] data-vertical:flex-col data-vertical:items-stretch",
+        className,
+      )}
+      {...props}
+    >
+      <ToggleGroupContext.Provider value={{ variant, size, spacing, orientation }}>
+        {children}
+      </ToggleGroupContext.Provider>
+    </ToggleGroupPrimitive.Root>
+  );
+}
+
+export function ToggleGroupItem({
+  className,
+  children,
+  variant = "default",
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof ToggleGroupPrimitive.Item> & VariantProps<typeof toggleVariants>) {
+  const context = React.useContext(ToggleGroupContext);
+
+  return (
+    <ToggleGroupPrimitive.Item
+      data-slot="toggle-group-item"
+      data-variant={context.variant || variant}
+      data-size={context.size || size}
+      data-spacing={context.spacing}
+      className={cn(
+        "shrink-0 group-data-[spacing=0]/toggle-group:rounded-none group-data-[spacing=0]/toggle-group:px-2 focus:z-10 focus-visible:z-10 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-end]:pr-1.5 group-data-[spacing=0]/toggle-group:has-data-[icon=inline-start]:pl-1.5 group-data-horizontal/toggle-group:data-[spacing=0]:first:rounded-l-lg group-data-vertical/toggle-group:data-[spacing=0]:first:rounded-t-lg group-data-horizontal/toggle-group:data-[spacing=0]:last:rounded-r-lg group-data-vertical/toggle-group:data-[spacing=0]:last:rounded-b-lg group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:border-l-0 group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:border-t-0 group-data-horizontal/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-l group-data-vertical/toggle-group:data-[spacing=0]:data-[variant=outline]:first:border-t",
+        toggleVariants({
+          variant: context.variant || variant,
+          size: context.size || size,
+        }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </ToggleGroupPrimitive.Item>
+  );
+}

package/pkgs/shadcn-snapshot/src/components/ui/toggle.tsx

@@ -0,0 +1,50 @@
+// Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/toggle).
+// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
+// Regenerate with `bun run vendor` — do not hand-edit unless you are adding a
+// canvas adaptation, in which case add the id to vendor.ts's ADAPTED set.
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import { Toggle as TogglePrimitive } from "radix-ui";
+import type * as React from "react";
+
+import { cn } from "../../lib/utils.ts";
+
+const toggleVariants = cva(
+  "group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted data-[state=on]:bg-muted dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline: "border border-input bg-transparent hover:bg-muted",
+      },
+      size: {
+        default:
+          "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
+        lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+
+function Toggle({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof TogglePrimitive.Root> & VariantProps<typeof toggleVariants>) {
+  return (
+    <TogglePrimitive.Root
+      data-slot="toggle"
+      className={cn(toggleVariants({ variant, size, className }))}
+      {...props}
+    />
+  );
+}
+
+export { Toggle, toggleVariants };

package/pkgs/shadcn-snapshot/src/components/ui/tooltip.tsx

@@ -0,0 +1,47 @@
+// Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/tooltip).
+// Snapshot version: see packages/shadcn-snapshot/package.json#snapshotVersion.
+// Canvas-safe: see ../canvas-portal.tsx.
+"use client";
+
+import { Tooltip as TooltipPrimitive } from "radix-ui";
+import type * as React from "react";
+import { cn } from "../../lib/utils.ts";
+import { inlineOpenAttrs, pinOpenInDesignMode } from "../canvas-portal.tsx";
+
+export function TooltipProvider({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return <TooltipPrimitive.Provider data-slot="tooltip-provider" {...props} />;
+}
+
+export function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipPrimitive.Provider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...pinOpenInDesignMode(props)} />
+    </TooltipPrimitive.Provider>
+  );
+}
+
+export function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />;
+}
+
+export function TooltipContent({
+  className,
+  sideOffset: _sideOffset,
+  ...props
+}: React.ComponentProps<"div"> & { sideOffset?: number }) {
+  return (
+    <div
+      data-slot="tooltip-content"
+      {...inlineOpenAttrs()}
+      className={cn(
+        "z-50 inline-flex w-fit max-w-xs items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-50 **:data-[slot=kbd]:rounded-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/pkgs/shadcn-snapshot/src/examples.ts

@@ -0,0 +1,36 @@
+/**
+ * Canonical usage examples merged into the generated manifest by
+ * build.ts. Only components whose prop *shapes* aren't obvious from
+ * names need one — the goal is that an agent can copy the example,
+ * swap values, and get a correct render on the first try.
+ *
+ * Covers the shadcn-sourced components only; the velloo helpers carry
+ * their examples inside `@velloo/helpers`' canonical descriptors.
+ */
+export const COMPONENT_EXAMPLES: Record<string, Record<string, unknown>> = {
+  Chart: {
+    // Single series: `data: [{ x, y }]`. Multi-series: `categories` +
+    // `series: [{ name, data: number[] }]` (legend auto-on). `kind`:
+    // bar | line | area | pie | scatter. `tickFormat`: number | compact |
+    // currency | percent. `xLabel`/`yLabel` add axis titles. `color`
+    // (single-series): primary | accent | muted — theme tokens, so charts
+    // flip under dark mode.
+    kind: "bar",
+    categories: ["Mon", "Tue", "Wed", "Thu", "Fri"],
+    series: [
+      { name: "Revenue", data: [4200, 5800, 5100, 7300, 6400] },
+      { name: "Refunds", data: [400, 600, 350, 720, 500] },
+    ],
+    yLabel: "USD",
+    tickFormat: "compact",
+    className: "h-64 w-full",
+  },
+  Button: { variant: "outline", size: "sm", children: "Action" },
+  Badge: { variant: "secondary", children: "Label" },
+  Progress: { value: 64, className: "h-2" },
+  Avatar: { className: "size-9" },
+  // `ratio` is width/height as a number, not the "16:9" string it reads as.
+  AspectRatio: { ratio: 16 / 9 },
+  // Renders a list, so it takes objects rather than the string it looks like.
+  FieldError: { errors: [{ message: "Enter a valid email address." }] },
+};

package/pkgs/shadcn-snapshot/src/groups.ts

@@ -0,0 +1,87 @@
+/**
+ * Which shelf each shadcn family sits on, keyed by its source file — the same
+ * key `build.ts` already resolves per component, so a newly vendored family
+ * gets grouped by adding one line here rather than by being re-listed
+ * somewhere downstream.
+ *
+ * A family with no entry falls into the catch-all bucket, which is why the
+ * manifest test asserts this table covers every vendored file: the previous
+ * arrangement kept the grouping in the canvas sidebar, where 20 new families
+ * were silently unbrowsable because nothing failed when the list went stale.
+ */
+import type { ComponentGroup } from "@velloo/provider";
+
+export const FAMILY_GROUPS: Record<string, ComponentGroup> = {
+  button: "actions",
+  "button-group": "actions",
+  toggle: "actions",
+  "toggle-group": "actions",
+
+  input: "forms",
+  textarea: "forms",
+  label: "forms",
+  checkbox: "forms",
+  "radio-group": "forms",
+  switch: "forms",
+  slider: "forms",
+  select: "forms",
+  "native-select": "forms",
+  combobox: "forms",
+  calendar: "forms",
+  field: "forms",
+  "input-group": "forms",
+
+  avatar: "display",
+  badge: "display",
+  card: "display",
+  skeleton: "display",
+  table: "display",
+  item: "display",
+  kbd: "display",
+
+  alert: "feedback",
+  progress: "feedback",
+  sonner: "feedback",
+  spinner: "feedback",
+  empty: "feedback",
+
+  tabs: "navigation",
+  breadcrumb: "navigation",
+  pagination: "navigation",
+  accordion: "navigation",
+  "navigation-menu": "navigation",
+  menubar: "navigation",
+
+  dialog: "overlays",
+  "alert-dialog": "overlays",
+  sheet: "overlays",
+  drawer: "overlays",
+  popover: "overlays",
+  "dropdown-menu": "overlays",
+  "context-menu": "overlays",
+  "hover-card": "overlays",
+  tooltip: "overlays",
+  collapsible: "overlays",
+
+  "scroll-area": "layout",
+  separator: "layout",
+  carousel: "layout",
+  "aspect-ratio": "layout",
+
+  chart: "visuals",
+
+  attachment: "chat",
+  bubble: "chat",
+  message: "chat",
+  marker: "chat",
+};
+
+/**
+ * Families that are intentionally ungrouped: real exports an agent can name,
+ * but not components anyone browses for. Listed rather than omitted so the
+ * coverage test can tell "decided" from "forgotten".
+ */
+export const UNGROUPED_FAMILIES: ReadonlySet<string> = new Set([
+  // Context provider for RTL — wraps a tree, renders no UI of its own.
+  "direction",
+]);

package/pkgs/shadcn-snapshot/src/index.ts

@@ -0,0 +1,43 @@
+import { type FrameworkAdapter, type Manifest, TAILWIND_CLASSNAME } from "@velloo/provider";
+import { componentsDir, entryCssPath, manifestPath, snapshotVersion } from "./paths.ts";
+import { registry } from "./registry.ts";
+
+export type { ComponentDescriptor, Manifest, PropDescriptor } from "./manifest.ts";
+export { componentsDir, entryCssPath, snapshotVersion } from "./paths.ts";
+export { registry } from "./registry.ts";
+
+/**
+ * Prop manifest extracted from the vendored sources via ts-morph at build time.
+ */
+export async function loadManifest(): Promise<Manifest> {
+  const file = Bun.file(manifestPath);
+  if (!(await file.exists())) {
+    throw new Error(
+      `@velloo/shadcn-snapshot: dist/manifest.json missing. Run \`bun run build\` in packages/shadcn-snapshot.`,
+    );
+  }
+  return (await file.json()) as Manifest;
+}
+
+/**
+ * Build a `ComponentProvider` instance for this snapshot. Optionally
+ * overrides the on-disk `componentsDir` when the user installed the
+ * snapshot files outside the binary (in-repo or cache mode) — the
+ * runtime registry stays bundled with velloo (so what the canvas
+ * renders is byte-identical across folders), but the JIT scan target
+ * follows the install location so user customizations contribute to
+ * the compiled CSS.
+ */
+export function createProvider(opts: { componentsDir?: string } = {}): FrameworkAdapter {
+  return {
+    id: "shadcn-react",
+    version: snapshotVersion,
+    componentsDir: opts.componentsDir ?? componentsDir,
+    styleEntryPath: entryCssPath,
+    registry,
+    loadManifest,
+    label: `shadcn-react ${snapshotVersion}`,
+    styleChannel: TAILWIND_CLASSNAME,
+    styleChannels: ["tailwind-classname"],
+  };
+}

package/pkgs/shadcn-snapshot/src/lib/utils.ts

@@ -0,0 +1,4 @@
+// Upstream shadcn's `cn`, re-pointed at velloo's configured tailwind-merge: a
+// design folder's theme generates the typeset utilities (`text-h1`, …), which
+// the stock config would misgroup as colors and silently drop.
+export { cn } from "@velloo/helpers";

package/pkgs/shadcn-snapshot/src/manifest.ts

@@ -0,0 +1,12 @@
+/**
+ * Manifest types moved to `@velloo/provider`. This module re-exports them
+ * so existing imports (`from "@velloo/shadcn-snapshot"`) keep working
+ * through the migration; consumers should prefer importing from
+ * `@velloo/provider` going forward.
+ */
+export type {
+  ComponentDescriptor,
+  ControlType,
+  Manifest,
+  PropDescriptor,
+} from "@velloo/provider";

package/pkgs/shadcn-snapshot/src/notes.ts

@@ -0,0 +1,97 @@
+/**
+ * Per-component `designModeNotes`, merged into the generated manifest by
+ * build.ts.
+ *
+ * Scoped to one job: telling an agent *when to reach for a component instead
+ * of building the same thing out of `Box` and `Text`*. Prop names already say
+ * what a component accepts and `example` shows the shapes; neither says that
+ * a label/control/help-text stack is what `Field` is for. That gap matters
+ * most for the families that postdate most models' training data (Field,
+ * InputGroup, Item, Empty, ButtonGroup, Spinner, Kbd, the chat set), which
+ * otherwise get hand-rolled — so notes go on family roots, and on the handful
+ * of sub-pieces whose own role isn't obvious from the name.
+ *
+ * Keep them to a couple of sentences. The composition shape belongs here as a
+ * JSX sketch because `compose` takes exactly that syntax.
+ */
+export const COMPONENT_NOTES: Record<string, string> = {
+  // ---- Forms -------------------------------------------------------------
+  Field:
+    "The form-field scaffold — reach for this instead of stacking Label + Input + help text by hand. " +
+    "`<Field><FieldLabel htmlFor='email'>Email</FieldLabel><Input id='email'/>" +
+    "<FieldDescription>We never share it.</FieldDescription></Field>`. " +
+    'Set `orientation="horizontal"` to put the label beside the control (checkbox/switch rows), ' +
+    "`FieldGroup` to stack several fields with consistent spacing, and `FieldSet` + `FieldLegend` for a titled section.",
+  FieldError:
+    "Renders a list, so `errors` takes objects: `[{ message: 'Enter a valid email.' }]` — not a string. " +
+    "Place it last inside a `Field`.",
+  FieldSeparator: "An 'or' divider between fields; put the label in `children`.",
+  InputGroup:
+    "An input with something attached inside its border — a leading icon, a trailing unit, a submit button. " +
+    "`<InputGroup><InputGroupAddon><Icon name='search'/></InputGroupAddon><InputGroupInput placeholder='Search'/></InputGroup>`. " +
+    "Use `InputGroupInput`/`InputGroupTextarea` rather than a bare `Input` inside it, and " +
+    '`InputGroupAddon align="inline-end"` for the trailing slot. This is the component for search bars and prefixed URL fields.',
+  NativeSelect:
+    "A real `<select>` — one tap-to-open list on mobile, and it renders faithfully in design mode. " +
+    "Prefer it over `Select` for plain option lists; `Select` is the Radix listbox, needed only for rich/custom option rows. " +
+    "Children are `NativeSelectOption` (and `NativeSelectOptGroup`).",
+  Combobox:
+    "Type-to-filter selection: `ComboboxInput` + `ComboboxList`/`ComboboxItem`, with `ComboboxChips` for multi-select. " +
+    "In design mode the list renders open and inline so you can see it; filtering does not run.",
+
+  // ---- Actions -----------------------------------------------------------
+  ButtonGroup:
+    "Joins adjacent buttons into one segmented control — shared borders, rounded only on the ends. " +
+    "Use it instead of a flex `Box` with `gap`, which leaves them as separate buttons. " +
+    "`ButtonGroupText` adds a static label segment; `ButtonGroupSeparator` divides groups.",
+
+  // ---- Display -----------------------------------------------------------
+  Item:
+    "One row of a list — the generic list-row surface, and the right building block for settings rows, " +
+    "notification lists and file lists that would otherwise be a hand-built flex `Box`. " +
+    "`<Item><ItemMedia><Icon name='file'/></ItemMedia><ItemContent><ItemTitle>Report.pdf</ItemTitle>" +
+    "<ItemDescription>2.4 MB</ItemDescription></ItemContent><ItemActions><Button/></ItemActions></Item>`. " +
+    "`ItemGroup` wraps a list; use `Card` only for actual card surfaces.",
+  Kbd: "A keyboard key cap (`⌘`, `K`). `KbdGroup` sets a chord — reach for it in shortcut hints and command-menu rows.",
+
+  // ---- Feedback ----------------------------------------------------------
+  Empty:
+    "The empty-state surface: centred icon, heading, explanation, action. " +
+    "`<Empty><EmptyHeader><EmptyMedia><Icon name='inbox'/></EmptyMedia><EmptyTitle>No invoices</EmptyTitle>" +
+    "<EmptyDescription>Create one to get started.</EmptyDescription></EmptyHeader><EmptyContent><Button/></EmptyContent></Empty>`. " +
+    "Use it for any 'nothing here yet' panel rather than centring text in a `Box`.",
+  Spinner:
+    "An inline loading indicator. Size it with a class (`size-4`) and pair it with `Skeleton` for block-level placeholders.",
+
+  // ---- Overlays ----------------------------------------------------------
+  Drawer:
+    "A sheet that slides from an edge with a drag handle — the mobile-idiomatic bottom sheet. " +
+    "For a desktop side panel prefer `Sheet`; the two are otherwise the same shape. " +
+    "Rendered open and inline in design mode.",
+  HoverCard:
+    "A rich preview shown on hover (user cards, link previews) — not a `Tooltip`, which is for a short text hint. " +
+    "Rendered open and inline in design mode.",
+  ContextMenu:
+    "The right-click menu. Same item vocabulary as `DropdownMenu`, which is the one to use for a button-triggered menu. " +
+    "Rendered open and inline in design mode.",
+
+  // ---- Navigation --------------------------------------------------------
+  Menubar:
+    "A persistent application menu bar (File / Edit / View). For a single button-triggered menu use `DropdownMenu`. " +
+    "Rendered open and inline in design mode.",
+  NavigationMenu:
+    "Site-level navigation with rich dropdown panels — marketing headers. " +
+    "For in-page section switching use `Tabs`.",
+
+  // ---- Chat & AI ---------------------------------------------------------
+  Bubble:
+    "One chat turn's speech bubble; `BubbleGroup` stacks consecutive turns from the same author " +
+    "and `BubbleReactions` adds the reaction row. For a full turn with avatar and header, use `Message`.",
+  Message:
+    "A full chat turn: `MessageAvatar` + `MessageHeader` + `MessageContent` (+ `MessageFooter`). " +
+    "`MessageGroup` wraps a transcript. Use `Bubble` when you only need the bubble itself.",
+  Attachment:
+    "A file chip attached to a chat message — `AttachmentMedia` + `AttachmentTitle`/`AttachmentDescription`, " +
+    "with `AttachmentGroup` for several and `AttachmentActions` for remove/download.",
+  Marker: "Inline annotation highlighting a span of chat text (citations, references).",
+};

package/pkgs/shadcn-snapshot/src/paths.ts

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import pkg from "../package.json" with { type: "json" };
+
+/** Date stamp recording which upstream shadcn pull this snapshot mirrors. */
+export const snapshotVersion: string = (pkg as { snapshotVersion: string }).snapshotVersion;
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Package root holding `src/` (the component sources + Tailwind entry CSS) and
+ * `dist/manifest.json`. Resolves from source (`here` = this `src/` dir) and
+ * from the bundled CLI, where `build.ts` copies these assets to
+ * `<dist>/pkgs/shadcn-snapshot` next to `cli.js`.
+ */
+function resolveRoot(): string {
+  const dev = join(here, "..");
+  const candidates = [
+    process.env.VELLOO_SNAPSHOT_ROOT,
+    join(here, "pkgs", "shadcn-snapshot"),
+    dev,
+  ].filter((p): p is string => Boolean(p));
+  return candidates.find((r) => existsSync(join(r, "src", "tailwind-entry.css"))) ?? dev;
+}
+
+const root = resolveRoot();
+const srcDir = join(root, "src");
+const distDir = join(root, "dist");
+
+/**
+ * Absolute path to the Tailwind entry CSS shipped with the snapshot. The
+ * server's JIT compiler reads this and runs Tailwind v4 against the live
+ * page folder so any class — including ones we haven't thought of yet —
+ * renders without a hand-rolled safelist.
+ */
+export const entryCssPath: string = join(srcDir, "tailwind-entry.css");
+
+/**
+ * Absolute path to the snapshot's component sources. The JIT scanner reads
+ * these so the canvas picks up classes used by shipped components even if
+ * no page references them directly.
+ */
+export const componentsDir: string = join(srcDir, "components");
+
+/** Absolute path to the prebuilt manifest JSON (filled at `bun run build`). */
+export const manifestPath: string = join(distDir, "manifest.json");