velloo 0.2.0 → 0.3.1

package/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
 // @bun
-import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-4fj5tahv.js";import{TOOL_VERSION}from"./chunk-dg6z4vdd.js";import{maybeNotifyAboutUpdate}from"./chunk-xt5ayg7g.js";import{defineCommand,runMain}from"./chunk-2smsg2ct.js";var main=defineCommand({meta:{name:"velloo",version:TOOL_VERSION,description:"Open-source, local-first canvas for agent-driven design."},subCommands:COMMANDS});await runMain(main);var command=process.argv[2];if(!["mcp","__daemon","__update_check","run","upgrade"].includes(command??""))await maybeNotifyAboutUpdate();
+import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-9ydc34wc.js";import{TOOL_VERSION}from"./chunk-9psr8atb.js";import{maybeNotifyAboutUpdate}from"./chunk-9p1dk5cb.js";import{defineCommand,runMain}from"./chunk-2smsg2ct.js";var main=defineCommand({meta:{name:"velloo",version:TOOL_VERSION,description:"Open-source, local-first canvas for agent-driven design."},subCommands:COMMANDS});await runMain(main);var command=process.argv[2];if(!["mcp","__daemon","__update_check","run","upgrade"].includes(command??""))await maybeNotifyAboutUpdate();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velloo",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Local-first, code-shaped design canvas — your AI agent designs with your real components, in your repo",
   "license": "Apache-2.0",

package/pkgs/helpers/src/descriptors.ts

@@ -15,7 +15,13 @@ export const HELPER_DESCRIPTORS: readonly ComponentDescriptor[] = [
     group: "layout",
     family: "Box",
     source: "velloo",
-    props: [],
+    props: [
+      // Undiscoverable before this: an agent reproducing inline markup
+      // concluded Box could only be a div and reached for classes instead.
+      { name: "as", type: "string", optional: true, control: "string" },
+    ],
+    designModeNotes:
+      'A plain div by default; `as` renders a lowercase HTML tag instead — "span" for an inline run inside a sentence, "ul"/"li", "section". Anything else falls back to div.',
     example: { className: "flex flex-col gap-6 px-8 py-12" },
   },
   {

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

@@ -63,6 +63,7 @@ export function createProvider(): FrameworkAdapter {
       factory: null,
       defaultPath: "antd-theme.ts",
     },
+    ownedModules: { packages: ["antd"] },
     // canvasBundleSpec is deliberately absent in v1: the server's bundle-entry
     // builder only implements the emotion style runtime, so antd folders render
     // via the in-process cssinjs SSR path. Extending it means a new

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

@@ -63,6 +63,7 @@ export function createProvider(): FrameworkAdapter {
       factory: "extendTheme",
       defaultPath: "chakra-theme.ts",
     },
+    ownedModules: { packages: ["@chakra-ui/react"] },
     // canvasBundleSpec is deliberately absent in v1: the server's bundle-entry
     // builder implements only the MUI-shaped emotion style runtime (its entry
     // template expects `ThemeProvider` + `createTheme` from `stylesModule`);

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

@@ -66,6 +66,7 @@ export function createProvider(): FrameworkAdapter {
       factory: "createTheme",
       defaultPath: "theme.ts",
     },
+    ownedModules: { packages: ["@mui/material"] },
     canvasBundleSpec: {
       components: (ids) =>
         ids.flatMap((id): CanvasComponentSpec[] => {

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

@@ -1,12 +1,22 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { type FrameworkAdapter, type Manifest, TAILWIND_CLASSNAME } from "@velloo/provider";
+import { helperSourcePath } from "@velloo/helpers/paths";
+import {
+  type CanvasComponentSpec,
+  type FrameworkAdapter,
+  type Manifest,
+  TAILWIND_CLASSNAME,
+} from "@velloo/provider";
 import { resolveProviderSrcDir } from "@velloo/provider/src-dir";
 import { NONE_INLINE_INTRO, NONE_INTRO } from "./intro.ts";
 import { NONE_MANIFEST } from "./manifest.ts";
 import { registry } from "./registry.ts";
 import { inlineRegistry } from "./registry-inline.ts";
 
+const PRIMITIVES = new Set(["Box", "Stack", "Container", "Card", "Button", "Input"]);
+/** Typography the inline channel restyles; the Tailwind channel reuses the helpers. */
+const INLINE_TYPOGRAPHY = new Set(["Heading", "Text"]);
+
 export { Box, Button, Card, Container, Input, Stack } from "./components.tsx";
 export { NONE_MANIFEST } from "./manifest.ts";
 export { registry } from "./registry.ts";
@@ -53,5 +63,36 @@ export function createProvider(): FrameworkAdapter {
     // Inline-styled primitives for the `style` channel; Tailwind-classed for
     // every other channel. Lets a `none/none` folder paint with the JIT off.
     registryForChannel: (kind) => (kind === "style" ? inlineRegistry : registry),
+    // No framework to install, so this only matters beside repository
+    // components: the screen then client-mounts, and these primitives have to
+    // render in the same browser tree as the app's own components.
+    canvasBundleSpec: {
+      styleRuntime: { kind: "none" },
+      onlyWithRepository: true,
+      components: (ids, context) => {
+        const inline = context?.channel === "style";
+        return ids.flatMap((id): CanvasComponentSpec[] => {
+          const own =
+            PRIMITIVES.has(id) || (inline && INLINE_TYPOGRAPHY.has(id))
+              ? join(srcDir, inline ? "components-inline.tsx" : "components.tsx")
+              : helperSourcePath(id);
+          return own
+            ? [
+                {
+                  id,
+                  sources: [
+                    {
+                      importPath: own,
+                      exportName: id,
+                      fidelity: "exact" as const,
+                      note: "Velloo primitive, mounted beside the app's components.",
+                    },
+                  ],
+                },
+              ]
+            : [];
+        });
+      },
+    },
   };
 }

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

@@ -6,12 +6,12 @@
  * vocabulary positively rather than correcting a shadcn claim.
  */
 export const NONE_INTRO: readonly string[] = [
-  "**This folder has no component library** — only bare primitives wrapping plain HTML: `Box`/`Stack`/`Container` for layout, `Card`, `Button`, `Input`, plus the velloo helpers (`Heading`/`Text`, `Image`, `Gradient`, `Layer`, `SVG`, `Divider`, `Placeholder`, `Icon`). There is no `Badge`/`Avatar`/`Tabs`/`Dialog` — build those from primitives or define snippets. Call `list_components` for the exact set. Styling is **Tailwind classes**.",
+  "**This folder has no component library** — only bare primitives wrapping plain HTML: `Box`/`Stack`/`Container` for layout, `Card`, `Button`, `Input`, plus the velloo helpers (`Heading`/`Text`, `Image`, `Gradient`, `Layer`, `SVG`, `Divider`, `Placeholder`, `Icon`). The primitives stop there: for a `Badge`/`Tabs`/`Dialog`, use the app's own component when `list_components` shows one on a Repo shelf, else build it from primitives or a snippet. Call `list_components` for the exact set. Styling is **Tailwind classes**.",
   "",
 ];
 
 export const NONE_INLINE_INTRO: readonly string[] = [
-  "**This folder has no component library and no CSS framework** — bare primitives wrapping plain HTML (`Box`/`Stack`/`Container`, `Card`, `Button`, `Input`) plus the velloo helpers (`Heading`/`Text`, `Image`, `Icon`, `SVG`, `Divider`, `Gradient`, `Layer`, `Placeholder`). There is no `Badge`/`Avatar`/`Tabs`/`Dialog` — build those from primitives or snippets. Call `list_components` for the exact set.",
+  "**This folder has no component library and no CSS framework** — bare primitives wrapping plain HTML (`Box`/`Stack`/`Container`, `Card`, `Button`, `Input`) plus the velloo helpers (`Heading`/`Text`, `Image`, `Icon`, `SVG`, `Divider`, `Gradient`, `Layer`, `Placeholder`). The primitives stop there: for a `Badge`/`Tabs`/`Dialog`, use the app's own component when `list_components` shows one on a Repo shelf, else build it from primitives or a snippet. Call `list_components` for the exact set.",
   "",
   '**Style through inline `style` objects.** `update_props { style: { display: "flex", gap: "16px", padding: "24px", borderRadius: "8px", color: "var(--color-foreground)" } }` — a plain React style object (merges shallowly; an inner `null` drops a key, `style: null` clears). Reference theme tokens as CSS variables (`var(--color-primary)`, `var(--radius)`) from `get_theme` so the design stays themable. `emit_code` emits `style={{…}}` on plain elements — no imports, no Tailwind. Tailwind utility diagnostics do not apply.',
   "",

package/pkgs/schema/src/config.ts

@@ -65,6 +65,25 @@ export type CodegenConfig = z.infer<typeof CodegenConfigSchema>;
 export const HostAppSchema = z.object({
   root: z.string().min(1),
   aliases: z.record(z.string().min(1), z.string().min(1)).optional(),
+  /**
+   * The app's preview entry: a module whose default export wraps mounted
+   * repository components in the context they need (providers, global CSS).
+   * Resolved from the design folder root. Absent ⇒ `preview.{tsx,jsx,ts,js}`
+   * in the design folder (`preview.<appKey>.*` for a named host app), then a
+   * built-in framework recipe, then no wrapper.
+   */
+  preview: z.string().min(1).optional(),
+  /**
+   * Bounds repository-component discovery beyond what the app's entries and
+   * routes import: `include` adds component roots (files or directories,
+   * host-root relative), `exclude` drops matching specifiers or paths.
+   */
+  components: z
+    .object({
+      include: z.array(z.string().min(1)).optional(),
+      exclude: z.array(z.string().min(1)).optional(),
+    })
+    .optional(),
 });
 
 export type HostApp = z.infer<typeof HostAppSchema>;

package/pkgs/schema/src/extension.ts

@@ -103,3 +103,29 @@ export const ExtensionSchema = z.object({
 });
 
 export type Extension = z.infer<typeof ExtensionSchema>;
+
+/**
+ * `repo-components.json` in a design folder: checked-in corrections to what
+ * repository-component discovery infers. Keyed `<importPath>#<export>` (or
+ * `…#<export>.<Member>` for a compound part). Overrides refine the inferred
+ * entry; they never replace discovery, and a key or prop that no longer
+ * matches anything discovered is reported as stale.
+ */
+export const RepoComponentOverrideSchema = z.object({
+  description: z.string().optional(),
+  /** Leave this component out of the catalog. */
+  exclude: z.boolean().optional(),
+  /** Snippet drawn in the component's place when it can't render for real. */
+  proxy: z.string().min(1).optional(),
+  /** Replaces or adds prop descriptors by name. */
+  props: z.array(ExtensionPropDescriptorSchema).optional(),
+  /** Named preview states: state name → props. */
+  states: z.record(z.string().min(1), z.record(z.string(), z.unknown())).optional(),
+});
+
+export const RepoComponentsManifestSchema = z.object({
+  components: z.record(z.string().min(1), RepoComponentOverrideSchema),
+});
+
+export type RepoComponentOverride = z.infer<typeof RepoComponentOverrideSchema>;
+export type RepoComponentsManifest = z.infer<typeof RepoComponentsManifestSchema>;

package/pkgs/schema/src/index.ts

@@ -66,6 +66,10 @@ export {
   type ExtensionPropDescriptor,
   ExtensionPropDescriptorSchema,
   ExtensionSchema,
+  type RepoComponentOverride,
+  RepoComponentOverrideSchema,
+  type RepoComponentsManifest,
+  RepoComponentsManifestSchema,
 } from "./extension.ts";
 export {
   type Frame,
@@ -90,12 +94,18 @@ export {
   type ComponentNode,
   isComponentNode,
   isParamRef,
+  isRepoNode,
   isSnippetInstance,
   type Node,
   NodeIdSchema,
   NodeSchema,
   nodeId,
   type ParamRef,
+  parseRepoKey,
+  type RepoComponentRef,
+  RepoComponentRefSchema,
+  repoImportIssue,
+  repoKey,
   type SnippetInstance,
 } from "./node.ts";
 export {

package/pkgs/schema/src/node.ts

@@ -47,6 +47,37 @@ export type ComponentNode = {
    * capture → design → emit. Absent ⇒ the node emits as itself.
    */
   $emitAs?: { name: string; importPath: string } | 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.
+   */
+  $repo?: RepoComponentRef | undefined;
+};
+
+/**
+ * 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
+ * never persisted.
+ */
+export type RepoComponentRef = {
+  /**
+   * Module specifier. Bare (`@mantine/core`) and aliased (`@/components/card`)
+   * specifiers are kept as the app writes them; a `./`-relative one is relative
+   * to the host app root, since the importing file varies per call site.
+   */
+  importPath: string;
+  /** The export binding, or `"default"` for a default export. */
+  exportName: string;
+  /** Static member path of a compound part: `"List"` for `Tabs.List`. */
+  member?: string | undefined;
+  /** `config.hostApps` key in a monorepo; absent ⇒ the default host app. */
+  app?: string | undefined;
+  /** Snippet id drawn in the component's place when it can't render for real. */
+  proxy?: string | undefined;
 };
 
 export type SnippetInstance = {
@@ -126,6 +157,42 @@ const EmitAsSchema = z.object({
   importPath: z.string().min(1),
 });
 
+/**
+ * A specifier codegen may print verbatim inside `import … from "…"` and the
+ * bundler may resolve against the host app. Conservative charset (no quotes,
+ * spaces, semicolons), and no absolute or `..` paths: a design folder is data a
+ * cloned repo supplies, and it must not be able to reach outside the app.
+ */
+export function repoImportIssue(importPath: string): string | null {
+  if (!/^[\w@./~-]+$/.test(importPath)) return "has characters an import specifier can't carry";
+  if (importPath.startsWith("/")) return "must not be an absolute path";
+  if (importPath.split("/").includes("..")) return "must not climb out of the host app with ..";
+  return null;
+}
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+export const RepoComponentRefSchema = z.object({
+  importPath: z
+    .string()
+    .min(1)
+    .superRefine((value, ctx) => {
+      const issue = repoImportIssue(value);
+      if (issue) ctx.addIssue({ code: "custom", message: `importPath ${issue}` });
+    }),
+  exportName: z
+    .string()
+    .regex(IDENTIFIER, { message: 'exportName must be an identifier or "default"' }),
+  member: z
+    .string()
+    .regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/, {
+      message: 'member must be a dotted identifier path like "List"',
+    })
+    .optional(),
+  app: z.string().min(1).optional(),
+  proxy: z.string().min(1).optional(),
+});
+
 const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
   z.object({
     $ref: z.string().min(1),
@@ -136,9 +203,41 @@ const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
       .transform((items) => items.map(wrapScalarChild))
       .optional(),
     $emitAs: EmitAsSchema.optional(),
+    $repo: RepoComponentRefSchema.optional(),
   }),
 );
 
+/** True when the node is a repository component (see ComponentNode.$repo). */
+export function isRepoNode(n: Node): n is ComponentNode & { $repo: RepoComponentRef } {
+  return isComponentNode(n) && n.$repo !== undefined;
+}
+
+/**
+ * The runtime key a repository component registers under — identity only, so
+ * two apps' `Button`s (or Mantine's vs the provider's) never collide.
+ */
+export function repoKey(ref: RepoComponentRef): string {
+  const member = ref.member ? `.${ref.member}` : "";
+  return `repo:${encodeURIComponent(ref.app ?? "")}:${ref.importPath}#${ref.exportName}${member}`;
+}
+
+/**
+ * Invert {@link repoKey}. A bundle URL carries only keys, so the runtime can
+ * resolve a screen's components from identity alone — no catalog lookup, which
+ * keeps a design renderable while discovery is cold or the app has moved on.
+ */
+export function parseRepoKey(key: string): RepoComponentRef | null {
+  const match = /^repo:([^:]*):([^#]+)#([A-Za-z_$][\w$]*)(?:\.(.+))?$/.exec(key);
+  if (!match) return null;
+  const parsed = RepoComponentRefSchema.safeParse({
+    importPath: match[2],
+    exportName: match[3],
+    ...(match[4] ? { member: match[4] } : {}),
+    ...(match[1] ? { app: decodeURIComponent(match[1]) } : {}),
+  });
+  return parsed.success ? parsed.data : null;
+}
+
 const SnippetInstanceSchema: z.ZodType<SnippetInstance> = z.object({
   $snippet: z.string().min(1),
   $id: NodeIdSchema.optional(),

package/pkgs/schema/src/screen.ts

@@ -24,6 +24,13 @@ export const ScreenSchema = z.object({
    * components and extensions resolve against this library's registry.
    */
   library: z.string().min(1).optional(),
+  /**
+   * The app route this screen stands for ("/", "/settings/account"). Set by
+   * the route scan `init` runs, and editable per screen. The canvas mount
+   * hands it to the host framework's router contexts, so a repository nav
+   * lights the item the real page would.
+   */
+  route: z.string().min(1).optional(),
   tree: NodeSchema,
 });
 

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

@@ -460,7 +460,15 @@
     "group": "layout",
     "family": "Box",
     "source": "velloo",
-    "props": [],
+    "props": [
+      {
+        "name": "as",
+        "type": "string",
+        "optional": true,
+        "control": "string"
+      }
+    ],
+    "designModeNotes": "A plain div by default; `as` renders a lowercase HTML tag instead — \"span\" for an inline run inside a sentence, \"ul\"/\"li\", \"section\". Anything else falls back to div.",
     "example": {
       "className": "flex flex-col gap-6 px-8 py-12"
     }

package/skills/velloo-setup/SKILL.md

@@ -11,18 +11,41 @@ description: >-
 
 # Calibrating Velloo to an existing app
 
-For shadcn folders, the canvas can import client-safe components directly from
-the app's configured `components/ui` directory. That is a bounded capability,
-not a promise that arbitrary application React can run inside a design iframe:
-portal/state-heavy families use named canvas-safe adaptations, and a missing or
-unbuildable file falls back independently. Other providers follow their own
-adapter contract. The fidelity is observable through `component_status`; never
-infer it from `installedInApp` or from a component merely appearing on screen.
+The canvas renders the app's own components — whatever library they come from
+(Mantine, a private design system, a hand-rolled `components/` directory) —
+as real, nested, editable nodes. `list_components` lists them on **Repo**
+shelves, found from what the app's routes actually render. For shadcn folders
+the configured `components/ui` files additionally back the library itself.
+None of that is a promise that arbitrary application React runs inside a
+design iframe: the components need the context the app gives them (providers,
+global CSS), portal-heavy families use adaptations, and a component that can't
+build or render falls back on its own. Fidelity is observable through
+`component_status`; never infer it from a component merely appearing on screen.
 
 Your job here is to close that gap **before** you start designing, and to say
 honestly what's left open. Do this once per design folder. Skip it only for a
 greenfield folder with no app to match.
 
+## 0. The preview entry — when the app has components
+
+Call `preview_status` first. It reports `state` (`absent` / `valid` /
+`failing`), the providers and stylesheets the app's own entry uses
+(`appWrappers`, `appStylesheets`), and mounts one real component to prove the
+setup works — a missing provider or an unstyled render shows up here, not
+halfway through a design.
+
+- **`valid` with a recipe** (Mantine and friends): a built-in wrapper is doing
+  the work, themed from Velloo's tokens. Good enough to design with; write your
+  own entry only when the app's theme, router or data providers matter.
+- **`absent` / `failing`**: adapt `suggestedPreviewEntry` — it is lifted from
+  the app's entry — and call `set_preview_entry { source }`. Keep the app's
+  global CSS imports, swap network-backed providers for fixtures (a
+  `QueryClient` with seeded data, a memory router), never pass credentials. The
+  tool re-probes and answers with the new state; iterate until `valid`.
+
+A snippet can't do this job: it is node data, so it can't import CSS, build a
+router or wrap the whole screen. Snippets are for step 4 below.
+
 ## 1. Theme first — it buys the most
 
 `import_theme { cssPath, apply: true }` against the app's stylesheet. This is
@@ -78,26 +101,28 @@ live data legitimately differ.
 
 Only after theme parity, call `component_status { screen: "<id>" }` for each
 screen you're about to design or verify (or `{ ids: [...] }` before a screen
-exists). Check `mounted` first: the mount is all-or-nothing, so a single
-`unavailable` component keeps the whole screen — and every screenshot and
-`compare_to_url` of it — on Velloo's bundled components, whatever the other
-statuses say. Fix or replace the blocking component before trusting any
-`exact`. Treat the statuses as part of the design brief:
-
-- **`exact`** — Velloo compile-checked and selected the app's source file for
-  the whole-screen canvas mount. Custom CVA variants and ordinary explicit
-  props are also reflected into discovery when their syntax is recognizable.
-- **`adapted`** — the real family depends on portals, runtime state, browser
-  layout, or another interaction that conflicts with a static selectable
-  canvas. Velloo deliberately renders a canvas-safe counterpart. Preserve the
-  component identity and props, but do not claim pixel-identical behavior.
-- **`fallback`** — the app file is absent or failed the browser preflight, so a
-  bundled provider component or Velloo helper is rendering. Read the returned
-  note/errors before deciding whether the visual difference matters.
-- **`unavailable`** — there is no usable canvas source, so a screen using it
-  does not mount at all (`mounted: false`); read its errors — a resolution
-  failure usually means the recorded app root is wrong
-  (`velloo design set-app-root`).
+exists — repo catalog ids work too). For library components, check `mounted`
+first: that mount is all-or-nothing, so a single `unavailable` library
+component keeps the whole screen on Velloo's bundled components. A screen with
+the app's own components always mounts, and each of those falls back alone.
+Treat the statuses as part of the design brief:
+
+- **`exact`** — the app's own source (or package export) renders in the canvas
+  mount. Custom CVA variants and ordinary explicit props are also reflected
+  into discovery when their syntax is recognizable.
+- **`adapted`** — the real component renders through a design-time wrapper
+  (an overlay kept inside the frame, focus trapping off). Preserve its identity
+  and props, but do not claim pixel-identical behavior.
+- **`unstyled`** — it rendered, but its stylesheet never loaded: import the
+  library's CSS in the preview entry.
+- **`fallback`** — a bundled provider component or Velloo helper is rendering
+  instead of the app's file. Read the returned note/errors.
+- **`proxy`** — the app's component can't render here, and the node's proxy
+  snippet stands in for it; emitted code still imports the real one.
+- **`unavailable`** — nothing renders it; read its `code` and `remedy`
+  (`missing-provider`, `resolve-failed`, `compile-failed`, `server-only`,
+  `render-threw`, `missing-export`). A resolution failure usually means the
+  recorded app root is wrong (`velloo design set-app-root`).
 
 Host-source edits invalidate the canvas bundle automatically. After changing a
 component, wait for the frame to reload and call `component_status` again; do
@@ -106,25 +131,22 @@ not restart the daemon merely to pick up a normal source edit.
 ## 4. Close only the important remaining gaps
 
 If an on-screen component is not `exact` and the difference is load-bearing,
-read its source and choose the smallest honest adaptation:
-
-- **A snippet** (`add_snippet`) that composes library primitives to match the
-  component's appearance. It stays editable on the canvas and is the preferred
-  answer for a bespoke compound component that is outside the shadcn library.
-  Library compound components whose files are `exact` already preserve their
-  children in the whole-screen mount and do not need a snippet. `render_snippet`
-  immediately after defining one.
-- **`$emitAs { name, importPath }`** on the node when the preview can be an
-  approximation but the generated code must import the real component. Design
-  with primitives, emit `<DataTable />`. Use this for anything whose appearance
-  you cannot reasonably rebuild but whose identity in the code matters.
-- **A live extension** (`add_extension` with `render: "live"`) only for the
-  genuinely dynamic minority — charts above all. It bundles the real host file
-  and client-mounts it, so it is the one path that renders the user's actual
-  code. Know its limits before reaching for it: children are stripped, the
-  mount is visual-only, and it breaks whenever the host file doesn't compile.
-  Never the default for library components, and never use it to work around a
-  compound component with children.
+choose the smallest honest adaptation:
+
+- **Fix the context** first: most `unavailable` app components are missing a
+  provider or fixture the preview entry can supply.
+- **A proxy snippet** for a component that genuinely can't render in a static
+  canvas (it needs live data, a server, a browser API). `add_snippet` composing
+  primitives to match its appearance, then point the node at it — `update_props`
+  can't set identity, so place it with `add_node { repo: { importPath,
+  exportName }, … }` and a `proxy`, or record `"proxy": "<snippet-id>"` for it in
+  the design folder's `repo-components.json`. The snippet draws on the canvas;
+  `emit_code` still imports the real component with the design's props.
+- **A snippet** (`add_snippet`) for a composition that isn't a component in the
+  app at all. `render_snippet` immediately after defining one.
+- **A live extension** (`add_extension` with `render: "live"`) only for a
+  dynamic leaf the preview entry can't make render as a normal node. Its
+  children are stripped and the mount is visual-only.
 
 Do not replace an `adapted` overlay merely because its status is not `exact`;
 the adaptation is what keeps dialogs, menus, popovers, and similar components
@@ -138,8 +160,8 @@ session — and the user — knows where things stand. Three headings, honest:
 
 - **Exact** — theme imported from `<path>`, fonts, and the components reported
   `exact` by `component_status`.
-- **Adapted / fallback** — the status, reason, and any snippet / `$emitAs` / live
-  decision made to close a load-bearing difference.
+- **Adapted / fallback / proxy** — the status, reason, and any preview-entry,
+  proxy-snippet or live decision made to close a load-bearing difference.
 - **Unverified** — screens behind auth you couldn't reach, pages whose dev
   server wouldn't start, tokens the stylesheet didn't declare.