velloo 0.6.0 → 0.8.0

package/pkgs/schema/src/flow.ts

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

package/pkgs/schema/src/frame.ts

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

package/pkgs/schema/src/index.ts

@@ -53,6 +53,9 @@ export {
   HostAppSchema,
   type Library,
   LibrarySchema,
+  StylingSchema,
+  type ThemeSource,
+  ThemeSourceSchema,
   type ViewportPreset,
   ViewportPresetSchema,
 } from "./config.ts";
@@ -73,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,
@@ -94,11 +108,15 @@ export {
 } from "./migrate.ts";
 export {
   type ComponentNode,
+  type ComponentType,
+  type ComponentTypeRef,
   type EmitAsRef,
   isComponentNode,
+  isComponentType,
   isParamRef,
   isRepoNode,
   isSnippetInstance,
+  isTextNode,
   type Node,
   NodeIdSchema,
   NodeSchema,
@@ -110,11 +128,14 @@ export {
   repoImportIssue,
   repoKey,
   type SnippetInstance,
+  type TextNode,
 } from "./node.ts";
 export {
+  componentTypesIn,
   type EmitAsNode,
   isNode,
   isSyntheticRef,
+  mapComponentTypes,
   type NodeShape,
   nodeShape,
   PARAM_TAG_REF,
@@ -151,12 +172,15 @@ export {
   type ColorsOverride,
   ColorsSchema,
   type LooseTokenGroup,
+  namedPaletteRoles,
+  normalizeThemeName,
   resolveColors,
   spacingCssTokens,
   TAILWIND_SIZE_NAMES,
   type Theme,
   ThemeSchema,
   TypographySchema,
+  themeNameProblem,
 } from "./theme.ts";
 export {
   DEFAULT_TYPESET_NAME,

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

@@ -1,13 +1,17 @@
 import {
   type ComponentNode,
+  type ComponentTypeRef,
   type EmitAsRef,
   isComponentNode,
+  isComponentType,
   isParamRef,
   isSnippetInstance,
+  isTextNode,
   type Node,
   type ParamRef,
   type RepoComponentRef,
   type SnippetInstance,
+  type TextNode,
 } from "./node.ts";
 
 /**
@@ -46,7 +50,7 @@ export type EmitAsNode = ComponentNode & { $emitAs: EmitAsRef };
  * 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
+ * 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 =
@@ -56,6 +60,8 @@ export type NodeShape =
   | { 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 };
 
@@ -79,6 +85,7 @@ export function nodeShape(value: unknown): NodeShape {
     }
     return { kind: "named", node, ref: node.$ref };
   }
+  if (isTextNode(node)) return { kind: "text", node, text: node.$text };
   return { kind: "invalid", value };
 }
 
@@ -90,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

@@ -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-
@@ -116,18 +121,54 @@ export type ParamRef = {
   $param: string;
 };
 
-export type Node = ComponentNode | SnippetInstance | ParamRef;
+export type TextNode = {
+  $text: string;
+};
+
+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 } | 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"
+  );
 }
 
 /**
@@ -147,18 +188,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({
@@ -202,14 +241,56 @@ 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((items) => items.map(wrapScalarChild))
+      .transform(scalarChildren)
       .optional(),
     $emitAs: EmitAsSchema.optional(),
     $repo: RepoComponentRefSchema.optional(),
@@ -251,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(),
 });
@@ -267,10 +348,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
@@ -280,7 +365,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;
     }
@@ -292,12 +377,15 @@ 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)',
+        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;
     }
@@ -332,6 +420,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;
 }