velloo 0.0.0 → 0.2.0

package/chunk-zb6hc1y0.js

@@ -0,0 +1,2 @@
+// @bun
+import{registry2,loadManifest2}from"./chunk-hcb68zt7.js";import"./chunk-jb21jkp1.js";import{snapshotVersion2,entryCssPath2,componentsDir2}from"./chunk-cvn689d5.js";export{componentsDir2 as componentsDir,entryCssPath2 as entryCssPath,loadManifest2 as loadManifest,registry2 as registry,snapshotVersion2 as snapshotVersion};

package/cli.js

@@ -0,0 +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();

package/launcher.cjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+
+const { existsSync, readFileSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function linuxLibc() {
+  if (process.platform !== "linux") return undefined;
+  try {
+    const report = process.report?.getReport();
+    if (report?.header?.glibcVersionRuntime) return "glibc";
+  } catch {}
+  try {
+    if (/musl/i.test(readFileSync("/usr/bin/ldd", "utf8"))) return "musl";
+  } catch {}
+  return "musl";
+}
+
+function runtimePackage() {
+  const arch = process.arch === "x64" ? "x64" : process.arch === "arm64" ? "arm64" : null;
+  if (!arch) return null;
+  if (process.platform === "darwin") {
+    return arch === "arm64" ? "@oven/bun-darwin-aarch64" : "@oven/bun-darwin-x64-baseline";
+  }
+  if (process.platform === "win32") {
+    return arch === "arm64" ? "@oven/bun-windows-aarch64" : "@oven/bun-windows-x64-baseline";
+  }
+  if (process.platform === "linux") {
+    const musl = linuxLibc() === "musl";
+    if (arch === "arm64") {
+      return musl ? "@oven/bun-linux-aarch64-musl" : "@oven/bun-linux-aarch64";
+    }
+    return musl ? "@oven/bun-linux-x64-musl-baseline" : "@oven/bun-linux-x64-baseline";
+  }
+  return null;
+}
+
+function die(message) {
+  process.stderr.write(`velloo: ${message}\n`);
+  process.exit(1);
+}
+
+// Windows cannot reliably replace an executable while that executable is
+// running. Handle the bare self-upgrade in the Node launcher before Bun starts;
+// folder migrations and `--check` still go through the normal CLI command.
+if (process.platform === "win32" && process.argv.length === 3 && process.argv[2] === "upgrade") {
+  const adjacentNpm = join(dirname(process.execPath), "npm.cmd");
+  const npm = existsSync(adjacentNpm) ? adjacentNpm : "npm.cmd";
+  const packageName = process.env.VELLOO_NPM_PACKAGE || "velloo";
+  const upgrade = spawnSync(npm, ["install", "-g", `${packageName}@latest`], { stdio: "inherit" });
+  if (upgrade.error) die(`could not start npm: ${upgrade.error.message}`);
+  if (upgrade.status !== 0) process.exit(upgrade.status == null ? 1 : upgrade.status);
+  // npm rewrote this launcher's package in place, so re-entering by the same
+  // path runs the NEW velloo — which is the one that must migrate the design
+  // folder, since only it knows the format it migrated towards.
+  const migrate = spawnSync(process.execPath, [__filename, "upgrade", "--design-only"], {
+    stdio: "inherit",
+  });
+  process.exit(migrate.status == null ? 1 : migrate.status);
+}
+
+const runtimeName = runtimePackage();
+if (!runtimeName) {
+  die(
+    `unsupported platform ${process.platform}/${process.arch}; supported platforms are macOS, Linux, and Windows on x64 or arm64`,
+  );
+}
+
+let runtimeRoot;
+try {
+  runtimeRoot = dirname(require.resolve(`${runtimeName}/package.json`));
+} catch {
+  die(
+    `the Bun runtime package ${runtimeName} is missing. Reinstall with \`npm install -g velloo@latest\` and make sure optional dependencies are enabled`,
+  );
+}
+
+const runtime = join(runtimeRoot, "bin", process.platform === "win32" ? "bun.exe" : "bun");
+if (!existsSync(runtime)) die(`the Bun runtime package ${runtimeName} is incomplete`);
+
+const app = join(__dirname, "cli.js");
+const child = spawnSync(runtime, [app, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    VELLOO_INSTALL_METHOD: process.env.VELLOO_INSTALL_METHOD || "npm",
+    VELLOO_NPM_PACKAGE: process.env.VELLOO_NPM_PACKAGE || "velloo",
+    VELLOO_NODE_EXECUTABLE: process.execPath,
+    // The install path is how a Homebrew-managed velloo is told apart from an
+    // npm one under a Homebrew-installed Node (both live under /opt/homebrew).
+    VELLOO_LAUNCHER_PATH: __filename,
+  },
+});
+
+if (child.error) die(`could not start the bundled Bun runtime: ${child.error.message}`);
+process.exit(child.status == null ? 1 : child.status);

package/package.json

@@ -1,11 +1,64 @@
 {
   "name": "velloo",
-  "version": "0.0.0",
-  "description": "Reserved.",
-  "license": "UNLICENSED",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Local-first, code-shaped design canvas — your AI agent designs with your real components, in your repo",
+  "license": "Apache-2.0",
+  "homepage": "https://velloo.design",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/velloo-dev/velloo.git"
+    "url": "git+https://github.com/velloo-design/velloo.git"
   },
-  "homepage": "https://velloo.dev"
+  "bugs": {
+    "url": "https://github.com/velloo-design/velloo/issues"
+  },
+  "keywords": [
+    "design",
+    "design-tool",
+    "canvas",
+    "mcp",
+    "ai-agent",
+    "claude-code",
+    "shadcn",
+    "tailwind",
+    "mui",
+    "local-first",
+    "bun"
+  ],
+  "bin": {
+    "velloo": "launcher.cjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "cli.js",
+    "launcher.cjs",
+    "chunk-*.js",
+    "assets",
+    "canvas",
+    "skills",
+    "plugins",
+    "pkgs",
+    "NOTICE",
+    "THIRD-PARTY-NOTICES.md",
+    "BUN-LICENSE.md"
+  ],
+  "dependencies": {
+    "@tailwindcss/node": "4.3.3",
+    "@tailwindcss/oxide": "4.3.3",
+    "playwright-core": "1.62.1",
+    "tailwindcss": "4.3.3",
+    "tw-animate-css": "1.4.0"
+  },
+  "optionalDependencies": {
+    "@oven/bun-darwin-aarch64": "1.4.2",
+    "@oven/bun-darwin-x64-baseline": "1.4.2",
+    "@oven/bun-linux-aarch64": "1.4.2",
+    "@oven/bun-linux-aarch64-musl": "1.4.2",
+    "@oven/bun-linux-x64-baseline": "1.4.2",
+    "@oven/bun-linux-x64-musl-baseline": "1.4.2",
+    "@oven/bun-windows-aarch64": "1.4.2",
+    "@oven/bun-windows-x64-baseline": "1.4.2"
+  }
 }

package/pkgs/helpers/src/box.tsx

@@ -0,0 +1,21 @@
+// Velloo-owned generic container. Designs are mostly layout: before Box
+// existed every flex/grid wrapper was a Card with its chrome reset
+// ("ring-0 shadow-none bg-transparent rounded-none p-0"), which bloated
+// trees and invited styling accidents (Card's overflow-hidden clipping
+// children). Box is a plain div: no chrome, no padding, no surprises —
+// className is the whole API. Codegen lowers it to `<as ?? div>`.
+
+import type * as React from "react";
+import { createElement } from "react";
+import { cn } from "./cn.ts";
+
+// Restrict `as` to a lowercase HTML tag name. Anything else (a component
+// reference, an injection attempt) falls back to div. Rendering the real tag
+// means inline elements (span/strong/a/…) get their natural inline display
+// from the UA stylesheet, instead of a div's block stacking inline runs.
+const TAG = /^[a-z][a-z0-9]*$/;
+
+export function Box({ as, className, ...props }: React.ComponentProps<"div"> & { as?: string }) {
+  const tag = typeof as === "string" && TAG.test(as) ? as : "div";
+  return createElement(tag, { "data-slot": "box", className: cn(className), ...props });
+}

package/pkgs/helpers/src/cn.ts

@@ -0,0 +1,32 @@
+import { TYPESET_SCALE_NAMES } from "@velloo/schema/typeset";
+import { type ClassValue, clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * The typeset ladder's utilities are theme-generated, so stock tailwind-merge
+ * has never heard of them: it would classify `text-h1` as a *color* (the
+ * `text-<color>` group) and `leading-h1` / `tracking-h1` as unknown. That
+ * misfiling both kept a component default alive next to an author's override
+ * (`<Heading className="text-sm">` still carried `text-h1`, and the larger one
+ * won) and dropped a size next to a tone (`text-body text-foreground`).
+ *
+ * Registering the role names in the right groups restores last-wins per group,
+ * which every helper relies on for `className` to be an override.
+ *
+ * Exported as the ONE merge for velloo-owned class strings — codegen's emit and
+ * the snapshot runtime use it too, so a typeset class survives the same way in
+ * the canvas and in generated code.
+ */
+export const mergeTailwind = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": TYPESET_SCALE_NAMES.map((role) => `text-${role}`),
+      leading: TYPESET_SCALE_NAMES.map((role) => `leading-${role}`),
+      tracking: TYPESET_SCALE_NAMES.map((role) => `tracking-${role}`),
+    },
+  },
+});
+
+export function cn(...inputs: ClassValue[]): string {
+  return mergeTailwind(clsx(inputs));
+}

package/pkgs/helpers/src/descriptors.ts

@@ -0,0 +1,270 @@
+import type { ComponentDescriptor } from "@velloo/provider";
+
+/**
+ * The canonical manifest entries for the velloo helpers (`source: "velloo"`).
+ * Single source: the shadcn snapshot's `build.ts` splices these into its
+ * generated `dist/manifest.json` (augmenting `Icon.name` with the live
+ * lucide-react name list at build time), and `provider-none` composes its
+ * hand-authored manifest from them. Keep each entry mirroring the co-located
+ * component's props (`./heading.tsx`, `./icon.tsx`, …).
+ */
+export const HELPER_DESCRIPTORS: readonly ComponentDescriptor[] = [
+  {
+    id: "Box",
+    category: "ui",
+    group: "layout",
+    family: "Box",
+    source: "velloo",
+    props: [],
+    example: { className: "flex flex-col gap-6 px-8 py-12" },
+  },
+  {
+    id: "Divider",
+    category: "ui",
+    group: "layout",
+    family: "Divider",
+    source: "velloo",
+    props: [
+      {
+        name: "variant",
+        type: '"solid" | "dotted" | "dashed" | "gradient" | "pinched" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["solid", "dotted", "dashed", "gradient", "pinched"],
+      },
+      {
+        name: "orientation",
+        type: '"horizontal" | "vertical" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["horizontal", "vertical"],
+      },
+      { name: "label", type: "string | undefined", optional: true, control: "string" },
+      {
+        name: "color",
+        type: '"primary" | "accent" | "muted" | "border" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["primary", "accent", "muted", "border"],
+      },
+    ],
+    example: { variant: "gradient", color: "primary", label: "OR" },
+  },
+  {
+    id: "Gradient",
+    category: "ui",
+    group: "visuals",
+    family: "Gradient",
+    source: "velloo",
+    props: [
+      {
+        name: "preset",
+        type: '"primary" | "accent" | "radial" | "mesh" | "dusk" | "dawn" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["primary", "accent", "radial", "mesh", "dusk", "dawn"],
+      },
+      {
+        name: "direction",
+        type: '"t" | "b" | "l" | "r" | "tl" | "tr" | "bl" | "br" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["t", "b", "l", "r", "tl", "tr", "bl", "br"],
+      },
+    ],
+    example: {
+      preset: "dusk",
+      direction: "br",
+      className: "absolute inset-0 -z-0 pointer-events-none",
+    },
+  },
+  {
+    id: "Heading",
+    category: "typography",
+    group: "typography",
+    family: "Heading",
+    source: "velloo",
+    props: [
+      {
+        name: "level",
+        type: "1 | 2 | 3 | 4 | 5 | 6 | undefined",
+        optional: true,
+        control: "enum",
+        enumValues: [1, 2, 3, 4, 5, 6],
+      },
+    ],
+    example: { level: 2, children: "Section title", className: "text-3xl font-semibold" },
+  },
+  {
+    id: "Icon",
+    category: "ui",
+    group: "visuals",
+    family: "Icon",
+    source: "velloo",
+    props: [
+      // `enumValues` (the lucide icon name list) is injected at snapshot build
+      // time from the installed lucide-react, so it never drifts from what the
+      // Icon component can actually resolve.
+      { name: "name", type: "string", optional: false, control: "icon", defaultValue: "Heart" },
+      { name: "size", type: "number | undefined", optional: true, control: "number" },
+      { name: "strokeWidth", type: "number | undefined", optional: true, control: "number" },
+    ],
+    designModeNotes:
+      "`name` accepts any lucide-react icon, PascalCase (ArrowRight) or kebab-case (arrow-right); full list at lucide.dev (the enumValues here are sampled). " +
+      "`size` sets width/height in px, but a Tailwind sizing class in `className` (e.g. `size-4`) wins via CSS — pass one or the other, not both expecting `size` to apply.",
+    example: { name: "Sparkles", className: "size-4 text-primary" },
+  },
+  {
+    id: "Image",
+    category: "ui",
+    group: "visuals",
+    family: "Image",
+    source: "velloo",
+    props: [
+      { name: "src", type: "string", optional: false, control: "string" },
+      {
+        name: "aspect",
+        type: '"1/1" | "4/3" | "3/4" | "16/9" | "21/9" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["1/1", "4/3", "3/4", "16/9", "21/9"],
+      },
+      {
+        name: "focal",
+        type: "{ x: number; y: number; } | undefined",
+        optional: true,
+        control: "string",
+      },
+      {
+        name: "treatment",
+        type: '"overlay-dark" | "overlay-light" | "blend-multiply" | "grayscale" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["overlay-dark", "overlay-light", "blend-multiply", "grayscale"],
+      },
+      { name: "fill", type: "boolean | undefined", optional: true, control: "boolean" },
+    ],
+    example: {
+      src: "/assets/hero.png",
+      aspect: "16/9",
+      focal: { x: 0.5, y: 0.35 },
+      treatment: "overlay-dark",
+      className: "rounded-xl",
+    },
+  },
+  {
+    id: "Layer",
+    category: "ui",
+    group: "layout",
+    family: "Layer",
+    source: "velloo",
+    props: [
+      { name: "top", type: "string | number | undefined", optional: true, control: "string" },
+      { name: "right", type: "string | number | undefined", optional: true, control: "string" },
+      { name: "bottom", type: "string | number | undefined", optional: true, control: "string" },
+      { name: "left", type: "string | number | undefined", optional: true, control: "string" },
+      { name: "z", type: "number | undefined", optional: true, control: "number" },
+      { name: "pointerEvents", type: "boolean | undefined", optional: true, control: "boolean" },
+    ],
+    example: { top: 16, left: 16, z: 2 },
+  },
+  {
+    id: "Placeholder",
+    category: "ui",
+    group: "visuals",
+    family: "Placeholder",
+    source: "velloo",
+    props: [
+      {
+        name: "kind",
+        type: '"image" | "avatar" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["image", "avatar"],
+      },
+      { name: "label", type: "string | undefined", optional: true, control: "string" },
+      {
+        name: "aspect",
+        type: '"1/1" | "4/3" | "3/4" | "16/9" | "21/9" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["1/1", "4/3", "3/4", "16/9", "21/9"],
+      },
+      {
+        name: "size",
+        type: '"sm" | "lg" | "md" | "xl" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["sm", "lg", "md", "xl"],
+      },
+    ],
+    example: { kind: "image", aspect: "16/9", label: "product screenshot" },
+  },
+  {
+    id: "Prose",
+    category: "typography",
+    group: "typography",
+    family: "Prose",
+    source: "velloo",
+    props: [
+      {
+        name: "preset",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
+      { name: "as", type: "string | undefined", optional: true, control: "string" },
+    ],
+    example: { as: "article", className: "max-w-prose" },
+  },
+  {
+    id: "SVG",
+    category: "ui",
+    group: "visuals",
+    family: "SVG",
+    source: "velloo",
+    props: [
+      { name: "content", type: "string | undefined", optional: true, control: "string" },
+      { name: "viewBox", type: "string | undefined", optional: true, control: "string" },
+      { name: "color", type: "string | undefined", optional: true, control: "color" },
+    ],
+    example: {
+      content: "<path d='M12 2 2 7l10 5 10-5-10-5z' />",
+      viewBox: "0 0 24 24",
+      color: "primary",
+      className: "h-8 w-8",
+    },
+  },
+  {
+    id: "Text",
+    category: "typography",
+    group: "typography",
+    family: "Text",
+    source: "velloo",
+    props: [
+      {
+        name: "variant",
+        type: '"muted" | "default" | "small" | "lead" | undefined',
+        optional: true,
+        control: "enum",
+        enumValues: ["muted", "default", "small", "lead"],
+      },
+    ],
+    example: { variant: "muted", children: "Supporting copy." },
+  },
+];
+
+/**
+ * Subset selector mirroring `helpersRegistry` — each provider passes its own
+ * deliberate id list and gets the canonical descriptors in that order.
+ * Unknown ids are skipped.
+ */
+export function helperDescriptors(ids: readonly string[]): ComponentDescriptor[] {
+  const byId = new Map(HELPER_DESCRIPTORS.map((d) => [d.id, d]));
+  const out: ComponentDescriptor[] = [];
+  for (const id of ids) {
+    const descriptor = byId.get(id);
+    if (descriptor) out.push(descriptor);
+  }
+  return out;
+}

package/pkgs/helpers/src/divider.tsx

@@ -0,0 +1,123 @@
+// Velloo-owned decorative divider. shadcn's Separator is a single
+// border-bg-border rule — fine for app chrome but too plain for
+// marketing pages. Divider adds variant styles (dotted, gradient,
+// pinched) and a label slot for "OR" / "section break" usage.
+import type * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface DividerProps extends React.HTMLAttributes<HTMLDivElement> {
+  variant?: "solid" | "dotted" | "dashed" | "gradient" | "pinched";
+  orientation?: "horizontal" | "vertical";
+  /** Optional centered label, like "OR" or "section break". */
+  label?: string;
+  /** Color source — semantic token name; defaults to border. */
+  color?: "border" | "muted" | "primary" | "accent";
+}
+
+const COLOR_BORDER: Record<NonNullable<DividerProps["color"]>, string> = {
+  border: "border-border",
+  muted: "border-muted-foreground/30",
+  primary: "border-primary/40",
+  accent: "border-accent/60",
+};
+
+const COLOR_BG: Record<NonNullable<DividerProps["color"]>, string> = {
+  border: "from-border via-border to-border",
+  muted: "from-transparent via-muted-foreground/40 to-transparent",
+  primary: "from-transparent via-primary to-transparent",
+  accent: "from-transparent via-accent to-transparent",
+};
+
+const VARIANT_BORDER: Record<NonNullable<DividerProps["variant"]>, string> = {
+  solid: "border-solid",
+  dotted: "border-dotted",
+  dashed: "border-dashed",
+  gradient: "",
+  pinched: "border-solid",
+};
+
+export function Divider({
+  variant = "solid",
+  orientation = "horizontal",
+  label,
+  color = "border",
+  className,
+  ...rest
+}: DividerProps) {
+  if (label) {
+    return (
+      <div
+        data-slot="divider"
+        data-variant={variant}
+        className={cn(
+          "flex items-center gap-3 text-xs uppercase tracking-wider text-muted-foreground",
+          className,
+        )}
+        {...rest}
+      >
+        <span
+          className={cn(
+            "flex-1",
+            variant === "gradient"
+              ? cn("h-px bg-gradient-to-r", COLOR_BG[color])
+              : cn("border-t", VARIANT_BORDER[variant], COLOR_BORDER[color]),
+          )}
+        />
+        <span className="shrink-0">{label}</span>
+        <span
+          className={cn(
+            "flex-1",
+            variant === "gradient"
+              ? cn("h-px bg-gradient-to-r", COLOR_BG[color])
+              : cn("border-t", VARIANT_BORDER[variant], COLOR_BORDER[color]),
+          )}
+        />
+      </div>
+    );
+  }
+
+  if (variant === "gradient") {
+    return (
+      <div
+        data-slot="divider"
+        data-variant="gradient"
+        className={cn(
+          orientation === "horizontal" ? "h-px w-full" : "w-px self-stretch",
+          "bg-gradient-to-r",
+          COLOR_BG[color],
+          className,
+        )}
+        {...rest}
+      />
+    );
+  }
+
+  if (variant === "pinched") {
+    return (
+      <div
+        data-slot="divider"
+        data-variant="pinched"
+        className={cn("flex items-center justify-center w-full", className)}
+        {...rest}
+      >
+        <span className={cn("h-px w-16 border-t", COLOR_BORDER[color])} />
+        <span className={cn("mx-1 size-1.5 rounded-full", COLOR_BG[color].split(" ")[1] ?? "")} />
+        <span className={cn("h-px w-16 border-t", COLOR_BORDER[color])} />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-slot="divider"
+      data-variant={variant}
+      className={cn(
+        orientation === "horizontal"
+          ? cn("w-full border-t", VARIANT_BORDER[variant], COLOR_BORDER[color])
+          : cn("self-stretch border-l", VARIANT_BORDER[variant], COLOR_BORDER[color]),
+        className,
+      )}
+      {...rest}
+    />
+  );
+}