velloo 0.7.0 → 0.8.0

package/{chunk-vs8j3x6t.js → chunk-z6r6wxm6.js}

@@ -1,3 +1,3 @@
 // @bun
-import{CURRENT_SCHEMA_VERSION}from"./chunk-5x4nw0zz.js";import{snapshotVersion2}from"./chunk-p93x4pn2.js";import{TOOL_VERSION}from"./chunk-3m28pvzr.js";function buildDefaultConfig(opts={}){return{schemaVersion:CURRENT_SCHEMA_VERSION,toolVersion:TOOL_VERSION,name:opts.name??"design",folderId:crypto.randomUUID(),libraries:{default:opts.library??{id:"shadcn-upstream",version:snapshotVersion2,source:"binary",componentsPath:"binary"}},defaultLibrary:"default",viewportPresets:[{name:"Mobile",w:390,h:844},{name:"Tablet",w:768,h:1024},{name:"Desktop",w:1440,h:900}],...opts.defaultScreen?{defaultScreen:opts.defaultScreen}:{},...opts.defaultBoard?{defaultBoard:opts.defaultBoard}:{},...opts.hostApp?{hostApp:opts.hostApp}:{},...opts.hostApps?{hostApps:opts.hostApps}:{},...opts.feedback?{feedback:opts.feedback}:{},...opts.styling?{styling:opts.styling}:{},...opts.codegen?{codegen:opts.codegen}:{},...opts.designSystem?{designSystem:opts.designSystem}:{}}}
+import{CURRENT_SCHEMA_VERSION}from"./chunk-xxw67jpk.js";import{snapshotVersion2}from"./chunk-p93x4pn2.js";import{TOOL_VERSION}from"./chunk-rrrn1mkq.js";function buildDefaultConfig(opts={}){return{schemaVersion:CURRENT_SCHEMA_VERSION,toolVersion:TOOL_VERSION,name:opts.name??"design",folderId:crypto.randomUUID(),libraries:{default:opts.library??{id:"shadcn-upstream",version:snapshotVersion2,source:"binary",componentsPath:"binary"}},defaultLibrary:"default",viewportPresets:[{name:"Mobile",w:390,h:844},{name:"Tablet",w:768,h:1024},{name:"Desktop",w:1440,h:900}],...opts.defaultScreen?{defaultScreen:opts.defaultScreen}:{},...opts.defaultBoard?{defaultBoard:opts.defaultBoard}:{},...opts.hostApp?{hostApp:opts.hostApp}:{},...opts.hostApps?{hostApps:opts.hostApps}:{},...opts.feedback?{feedback:opts.feedback}:{},...opts.styling?{styling:opts.styling}:{},...opts.codegen?{codegen:opts.codegen}:{},...opts.designSystem?{designSystem:opts.designSystem}:{},...opts.themeSource?{themeSource:opts.themeSource}:{}}}
 export{buildDefaultConfig};

package/{chunk-srp5gyr1.js → chunk-zgwvkgsz.js}

@@ -1,2 +1,2 @@
 // @bun
-import"./chunk-bys7pqdb.js";import"./chunk-5x4nw0zz.js";import{normalizeCloudUrl,loadCredential,listCredentials,deleteCredential,clearCredentials,revokeCredential}from"./chunk-kkvf0xk2.js";import{defaultCloudUrl}from"./chunk-abr2hgay.js";import{defineCommand}from"./chunk-2smsg2ct.js";var logout_default=defineCommand({meta:{name:"logout",description:"Log out of velloo-cloud (signs the CLI token out and removes it)"},args:{url:{type:"string",description:"velloo-cloud base URL (default: $VELLOO_CLOUD_URL or the built-in default)"},all:{type:"boolean",default:!1,description:"Remove saved credentials for every cloud"}},async run({args}){if(args.all){await Promise.all(Object.entries(await listCredentials()).map(([cloudUrl,credential])=>revokeCredential(cloudUrl,credential.token)));let count=await clearCredentials();console.log(count>0?`velloo logout: removed credentials for ${count} cloud${count===1?"":"s"}`:"velloo logout: no saved credentials");return}let cloudUrl=args.url?normalizeCloudUrl(args.url):defaultCloudUrl(),existing=await loadCredential(cloudUrl);if(existing)await revokeCredential(cloudUrl,existing.token);if(await deleteCredential(cloudUrl))console.log(`velloo logout: logged out of ${cloudUrl}${existing?.email?` (${existing.email})`:""}`);else console.log(`velloo logout: not logged in to ${cloudUrl}`)}});export{logout_default as default};
+import"./chunk-bntsn3wj.js";import"./chunk-xxw67jpk.js";import{normalizeCloudUrl,loadCredential,listCredentials,deleteCredential,clearCredentials,revokeCredential}from"./chunk-rg86bhtb.js";import{defaultCloudUrl}from"./chunk-w30zfv3m.js";import{defineCommand}from"./chunk-2smsg2ct.js";var logout_default=defineCommand({meta:{name:"logout",description:"Log out of velloo-cloud (signs the CLI token out and removes it)"},args:{url:{type:"string",description:"velloo-cloud base URL (default: $VELLOO_CLOUD_URL or the built-in default)"},all:{type:"boolean",default:!1,description:"Remove saved credentials for every cloud"}},async run({args}){if(args.all){await Promise.all(Object.entries(await listCredentials()).map(([cloudUrl,credential])=>revokeCredential(cloudUrl,credential.token)));let count=await clearCredentials();console.log(count>0?`velloo logout: removed credentials for ${count} cloud${count===1?"":"s"}`:"velloo logout: no saved credentials");return}let cloudUrl=args.url?normalizeCloudUrl(args.url):defaultCloudUrl(),existing=await loadCredential(cloudUrl);if(existing)await revokeCredential(cloudUrl,existing.token);if(await deleteCredential(cloudUrl))console.log(`velloo logout: logged out of ${cloudUrl}${existing?.email?` (${existing.email})`:""}`);else console.log(`velloo logout: not logged in to ${cloudUrl}`)}});export{logout_default as default};

package/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
 // @bun
-import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-acsv6m3n.js";import{TOOL_VERSION}from"./chunk-3m28pvzr.js";import{maybeNotifyAboutUpdate}from"./chunk-s84vxcdv.js";import{defineCommand,runMain}from"./chunk-2smsg2ct.js";var main=defineCommand({meta:{name:"velloo",version:TOOL_VERSION,description:"Open-source, local-first canvas for agent-driven design."},subCommands:COMMANDS});await runMain(main);var command=process.argv[2];if(!["mcp","__daemon","__update_check","run","upgrade"].includes(command??""))await maybeNotifyAboutUpdate();
+import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-32cq4wpr.js";import{TOOL_VERSION}from"./chunk-rrrn1mkq.js";import{maybeNotifyAboutUpdate}from"./chunk-d19ttv1a.js";import{defineCommand,runMain}from"./chunk-2smsg2ct.js";var main=defineCommand({meta:{name:"velloo",version:TOOL_VERSION,description:"Open-source, local-first canvas for agent-driven design."},subCommands:COMMANDS});await runMain(main);var command=process.argv[2];if(!["mcp","__daemon","__update_check","run","upgrade"].includes(command??""))await maybeNotifyAboutUpdate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velloo",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Local-first, code-shaped design canvas — your AI agent designs with your real components, in your repo",
   "license": "Apache-2.0",

package/pkgs/provider-antd/src/index.ts

@@ -54,6 +54,7 @@ export function createProvider(): FrameworkAdapter {
       ),
     styleChannel: STYLE_PROP,
     styleChannels: ["style"],
+    themeRoles: ["background", "foreground", "primary", "destructive", "card"],
     mcpIntro: () => [...ANTD_INTRO],
     renderPass: (theme, dark) => makeRenderPass(theme, dark ?? false),
     codegenModule: "antd",

package/pkgs/provider-html/src/index.ts

@@ -59,6 +59,7 @@ export function createProvider(): FrameworkAdapter {
     loadManifest: async () => HTML_MANIFEST,
     styleChannel: STYLE_PROP,
     styleChannels: ["style"],
+    themeRoles: ["background", "foreground", "card", "muted", "border", "input"],
     registryForChannel: () => registry,
     mcpIntro: () => HTML_INTRO,
     hostStylesheets: true,

package/pkgs/provider-mui/src/index.ts

@@ -57,6 +57,16 @@ export function createProvider(): FrameworkAdapter {
       ),
     styleChannel: SX_PROP,
     styleChannels: ["sx"],
+    themeRoles: [
+      "background",
+      "foreground",
+      "primary",
+      "secondary",
+      "destructive",
+      "card",
+      "muted",
+      "border",
+    ],
     mcpIntro: () => [...MUI_INTRO],
     renderPass: (theme, dark) => makeRenderPass(theme, dark ?? false),
     codegenModule: "@mui/material",

package/pkgs/provider-none/src/index.ts

@@ -59,6 +59,7 @@ export function createProvider(): FrameworkAdapter {
     // is `none` resolves to the inline-`style` channel instead.
     styleChannel: TAILWIND_CLASSNAME,
     styleChannels: ["tailwind-classname", "style"],
+    themeRoles: ["background", "foreground", "card", "muted", "border", "input"],
     mcpIntro: (channel) => [...(channel === "style" ? NONE_INLINE_INTRO : NONE_INTRO)],
     // Inline-styled primitives for the `style` channel; Tailwind-classed for
     // every other channel. Lets a `none/none` folder paint with the JIT off.

package/pkgs/schema/src/board.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { FlowEdgeSchema } from "./flow.ts";
 import { FrameSchema } from "./frame.ts";
 import { ResourceIdSchema } from "./ids.ts";
 
@@ -12,7 +13,11 @@ import { ResourceIdSchema } from "./ids.ts";
 export const BoardGroupSchema = z.object({
   id: ResourceIdSchema,
   name: z.string().min(1),
-  /** CSS color value; canvas uses it for the group region tint and tag chip. */
+  /**
+   * CSS color value. The sidebar uses a board group's for its chip and rail;
+   * a frame group may carry one, but the canvas draws nothing for frame
+   * groups yet.
+   */
   color: z.string().optional(),
 });
 
@@ -61,6 +66,13 @@ export const BoardSchema = z.object({
   frames: z.array(FrameSchema).default([]),
   /** Frame regions within this board (see {@link BoardGroupSchema}). */
   groups: z.array(BoardGroupSchema).default([]),
+  /**
+   * Arrows between this board's frames (see {@link FlowEdgeSchema}). Absent ⇒
+   * a board of unconnected frames, which is every existing one — and the field
+   * is dropped again when the last arrow goes, so such a board's file never
+   * changes shape.
+   */
+  edges: z.array(FlowEdgeSchema).optional(),
 });
 
 export type Board = z.infer<typeof BoardSchema>;

package/pkgs/schema/src/config.ts

@@ -106,6 +106,35 @@ export const HostAppSchema = z.object({
 
 export type HostApp = z.infer<typeof HostAppSchema>;
 
+/**
+ * Where the design's theme came from in the app: what `velloo init` read (or
+ * left alone), and what an `import_theme` from a stylesheet into the default
+ * theme records again. Agents are told by it what checking the theme against
+ * the app means — a theme read from a JavaScript theme object (`mantine`,
+ * `mui`) is compared with that module, since no stylesheet holds it.
+ *
+ *   "stylesheet"       — the app's stylesheet, and what it brings with it.
+ *   "design-md"        — a DESIGN.md, layered on the stylesheet.
+ *   "mantine" / "mui"  — the theme object the app hands that library.
+ *   "library-defaults" — the app uses `library` and sets no theme of its own,
+ *                        so the design is on that library's.
+ *   "preset"           — nothing of the app's: a built-in preset.
+ */
+export const ThemeSourceSchema = z.object({
+  kind: z.enum(["stylesheet", "design-md", "mantine", "mui", "library-defaults", "preset"]),
+  /**
+   * The app's files it was read from, relative to the app root, the one
+   * `kind` names first: a stylesheet is followed by the sheets it imports,
+   * the tailwind.config it merged and the modules whose font loader calls
+   * set a face. Absent when nothing was read from a file in the app.
+   */
+  files: z.array(AppRelativePathSchema).min(1).optional(),
+  /** The library whose own theme it is — for `"library-defaults"`. */
+  library: z.string().min(1).optional(),
+});
+
+export type ThemeSource = z.infer<typeof ThemeSourceSchema>;
+
 /** The CSS framework a folder styles with. See `ConfigSchema.styling`. */
 export const StylingSchema = z.object({ framework: z.enum(["tailwind", "none"]) });
 
@@ -206,6 +235,11 @@ export const ConfigSchema = z
      * a file somewhere unconventional, or pins the choice when several exist.
      */
     designSystem: z.object({ path: AppRelativePathSchema }).optional(),
+    /**
+     * Where the default theme was read from in the app. See `ThemeSourceSchema`.
+     * Absent for a design made before it was recorded: nothing is assumed.
+     */
+    themeSource: ThemeSourceSchema.optional(),
     /**
      * Named host apps for monorepos — the multi-app twin of `hostApp`, keyed
      * by a short app name (`"web"`, `"admin"`; `init`'s multi-app scan uses

package/pkgs/schema/src/flow.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+
+/**
+ * An arrow between two frames of one board — what makes a board readable as a
+ * flow. It is a spec, not behaviour: nothing here runs, and nothing here emits.
+ *
+ * One arrow says one of two things, and `state` is what tells them apart:
+ *
+ *  - **A transition** (no `state`): from this step, `label` happens, and the
+ *    user is on `to`.
+ *  - **A state** (`state` set): `to` shows the *same step* as `from`, in that
+ *    state — its loading, empty or error version — and `label` is when.
+ *
+ * Different layouts are separate screens, so the states of a step are separate
+ * frames; the arrows between them are what groups them into one step, which is
+ * why a frame carries no state of its own (see {@link deriveFlowSteps}).
+ *
+ * An arrow has no id: a board holds at most one per ordered pair of frames, so
+ * the pair is the identity.
+ */
+export const FlowEdgeSchema = z.object({
+  /** Frame id the arrow leaves. */
+  from: z.string().min(1),
+  /** Frame id the arrow points at. */
+  to: z.string().min(1),
+  /** The trigger or condition, in plain words ("Submit", "Email already taken"). */
+  label: z.string().min(1).optional(),
+  /** Present ⇒ `to` is `from`'s step in this state. Free text; see {@link FLOW_STATES}. */
+  state: z.string().min(1).optional(),
+  /**
+   * Where along the arrow its label sits, from 0 at the frame it leaves to 1
+   * at the one it reaches. Set when someone slides the label out of the way;
+   * absent, the canvas puts it mid-way along the part of the arrow in view.
+   * Layout only: no reader of the flow looks at it.
+   */
+  labelAt: z.number().min(0).max(1).optional(),
+});
+
+export type FlowEdge = z.infer<typeof FlowEdgeSchema>;
+
+/**
+ * The states a step conventionally has besides its default one. A vocabulary to
+ * offer, not a constraint: `state` stays free text on disk so "offline" or
+ * "expired" need no schema change.
+ */
+export const FLOW_STATES = ["loading", "empty", "error", "success"] as const;
+
+/** What the frame a step's state arrows start from is called. Never stored. */
+export const DEFAULT_FLOW_STATE = "default";
+
+interface FlowBoard {
+  frames: ReadonlyArray<{ id: string }>;
+  edges?: FlowEdge[] | undefined;
+}
+
+/**
+ * The arrows whose two ends are both still frames on the board. Reading goes
+ * through this so a hand-edited or half-synced file draws what it can instead
+ * of failing, and writing goes through it so removing a frame takes its arrows
+ * with it wherever the removal happened.
+ */
+export function liveFlowEdges(board: FlowBoard): FlowEdge[] {
+  if (!board.edges || board.edges.length === 0) return [];
+  const frames = new Set(board.frames.map((frame) => frame.id));
+  return board.edges.filter(
+    (edge) => edge.from !== edge.to && frames.has(edge.from) && frames.has(edge.to),
+  );
+}
+
+/** One frame of a step other than its default one. */
+interface FlowStepState {
+  frame: string;
+  state: string;
+  /** The arrow's label: when the step is in this state. */
+  when?: string;
+  /**
+   * The state this one follows, when its arrow leaves another state rather
+   * than the step's default frame: loading → error is "it was sent, then it
+   * failed", and without this the read would say only that both exist.
+   */
+  after?: string;
+}
+
+/**
+ * A step of the flow: the frame its state arrows start from, plus the frames
+ * those arrows reach.
+ */
+export interface FlowStep {
+  /** The default state's frame. Its id stands for the step. */
+  frame: string;
+  states: FlowStepState[];
+}
+
+export interface FlowSteps {
+  /** Every frame belongs to exactly one step; a frame with no state arrows is a step alone. */
+  steps: FlowStep[];
+  /** Arrows that move between steps, endpoints as drawn (possibly a state's frame). */
+  transitions: FlowEdge[];
+  /** Frame id → the frame that stands for its step. */
+  stepOf: Map<string, string>;
+}
+
+/**
+ * Group a board's frames into steps by following its state arrows.
+ *
+ * A step is a tree: the default frame at the root, a state arrow down to each
+ * state, and onward from there (loading → error is "it loaded, then failed").
+ * Writes keep that shape — one state arrow into a frame, no cycles — but this
+ * reads whatever is on disk, so a state arrow that would break the tree is
+ * handed back as a transition rather than trusted.
+ */
+export function deriveFlowSteps(board: FlowBoard): FlowSteps {
+  const parent = new Map<string, FlowEdge>();
+  const transitions: FlowEdge[] = [];
+  for (const edge of liveFlowEdges(board)) {
+    if (edge.state === undefined || parent.has(edge.to) || reaches(parent, edge.from, edge.to)) {
+      transitions.push(edge);
+    } else {
+      parent.set(edge.to, edge);
+    }
+  }
+
+  const children = new Map<string, FlowEdge[]>();
+  for (const edge of parent.values()) {
+    const siblings = children.get(edge.from);
+    if (siblings) siblings.push(edge);
+    else children.set(edge.from, [edge]);
+  }
+
+  const steps: FlowStep[] = [];
+  const stepOf = new Map<string, string>();
+  for (const { id } of board.frames) {
+    if (parent.has(id)) continue;
+    const states: FlowStepState[] = [];
+    stepOf.set(id, id);
+    const pending = [...(children.get(id) ?? [])].reverse();
+    for (let edge = pending.pop(); edge; edge = pending.pop()) {
+      stepOf.set(edge.to, id);
+      states.push({
+        frame: edge.to,
+        state: edge.state as string,
+        ...(edge.label !== undefined ? { when: edge.label } : {}),
+        ...(edge.from !== id ? { after: edge.from } : {}),
+      });
+      pending.push(...[...(children.get(edge.to) ?? [])].reverse());
+    }
+    steps.push({ frame: id, states });
+  }
+  return { steps, transitions, stepOf };
+}
+
+/** Whether walking state arrows up from `start` arrives at `target`. */
+function reaches(parent: Map<string, FlowEdge>, start: string, target: string): boolean {
+  for (let at: string | undefined = start; at !== undefined; at = parent.get(at)?.from) {
+    if (at === target) return true;
+  }
+  return false;
+}
+
+/**
+ * State arrows that can only be transitions inside their step. Anyone who
+ * reads `state` as "what the arrow arrives at" draws these, and none of them
+ * contradicts anything — so a writer keeps each as the transition it is
+ * instead of refusing it:
+ *
+ *  - **a way back**: from a state to the frame it came from, or to the step's
+ *    default ("fix the fields and resubmit", tagged `recovery`). Taken as a
+ *    state it would make the step's default a state of its own state.
+ *  - **a state restated**: into a frame that is already that state of the same
+ *    step ("try again", arriving at `loading` a second time).
+ *  - **`default`**: the frame a step's states start from is not one of them.
+ *
+ * A *different* state for a frame that has one, or the same state claimed by
+ * another step, is a real contradiction and is left for the writer to refuse.
+ */
+export function transitionsDrawnAsStates(board: FlowBoard): FlowEdge[] {
+  const parent = new Map<string, FlowEdge>();
+  const drawn = new Set<FlowEdge>();
+  const second: FlowEdge[] = [];
+  const edges = liveFlowEdges(board);
+  for (const edge of edges) {
+    if (edge.state === undefined) continue;
+    if (edge.state === DEFAULT_FLOW_STATE || reaches(parent, edge.from, edge.to)) drawn.add(edge);
+    else if (parent.has(edge.to)) second.push(edge);
+    else parent.set(edge.to, edge);
+  }
+  // Which step a frame is in is only known once every arrow has been read:
+  // the one that puts `from` in the step may come after the one being judged.
+  const stepOf = (frame: string): string => {
+    let at = frame;
+    for (let up = parent.get(at); up; up = parent.get(at)) at = up.from;
+    return at;
+  };
+  for (const edge of second) {
+    if (parent.get(edge.to)?.state === edge.state && stepOf(edge.from) === stepOf(edge.to)) {
+      drawn.add(edge);
+    }
+  }
+  return edges.filter((edge) => drawn.has(edge));
+}
+
+/**
+ * Why a set of arrows can't be a board's flow, or null when it can. The one
+ * rule set shared by every writer, so a board never holds arrows
+ * {@link deriveFlowSteps} would have to reinterpret.
+ */
+export function flowEdgeProblem(board: FlowBoard): string | null {
+  const frames = new Set(board.frames.map((frame) => frame.id));
+  const pairs = new Set<string>();
+  const parent = new Map<string, FlowEdge>();
+  for (const edge of board.edges ?? []) {
+    for (const end of [edge.from, edge.to]) {
+      if (!frames.has(end)) return `no frame "${end}" on this board`;
+    }
+    if (edge.from === edge.to) return `"${edge.from}" can't point at itself`;
+    const pair = `${edge.from}\u0000${edge.to}`;
+    if (pairs.has(pair)) return `two arrows from "${edge.from}" to "${edge.to}"`;
+    pairs.add(pair);
+    if (edge.state === undefined) continue;
+    const other = parent.get(edge.to);
+    if (other) {
+      return `"${edge.to}" is already the ${other.state} state of "${other.from}" — a frame is one state of one step`;
+    }
+    if (reaches(parent, edge.from, edge.to)) {
+      return `"${edge.to}" → "${edge.from}" → "${edge.to}" loops — a step's states need one default frame to start from`;
+    }
+    parent.set(edge.to, edge);
+  }
+  return null;
+}

package/pkgs/schema/src/frame.ts

@@ -27,6 +27,13 @@ export const FrameSchema = z.object({
   group: z.string().optional(),
   /** Pinned render scheme; absent means follow the canvas default. */
   scheme: FrameSchemeSchema.optional(),
+  /**
+   * `"content"`: the height follows the screen — the daemon measures how tall
+   * the screen renders at this width after each change to it and sets `h`.
+   * Absent ⇒ `h` is whatever it was last set to, which is every frame someone
+   * sized: setting a frame's height drops this.
+   */
+  fit: z.literal("content").optional(),
 });
 
 export type Frame = z.infer<typeof FrameSchema>;

package/pkgs/schema/src/index.ts

@@ -54,6 +54,8 @@ export {
   type Library,
   LibrarySchema,
   StylingSchema,
+  type ThemeSource,
+  ThemeSourceSchema,
   type ViewportPreset,
   ViewportPresetSchema,
 } from "./config.ts";
@@ -74,6 +76,17 @@ export {
   type RepoComponentsManifest,
   RepoComponentsManifestSchema,
 } from "./extension.ts";
+export {
+  DEFAULT_FLOW_STATE,
+  deriveFlowSteps,
+  FLOW_STATES,
+  type FlowEdge,
+  FlowEdgeSchema,
+  type FlowStep,
+  flowEdgeProblem,
+  liveFlowEdges,
+  transitionsDrawnAsStates,
+} from "./flow.ts";
 export {
   type Frame,
   FrameSchema,
@@ -95,8 +108,11 @@ export {
 } from "./migrate.ts";
 export {
   type ComponentNode,
+  type ComponentType,
+  type ComponentTypeRef,
   type EmitAsRef,
   isComponentNode,
+  isComponentType,
   isParamRef,
   isRepoNode,
   isSnippetInstance,
@@ -115,9 +131,11 @@ export {
   type TextNode,
 } from "./node.ts";
 export {
+  componentTypesIn,
   type EmitAsNode,
   isNode,
   isSyntheticRef,
+  mapComponentTypes,
   type NodeShape,
   nodeShape,
   PARAM_TAG_REF,
@@ -154,12 +172,15 @@ export {
   type ColorsOverride,
   ColorsSchema,
   type LooseTokenGroup,
+  namedPaletteRoles,
+  normalizeThemeName,
   resolveColors,
   spacingCssTokens,
   TAILWIND_SIZE_NAMES,
   type Theme,
   ThemeSchema,
   TypographySchema,
+  themeNameProblem,
 } from "./theme.ts";
 export {
   DEFAULT_TYPESET_NAME,

package/pkgs/schema/src/node-identity.ts

@@ -1,7 +1,9 @@
 import {
   type ComponentNode,
+  type ComponentTypeRef,
   type EmitAsRef,
   isComponentNode,
+  isComponentType,
   isParamRef,
   isSnippetInstance,
   isTextNode,
@@ -95,3 +97,49 @@ export function nodeShape(value: unknown): NodeShape {
 export function isNode(value: unknown): value is Node {
   return nodeShape(value).kind !== "invalid";
 }
+
+/**
+ * Replace every component type in a prop value — the value itself, or one
+ * nested in the arrays and plain objects it holds — with what `resolve` makes
+ * of it. A node inside the value is left as it is: its own props are resolved
+ * when that node is walked. Returns `value` itself when nothing changed, so a
+ * props bag with no type in it keeps its identity.
+ *
+ * A component type is not a node (`nodeShape` calls one `invalid`, so no node
+ * position ever takes it), which is why the walkers that read prop values ask
+ * this rather than switching on the node union.
+ */
+export function mapComponentTypes(
+  value: unknown,
+  resolve: (type: ComponentTypeRef) => unknown,
+): unknown {
+  if (isComponentType(value)) return resolve(value.$type);
+  if (Array.isArray(value)) {
+    let changed = false;
+    const out = value.map((item) => {
+      const next = mapComponentTypes(item, resolve);
+      if (next !== item) changed = true;
+      return next;
+    });
+    return changed ? out : value;
+  }
+  if (value === null || typeof value !== "object" || isNode(value)) return value;
+  let changed = false;
+  const out: Record<string, unknown> = {};
+  for (const [key, nested] of Object.entries(value)) {
+    const next = mapComponentTypes(nested, resolve);
+    if (next !== nested) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : value;
+}
+
+/** Every component type in a prop value, by the same reach as {@link mapComponentTypes}. */
+export function componentTypesIn(value: unknown): ComponentTypeRef[] {
+  const out: ComponentTypeRef[] = [];
+  mapComponentTypes(value, (type) => {
+    out.push(type);
+    return type;
+  });
+  return out;
+}

package/pkgs/schema/src/node.ts

@@ -127,20 +127,48 @@ export type TextNode = {
 
 export type Node = ComponentNode | SnippetInstance | ParamRef | TextNode;
 
+/**
+ * A component *type* held as a prop value: `component={ScrollArea}`,
+ * `as={Link}`, `icon={IconBolt}` — the component itself, not an element of it.
+ * The reference is a component node with no props, children or `$id`, so the
+ * name resolves exactly as a `$ref` of that name would (the app's component by
+ * its `$repo`, else an extension, else the screen's library). It is a value,
+ * not a node: it sits anywhere a prop value can, nested in arrays and objects
+ * too, and never in a tree's children.
+ */
+export type ComponentTypeRef = {
+  $ref: string;
+  $repo?: RepoComponentRef | undefined;
+};
+
+export type ComponentType = { $type: ComponentTypeRef };
+
+// Walkers ask these of raw prop values too (`rightSection: null`), so each one
+// has to answer for a value that is not an object at all.
 export function isComponentNode(n: Node): n is ComponentNode {
-  return typeof (n as { $ref?: unknown }).$ref === "string";
+  return typeof (n as { $ref?: unknown } | null | undefined)?.$ref === "string";
 }
 
 export function isSnippetInstance(n: Node): n is SnippetInstance {
-  return typeof (n as { $snippet?: unknown }).$snippet === "string";
+  return typeof (n as { $snippet?: unknown } | null | undefined)?.$snippet === "string";
 }
 
 export function isParamRef(n: Node): n is ParamRef {
-  return typeof (n as { $param?: unknown }).$param === "string";
+  return typeof (n as { $param?: unknown } | null | undefined)?.$param === "string";
 }
 
 export function isTextNode(n: Node): n is TextNode {
-  return typeof (n as { $text?: unknown }).$text === "string";
+  return typeof (n as { $text?: unknown } | null | undefined)?.$text === "string";
+}
+
+export function isComponentType(value: unknown): value is ComponentType {
+  const inner = (value as { $type?: unknown } | null | undefined)?.$type;
+  return (
+    !Array.isArray(value) &&
+    typeof inner === "object" &&
+    inner !== null &&
+    typeof (inner as { $ref?: unknown }).$ref === "string"
+  );
 }
 
 /**
@@ -213,11 +241,53 @@ export const RepoComponentRefSchema = z.object({
   proxy: z.string().min(1).optional(),
 });
 
+const ComponentTypeSchema: z.ZodType<ComponentType> = z.strictObject({
+  $type: z.strictObject({
+    // Printed bare as a JS expression (`component={AppShell.Section}`), so it
+    // has to be an identifier path — which also keeps a synthetic `velloo:` ref out.
+    $ref: z.string().regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/, {
+      message: 'a component type\'s $ref must be a component name like "ScrollArea"',
+    }),
+    $repo: RepoComponentRefSchema.optional(),
+  }),
+});
+
+/**
+ * Prop values are free-form JSON with one exception: an object carrying
+ * `$type` must be a well-formed component type, wherever it sits. Its `$repo`
+ * reaches codegen's imports and the canvas bundler exactly as a node's does, so
+ * it is held to the same checks.
+ */
+function checkComponentTypes(value: unknown, ctx: z.RefinementCtx, path: PropertyKey[]): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => {
+      checkComponentTypes(item, ctx, [...path, i]);
+    });
+    return;
+  }
+  if (value === null || typeof value !== "object") return;
+  if (Object.hasOwn(value, "$type")) {
+    const parsed = ComponentTypeSchema.safeParse(value);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue({ code: "custom", message: issue.message, path: [...path, ...issue.path] });
+      }
+    }
+    return;
+  }
+  for (const [key, nested] of Object.entries(value))
+    checkComponentTypes(nested, ctx, [...path, key]);
+}
+
+const PropsSchema = z.record(z.string(), z.unknown()).superRefine((props, ctx) => {
+  checkComponentTypes(props, ctx, []);
+});
+
 const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
   z.object({
     $ref: z.string().min(1),
     $id: NodeIdSchema.optional(),
-    props: z.record(z.string(), z.unknown()).optional(),
+    props: PropsSchema.optional(),
     children: z
       .array(z.union([z.string(), z.number(), NodeSchema]))
       .transform(scalarChildren)
@@ -262,14 +332,14 @@ const SnippetInstanceSchema: z.ZodType<SnippetInstance> = z.object({
   $snippet: z.string().min(1),
   $id: NodeIdSchema.optional(),
   $extraClassName: z.string().optional(),
-  args: z.record(z.string(), z.unknown()).optional(),
+  args: PropsSchema.optional(),
   $overrides: z
     .record(
       z.string().regex(/^$|^\d+(\.\d+)*$|^@[a-zA-Z][a-zA-Z0-9_-]*$/, {
         message:
           'override key must be a dotted index path like "0.2", an "@id" reference with a literal leading @ (e.g. "@row-active" to target the body node whose $id is "row-active"), or "" for the body root',
       }),
-      z.object({ props: z.record(z.string(), z.unknown()) }),
+      z.object({ props: PropsSchema }),
     )
     .optional(),
 });
@@ -313,8 +383,9 @@ export const NodeSchema: z.ZodType<Node> = z
     if (!branch) {
       ctx.addIssue({
         code: "custom",
-        message:
-          'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), "$param" (param ref, snippet bodies only), or "$text" (text beside elements)',
+        message: isComponentType(v)
+          ? `a component type ({"$type": …}) is a prop value, not a node — to render one here, write {"$ref": ${JSON.stringify(v.$type.$ref)}}`
+          : 'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), "$param" (param ref, snippet bodies only), or "$text" (text beside elements)',
       });
       return z.NEVER;
     }