velloo 0.5.0 → 0.6.0

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

@@ -36,6 +36,7 @@ import {
 import { Drawer, Dropdown, Modal, Popover, Tooltip } from "./overlays.ts";
 
 const REUSED_HELPER_IDS = [
+  "Box",
   "Icon",
   "Image",
   "Placeholder",
@@ -49,8 +50,9 @@ const REUSED_HELPER_IDS = [
  * The runtime registry for antd-native folders: design `$ref` ids → real antd
  * components, SSR'd in-process via the adapter's cssinjs render pass. Dotted
  * antd subcomponents get manifest-friendly flat ids (`Typography.Title` ⇒
- * `TypographyTitle`, `List.Item` ⇒ `ListItem`) — the MCP intro tells the agent
- * how those destructure in emitted code. The overlay surface
+ * `TypographyTitle`, `List.Item` ⇒ `ListItem`) because neither a manifest id nor
+ * a `$ref` can carry a dot; the manifest records the dotted export as
+ * `nativeExport`, so emitted code names it directly. The overlay surface
  * (Modal/Drawer/Popover/Tooltip/Dropdown) is canvas-safe-wrapped in
  * `overlays.ts` — antd's own overlays portal and render NOTHING in SSR, so the
  * shims render them open + inline instead.
@@ -97,8 +99,9 @@ export const registry: ComponentRegistry = {
   TypographyText: Typography.Text,
   TypographyTitle: Typography.Title,
   // Framework-neutral velloo helpers antd has no equivalent for — chiefly
-  // `Icon` (lucide; @ant-design/icons isn't surfaced) + imagery/composition
-  // helpers. Reused verbatim from `@velloo/helpers`, like provider-mui. They
-  // size via props (`Icon size`), not Tailwind — the JIT is off on an antd folder.
+  // `Icon` (lucide; @ant-design/icons isn't surfaced), `Box` (the plain element
+  // compose lowers `<div>` and stray text to) + imagery/composition helpers.
+  // Reused verbatim from `@velloo/helpers`, like provider-mui. They size via
+  // props (`Icon size`), not Tailwind — the JIT is off on an antd folder.
   ...helpersRegistry(REUSED_HELPER_IDS),
 };

package/pkgs/provider-antd/src/render-pass.ts

@@ -2,8 +2,9 @@ import { createCache, extractStyle, StyleProvider } from "@ant-design/cssinjs";
 import type { RenderPass } from "@velloo/provider";
 import type { Theme as VellooTheme } from "@velloo/schema";
 import { ConfigProvider } from "antd";
+import antdResetCss from "antd/dist/reset.css" with { type: "text" };
 import { createElement } from "react";
-import { antdThemeConfig } from "./theme.ts";
+import { antdDocumentCss, antdThemeConfig } from "./theme.ts";
 
 /**
  * A fresh cssinjs + antd render pass for one SSR. `wrap` nests the tree under
@@ -11,8 +12,12 @@ import { antdThemeConfig } from "./theme.ts";
  * projected velloo tokens (with `cssVar: true`, so `--ant-*` variables reach
  * inline styles); `css()` extracts the style rules the render registered in
  * the cache. The renderer injects that CSS into a `data-velloo-adapter`
- * <style>. Unlike emotion, cssinjs extraction reads the cache directly — the
- * rendered HTML isn't needed.
+ * <style>, led by antd's own `reset.css` — the global sheet every antd app
+ * imports, which makes boxes border-box and zeroes body and heading margins,
+ * so a sized container measures what it does in the app — and the document
+ * baseline (`antdDocumentCss`) that gives plain elements the theme's type
+ * and color. Unlike emotion, cssinjs extraction
+ * reads the cache directly — the rendered HTML isn't needed.
  *
  * SSR works in-process because antd is a velloo dependency, so it links the
  * shared monorepo React — no dual-React hazard.
@@ -29,7 +34,8 @@ export function makeRenderPass(theme: VellooTheme, dark = false): RenderPass {
       ),
     // `plain: true` returns bare CSS text; strip <style> wrappers defensively
     // anyway — the RenderPass contract returns CSS, not markup.
-    css: () => stripStyleTags(extractStyle(cache, { plain: true })),
+    css: () =>
+      `${antdResetCss}\n${antdDocumentCss(theme, dark)}\n${stripStyleTags(extractStyle(cache, { plain: true }))}`,
   };
 }
 

package/pkgs/provider-antd/src/reset-css.d.ts

@@ -0,0 +1,5 @@
+/** antd's global reset, imported as text so the render pass can inline it. */
+declare module "antd/dist/reset.css" {
+  const css: string;
+  export default css;
+}

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

@@ -3,6 +3,8 @@ import {
   type ColorPair,
   DEFAULT_TYPESET_NAME,
   resolveColors,
+  sanitizeCssTokenValue,
+  TYPESET_DEFAULT,
   typesetScale,
   type Theme as VellooTheme,
 } from "@velloo/schema";
@@ -18,7 +20,9 @@ import { formatRgb, parse } from "culori";
  * theme stays hex (and round-trips identically in codegen).
  */
 function antdColor(css: string): string {
-  const s = css.trim();
+  // Theme strings are free text from the design JSON and end up inside
+  // cssinjs rules, so nothing that could close a declaration gets through.
+  const s = sanitizeCssTokenValue(css);
   if (/^(#|rgb|hsl)/i.test(s)) return s;
   return formatRgb(parse(s)) ?? s;
 }
@@ -74,17 +78,27 @@ function antdTokens(theme: VellooTheme, dark: boolean): NonNullable<ThemeConfig[
  * antd has only five heading tokens (h1–h5), so the velloo `h6` rung has no
  * antd equivalent and is intentionally dropped here; `Prose` regions still get
  * it from the typeset CSS.
+ *
+ * Line heights are left to antd unless the typeset chose its own leading.
+ * antd derives each one from its font size (14px reads 1.5714), and an antd
+ * app that sets only sizes gets those; velloo's default leading is a
+ * long-form reading rhythm, not something the app asked for, so projecting
+ * it would put every component on a rhythm the app does not have. A leading
+ * the user changed is a decision, and it reaches every antd line height.
  */
 function antdTypography(theme: VellooTheme): NonNullable<ThemeConfig["token"]> {
   const typography = theme.typography;
-  const scale = typesetScale(typography.typesets?.[DEFAULT_TYPESET_NAME], {
+  const typeset = typography.typesets?.[DEFAULT_TYPESET_NAME];
+  const scale = typesetScale(typeset, {
     ...(typography.fontFamily ? { fontFamily: typography.fontFamily } : {}),
   });
+  const ownLeading = typeset?.leading !== undefined && typeset.leading !== TYPESET_DEFAULT.leading;
   return {
-    fontFamily:
+    fontFamily: sanitizeCssTokenValue(
       scale.body.fontFamily ??
-      typography.fontFamily?.sans ??
-      "system-ui, -apple-system, sans-serif",
+        typography.fontFamily?.sans ??
+        "system-ui, -apple-system, sans-serif",
+    ),
     fontSize: scale.body.fontSize,
     fontSizeSM: scale.caption.fontSize,
     fontSizeLG: scale.lead.fontSize,
@@ -93,12 +107,16 @@ function antdTypography(theme: VellooTheme): NonNullable<ThemeConfig["token"]> {
     fontSizeHeading3: scale.h3.fontSize,
     fontSizeHeading4: scale.h4.fontSize,
     fontSizeHeading5: scale.h5.fontSize,
-    lineHeight: scale.body.lineHeight,
-    lineHeightHeading1: scale.h1.lineHeight,
-    lineHeightHeading2: scale.h2.lineHeight,
-    lineHeightHeading3: scale.h3.lineHeight,
-    lineHeightHeading4: scale.h4.lineHeight,
-    lineHeightHeading5: scale.h5.lineHeight,
+    ...(ownLeading
+      ? {
+          lineHeight: scale.body.lineHeight,
+          lineHeightHeading1: scale.h1.lineHeight,
+          lineHeightHeading2: scale.h2.lineHeight,
+          lineHeightHeading3: scale.h3.lineHeight,
+          lineHeightHeading4: scale.h4.lineHeight,
+          lineHeightHeading5: scale.h5.lineHeight,
+        }
+      : {}),
   };
 }
 
@@ -116,6 +134,31 @@ export function antdThemeConfig(theme: VellooTheme, dark = false): ThemeConfig {
   };
 }
 
+/**
+ * The document rules an antd frame renders on, after antd's own `reset.css`
+ * (which a real antd app imports, and which sets box-sizing and margins but
+ * no type or color). antd v5 styles only its own components, so a plain
+ * element — a `Box`, a `Flex` container's own text — inherits from `<body>`,
+ * and the `style` channel skips the JIT that gives other providers a themed
+ * body. So `<body>` takes antd's resolved tokens for this theme, the values
+ * its components read, and the text between antd components matches them.
+ * The seed tokens are already sanitized, so they interpolate as-is.
+ */
+export function antdDocumentCss(theme: VellooTheme, dark = false): string {
+  const token = antdTheme.getDesignToken(antdThemeConfig(theme, dark));
+  return (
+    "html,body{" +
+    [
+      `background-color:${token.colorBgBase}`,
+      `color:${token.colorTextBase}`,
+      `font-family:${token.fontFamily}`,
+      `font-size:${token.fontSize}px`,
+      `line-height:${token.lineHeight}`,
+    ].join(";") +
+    "}"
+  );
+}
+
 /**
  * The codegen projection (`themeToNative`): the same token mapping, but the
  * algorithm emits as a bare identifier (`antdTheme.darkAlgorithm`) that the

package/pkgs/provider-chakra/src/manifest.ts

@@ -96,7 +96,11 @@ function helper(
 
 export const CHAKRA_MANIFEST: Manifest = [
   // --- layout ---
-  ui("Box", [children], "Generic layout primitive; style via sx."),
+  ui(
+    "Box",
+    [children, str("as")],
+    'Generic layout primitive; style via sx. `as` renders another HTML tag ("span", "section").',
+  ),
   ui(
     "Flex",
     [children, json("gap", "number | string"), str("align"), str("justify"), str("direction")],

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

@@ -82,8 +82,10 @@ export function createProvider(): FrameworkAdapter {
                       {
                         importPath: path,
                         exportName: id,
-                        fidelity: "fallback" as const,
-                        note: "Velloo helper used alongside the host framework.",
+                        // A helper is Velloo's own component, not a stand-in
+                        // for an MUI one: this file is its real render.
+                        fidelity: "exact" as const,
+                        note: "Velloo helper, mounted beside the host framework's components.",
                       },
                     ],
                   },

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

@@ -70,7 +70,16 @@ function helper(
 }
 
 export const MUI_MANIFEST: Manifest = [
-  ui("Box", [children], "Generic layout primitive; style via sx."),
+  ui(
+    "Box",
+    [
+      children,
+      // Compose writes `<span>` as `as="span"` on every library's element; MUI
+      // types and documents the override as `component`, so it emits as that.
+      { name: "as", type: "string", optional: true, control: "string", nativeName: "component" },
+    ],
+    'Generic layout primitive; style via sx. `as` renders another HTML tag ("span", "section") and emits as MUI\'s `component`.',
+  ),
   ui(
     "Stack",
     [children, enumProp("direction", ["row", "column"], "column")],

package/pkgs/provider-mui/src/render-pass.ts

@@ -1,6 +1,7 @@
 import createCache from "@emotion/cache";
 import { CacheProvider } from "@emotion/react";
 import createEmotionServer from "@emotion/server/create-instance";
+import CssBaseline from "@mui/material/CssBaseline";
 import { ThemeProvider } from "@mui/material/styles";
 import type { RenderPass } from "@velloo/provider";
 import type { Theme as VellooTheme } from "@velloo/schema";
@@ -13,6 +14,14 @@ import { muiThemeFrom } from "./theme.ts";
  * tokens; `css(html)` extracts exactly the emotion rules the rendered markup
  * uses. The renderer injects that CSS into a `data-velloo-adapter` <style>.
  *
+ * The tree renders beside a `CssBaseline`, as a real MUI app's root does: MUI
+ * styles only its own components, and the style channel skips the Tailwind
+ * JIT, so without it a plain element inherits a bare `<body>` (Times, 16px,
+ * black, an 8px margin). The baseline puts the theme's body1 type, text color
+ * and background on the body, from the same theme the components get, and
+ * `enableColorScheme` gives a dark frame dark native controls. Its rules are
+ * emotion globals, which `extractCriticalToChunks` always keeps.
+ *
  * SSR works in-process because @mui/material is a velloo dependency, so it links
  * the shared monorepo React — no dual-React hazard.
  */
@@ -25,7 +34,12 @@ export function makeRenderPass(theme: VellooTheme, dark = false): RenderPass {
       createElement(
         CacheProvider,
         { value: cache },
-        createElement(ThemeProvider, { theme: muiTheme }, element),
+        createElement(
+          ThemeProvider,
+          { theme: muiTheme },
+          createElement(CssBaseline, { enableColorScheme: true }),
+          element,
+        ),
       ),
     css: (html) =>
       server

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

@@ -3,6 +3,7 @@ import {
   type ColorPair,
   DEFAULT_TYPESET_NAME,
   resolveColors,
+  sanitizeCssTokenValue,
   typesetScale,
   type Theme as VellooTheme,
 } from "@velloo/schema";
@@ -16,7 +17,9 @@ import { formatRgb, parse } from "culori";
  * theme stays hex (and round-trips identically in codegen).
  */
 function muiColor(css: string): string {
-  const s = css.trim();
+  // Theme strings are free text from the design JSON and end up inside
+  // emotion rules, so nothing that could close a declaration gets through.
+  const s = sanitizeCssTokenValue(css);
   if (/^(#|rgb|hsl)/i.test(s)) return s;
   return formatRgb(parse(s)) ?? s;
 }
@@ -90,15 +93,18 @@ function muiTypography(theme: VellooTheme): NonNullable<ThemeOptions["typography
     ...(typography.fontFamily ? { fontFamily: typography.fontFamily } : {}),
   });
   // The body face, falling back to the `sans` role then the system stack.
-  const bodyFamily =
-    scale.body.fontFamily ?? typography.fontFamily?.sans ?? "system-ui, -apple-system, sans-serif";
+  const bodyFamily = sanitizeCssTokenValue(
+    scale.body.fontFamily ?? typography.fontFamily?.sans ?? "system-ui, -apple-system, sans-serif",
+  );
 
   const variant = (role: keyof typeof scale) => {
     const r = scale[role];
     return {
       // Only override the family when the typeset names a *different* face for
       // this role; otherwise inherit the theme's own fontFamily.
-      ...(r.fontFamily && r.fontFamily !== bodyFamily ? { fontFamily: r.fontFamily } : {}),
+      ...(r.fontFamily && sanitizeCssTokenValue(r.fontFamily) !== bodyFamily
+        ? { fontFamily: sanitizeCssTokenValue(r.fontFamily) }
+        : {}),
       fontSize: `${r.fontSize}px`,
       lineHeight: r.lineHeight,
       letterSpacing: r.letterSpacing,

package/pkgs/provider-none/src/components.tsx

@@ -1,3 +1,12 @@
+import {
+  BUTTON_BASE_CLASS,
+  BUTTON_VARIANT_CLASS,
+  CARD_CLASS,
+  CONTAINER_WIDTH_CLASS,
+  INPUT_CLASS,
+  STACK_ALIGN_CLASS,
+  STACK_JUSTIFY_CLASS,
+} from "@velloo/helpers";
 import { clsx } from "clsx";
 import * as React from "react";
 
@@ -38,20 +47,6 @@ export interface StackProps extends DivProps {
   justify?: "start" | "center" | "end" | "between" | "around";
 }
 
-const alignClass: Record<NonNullable<StackProps["align"]>, string> = {
-  start: "items-start",
-  center: "items-center",
-  end: "items-end",
-  stretch: "items-stretch",
-};
-const justifyClass: Record<NonNullable<StackProps["justify"]>, string> = {
-  start: "justify-start",
-  center: "justify-center",
-  end: "justify-end",
-  between: "justify-between",
-  around: "justify-around",
-};
-
 export const Stack = React.forwardRef<HTMLDivElement, StackProps>(
   ({ direction = "col", gap = 4, align, justify, className, ...rest }, ref) => (
     <div
@@ -60,8 +55,8 @@ export const Stack = React.forwardRef<HTMLDivElement, StackProps>(
         "flex",
         direction === "row" ? "flex-row" : "flex-col",
         `gap-${gap}`,
-        align ? alignClass[align] : undefined,
-        justify ? justifyClass[justify] : undefined,
+        align ? STACK_ALIGN_CLASS[align] : undefined,
+        justify ? STACK_JUSTIFY_CLASS[justify] : undefined,
         className,
       )}
       {...rest}
@@ -75,19 +70,11 @@ export interface ContainerProps extends DivProps {
   size?: "sm" | "md" | "lg" | "xl" | "full";
 }
 
-const containerWidth: Record<NonNullable<ContainerProps["size"]>, string> = {
-  sm: "max-w-screen-sm",
-  md: "max-w-screen-md",
-  lg: "max-w-screen-lg",
-  xl: "max-w-screen-xl",
-  full: "max-w-full",
-};
-
 export const Container = React.forwardRef<HTMLDivElement, ContainerProps>(
   ({ size = "md", className, ...rest }, ref) => (
     <div
       ref={ref}
-      className={clsx("mx-auto w-full px-4", containerWidth[size], className)}
+      className={clsx("mx-auto w-full px-4", CONTAINER_WIDTH_CLASS[size], className)}
       {...rest}
     />
   ),
@@ -98,23 +85,12 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
   variant?: "default" | "ghost" | "outline";
 }
 
-const buttonVariant: Record<NonNullable<ButtonProps["variant"]>, string> = {
-  default: "bg-foreground text-background hover:bg-foreground/90",
-  ghost: "bg-transparent text-foreground hover:bg-muted",
-  outline: "bg-transparent text-foreground border border-border hover:bg-muted",
-};
-
 export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
   ({ variant = "default", className, type, ...rest }, ref) => (
     <button
       ref={ref}
       type={type ?? "button"}
-      className={clsx(
-        "inline-flex items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium",
-        "focus-visible:outline-2 focus-visible:outline-offset-2",
-        buttonVariant[variant],
-        className,
-      )}
+      className={clsx(BUTTON_BASE_CLASS, BUTTON_VARIANT_CLASS[variant], className)}
       {...rest}
     />
   ),
@@ -136,11 +112,7 @@ export const Input = React.forwardRef<HTMLInputElement, InputProps>(
         value={value}
         onChange={onChange}
         readOnly={isStatic || rest.readOnly}
-        className={clsx(
-          "block w-full rounded-md border border-input bg-background px-3 py-2 text-sm",
-          "placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2",
-          className,
-        )}
+        className={clsx(INPUT_CLASS, className)}
         {...rest}
       />
     );
@@ -151,13 +123,6 @@ Input.displayName = "Input";
 export interface CardProps extends DivProps {}
 
 export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, ...rest }, ref) => (
-  <div
-    ref={ref}
-    className={clsx(
-      "rounded-lg border border-border bg-card p-6 text-card-foreground shadow-sm",
-      className,
-    )}
-    {...rest}
-  />
+  <div ref={ref} className={clsx(CARD_CLASS, className)} {...rest} />
 ));
 Card.displayName = "Card";

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

@@ -14,6 +14,7 @@ const PRIMITIVE_DESCRIPTORS: ComponentDescriptor[] = [
     id: "Box",
     category: "ui",
     source: "velloo",
+    plainElement: true,
     props: [
       { name: "as", type: "string", optional: true, control: "string" },
       {

package/pkgs/schema/src/annotation.ts

@@ -100,11 +100,14 @@ export const CanvasNoteSchema = z
      */
     x: z.number().optional(),
     y: z.number().optional(),
+    /** User-resizable width. */
+    width: z.number().positive(),
     /**
-     * User-resizable width. Height is always derived from content (notes
-     * never scroll; the box expands downward).
+     * The height the author drew or resized the note to. Absent, the note is
+     * exactly as tall as its text; set, it is this tall, and text that runs
+     * past it scrolls inside the note.
      */
-    width: z.number().positive(),
+    height: z.number().positive().optional(),
     /** Markdown body. */
     body: z.string(),
     /** Present when the note is about a specific node rather than the board. */

package/pkgs/schema/src/comment.ts

@@ -116,4 +116,13 @@ export type CommentAnchorState =
   | { status: "attached"; resolvedPath: number[] }
   | { status: "stale" };
 
-export type CommentThreadView = CommentThread & { anchorState: CommentAnchorState };
+export type CommentThreadView = CommentThread & {
+  anchorState: CommentAnchorState;
+  /**
+   * False when the viewer can read the thread but not resolve or delete it — a
+   * cloud thread on a link they no longer manage. Absent means they can.
+   */
+  manage?: false;
+  /** The git branch a cloud thread's link was last published from, where known. */
+  branch?: string;
+};

package/pkgs/schema/src/index.ts

@@ -94,6 +94,7 @@ export {
 } from "./migrate.ts";
 export {
   type ComponentNode,
+  type EmitAsRef,
   isComponentNode,
   isParamRef,
   isRepoNode,
@@ -110,6 +111,17 @@ export {
   repoKey,
   type SnippetInstance,
 } from "./node.ts";
+export {
+  type EmitAsNode,
+  isNode,
+  isSyntheticRef,
+  type NodeShape,
+  nodeShape,
+  PARAM_TAG_REF,
+  type RepoNode,
+  STATIC_REF,
+  type SyntheticRef,
+} from "./node-identity.ts";
 export {
   DesignNameSchema,
   designNameIssue,
@@ -176,7 +188,7 @@ export {
   typesetSizePx,
   typesetThemeTokens,
   typesetUtilityClasses,
-  typesetV3FontSize,
+  typesetV3Theme,
   typesetVars,
 } from "./typeset.ts";
 export { type DuplicateId, findDuplicateIds } from "./validate-ids.ts";

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

@@ -0,0 +1,92 @@
+import {
+  type ComponentNode,
+  type EmitAsRef,
+  isComponentNode,
+  isParamRef,
+  isSnippetInstance,
+  type Node,
+  type ParamRef,
+  type RepoComponentRef,
+  type SnippetInstance,
+} 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. 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 }
+  /** 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 };
+  }
+  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

@@ -46,18 +46,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

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),
 );