velloo 0.7.0 → 0.9.0

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,
@@ -145,6 +163,7 @@ export {
   applySnippetOverrides,
   type InvalidParamPlacement,
   resolveSnippetArgs,
+  snippetChildSlots,
   substituteSnippetParams,
 } from "./snippet-resolve.ts";
 export { sanitizeSvgMarkup, svgLooksActive } from "./svg-sanitize.ts";
@@ -154,12 +173,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;
     }

package/pkgs/schema/src/snippet-resolve.ts

@@ -19,6 +19,49 @@ const OMITTED: unique symbol = Symbol("velloo.omitted-optional-param");
 /** Substitution result for an OMITTED value — pruned from arrays and prop objects. */
 const DROP: unique symbol = Symbol("velloo.drop");
 
+/**
+ * The params a snippet body places only as children — the `node` params whose
+ * args are nodes. One that also fills a prop, or is forwarded into another
+ * instance's args, carries data: what it holds there is the body's business,
+ * not a node's. The server reads only these args as nodes, and the canvas
+ * inspector edits only these as nodes.
+ */
+export function snippetChildSlots(snippet: Pick<Snippet, "tree">): Set<string> {
+  const asChild = new Set<string>();
+  const elsewhere = new Set<string>();
+  const paramsIn = (v: unknown, into: Set<string>): void => {
+    if (v === null || typeof v !== "object") return;
+    if (Array.isArray(v)) {
+      for (const item of v) paramsIn(item, into);
+      return;
+    }
+    const record = v as Record<string, unknown>;
+    if (typeof record.$param === "string") into.add(record.$param);
+    for (const nested of Object.values(record)) paramsIn(nested, into);
+  };
+  const child = (v: unknown): void => {
+    if (Array.isArray(v)) {
+      for (const item of v) child(item);
+      return;
+    }
+    if (v === null || typeof v !== "object") return;
+    const record = v as Record<string, unknown>;
+    if (typeof record.$param === "string") asChild.add(record.$param);
+    else if (typeof record.$if === "string") {
+      child(record.then);
+      child(record.else);
+    } else node(record);
+  };
+  const node = (record: Record<string, unknown>): void => {
+    paramsIn(record.props, elsewhere);
+    paramsIn(record.args, elsewhere);
+    child(record.children);
+  };
+  child(snippet.tree);
+  for (const name of elsewhere) asChild.delete(name);
+  return asChild;
+}
+
 /** Resolve declared params against passed args, applying defaults. */
 export function resolveSnippetArgs(
   snippet: Snippet,

package/pkgs/schema/src/theme.ts

@@ -140,6 +140,20 @@ const PaletteSchema = z.record(
   z.string().min(1),
 );
 
+/**
+ * The palette entries that are roles in their own right — `success`,
+ * `tertiary`, `brand-soft` — as opposed to steps of a scale (`primary-600`),
+ * which an import can add by the hundred. A design language lists the first
+ * kind next to the semantic slots; the second kind is an app's raw material.
+ */
+export function namedPaletteRoles(theme: Pick<Theme, "palette" | "paletteDark">): string[] {
+  const names = new Set([
+    ...Object.keys(theme.palette ?? {}),
+    ...Object.keys(theme.paletteDark ?? {}),
+  ]);
+  return [...names].filter((name) => !/(?:^|-)\d+$/.test(name)).sort();
+}
+
 /**
  * A typeset: three rhythm controls plus font roles. Everything visible —
  * the h1..h6 ladder, body/lead/small copy, the space under a heading — derives
@@ -261,3 +275,45 @@ export const ThemeSchema = z.object({
 });
 
 export type Theme = z.infer<typeof ThemeSchema>;
+
+/** Longer than any name a person would give a theme, short enough for a file name anywhere. */
+const THEME_NAME_MAX = 48;
+
+/**
+ * A theme's name is the stem of its file (`theme/<name>.json`), the value a
+ * board pins and the argument an agent passes, so there is one name and it is
+ * the one a person typed: "Night", "Brand B", "high-contrast".
+ *
+ * What it may contain is what a file name carries on every platform without
+ * quoting surprises — ASCII letters of either case, digits, spaces, dashes and
+ * underscores, beginning and ending on a letter or digit (Windows drops a
+ * trailing space or dot). Accented letters are left out because macOS and
+ * Linux disagree about how to spell them on disk, which git then reports as a
+ * renamed file.
+ */
+const THEME_NAME = /^[A-Za-z0-9](?:[A-Za-z0-9 _-]*[A-Za-z0-9])?$/;
+
+/** A typed name as it will be stored: no outer space, single spaces within. */
+export function normalizeThemeName(raw: string): string {
+  return raw.trim().replace(/\s+/g, " ");
+}
+
+/**
+ * Why `name` cannot be a new theme's name, as a sentence for whoever chose it;
+ * null when it can. `existing` is compared without case: macOS and Windows
+ * keep `Night.json` and `night.json` as one file, so the two cannot coexist in
+ * a design that is cloned onto either.
+ */
+export function themeNameProblem(name: string, existing: Iterable<string> = []): string | null {
+  if (name === "") return "Give the theme a name.";
+  if (name.length > THEME_NAME_MAX) return `Keep the name to ${THEME_NAME_MAX} characters.`;
+  if (!THEME_NAME.test(name)) {
+    return "Use letters, digits, spaces, dashes and underscores, starting and ending with a letter or digit.";
+  }
+  const folded = name.toLowerCase();
+  if (folded === "default") return 'Every design already has a "Default" theme.';
+  for (const other of existing) {
+    if (other.toLowerCase() === folded) return `A theme named "${other}" already exists.`;
+  }
+  return null;
+}

package/plugins/claude/velloo/agents/velloo-designer.md

@@ -20,10 +20,13 @@ Workflow:
    file and read it: it is the folder's own design system in prose — house rules
    that outrank the defaults below, and what the reviewer will check this work
    against. Velloo points at the file rather than copying it, so it is current.
-2. **Build in big strokes.** `compose` accepts a full subtree as restricted
-   JSX — a whole section per call, not node-by-node; `batch` groups mutations
-   atomically. Repeated structure (cards, rows, nav items) becomes a snippet
-   with typed params (`add_snippet`, then placed in `compose` by its tag).
+2. **Build in big strokes.** `compose` accepts the JSX you would write for
+   the app — `const` data, `.map`, `cond && <X />`, small components, or a page
+   `file` to read — a whole screen per call, not node-by-node; `get_screen
+   mode: "jsx"` reads one back to edit and send again; `batch` groups mutations
+   atomically. Structure that should stay reusable on the canvas (cards, rows,
+   nav items) becomes a snippet with typed params (`add_snippet`, then placed
+   in `compose` by its tag).
    Set `vellooId` at creation and address nodes as `"@id"` afterwards.
 3. **Prefer semantic theme tokens** (`bg-background`, `text-foreground`,
    `border-border`, `bg-primary`, …) over raw palette colors; raw palette only

package/plugins/claude/velloo/commands/setup.md

@@ -0,0 +1,13 @@
+---
+description: Set Velloo up for this app — the first step after velloo init
+argument-hint: (optional) the design to set up, when the repo has several
+---
+
+Use the velloo-setup skill to set this design up for its app: $ARGUMENTS
+
+Work through the velloo MCP tools — they own the design folder; never edit its
+JSON by hand. If the tools aren't available, tell the user to run
+`velloo connect` and restart this session. Give the user the canvas URL up
+front, finish by telling them what is exact, what is adapted and what you
+could not verify, and point them at the Design language stage on the canvas to
+review what you proposed.

package/plugins/gemini/GEMINI.md

@@ -19,13 +19,17 @@ Ground rules:
 - **Prefer semantic theme tokens** (`bg-background`, `text-foreground`,
   `bg-primary`, …) over raw palette colors — they adapt to dark mode and
   theme changes.
-- **Build in big strokes:** `compose` takes full subtrees as restricted JSX;
-  `batch` groups mutations; repeated structure becomes a snippet
-  (`add_snippet`, then placed in `compose` by its tag).
+- **Build in big strokes:** `compose` takes the JSX you would write for the
+  app (`const` data, `.map`, `cond && <X />`, small components, or a page
+  `file`) and writes it out as elements; `get_screen mode: "jsx"` reads a
+  screen back to edit; `batch` groups mutations; structure that should stay
+  reusable becomes a snippet (`add_snippet`, then placed in `compose` by its
+  tag).
 - **Verify:** `screenshot mode: "compare"` (light + dark), its `diagnostics`,
   `score_theme_contrast`, and `compare_to_url` against a running app.
 - The user can watch on the live canvas — `velloo run` prints its URL.
 
-This extension ships the Velloo skills (design, implement, brand, design
-system, logo) — reach for `velloo-design` when composing and
+This extension ships the Velloo skills (setup, design, implement, brand,
+design system, logo) — start a design that has an app to match with
+`velloo-setup`, reach for `velloo-design` when composing and
 `velloo-implement` when turning a finished design into production code.

package/plugins/gemini/commands/velloo/setup.toml

@@ -0,0 +1,11 @@
+description = "Set Velloo up for this app — the first step after velloo init"
+
+prompt = """
+Use the velloo-setup skill (or the velloo MCP tools directly) to set this design up for its app: {{args}}
+
+Work through the velloo MCP tools — they own the design folder; never edit its
+JSON by hand. Import the app's theme and real fonts, get `preview_status` to
+`valid`, look at what `check_components` returns, then propose the design
+language with `set_design_language`. Finish by telling the user what is exact,
+what is adapted and what you could not verify.
+"""

package/skills/velloo-design/SKILL.md

@@ -44,12 +44,17 @@ reference — read them; this skill is the workflow on top.
    dark mode and survive theme changes; raw palette colors render identically in
    both. Use raw palette only for an *intentional* accent that should not flip —
    and mark that node `data-accent: "ok"` so the raw-color diagnostic exempts it.
-3. **Build whole subtrees, not node-by-node.** `compose` takes a full subtree
-   as restricted JSX in one call (`mode: "append"` under a parent, or
-   `"replace"` for the whole screen). For repeated structure (list rows, cards,
-   nav items), define a **snippet** with typed params once (`add_snippet`), then
-   place it in `compose` by its PascalCase tag, args as props. `batch` runs many
-   mutations atomically in one round-trip.
+3. **Build whole subtrees, not node-by-node.** `compose` takes the JSX you
+   would write for the app in one call — `const` data above the markup, `.map`,
+   `cond && <X />`, small components — or reads it from a page file (`file`);
+   `mode: "append"` adds under a parent, `"replace"` swaps the whole screen
+   (creating it if it is new) or one node (`path`). It is read as data and
+   written out as elements; nothing runs. `get_screen mode: "jsx"` reads a
+   screen back in that form to edit and send again. For structure that should
+   stay reusable on the canvas (list rows, cards, nav items), define a
+   **snippet** with typed params once (`add_snippet`), then place it in
+   `compose` by its PascalCase tag, args as props. `batch` runs many mutations
+   atomically in one round-trip.
 4. **Think in ids.** Set `vellooId` at creation and address nodes as `"@id"` in
    later calls — number paths shift when siblings move.