velloo 0.0.0 → 0.2.0

package/pkgs/schema/src/node.ts

@@ -0,0 +1,229 @@
+import { z } from "zod";
+
+/**
+ * A node tree is a discriminated union over three shapes, distinguished by
+ * which `$`-prefixed key is present:
+ *
+ * - `ComponentNode` — a real shadcn / velloo component (`{ $ref }`).
+ * - `SnippetInstance` — an instantiation of a snippet defined in `snippets/`
+ *   (`{ $snippet, args }`). From the page's POV the instance is opaque —
+ *   path navigation stops at the instance; you can edit its args but not
+ *   descend into the snippet body.
+ * - `ParamRef` — `{ $param: name }`. Valid only inside a snippet body;
+ *   substituted with the corresponding instance arg at render time. May
+ *   appear as a child node OR anywhere inside a `props` value via the
+ *   normal JSON walk during substitution.
+ *
+ * Optional fields are spelled `?: T | undefined` rather than `?: T`. Under
+ * `exactOptionalPropertyTypes` those differ, but not for a shape that round-
+ * trips through JSON: `JSON.stringify` drops an explicitly-undefined key, so
+ * "absent" and "present but undefined" are the same node on disk. Writing it
+ * this way lets the zod schemas below (whose `.optional()` yields
+ * `T | undefined`) describe these types exactly.
+ *
+ * `ComponentNode` and `SnippetInstance` may carry an optional `$id` —
+ * a stable anchor that survives sibling insertions and deletions. Ids
+ * are unique within a single screen tree (validated at persist time).
+ * Agents address `$id`-bearing nodes via the locator form `"@id"` in
+ * place of a path array.
+ *
+ * Schema-level validation accepts all three at every Node position. Screen
+ * trees are expected to contain only `ComponentNode | SnippetInstance`;
+ * `ParamRef`s in a screen tree fail at substitution time rather than at
+ * parse time so the schema stays simple.
+ */
+export type ComponentNode = {
+  $ref: string;
+  $id?: string | undefined;
+  props?: Record<string, unknown> | undefined;
+  children?: Node[] | undefined;
+  /**
+   * Host-component facade (scan/import of a host-app component). When
+   * set, the canvas renders this node's real
+   * velloo subtree (the design agent's faithful approximation of a scanned app
+   * component it can't map to a primitive — SSR-only, data-bound, bespoke), but
+   * `emit_code` emits `<name />` imported from `importPath` *instead* of the
+   * subtree — preserving the app's real component identity through
+   * capture → design → emit. Absent ⇒ the node emits as itself.
+   */
+  $emitAs?: { name: string; importPath: string } | undefined;
+};
+
+export type SnippetInstance = {
+  $snippet: string;
+  $id?: string | undefined;
+  /**
+   * Extra Tailwind classes merged into the snippet body's root element at
+   * render time. Lets one-off instances tweak styling (e.g. wider, accent
+   * border) without forking the snippet definition. Pass it via
+   * a snippet tag's `className` in `compose`, or `update_snippet_instance`.
+   */
+  $extraClassName?: string | undefined;
+  args?: Record<string, unknown> | undefined;
+  /**
+   * Per-instance interior prop patches, keyed by dotted path into the
+   * *resolved* snippet body ("" = root, "0.2" = third child of root's
+   * first child). Each patch shallow-merges over the body node's props
+   * at render time. The escape hatch for "this one instance needs its
+   * badge red" without forking the snippet — instances carrying
+   * overrides are inlined (not emitted as the shared component) by
+   * emit_code, since a shared React component can't express them.
+   */
+  $overrides?: Record<string, { props: Record<string, unknown> }> | undefined;
+};
+
+export type ParamRef = {
+  $param: string;
+};
+
+export type Node = ComponentNode | SnippetInstance | ParamRef;
+
+export function isComponentNode(n: Node): n is ComponentNode {
+  return typeof (n as { $ref?: unknown }).$ref === "string";
+}
+
+export function isSnippetInstance(n: Node): n is SnippetInstance {
+  return typeof (n as { $snippet?: unknown }).$snippet === "string";
+}
+
+export function isParamRef(n: Node): n is ParamRef {
+  return typeof (n as { $param?: unknown }).$param === "string";
+}
+
+/**
+ * Format constraint for `$id` values. Must start with a letter; the rest
+ * is letters / digits / dashes / underscores. Matches typical anchor
+ * naming (`hero-cta`, `feature_card_3`, `nav`). The leading-letter rule
+ * keeps ids from colliding with numeric path indices in the locator
+ * parser if we ever support compound locators.
+ */
+export const NodeIdSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/, {
+    message: "node id must match /^[a-zA-Z][a-zA-Z0-9_-]*$/",
+  });
+
+/**
+ * A bare string/number in a `children` array is a common first-try shape
+ * ("just put the label here"). Rather than reject it — `children` renders
+ * nodes only — auto-wrap it into an inline `Box as="span"` so it renders as
+ * text without stacking. Wrapping (vs. allowing scalars through) keeps
+ * `children` typed `Node[]` for every downstream consumer. The styled-run
+ * idiom (a mixed array in the `children` *prop*) is still preferred for rich
+ * text; this just removes a needless failure.
+ */
+function wrapScalarChild(item: string | number | Node): Node {
+  if (typeof item === "string" || typeof item === "number") {
+    return { $ref: "Box", props: { as: "span", children: item } };
+  }
+  return item;
+}
+
+const EmitAsSchema = z.object({
+  name: z.string().min(1),
+  importPath: z.string().min(1),
+});
+
+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(),
+    children: z
+      .array(z.union([z.string(), z.number(), NodeSchema]))
+      .transform((items) => items.map(wrapScalarChild))
+      .optional(),
+    $emitAs: EmitAsSchema.optional(),
+  }),
+);
+
+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(),
+  $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()) }),
+    )
+    .optional(),
+});
+
+const ParamRefSchema: z.ZodType<ParamRef> = z.object({
+  $param: z.string().min(1),
+});
+
+/**
+ * Key-routed parse instead of `z.union`: a malformed node yields the
+ * issues of the *one* branch its `$`-key selects (with a full path),
+ * not a three-branch union explosion. The MCP layer surfaces these
+ * issues verbatim to agents, so error shape is part of the tool UX.
+ */
+export const NodeSchema: z.ZodType<Node> = z
+  .unknown()
+  .transform((val, ctx): Node => {
+    if (val === null || typeof val !== "object" || Array.isArray(val)) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          'node must be an object with one of "$ref" (component), "$snippet" (instance), or "$param" (param ref)',
+      });
+      return z.NEVER;
+    }
+    const v = val as Record<string, unknown>;
+    const branch =
+      typeof v.$ref === "string"
+        ? ComponentNodeSchema
+        : typeof v.$snippet === "string"
+          ? SnippetInstanceSchema
+          : typeof v.$param === "string"
+            ? ParamRefSchema
+            : null;
+    if (!branch) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), or "$param" (param ref, snippet bodies only)',
+      });
+      return z.NEVER;
+    }
+    const parsed = branch.safeParse(val);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue({ ...issue });
+      }
+      return z.NEVER;
+    }
+    return parsed.data;
+  })
+  // Kept short on purpose: this string is inlined into five tools' schemas, so
+  // every character is paid five times by every session. The full shapes —
+  // $overrides, $extraClassName, $if, param placement — are in
+  // velloo://guide/components and velloo://guide/snippets.
+  .describe(
+    '{"$ref":"Button","$id?":"cta","props?":{...},"children?":[Node]}, or {"$snippet":"<id>","args?":{...}}. Guide: velloo://guide/components',
+  )
+  // `z.unknown()` emits a JSON Schema with no `type`, so strict MCP clients
+  // can't tell `tree`/`children` params are objects and serialize them as
+  // strings — the server then rejects a valid `{"$ref":"Box"}`. The runtime
+  // transform above still does the real validation; this only annotates the
+  // emitted schema so clients send objects. Keep it as `additionalProperties:
+  // true` (any object) rather than the full union — minimal and permissive.
+  // Unavoidable cast: `.transform().meta()` erases the recursive output type
+  // (ZodPipe of unknown), so reassert the declared `z.ZodType<Node>`.
+  .meta({ type: "object", additionalProperties: true }) as unknown as z.ZodType<Node>;
+
+/**
+ * Read the `$id` of a node, if any. Convenience wrapper so callers don't
+ * have to narrow by node kind first.
+ */
+export function nodeId(n: Node): string | undefined {
+  if (isParamRef(n)) return undefined;
+  return (n as { $id?: string }).$id;
+}

package/pkgs/schema/src/paths.ts

@@ -0,0 +1,28 @@
+// Node-only module — exported as `@velloo/schema/paths`, deliberately NOT from
+// the package index: the index is compiled into browser bundles where `node:*`
+// imports fail. Mirrors `@velloo/helpers/paths`.
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the schema sources. The canvas bundler resolves the
+ * zero-dependency leaf modules the velloo helper components import
+ * (`typeset`, `icon-name`, `svg-sanitize`) from here, because the installed
+ * binary inlines `@velloo/*` into `cli.js` — a runtime `Bun.build` of the
+ * shipped `.tsx` under `dist/pkgs` has no node_modules to walk up into.
+ * Resolves from source (`here` = this `src/` dir) and from the bundled CLI,
+ * where the CLI's `build.ts` copies these sources to `<dist>/pkgs/schema/src`.
+ */
+function resolveDir(): string {
+  const candidates = [
+    process.env.VELLOO_SCHEMA_SRC,
+    join(here, "pkgs", "schema", "src"),
+    here,
+  ].filter((p): p is string => Boolean(p));
+  return candidates.find((d) => existsSync(join(d, "typeset.ts"))) ?? here;
+}
+
+export const schemaSrcDir: string = resolveDir();

package/pkgs/schema/src/repo.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+
+/**
+ * Consent for the `send_feedback` tool.
+ *
+ * `enabled` is a repo decision (committed in `velloo.json`) — whether the tool
+ * exists for this project at all. `contactOk` records consent to be *contacted*
+ * about what was sent, which is personal: it is read from and written to the
+ * machine's `~/.velloo/prefs.json`, never committed, so cloning a repo can't
+ * opt a different person into being emailed. It stays in this shape because
+ * every reader wants the pair, and because folders written before the split
+ * still carry it on disk (where it is now ignored).
+ */
+export const FeedbackPrefsSchema = z.object({
+  enabled: z.boolean(),
+  contactOk: z.boolean().optional(),
+});
+
+export type FeedbackPrefs = z.infer<typeof FeedbackPrefsSchema>;
+
+const MAX_DESIGN_NAME = 80;
+
+/**
+ * Why `name` can't name a design, or null when it can. Almost anything goes —
+ * spaces, emoji, any script. The limits are the ones a name typed as a command
+ * argument needs: no path separator (a bare argument with one is read as a
+ * path), no control characters, nothing that is only whitespace or a dot
+ * path, and no padding a shell would silently strip.
+ */
+export function designNameIssue(name: string): string | null {
+  if (name.trim() === "") return "a design name can't be empty";
+  if (name !== name.trim()) return "a design name can't start or end with spaces";
+  if (name === "." || name === "..") return `"${name}" can't be a design name`;
+  if (/[/\\]/.test(name)) return "a design name can't contain / or \\";
+  if (/\p{Cc}/u.test(name)) return "a design name can't contain control characters";
+  if ([...name].length > MAX_DESIGN_NAME)
+    return `a design name can't be longer than ${MAX_DESIGN_NAME} characters`;
+  return null;
+}
+
+export function isDesignName(name: string): boolean {
+  return designNameIssue(name) === null;
+}
+
+/** A Zod string that must be a design name, with the specific reason when it isn't. */
+export const DesignNameSchema = z.string().superRefine((name, ctx) => {
+  const issue = designNameIssue(name);
+  if (issue) ctx.addIssue({ code: "custom", message: issue });
+});
+
+/**
+ * Coerce free text (a directory name, an app name) into a valid design name,
+ * or null when nothing usable is left.
+ */
+export function toDesignName(text: string): string | null {
+  const cleaned = [...text.replace(/[/\\\p{Cc}]+/gu, " ").trim()]
+    .slice(0, MAX_DESIGN_NAME)
+    .join("")
+    .trim();
+  return cleaned && isDesignName(cleaned) ? cleaned : null;
+}
+
+/**
+ * The repo-root `velloo.json`. It lists a repo's designs so a monorepo can
+ * hold several, and carries the handful of preferences that belong to the
+ * repo rather than to any one design — feedback consent is answered once per
+ * person, not once per canvas.
+ *
+ * Only locations live here: each design's name and settings are in its own
+ * `.design/config.json`, so nothing here can drift from the design itself.
+ * Every entry is a path to a design folder inside the repository. A design
+ * kept outside it is recorded only on the machine that has it, never here.
+ */
+export const RepoManifestSchema = z
+  .object({
+    $schema: z.string().optional(),
+    designs: z.array(z.string().min(1)),
+    /** The name of the design a bare command resolves to when nothing else picks one. */
+    defaultDesign: DesignNameSchema.optional(),
+    feedback: FeedbackPrefsSchema.optional(),
+  })
+  .refine((m) => new Set(m.designs).size === m.designs.length, {
+    message: "designs lists the same path twice",
+  });
+
+export type RepoManifest = z.infer<typeof RepoManifestSchema>;
+
+/** Filename of the repo-root manifest, resolved by walking up from a folder. */
+export const REPO_MANIFEST_FILE = "velloo.json";
+
+export interface NormalizedRepoManifest {
+  /** The manifest in the current shape, ready for {@link RepoManifestSchema}. */
+  manifest: unknown;
+  /**
+   * Names the pre-v4 `projects` map gave each path. A folder not yet migrated
+   * has no `name` in its config, so these stand in until `velloo upgrade`
+   * writes them there.
+   */
+  legacyNames: Record<string, string>;
+  /** True when the file was in the pre-v4 shape and should be rewritten. */
+  legacy: boolean;
+}
+
+/**
+ * Read either manifest shape. Before designs carried their own names the file
+ * was `{ projects: { name: path }, defaultProject }`; the schema would silently
+ * drop those keys, so they are converted here, before parsing.
+ */
+export function normalizeRepoManifest(raw: unknown): NormalizedRepoManifest {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { manifest: raw, legacyNames: {}, legacy: false };
+  }
+  const { projects, defaultProject, ...rest } = raw as Record<string, unknown>;
+  if (projects === undefined || "designs" in rest) {
+    return { manifest: raw, legacyNames: {}, legacy: false };
+  }
+  const legacyNames: Record<string, string> = {};
+  const designs: unknown[] = [];
+  if (typeof projects === "object" && projects !== null && !Array.isArray(projects)) {
+    for (const [name, path] of Object.entries(projects)) {
+      designs.push(path);
+      if (typeof path === "string") legacyNames[path] = name;
+    }
+  }
+  return {
+    manifest: {
+      ...rest,
+      designs,
+      ...(defaultProject !== undefined ? { defaultDesign: defaultProject } : {}),
+    },
+    legacyNames,
+    legacy: true,
+  };
+}

package/pkgs/schema/src/screen.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { ResourceIdSchema } from "./ids.ts";
+import { NodeSchema } from "./node.ts";
+
+/**
+ * A Screen is one composition: a single responsive React tree built from
+ * the design folder's library. Lives at `screens/<id>.json`.
+ *
+ * One screen → one tree. Different viewport renderings are not separate
+ * screens — they're separate Frames on the Board pointing at the same
+ * screen. Edits to the tree propagate to every frame of that screen.
+ *
+ * If a layout truly diverges per breakpoint (e.g. drawer vs sidebar nav),
+ * the user/agent creates a *second* screen and a second frame. Explicit
+ * fork, no background sync.
+ */
+export const ScreenSchema = z.object({
+  id: ResourceIdSchema,
+  name: z.string().min(1),
+  /**
+   * Library id (key in `Config.libraries`) this screen renders against.
+   * Optional — when absent the folder's `defaultLibrary` is used.
+   * Multi-library per folder; one library per screen. A screen's
+   * components and extensions resolve against this library's registry.
+   */
+  library: z.string().min(1).optional(),
+  tree: NodeSchema,
+});
+
+export type Screen = z.infer<typeof ScreenSchema>;

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

@@ -0,0 +1,193 @@
+import { isComponentNode, isParamRef, isSnippetInstance, type Node } from "./node.ts";
+import type { Snippet } from "./snippet.ts";
+
+/**
+ * Pure snippet-body resolution helpers shared by the renderer (render
+ * time) and codegen (inlining instances that carry `$overrides`). No
+ * throwing — callers wrap missing-param reports in their own error
+ * vocabulary (renderer throws SnippetParamError, codegen returns a
+ * CodegenError).
+ */
+
+/**
+ * An optional param supplied no value and no default — resolves to "nothing".
+ * A node slot bearing it is dropped (renders/emits nothing); a prop bearing it
+ * is omitted. Internal sentinel: never appears in a persisted tree.
+ */
+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");
+
+/** Resolve declared params against passed args, applying defaults. */
+export function resolveSnippetArgs(
+  snippet: Snippet,
+  passed: Record<string, unknown>,
+): { args: Record<string, unknown>; missing: string[] } {
+  const args: Record<string, unknown> = {};
+  const missing: string[] = [];
+  for (const param of snippet.params) {
+    if (param.name in passed) {
+      args[param.name] = passed[param.name];
+    } else if (param.default !== undefined) {
+      args[param.name] = param.default;
+    } else if (param.optional) {
+      args[param.name] = OMITTED;
+    } else {
+      missing.push(param.name);
+    }
+  }
+  return { args, missing };
+}
+
+function isTruthy(v: unknown): boolean {
+  if (v === undefined || v === null || v === OMITTED) return false;
+  if (typeof v === "boolean") return v;
+  if (typeof v === "number") return v !== 0 && !Number.isNaN(v);
+  if (typeof v === "string") return v !== "";
+  return true;
+}
+
+/** A `$param` that substituted to a scalar where a child node was expected. */
+export interface InvalidParamPlacement {
+  param: string;
+  /** typeof the resolved value (or "null") — for a precise error message. */
+  valueType: string;
+}
+
+/**
+ * Recursively rewrite snippet body values:
+ * - `{ $param: "name" }` → `args.name`
+ * - `{ $if: "name", then, else }` → branch by truthiness
+ * - `{ $if: "name", eq, then, else }` → branch by strict equality
+ * Unknown param names are collected in `missing` (the offending
+ * substitution resolves to undefined) rather than thrown.
+ *
+ * `invalid` collects scalar params dropped into a *node* position — a
+ * component node's own `children` array, where only subtrees render. This
+ * is the classic mis-wire (a `string` param used as a child instead of as
+ * a prop value); flagging it lets the renderer name the param and point at
+ * the fix instead of failing opaquely deep in React. A `children` *prop*
+ * value (`props.children`) is plain content, not a node position, so a
+ * scalar param there is correct and never flagged.
+ */
+export function substituteSnippetParams(
+  value: unknown,
+  args: Record<string, unknown>,
+): { value: unknown; missing: string[]; invalid: InvalidParamPlacement[] } {
+  const missing: string[] = [];
+  const invalid: InvalidParamPlacement[] = [];
+  function walk(v: unknown, inNodePosition: boolean): unknown {
+    if (v === null || typeof v !== "object") return v;
+    if (Array.isArray(v)) {
+      // Prune DROP holes so an omitted optional `node` slot leaves no gap.
+      return v.map((item) => walk(item, inNodePosition)).filter((item) => item !== DROP);
+    }
+    if (typeof (v as { $param?: unknown }).$param === "string") {
+      const name = (v as { $param: string }).$param;
+      if (!(name in args)) {
+        missing.push(name);
+        return undefined;
+      }
+      const resolved = args[name];
+      // An omitted optional param resolves to nothing — never a mis-wire.
+      if (resolved === OMITTED) return DROP;
+      if (inNodePosition && (resolved === null || typeof resolved !== "object")) {
+        invalid.push({ param: name, valueType: resolved === null ? "null" : typeof resolved });
+        return undefined;
+      }
+      return resolved;
+    }
+    if (typeof (v as { $if?: unknown }).$if === "string") {
+      const cond = v as { $if: string; eq?: unknown; then?: unknown; else?: unknown };
+      if (!(cond.$if in args)) {
+        missing.push(cond.$if);
+        return undefined;
+      }
+      const matched = "eq" in cond ? args[cond.$if] === cond.eq : isTruthy(args[cond.$if]);
+      return walk(matched ? cond.then : cond.else, inNodePosition);
+    }
+    // Only a component node's own `children` array carries node positions.
+    const isComponentNodeObj = typeof (v as { $ref?: unknown }).$ref === "string";
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v)) {
+      const w = walk(val, isComponentNodeObj && k === "children");
+      // A prop resolving to an omitted optional param is left off entirely.
+      if (w !== DROP) out[k] = w;
+    }
+    return out;
+  }
+  return { value: walk(value, false), missing, invalid };
+}
+
+/** Depth-first search for a `$id`-bearing component node inside a body. */
+function findNodeById(root: Node, id: string): Node | undefined {
+  if (!isComponentNode(root)) return undefined;
+  if (root.$id === id) return root;
+  for (const child of root.children ?? []) {
+    const hit = findNodeById(child, id);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/**
+ * Apply per-instance interior prop patches (`SnippetInstance.$overrides`)
+ * to a resolved body. Keys address the substituted tree either as dotted
+ * index paths ("0.2") or as "@id" references to `$id`-bearing body nodes
+ * — ids survive definition restructures, so prefer them when the body
+ * declares ids. A key that no longer resolves (definition changed since
+ * the override was written) is skipped silently — stale overrides
+ * degrade to "no effect".
+ */
+export function applySnippetOverrides(
+  body: Node,
+  overrides: Record<string, { props: Record<string, unknown> }>,
+): Node {
+  const clone = structuredClone(body);
+  for (const [key, patch] of Object.entries(overrides)) {
+    let target: Node | undefined;
+    if (key.startsWith("@")) {
+      target = findNodeById(clone, key.slice(1));
+    } else {
+      const segments = key === "" ? [] : key.split(".").map(Number);
+      target = clone;
+      for (const i of segments) {
+        if (!target || !isComponentNode(target) || !target.children) {
+          target = undefined;
+          break;
+        }
+        target = target.children[i];
+      }
+    }
+    if (!target || !isComponentNode(target)) continue;
+    const props = { ...(target.props ?? {}) };
+    for (const [k, v] of Object.entries(patch.props)) {
+      if (v === null) delete props[k];
+      else props[k] = v;
+    }
+    target.props = props;
+  }
+  return clone;
+}
+
+/**
+ * Merge an instance's `$extraClassName` onto a resolved body's root.
+ * Snippet-of-snippet roots forward the extra to the inner instance;
+ * param-ref roots can't carry a className and pass through unchanged.
+ */
+export function applySnippetExtraClassName(node: Node, extra: string): Node {
+  if (isParamRef(node)) return node;
+  if (isSnippetInstance(node)) {
+    const existing = node.$extraClassName ? `${node.$extraClassName} ${extra}` : extra;
+    return { ...node, $extraClassName: existing };
+  }
+  if (!isComponentNode(node)) return node;
+  const existingClass =
+    typeof node.props?.className === "string" ? (node.props.className as string) : "";
+  const merged = existingClass ? `${existingClass} ${extra}` : extra;
+  return {
+    ...node,
+    props: { ...(node.props ?? {}), className: merged },
+  };
+}