velloo 0.0.0 → 0.2.0

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

@@ -0,0 +1,163 @@
+import { helperDescriptors } from "@velloo/helpers";
+import type { ComponentDescriptor, Manifest } from "@velloo/provider";
+import { REUSED_HELPER_IDS } from "./registry.ts";
+
+/**
+ * Manifest for the no-library provider. The six bare primitives are
+ * hand-authored (a dozen props, easier to maintain by hand than to wire a
+ * ts-morph pipeline for); the reused helpers (`Heading`, `Text`, `Icon`, …)
+ * come from `@velloo/helpers`' canonical descriptors so the props the
+ * inspector sees can't drift from the components the registry renders.
+ */
+const PRIMITIVE_DESCRIPTORS: ComponentDescriptor[] = [
+  {
+    id: "Box",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+  {
+    id: "Stack",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "direction",
+        type: '"row" | "col" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["row", "col"],
+        defaultValue: "col",
+      },
+      {
+        name: "gap",
+        type: "number | undefined",
+        optional: true,
+        control: "number",
+        defaultValue: "4",
+      },
+      {
+        name: "align",
+        type: '"start" | "center" | "end" | "stretch" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["start", "center", "end", "stretch"],
+      },
+      {
+        name: "justify",
+        type: '"start" | "center" | "end" | "between" | "around" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["start", "center", "end", "between", "around"],
+      },
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+  {
+    id: "Container",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "size",
+        type: '"sm" | "md" | "lg" | "xl" | "full" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["sm", "md", "lg", "xl", "full"],
+        defaultValue: "md",
+      },
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+  {
+    id: "Card",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+  {
+    id: "Button",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "variant",
+        type: '"default" | "ghost" | "outline" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["default", "ghost", "outline"],
+        defaultValue: "default",
+      },
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+  {
+    id: "Input",
+    category: "ui",
+    source: "velloo",
+    props: [
+      {
+        name: "placeholder",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+      {
+        name: "value",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+      {
+        name: "type",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+        defaultValue: "text",
+      },
+      {
+        name: "className",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+    ],
+  },
+] satisfies ComponentDescriptor[];
+
+export const NONE_MANIFEST: Manifest = [
+  ...PRIMITIVE_DESCRIPTORS,
+  // Reused velloo helpers — the same canonical descriptors the shadcn
+  // snapshot's generated manifest carries (minus the build-time lucide
+  // name sampling for `Icon`).
+  ...helperDescriptors(REUSED_HELPER_IDS),
+];

package/pkgs/provider-none/src/registry-inline.ts

@@ -0,0 +1,36 @@
+import { helpersRegistry } from "@velloo/helpers";
+import type { ComponentRegistry } from "@velloo/provider";
+import { Box, Button, Card, Container, Heading, Input, Stack, Text } from "./components-inline.tsx";
+
+/**
+ * The no-library registry for a `none`-CSS folder (inline `style` channel). Same
+ * shape as the Tailwind `registry`, but the primitives + typography are the
+ * inline-styled variants so they paint with the JIT off. The remaining helpers
+ * are structural (an SVG, an image, a gradient layer) — they carry no Tailwind
+ * visual defaults that the inline channel would lose — so they're reused
+ * verbatim from `@velloo/helpers`, same as the Tailwind registry. `Prose` joins
+ * them: its `typeset` class is velloo-owned CSS that `themeToCss` ships on every
+ * channel, not a Tailwind utility, so it needs no inline variant.
+ */
+const REUSED_HELPER_IDS = [
+  "Prose",
+  "Icon",
+  "SVG",
+  "Image",
+  "Layer",
+  "Divider",
+  "Gradient",
+  "Placeholder",
+];
+
+export const inlineRegistry: ComponentRegistry = {
+  Box,
+  Stack,
+  Container,
+  Card,
+  Button,
+  Input,
+  Heading,
+  Text,
+  ...helpersRegistry(REUSED_HELPER_IDS),
+};

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

@@ -0,0 +1,39 @@
+import { helpersRegistry } from "@velloo/helpers";
+import type { ComponentRegistry } from "@velloo/provider";
+import { Box, Button, Card, Container, Input, Stack } from "./components.tsx";
+
+/**
+ * Framework-neutral velloo helpers (no portals, no providers, no shadcn
+ * idioms) useful in no-lib designs. Reused verbatim from `@velloo/helpers`
+ * instead of forking — these helpers haven't needed to change in a year.
+ */
+export const REUSED_HELPER_IDS = [
+  "Heading",
+  "Text",
+  "Prose",
+  "Icon",
+  "SVG",
+  "Image",
+  "Layer",
+  "Divider",
+  "Gradient",
+  "Placeholder",
+] as const;
+
+/**
+ * The no-library provider's runtime registry. Five bare primitives
+ * (`Box`, `Stack`, `Container`, `Card`, `Button`, `Input`) plus the
+ * reusable velloo helpers from the shadcn snapshot. No `Avatar`,
+ * `Tabs`, `Dialog`, etc. — those would require either a real component
+ * library or a custom implementation; users in this mode either don't
+ * need them or write them as snippets.
+ */
+export const registry: ComponentRegistry = {
+  Box,
+  Stack,
+  Container,
+  Card,
+  Button,
+  Input,
+  ...helpersRegistry(REUSED_HELPER_IDS),
+};

package/pkgs/provider-none/src/tailwind-entry.css

@@ -0,0 +1,57 @@
+@import "tailwindcss";
+
+@source "./components.tsx";
+
+/*
+ * Same canvas-mode variant overrides as the shadcn snapshot — the
+ * canvas writes data-velloo-state on the selected node so the user can
+ * preview hover/focus/active without actually triggering the pseudo-class.
+ */
+@custom-variant hover (&:hover, &[data-velloo-state*="hover"]);
+@custom-variant focus (&:focus, &[data-velloo-state*="focus"]);
+@custom-variant focus-visible (&:focus-visible, &[data-velloo-state*="focus"]);
+@custom-variant active (&:active, &[data-velloo-state*="active"]);
+@custom-variant disabled (&:disabled, &[data-velloo-state*="disabled"]);
+
+/*
+ * Default token values. Designs override these via inline :root styles
+ * injected by @velloo/renderer at render time.
+ */
+@theme {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+
+  --color-card: oklch(1 0 0);
+  --color-card-foreground: oklch(0.145 0 0);
+
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+
+  --color-secondary: oklch(0.97 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+
+  --color-muted: oklch(0.97 0 0);
+  --color-muted-foreground: oklch(0.556 0 0);
+
+  --color-accent: oklch(0.97 0 0);
+  --color-accent-foreground: oklch(0.205 0 0);
+
+  --color-destructive: oklch(0.577 0.245 27.325);
+  --color-destructive-foreground: oklch(0.985 0 0);
+
+  --color-border: oklch(0.922 0 0);
+  --color-input: oklch(0.922 0 0);
+  --color-ring: oklch(0.708 0 0);
+
+  --radius: 0.5rem;
+
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, monospace;
+}
+
+html, body {
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-sans);
+  -webkit-font-smoothing: antialiased;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Version of the no-library primitive set. Bumped on breaking changes
+ * to the Box/Stack/Button surface (a renamed prop, a removed variant,
+ * a behavior change).
+ *
+ * Lives in its own module (exported as `@velloo/provider-none/version`) so
+ * version-only consumers — the CLI init wizard — don't pull the provider's
+ * registry into their import graph.
+ */
+export const noLibVersion = "0.1.0";

package/pkgs/schema/src/annotation.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { ResourceIdSchema } from "./ids.ts";
+
+/**
+ * Two annotation primitives, deliberately split:
+ *
+ *  - **CanvasNote**: markdown board markup, either free-positioned in board
+ *    coordinate space or attached to a node inside a frame. Lives per board
+ *    in `boards/<id>.notes.json`.
+ *
+ *  - **Annotation**: tied to a specific node in a Screen via `locator`.
+ *    The screen id is implied by the sidecar filename
+ *    (`screens/<screenId>.annotations.json`). Canvas draws a dashed
+ *    connector between the annotation pill and the targeted node's
+ *    bounding box across every Frame that shows that screen. Exposed
+ *    read-only to the agent so designer commentary flows into the agent's
+ *    context naturally.
+ *
+ * Both formats use markdown for `body` (a small subset: headers, bold,
+ * italic, line breaks, emoji as literal unicode). Stored verbatim;
+ * canvas renders, agent reads as-is.
+ */
+
+/**
+ * Locator value embedded in an annotation target. Mirrors the server's
+ * `Locator` union but the schema package can't depend on server code so
+ * the validation is repeated here.
+ */
+const AnnotationLocatorSchema = z.union([
+  z.array(z.number().int().nonnegative()),
+  z.string().regex(/^@[a-zA-Z][a-zA-Z0-9_-]*$/),
+]);
+
+export const AnnotationTargetSchema = z.object({
+  /** Path array or `"@id"` string identifying the anchored node within a screen tree. */
+  locator: AnnotationLocatorSchema,
+});
+export type AnnotationTarget = z.infer<typeof AnnotationTargetSchema>;
+
+const PositionSchema = z.union([z.object({ x: z.number(), y: z.number() }), z.literal("auto")]);
+
+export const AnnotationSchema = z.object({
+  id: ResourceIdSchema,
+  target: AnnotationTargetSchema,
+  /**
+   * Canvas placement. `"auto"` lets the canvas position it to the left of
+   * the anchored node's bounding box; an explicit `{x, y}` is set when the
+   * user drags the annotation to override.
+   */
+  position: PositionSchema.default("auto"),
+  /** Markdown body. */
+  body: z.string(),
+  /** Persisted collapsed state. Optional — undefined means "use canvas default". */
+  collapsed: z.boolean().optional(),
+  /**
+   * Who wrote it. Agents may create annotations (questions pinned to a
+   * node, review remarks) but may only edit/remove their own —
+   * user-authored annotations remain the protected designer→agent
+   * channel.
+   */
+  author: z.enum(["user", "agent"]),
+  /**
+   * Provenance for an annotation pulled from a velloo-cloud share-link
+   * comment (the `pull_comments` sync). `commentId` keys idempotent
+   * re-pulls — a cloud comment lands as at most one annotation, on any
+   * machine that syncs this folder. `slug` names the share link it came
+   * from; `author` is the commenter's display name. Locally authored
+   * annotations never carry this field.
+   */
+  cloud: z
+    .object({
+      commentId: z.string().min(1),
+      slug: z.string().min(1),
+      author: z.string().optional(),
+    })
+    .optional(),
+});
+export type Annotation = z.infer<typeof AnnotationSchema>;
+
+/**
+ * Anchors a note to a node inside a frame. The frame is named explicitly
+ * (a screen can be framed more than once on a board, and the note belongs
+ * to the one the author clicked) with `screenId` alongside it so the
+ * locator can be resolved without walking the board first.
+ */
+export const CanvasNoteAttachmentSchema = z.object({
+  frameId: ResourceIdSchema,
+  screenId: ResourceIdSchema,
+  locator: AnnotationLocatorSchema,
+});
+export type CanvasNoteAttachment = z.infer<typeof CanvasNoteAttachmentSchema>;
+
+export const CanvasNoteSchema = z
+  .object({
+    id: ResourceIdSchema,
+    /**
+     * Board-space placement. Required for a free note. An attached note
+     * omits it until the user drags the card, which pins it here — the same
+     * "auto until moved" rule as `Annotation.position`.
+     */
+    x: z.number().optional(),
+    y: z.number().optional(),
+    /**
+     * User-resizable width. Height is always derived from content (notes
+     * never scroll; the box expands downward).
+     */
+    width: z.number().positive(),
+    /** Markdown body. */
+    body: z.string(),
+    /** Present when the note is about a specific node rather than the board. */
+    attachment: CanvasNoteAttachmentSchema.optional(),
+  })
+  .refine(
+    (note) => note.attachment !== undefined || (note.x !== undefined && note.y !== undefined),
+    {
+      message: "A note without an attachment needs x and y",
+      path: ["x"],
+    },
+  );
+export type CanvasNote = z.infer<typeof CanvasNoteSchema>;

package/pkgs/schema/src/asset.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+/**
+ * Provenance for the assets `generate_asset` produced, stored in the design
+ * folder's `assets.json`.
+ *
+ * A generated image is the one asset a designer cannot re-derive by looking at
+ * it: the prompt that made it lives only in the agent transcript that ran the
+ * generation, so a week later nobody can nudge the image without starting over.
+ * Recording it next to the design turns every generated asset into something
+ * you can re-roll or rewrite from the canvas.
+ *
+ * Keyed by folder-relative asset path, so an image the canvas has selected
+ * (`/assets/hero.png` → `assets/hero.png`) is a direct lookup, and an asset
+ * that isn't in the map is simply one velloo didn't generate.
+ */
+export const GeneratedAssetSchema = z.object({
+  /** Verbatim prompt, so it can be edited and re-run. */
+  prompt: z.string(),
+  /**
+   * Intent name from the cloud catalogue ("photo", "illustration", …). This is
+   * as specific as provenance gets on purpose: which model serves an intent is
+   * the cloud's to change, so recording a model name here would bake a
+   * server-side detail into every design folder.
+   */
+  intent: z.string(),
+  /** Requested aspect; absent for intents whose output follows their input. */
+  aspect: z.string().optional(),
+  /** Pixel dimensions, when the result was a raster. */
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  /** ISO-8601, so the panel can say how old an image is. */
+  generatedAt: z.string(),
+  /** Reference assets the generation worked from (edit/cutout/upscale). */
+  reference: z.array(z.string()).optional(),
+  /**
+   * The asset this one was generated to replace. Set when a regenerate ran
+   * from the canvas, so the chain back to the original stays walkable after
+   * several re-rolls.
+   */
+  replaces: z.string().optional(),
+});
+export type GeneratedAsset = z.infer<typeof GeneratedAssetSchema>;
+
+export const AssetsFileSchema = z.object({
+  version: z.literal(1),
+  /** Keyed by folder-relative asset path, e.g. "assets/hero.png". */
+  generated: z.record(z.string(), GeneratedAssetSchema),
+});
+export type AssetsFile = z.infer<typeof AssetsFileSchema>;
+
+export const EMPTY_ASSETS_FILE: AssetsFile = { version: 1, generated: {} };
+
+/**
+ * Folder-relative asset path for a node's `src`, or null when the src points
+ * somewhere else (a remote URL, a host-app path). The canvas writes srcs as
+ * `/assets/<name>`; the store keys on `assets/<name>`.
+ */
+export function assetPathFromSrc(src: string): string | null {
+  if (typeof src !== "string" || src.length === 0) return null;
+  const trimmed = src.replace(/^\.?\//, "");
+  if (!trimmed.startsWith("assets/")) return null;
+  // A query/hash is a cache-buster, not part of the stored name.
+  const clean = trimmed.split(/[?#]/)[0] ?? "";
+  return clean.length > "assets/".length ? clean : null;
+}

package/pkgs/schema/src/board.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { FrameSchema } from "./frame.ts";
+import { ResourceIdSchema } from "./ids.ts";
+
+/**
+ * A colored, named container. Used at two levels, same shape both times:
+ * `config.boardGroups` holds the sidebar's groups of *boards* (an area of
+ * work — "Side pane", "Account page") and `Board.groups` holds a board's
+ * regions of *frames*. The member carries the group id (`Board.group`,
+ * `Frame.group`); the group itself only defines name + color.
+ */
+export const BoardGroupSchema = z.object({
+  id: ResourceIdSchema,
+  name: z.string().min(1),
+  /** CSS color value; canvas uses it for the group region tint and tag chip. */
+  color: z.string().optional(),
+});
+
+export type BoardGroup = z.infer<typeof BoardGroupSchema>;
+
+/**
+ * Cap on board names, enforced at the mutation boundary (add/update), not
+ * here in the on-disk schema — a pre-existing folder with a longer name
+ * must still load. Ids are safe regardless (slugify caps them at 48).
+ */
+export const MAX_BOARD_NAME_LENGTH = 80;
+
+/**
+ * A Board is one infinite canvas with its own collection of frames + groups.
+ * A design folder has many Boards (one per "flow" — onboarding, settings,
+ * pricing, etc.). Each Board persists as `boards/<id>.json`.
+ *
+ * Frames within a Board reference Screens by id. The same Screen can appear
+ * in multiple Boards (and multiple frames within a single Board); edits to
+ * the underlying screen propagate to every frame everywhere.
+ */
+export const BoardSchema = z.object({
+  id: ResourceIdSchema,
+  name: z.string().min(1),
+  /**
+   * Named theme (stem of `theme/<name>.json`) the canvas applies when
+   * rendering this board's frames. Absent = the folder default. Lets
+   * candidate boards carry their own palette/typography side by side —
+   * mirroring the per-screen `library` twin pattern.
+   */
+  theme: z.string().min(1).optional(),
+  /**
+   * ISO timestamp of when the board was archived. **Presence is the state** —
+   * there is no `archived: false` twin to contradict it. Archived boards drop
+   * out of the sidebar, `/api/design`, `list_boards`, and a default publish,
+   * but stay on disk untouched and fully editable; archive is not lock.
+   * Absent ⇒ active, so existing folders are unaffected.
+   */
+  archivedAt: z.string().datetime().optional(),
+  /**
+   * Id of the `config.boardGroups` entry this board is filed under — the
+   * sidebar section it appears in. Absent ⇒ Ungrouped, which is also every
+   * existing folder, so grouping is additive.
+   */
+  group: z.string().min(1).optional(),
+  frames: z.array(FrameSchema).default([]),
+  /** Frame regions within this board (see {@link BoardGroupSchema}). */
+  groups: z.array(BoardGroupSchema).default([]),
+});
+
+export type Board = z.infer<typeof BoardSchema>;
+
+/** Archived state is the presence of `archivedAt` — never a separate boolean. */
+export function isArchived(board: Pick<Board, "archivedAt">): boolean {
+  return board.archivedAt !== undefined;
+}

package/pkgs/schema/src/comment.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { ResourceIdSchema } from "./ids.ts";
+
+export const CommentLocatorSchema = z.union([
+  z.array(z.number().int().nonnegative()),
+  z.string().regex(/^@[a-zA-Z][a-zA-Z0-9_-]*$/),
+]);
+export type CommentLocator = z.infer<typeof CommentLocatorSchema>;
+
+export const CommentBoundsSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  w: z.number().nonnegative(),
+  h: z.number().nonnegative(),
+});
+export type CommentBounds = z.infer<typeof CommentBoundsSchema>;
+
+export const CommentNodeFingerprintSchema = z.object({
+  ref: z.string().min(1).optional(),
+  text: z.string().max(500).optional(),
+  ancestorIds: z.array(z.string().min(1)).max(16).optional(),
+});
+export type CommentNodeFingerprint = z.infer<typeof CommentNodeFingerprintSchema>;
+
+/**
+ * A comment anchor always names the board it was authored on. Node anchors
+ * additionally retain the exact frame + screen + locator and rendered bounds
+ * the author saw. The locator is authoritative only for the origin design
+ * state; bounds and fingerprint preserve honest context when it goes stale.
+ */
+export const CommentAnchorSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("node"),
+    boardId: ResourceIdSchema,
+    frameId: ResourceIdSchema,
+    screenId: ResourceIdSchema,
+    locator: CommentLocatorSchema,
+    bounds: CommentBoundsSchema,
+    fingerprint: CommentNodeFingerprintSchema.optional(),
+  }),
+  z.object({
+    kind: z.literal("board"),
+    boardId: ResourceIdSchema,
+    x: z.number(),
+    y: z.number(),
+  }),
+]);
+export type CommentAnchor = z.infer<typeof CommentAnchorSchema>;
+
+export const CommentAuthorSchema = z.object({
+  kind: z.enum(["user", "agent", "reviewer"]),
+  displayName: z.string().min(1).max(200).optional(),
+  accountId: z.string().min(1).max(200).optional(),
+});
+export type CommentAuthor = z.infer<typeof CommentAuthorSchema>;
+
+export const CommentMessageSchema = z
+  .object({
+    id: z.uuid(),
+    author: CommentAuthorSchema,
+    /** Empty only on a tombstone — taking a message back erases what it said. */
+    body: z.string().trim().max(4000),
+    createdAt: z.iso.datetime(),
+    /**
+     * When the author took this message back. The message stays in the thread
+     * so the conversation still reads in order and replies keep their
+     * antecedent; only the body goes.
+     */
+    deletedAt: z.iso.datetime().optional(),
+  })
+  .refine((message) => message.deletedAt !== undefined || message.body.length > 0, {
+    message: "A comment needs something to say",
+    path: ["body"],
+  });
+export type CommentMessage = z.infer<typeof CommentMessageSchema>;
+
+export const CommentOriginSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("local") }),
+  z.object({
+    kind: z.literal("published"),
+    slug: z.string().min(1),
+    versionId: z.string().min(1),
+  }),
+]);
+export type CommentOrigin = z.infer<typeof CommentOriginSchema>;
+
+export const CommentThreadSchema = z.object({
+  id: z.uuid(),
+  scope: z.enum(["local", "shared"]),
+  folderId: z.string().min(1),
+  boardId: ResourceIdSchema,
+  anchor: CommentAnchorSchema.optional(),
+  origin: CommentOriginSchema,
+  status: z.enum(["open", "resolved"]),
+  messages: z.array(CommentMessageSchema).min(1),
+  createdAt: z.iso.datetime(),
+  updatedAt: z.iso.datetime(),
+  resolvedAt: z.iso.datetime().optional(),
+});
+export type CommentThread = z.infer<typeof CommentThreadSchema>;
+
+export type CommentAnchorState =
+  | { status: "board" }
+  | { status: "attached"; resolvedPath: number[] }
+  | { status: "stale" };
+
+export type CommentThreadView = CommentThread & { anchorState: CommentAnchorState };