velloo 0.5.0 → 0.7.0

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

@@ -0,0 +1,97 @@
+import {
+  type ComponentNode,
+  type EmitAsRef,
+  isComponentNode,
+  isParamRef,
+  isSnippetInstance,
+  isTextNode,
+  type Node,
+  type ParamRef,
+  type RepoComponentRef,
+  type SnippetInstance,
+  type TextNode,
+} from "./node.ts";
+
+/**
+ * A `$ref` the renderer resolves itself rather than through any registry.
+ * Synthetic refs are never persisted — a preview synthesizes them — and every
+ * provider has to be able to draw them, so they can't be library components
+ * (a `none` folder has no `Badge` to draw a param slot with).
+ */
+export const PARAM_TAG_REF = "velloo:param-tag";
+
+/**
+ * The ref a node serializes to when the canvas bundle has no browser source
+ * for it and the client must drop in its server render instead.
+ */
+export const STATIC_REF = "velloo:static";
+
+export type SyntheticRef = typeof PARAM_TAG_REF | typeof STATIC_REF;
+
+const SYNTHETIC_REFS: readonly SyntheticRef[] = [PARAM_TAG_REF, STATIC_REF];
+
+export function isSyntheticRef(ref: string): ref is SyntheticRef {
+  return (SYNTHETIC_REFS as readonly string[]).includes(ref);
+}
+
+/** A component node carrying a repository identity (see {@link ComponentNode.$repo}). */
+export type RepoNode = ComponentNode & { $repo: RepoComponentRef };
+
+/** A component node carrying an emit-time host facade (see {@link ComponentNode.$emitAs}). */
+export type EmitAsNode = ComponentNode & { $emitAs: EmitAsRef };
+
+/**
+ * What a node's own fields say it is. Purely structural: no registry, no
+ * catalog, no I/O — a `named` shape is as far as the node alone can go, and
+ * `resolveNodeIdentity` in `@velloo/provider` takes it from there.
+ *
+ * The order of the `$`-keys is the contract, stated here once and nowhere
+ * else: `$snippet`, then `$param`, then a component — where an identity
+ * (`$repo`) beats an emit-time facade (`$emitAs`) beats a synthetic ref beats
+ * a plain name — then `$text`. A malformed value carrying both `$snippet` and `$ref` is a
+ * snippet instance, as every walker has always read it.
+ */
+export type NodeShape =
+  | { kind: "repo"; node: RepoNode; ref: string; repo: RepoComponentRef }
+  | { kind: "emit-as"; node: EmitAsNode; ref: string; emitAs: EmitAsRef }
+  | { kind: "synthetic"; node: ComponentNode; ref: SyntheticRef }
+  | { kind: "named"; node: ComponentNode; ref: string }
+  | { kind: "snippet"; node: SnippetInstance }
+  | { kind: "param"; node: ParamRef }
+  /** A run of text beside elements: a bare text node, no element of its own. */
+  | { kind: "text"; node: TextNode; text: string }
+  /** Not a node at all — a raw scalar or object sitting in a node position. */
+  | { kind: "invalid"; value: unknown };
+
+/** Discriminate a value by its own fields. Accepts `unknown`: node positions are a trust boundary. */
+export function nodeShape(value: unknown): NodeShape {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { kind: "invalid", value };
+  }
+  const node = value as Node;
+  if (isSnippetInstance(node)) return { kind: "snippet", node };
+  if (isParamRef(node)) return { kind: "param", node };
+  if (isComponentNode(node)) {
+    if (node.$repo !== undefined) {
+      return { kind: "repo", node: node as RepoNode, ref: node.$ref, repo: node.$repo };
+    }
+    if (node.$emitAs !== undefined) {
+      return { kind: "emit-as", node: node as EmitAsNode, ref: node.$ref, emitAs: node.$emitAs };
+    }
+    if (isSyntheticRef(node.$ref)) {
+      return { kind: "synthetic", node, ref: node.$ref };
+    }
+    return { kind: "named", node, ref: node.$ref };
+  }
+  if (isTextNode(node)) return { kind: "text", node, text: node.$text };
+  return { kind: "invalid", value };
+}
+
+/**
+ * Whether a raw JSON value is itself a node. The check every walker needs when
+ * it meets a *prop* value — a `children` prop carrying inline rich text, a slot
+ * prop holding an icon — where a node and a plain value are both legal.
+ */
+export function isNode(value: unknown): value is Node {
+  return nodeShape(value).kind !== "invalid";
+}

package/pkgs/schema/src/node.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 /**
- * A node tree is a discriminated union over three shapes, distinguished by
+ * A node tree is a discriminated union over four shapes, distinguished by
  * which `$`-prefixed key is present:
  *
  * - `ComponentNode` — a real shadcn / velloo component (`{ $ref }`).
@@ -13,6 +13,11 @@ import { z } from "zod";
  *   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.
+ * - `TextNode` — `{ $text }`. A run of text sitting beside elements
+ *   (`<li>Remote <a>Apply</a></li>`). It renders as a bare text node, with no
+ *   element of its own, so no selector in the app's stylesheet can tell the
+ *   design's DOM from the app's. Text that is a component's *whole* content
+ *   stays in `props.children`.
  *
  * Optional fields are spelled `?: T | undefined` rather than `?: T`. Under
  * `exactOptionalPropertyTypes` those differ, but not for a shape that round-
@@ -46,18 +51,27 @@ export type ComponentNode = {
    * subtree — preserving the app's real component identity through
    * capture → design → emit. Absent ⇒ the node emits as itself.
    */
-  $emitAs?: { name: string; importPath: string } | undefined;
+  $emitAs?: EmitAsRef | undefined;
   /**
    * Repository component identity: this node IS a component the host app
    * imports (a package export such as Mantine's `Tabs`, or the app's own
    * `StatCard`), not a library component. `$ref` stays the JSX name codegen
-   * prints; the identity decides rendering and imports. Takes precedence over
-   * any provider component or extension of the same name, so shadowing is
-   * explicit on the node rather than a registry-order accident.
+   * prints; the identity decides rendering and imports. Where it sits against
+   * the node's other keys is `nodeShape`'s to say (`./node-identity.ts`).
    */
   $repo?: RepoComponentRef | undefined;
 };
 
+/**
+ * A host component a node emits *as*, in place of its own subtree. Superseded
+ * in practice by {@link RepoComponentRef}, which renders for real; kept because
+ * design folders carry it.
+ */
+export type EmitAsRef = {
+  name: string;
+  importPath: string;
+};
+
 /**
  * Where a repository component comes from. The import form is kept exactly as
  * code generation must print it; the resolved file is runtime cache data and
@@ -107,7 +121,11 @@ export type ParamRef = {
   $param: string;
 };
 
-export type Node = ComponentNode | SnippetInstance | ParamRef;
+export type TextNode = {
+  $text: string;
+};
+
+export type Node = ComponentNode | SnippetInstance | ParamRef | TextNode;
 
 export function isComponentNode(n: Node): n is ComponentNode {
   return typeof (n as { $ref?: unknown }).$ref === "string";
@@ -121,6 +139,10 @@ export function isParamRef(n: Node): n is ParamRef {
   return typeof (n as { $param?: unknown }).$param === "string";
 }
 
+export function isTextNode(n: Node): n is TextNode {
+  return typeof (n as { $text?: unknown }).$text === "string";
+}
+
 /**
  * Format constraint for `$id` values. Must start with a letter; the rest
  * is letters / digits / dashes / underscores. Matches typical anchor
@@ -138,18 +160,16 @@ export const NodeIdSchema = z
 
 /**
  * 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.
+ * ("just put the label here"), and it means what it says: text. It becomes a
+ * text node rather than being rejected, which keeps `children` typed `Node[]`
+ * for every downstream consumer. An empty string is nothing to hold.
  */
-function wrapScalarChild(item: string | number | Node): Node {
-  if (typeof item === "string" || typeof item === "number") {
-    return { $ref: "Box", props: { as: "span", children: item } };
-  }
-  return item;
+function scalarChildren(items: (string | number | Node)[]): Node[] {
+  return items.flatMap((item): Node[] => {
+    if (typeof item !== "string" && typeof item !== "number") return [item];
+    const text = String(item);
+    return text === "" ? [] : [{ $text: text }];
+  });
 }
 
 const EmitAsSchema = z.object({
@@ -200,7 +220,7 @@ const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
     props: z.record(z.string(), z.unknown()).optional(),
     children: z
       .array(z.union([z.string(), z.number(), NodeSchema]))
-      .transform((items) => items.map(wrapScalarChild))
+      .transform(scalarChildren)
       .optional(),
     $emitAs: EmitAsSchema.optional(),
     $repo: RepoComponentRefSchema.optional(),
@@ -258,10 +278,14 @@ const ParamRefSchema: z.ZodType<ParamRef> = z.object({
   $param: z.string().min(1),
 });
 
+const TextNodeSchema: z.ZodType<TextNode> = z.strictObject({
+  $text: 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
+ * not a four-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
@@ -271,7 +295,7 @@ export const NodeSchema: z.ZodType<Node> = z
       ctx.addIssue({
         code: "custom",
         message:
-          'node must be an object with one of "$ref" (component), "$snippet" (instance), or "$param" (param ref)',
+          'node must be an object with one of "$ref" (component), "$snippet" (instance), "$param" (param ref), or "$text" (text beside elements)',
       });
       return z.NEVER;
     }
@@ -283,12 +307,14 @@ export const NodeSchema: z.ZodType<Node> = z
           ? SnippetInstanceSchema
           : typeof v.$param === "string"
             ? ParamRefSchema
-            : null;
+            : typeof v.$text === "string"
+              ? TextNodeSchema
+              : 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)',
+          'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), "$param" (param ref, snippet bodies only), or "$text" (text beside elements)',
       });
       return z.NEVER;
     }
@@ -323,6 +349,6 @@ export const NodeSchema: z.ZodType<Node> = z
  * have to narrow by node kind first.
  */
 export function nodeId(n: Node): string | undefined {
-  if (isParamRef(n)) return undefined;
+  if (isParamRef(n) || isTextNode(n)) return undefined;
   return (n as { $id?: string }).$id;
 }

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

@@ -48,7 +48,7 @@ function isTruthy(v: unknown): boolean {
   return true;
 }
 
-/** A `$param` that substituted to a scalar where a child node was expected. */
+/** A `$param` that substituted to a boolean or null where a child node was expected. */
 export interface InvalidParamPlacement {
   param: string;
   /** typeof the resolved value (or "null") — for a precise error message. */
@@ -63,13 +63,17 @@ export interface InvalidParamPlacement {
  * 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.
+ * A string or number param in a *node* position — a component node's own
+ * `children` array — is the text it holds, and becomes a text node, exactly
+ * as a bare string written there does (`scalarChildren` in node.ts). It was a
+ * refusal before text nodes existed, and one that only surfaced at the next
+ * render: the write was accepted, and the screenshot after it failed. An
+ * empty string is nothing to hold.
+ *
+ * `invalid` collects what is left: a boolean or null param in a node position,
+ * which is a flag wired where content goes. A `children` *prop* value
+ * (`props.children`) is plain content, not a node position, so any scalar
+ * param there is correct and never flagged.
  */
 export function substituteSnippetParams(
   value: unknown,
@@ -92,11 +96,13 @@ export function substituteSnippetParams(
       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;
+      if (!inNodePosition || (resolved !== null && typeof resolved === "object")) return resolved;
+      if (typeof resolved === "string" || typeof resolved === "number") {
+        const text = String(resolved);
+        return text === "" ? DROP : { $text: text };
       }
-      return resolved;
+      invalid.push({ param: name, valueType: resolved === null ? "null" : typeof resolved });
+      return undefined;
     }
     if (typeof (v as { $if?: unknown }).$if === "string") {
       const cond = v as { $if: string; eq?: unknown; then?: unknown; else?: unknown };

package/pkgs/schema/src/svg-sanitize.ts

@@ -76,6 +76,9 @@ const ALLOWED_ELEMENTS: ReadonlyMap<string, string> = new Map(
   ].map((name) => [name.toLowerCase(), name]),
 );
 
+/** The static SVG elements, by their canonical (camelCase) names. */
+export const SVG_ELEMENT_NAMES: ReadonlySet<string> = new Set(ALLOWED_ELEMENTS.values());
+
 /**
  * Elements whose presence means the input tried to run or load something.
  * They are dropped like any unknown element; naming them is what lets

package/pkgs/schema/src/theme.ts

@@ -131,7 +131,12 @@ export function resolveColors(theme: Theme, dark = false): Colors {
  * CSS-safe ident so they can't inject into the emitted stylesheet.
  */
 const PaletteSchema = z.record(
-  z.string().regex(/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/),
+  z
+    .string()
+    .regex(
+      /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/,
+      'palette keys are lowercase kebab-case, letter first — "primary-soft", "success-500", "border-primary-300"',
+    ),
   z.string().min(1),
 );
 

package/pkgs/schema/src/typeset.ts

@@ -231,8 +231,21 @@ export function headingClasses(level: unknown): string {
   return TYPESET_CLASSES[role];
 }
 
-/** The Tailwind classes a `Text` of this variant renders with, tone included. */
-export function textClasses(variant: unknown): string {
+/**
+ * A `Text` inside a `Text` with no variant of its own is that paragraph's
+ * text: a run changes a word's colour or weight, and restating the body rung
+ * on it would resize `12 km` inside a 17px line to the default 14.
+ */
+function inheritsItsParagraph(variant: unknown, run: boolean): boolean {
+  return run && variant === undefined;
+}
+
+/**
+ * The Tailwind classes a `Text` of this variant renders with, tone included.
+ * `run` is true beneath another `Text`.
+ */
+export function textClasses(variant: unknown, run = false): string {
+  if (inheritsItsParagraph(variant, run)) return "";
   const v = textVariant(variant);
   const tone = TEXT_TONE_BY_VARIANT[v];
   return tone
@@ -246,8 +259,12 @@ export function headingInlineStyle(level: unknown): Record<string, string | numb
   return { ...TYPESET_INLINE_STYLE[role] };
 }
 
-/** The inline `style` a `Text` of this variant renders with, on the `none`-CSS channel. */
-export function textInlineStyle(variant: unknown): Record<string, string | number> {
+/**
+ * The inline `style` a `Text` of this variant renders with, on the `none`-CSS
+ * channel. `run` is true beneath another `Text`.
+ */
+export function textInlineStyle(variant: unknown, run = false): Record<string, string | number> {
+  if (inheritsItsParagraph(variant, run)) return {};
   const v = textVariant(variant);
   const tone = TEXT_TONE_BY_VARIANT[v];
   return {
@@ -287,24 +304,31 @@ export function typesetUtilityClasses(): string[] {
 }
 
 /**
- * The scale as a Tailwind v3 `theme.extend.fontSize` map. Each entry carries its
- * paired leading and tracking, and every value is a `var()` into the typeset
- * sheet — so a v3 app re-derives inside a `.typeset-<preset>` region exactly
- * like a v4 one.
+ * The scale as Tailwind v3 `theme.extend` maps. `fontSize` carries each role's
+ * paired leading and tracking (so `text-h1` alone sets all three), and
+ * `lineHeight` / `letterSpacing` make the standalone `leading-<role>` /
+ * `tracking-<role>` utilities exist — v3 derives no utility from a fontSize
+ * tuple's extras, and `TYPESET_CLASSES` spells all three. Every value is a
+ * `var()` into the typeset sheet, so a v3 app re-derives inside a
+ * `.typeset-<preset>` region exactly like a v4 one.
  */
-export function typesetV3FontSize(): Record<
-  string,
-  [string, { lineHeight: string; letterSpacing: string }]
-> {
-  return Object.fromEntries(
-    TYPESET_SCALE_NAMES.map((role) => [
-      role,
-      [
-        `var(--text-${role})`,
-        { lineHeight: `var(--leading-${role})`, letterSpacing: `var(--tracking-${role})` },
-      ],
-    ]),
-  );
+export function typesetV3Theme(): {
+  fontSize: Record<string, [string, { lineHeight: string; letterSpacing: string }]>;
+  lineHeight: Record<string, string>;
+  letterSpacing: Record<string, string>;
+} {
+  const fontSize: Record<string, [string, { lineHeight: string; letterSpacing: string }]> = {};
+  const lineHeight: Record<string, string> = {};
+  const letterSpacing: Record<string, string> = {};
+  for (const role of TYPESET_SCALE_NAMES) {
+    fontSize[role] = [
+      `var(--text-${role})`,
+      { lineHeight: `var(--leading-${role})`, letterSpacing: `var(--tracking-${role})` },
+    ];
+    lineHeight[role] = `var(--leading-${role})`;
+    letterSpacing[role] = `var(--tracking-${role})`;
+  }
+  return { fontSize, lineHeight, letterSpacing };
 }
 
 /**

package/pkgs/shadcn-snapshot/dist/manifest.json

@@ -460,6 +460,7 @@
     "group": "layout",
     "family": "Box",
     "source": "velloo",
+    "plainElement": true,
     "props": [
       {
         "name": "as",
@@ -7477,6 +7478,12 @@
         "optional": true,
         "control": "string"
       },
+      {
+        "name": "preserveAspectRatio",
+        "type": "string | undefined",
+        "optional": true,
+        "control": "string"
+      },
       {
         "name": "color",
         "type": "string | undefined",

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

@@ -1,11 +1,9 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/alert).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 const alertVariants = cva(

package/pkgs/shadcn-snapshot/src/components/ui/aspect-ratio.tsx

@@ -1,7 +1,6 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/aspect-ratio).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { AspectRatio as AspectRatioPrimitive } from "radix-ui";

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

@@ -1,13 +1,12 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/attachment).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Button } from "./button.tsx";
 
 const attachmentVariants = cva(

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

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/avatar).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { Avatar as AvatarPrimitive } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Avatar({

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

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/badge).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 const badgeVariants = cva(

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

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/breadcrumb).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { ChevronRightIcon, MoreHorizontalIcon } from "lucide-react";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {

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

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/bubble).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function BubbleGroup({ className, ...props }: React.ComponentProps<"div">) {

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

@@ -1,11 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/button-group).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Separator } from "./separator.tsx";
 
 const buttonGroupVariants = cva(

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

@@ -1,12 +1,10 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/button).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 
 import { cva, type VariantProps } from "class-variance-authority";
 import { Slot } from "radix-ui";
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 const buttonVariants = cva(

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

@@ -1,9 +1,7 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/card).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 import type * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
 
 function Card({

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

@@ -1,14 +1,13 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/carousel).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
 import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 import * as React from "react";
-
 import { cn } from "../../lib/utils.ts";
+
 import { Button } from "./button.tsx";
 
 type CarouselApi = UseEmblaCarouselType[1];

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

@@ -1,4 +1,4 @@
-// Velloo-flavored Chart. shadcn's `chart` is a recharts wrapper that needs a
+// Canvas-safe: Velloo-flavored Chart. shadcn's `chart` is a recharts wrapper that needs a
 // measured DOM (ResponsiveContainer), so it renders nothing under the
 // renderer's static SSR. We render a realistic preview server-side via
 // echarts' headless SSR-to-SVG mode (see chart-option.ts) — bar/line/area/

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

@@ -1,7 +1,6 @@
 // Vendored from shadcn-ui (https://ui.shadcn.com/docs/components/radix/direction).
-// 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.
+// Design-mode fork for the Velloo canvas — not the shadcn the IDE chrome renders.
+// Regenerate with `bun run vendor` — the pipeline is scripts/vendor-shadcn/.
 "use client";
 
 import { Direction } from "radix-ui";