velloo 0.0.0 → 0.1.0

package/chunk-xr6f94rj.js

@@ -0,0 +1,2 @@
+// @bun
+import{headingInlineStyle,textInlineStyle}from"./chunk-bk8b7f9a.js";import{clsx,helperDescriptors,require_react_jsx_dev_runtime_development,helpersRegistry,TAILWIND_CLASSNAME}from"./chunk-329e3phg.js";import{resolveProviderSrcDir}from"./chunk-fjbzk4sw.js";import{require_react_development}from"./chunk-w5rzk6ms.js";import{__toESM}from"./chunk-2smsg2ct.js";import{noLibVersion}from"./chunk-cxe6jjwj.js";import{dirname,join}from"path";import{fileURLToPath}from"url";var NONE_INTRO=["**This folder has no component library** \u2014 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` \u2014 build those from primitives or define snippets. Call `list_components` for the exact set. Styling is **Tailwind classes**.",""],NONE_INLINE_INTRO=["**This folder has no component library and no CSS framework** \u2014 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` \u2014 build those from primitives or snippets. 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)" } }` \u2014 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={{\u2026}}` on plain elements \u2014 no imports, no Tailwind. Tailwind utility diagnostics do not apply.',""];var React=__toESM(require_react_development(),1),jsx_dev_runtime=__toESM(require_react_jsx_dev_runtime_development(),1),Box=React.forwardRef(({className,...rest},ref)=>jsx_dev_runtime.jsxDEV("div",{ref,className:clsx(className),...rest},void 0,!1,void 0,this));Box.displayName="Box";var alignClass={start:"items-start",center:"items-center",end:"items-end",stretch:"items-stretch"},justifyClass={start:"justify-start",center:"justify-center",end:"justify-end",between:"justify-between",around:"justify-around"},Stack=React.forwardRef(({direction="col",gap=4,align,justify,className,...rest},ref)=>jsx_dev_runtime.jsxDEV("div",{ref,className:clsx("flex",direction==="row"?"flex-row":"flex-col",`gap-${gap}`,align?alignClass[align]:void 0,justify?justifyClass[justify]:void 0,className),...rest},void 0,!1,void 0,this));Stack.displayName="Stack";var containerWidth={sm:"max-w-screen-sm",md:"max-w-screen-md",lg:"max-w-screen-lg",xl:"max-w-screen-xl",full:"max-w-full"},Container=React.forwardRef(({size="md",className,...rest},ref)=>jsx_dev_runtime.jsxDEV("div",{ref,className:clsx("mx-auto w-full px-4",containerWidth[size],className),...rest},void 0,!1,void 0,this));Container.displayName="Container";var buttonVariant={default:"bg-foreground text-background hover:bg-foreground/90",ghost:"bg-transparent text-foreground hover:bg-muted",outline:"bg-transparent text-foreground border border-border hover:bg-muted"},Button=React.forwardRef(({variant="default",className,type,...rest},ref)=>jsx_dev_runtime.jsxDEV("button",{ref,type:type??"button",className:clsx("inline-flex items-center justify-center gap-2 rounded-md px-4 py-2 text-sm font-medium","focus-visible:outline-2 focus-visible:outline-offset-2",buttonVariant[variant],className),...rest},void 0,!1,void 0,this));Button.displayName="Button";var Input=React.forwardRef(({className,type="text",value,onChange,...rest},ref)=>jsx_dev_runtime.jsxDEV("input",{ref,type,value,onChange,readOnly:value!==void 0&&onChange===void 0||rest.readOnly,className:clsx("block w-full rounded-md border border-input bg-background px-3 py-2 text-sm","placeholder:text-muted-foreground focus-visible:outline-2 focus-visible:outline-offset-2",className),...rest},void 0,!1,void 0,this));Input.displayName="Input";var Card=React.forwardRef(({className,...rest},ref)=>jsx_dev_runtime.jsxDEV("div",{ref,className:clsx("rounded-lg border border-border bg-card p-6 text-card-foreground shadow-sm",className),...rest},void 0,!1,void 0,this));Card.displayName="Card";var REUSED_HELPER_IDS=["Heading","Text","Prose","Icon","SVG","Image","Layer","Divider","Gradient","Placeholder"],registry={Box,Stack,Container,Card,Button,Input,...helpersRegistry(REUSED_HELPER_IDS)};var PRIMITIVE_DESCRIPTORS=[{id:"Box",category:"ui",source:"velloo",props:[{name:"className",type:"string | undefined",optional:!0,control:"string"}]},{id:"Stack",category:"ui",source:"velloo",props:[{name:"direction",type:'"row" | "col" | undefined',optional:!0,control:"enum",enumValues:["row","col"],defaultValue:"col"},{name:"gap",type:"number | undefined",optional:!0,control:"number",defaultValue:"4"},{name:"align",type:'"start" | "center" | "end" | "stretch" | undefined',optional:!0,control:"enum",enumValues:["start","center","end","stretch"]},{name:"justify",type:'"start" | "center" | "end" | "between" | "around" | undefined',optional:!0,control:"enum",enumValues:["start","center","end","between","around"]},{name:"className",type:"string | undefined",optional:!0,control:"string"}]},{id:"Container",category:"ui",source:"velloo",props:[{name:"size",type:'"sm" | "md" | "lg" | "xl" | "full" | undefined',optional:!0,control:"enum",enumValues:["sm","md","lg","xl","full"],defaultValue:"md"},{name:"className",type:"string | undefined",optional:!0,control:"string"}]},{id:"Card",category:"ui",source:"velloo",props:[{name:"className",type:"string | undefined",optional:!0,control:"string"}]},{id:"Button",category:"ui",source:"velloo",props:[{name:"variant",type:'"default" | "ghost" | "outline" | undefined',optional:!0,control:"enum",enumValues:["default","ghost","outline"],defaultValue:"default"},{name:"className",type:"string | undefined",optional:!0,control:"string"}]},{id:"Input",category:"ui",source:"velloo",props:[{name:"placeholder",type:"string | undefined",optional:!0,control:"string"},{name:"value",type:"string | undefined",optional:!0,control:"string"},{name:"type",type:"string | undefined",optional:!0,control:"string",defaultValue:"text"},{name:"className",type:"string | undefined",optional:!0,control:"string"}]}],NONE_MANIFEST=[...PRIMITIVE_DESCRIPTORS,...helperDescriptors(REUSED_HELPER_IDS)];var React2=__toESM(require_react_development(),1),jsx_dev_runtime2=__toESM(require_react_jsx_dev_runtime_development(),1);function merge(defaults,authored){return authored?{...defaults,...authored}:defaults}var space=(n)=>`${n*0.25}rem`,Box2=React2.forwardRef(({style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("div",{ref,style,...rest},void 0,!1,void 0,this));Box2.displayName="Box";var alignStyle={start:"flex-start",center:"center",end:"flex-end",stretch:"stretch"},justifyStyle={start:"flex-start",center:"center",end:"flex-end",between:"space-between",around:"space-around"},Stack2=React2.forwardRef(({direction="col",gap=4,align,justify,style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("div",{ref,style:merge({display:"flex",flexDirection:direction==="row"?"row":"column",gap:space(gap),...align?{alignItems:alignStyle[align]}:{},...justify?{justifyContent:justifyStyle[justify]}:{}},style),...rest},void 0,!1,void 0,this));Stack2.displayName="Stack";var containerMaxWidth={sm:"640px",md:"768px",lg:"1024px",xl:"1280px",full:"100%"},Container2=React2.forwardRef(({size="md",style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("div",{ref,style:merge({marginInline:"auto",width:"100%",paddingInline:"1rem",maxWidth:containerMaxWidth[size]},style),...rest},void 0,!1,void 0,this));Container2.displayName="Container";var buttonVariantStyle={default:{background:"var(--color-foreground)",color:"var(--color-background)"},ghost:{background:"transparent",color:"var(--color-foreground)"},outline:{background:"transparent",color:"var(--color-foreground)",border:"1px solid var(--color-border)"}},Button2=React2.forwardRef(({variant="default",type,style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("button",{ref,type:type??"button",style:merge({display:"inline-flex",alignItems:"center",justifyContent:"center",gap:"0.5rem",borderRadius:"var(--radius)",padding:"0.5rem 1rem",fontSize:"0.875rem",fontWeight:500,cursor:"pointer",...buttonVariantStyle[variant]},style),...rest},void 0,!1,void 0,this));Button2.displayName="Button";var Input2=React2.forwardRef(({type="text",value,onChange,style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("input",{ref,type,value,onChange,readOnly:value!==void 0&&onChange===void 0||rest.readOnly,style:merge({display:"block",width:"100%",borderRadius:"var(--radius)",border:"1px solid var(--color-input)",background:"var(--color-background)",padding:"0.5rem 0.75rem",fontSize:"0.875rem"},style),...rest},void 0,!1,void 0,this));Input2.displayName="Input";var Card2=React2.forwardRef(({style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("div",{ref,style:merge({borderRadius:"var(--radius)",border:"1px solid var(--color-border)",background:"var(--color-card)",color:"var(--color-card-foreground)",padding:"1.5rem",boxShadow:"0 1px 2px 0 rgb(0 0 0 / 0.05)"},style),...rest},void 0,!1,void 0,this));Card2.displayName="Card";var Heading=React2.forwardRef(({level=1,style,...rest},ref)=>{let Tag=`h${level}`;return jsx_dev_runtime2.jsxDEV(Tag,{ref,style:merge(headingInlineStyle(level),style),...rest},void 0,!1,void 0,this)});Heading.displayName="Heading";var Text=React2.forwardRef(({variant="default",style,...rest},ref)=>jsx_dev_runtime2.jsxDEV("p",{ref,style:merge(textInlineStyle(variant),style),...rest},void 0,!1,void 0,this));Text.displayName="Text";var REUSED_HELPER_IDS2=["Prose","Icon","SVG","Image","Layer","Divider","Gradient","Placeholder"],inlineRegistry={Box:Box2,Stack:Stack2,Container:Container2,Card:Card2,Button:Button2,Input:Input2,Heading,Text,...helpersRegistry(REUSED_HELPER_IDS2)};var here=dirname(fileURLToPath(import.meta.url)),srcDir=resolveProviderSrcDir(here,"provider-none",process.env.VELLOO_NOLIB_SRC),entryCssPath=join(srcDir,"tailwind-entry.css"),componentsDir=srcDir;async function loadManifest(){return NONE_MANIFEST}function createProvider(){return{id:"none",version:noLibVersion,componentsDir,styleEntryPath:entryCssPath,registry,loadManifest,label:`none ${noLibVersion}`,styleChannel:TAILWIND_CLASSNAME,styleChannels:["tailwind-classname","style"],mcpIntro:(channel)=>[...channel==="style"?NONE_INLINE_INTRO:NONE_INTRO],registryForChannel:(kind)=>kind==="style"?inlineRegistry:registry}}export{createProvider};

package/chunk-y0zxzefg.js

@@ -0,0 +1,5 @@
+// @bun
+import{CURRENT_SCHEMA_VERSION,schemaVersionOf,planMigration}from"./chunk-bk8b7f9a.js";import{loadDesignFolder}from"./chunk-329e3phg.js";import{TOOL_VERSION}from"./chunk-65wb0g7d.js";import{readdir,readFile,writeFile}from"fs/promises";import{join}from"path";function isObject(value){return typeof value==="object"&&value!==null&&!Array.isArray(value)}var isAnnotationSidecar=(file)=>file.endsWith(".annotations.json"),isThemeDocument=(file)=>file.endsWith(".json");async function planRewrites(folder,dir,matches,transform){let files=[];try{files=await readdir(join(folder,dir))}catch{return[]}let out=[];for(let file of files.sort()){if(!matches(file))continue;let rel=join(dir,file),prev=await readFile(join(folder,rel),"utf8"),next=`${JSON.stringify(transform(JSON.parse(prev)),null,2)}
+`;if(next!==prev)out.push({rel,next})}return out}async function upgradeFolder(folder,opts={}){let configPath=join(folder,".design","config.json"),rawConfig=JSON.parse(await readFile(configPath,"utf8")),from=schemaVersionOf(rawConfig),run=planMigration(rawConfig);if(run.applied.length===0)return{from,to:CURRENT_SCHEMA_VERSION,applied:[],changedFiles:[]};let rewrites=[...await planRewrites(folder,"screens",isAnnotationSidecar,(parsed)=>Array.isArray(parsed)?parsed.map((e)=>typeof e==="object"&&e!==null?run.annotation(e):e):parsed),...await planRewrites(folder,"theme",isThemeDocument,(parsed)=>isObject(parsed)?run.theme(parsed):parsed)],nextConfig={...run.config,toolVersion:TOOL_VERSION},changedFiles=[join(".design","config.json"),...rewrites.map((r)=>r.rel)];if(opts.dryRun)return{from,to:CURRENT_SCHEMA_VERSION,applied:run.applied,changedFiles};await writeFile(configPath,`${JSON.stringify(nextConfig,null,2)}
+`,"utf8");for(let r of rewrites)await writeFile(join(folder,r.rel),r.next,"utf8");return await loadDesignFolder(folder),{from,to:CURRENT_SCHEMA_VERSION,applied:run.applied,changedFiles}}
+export{upgradeFolder};

package/chunk-zf3xc1wz.js

@@ -0,0 +1,2 @@
+// @bun
+import"./chunk-mq4znqv2.js";import"./chunk-bk8b7f9a.js";import{loadCredential}from"./chunk-b7j86xq7.js";import"./chunk-329e3phg.js";import"./chunk-w5rzk6ms.js";import"./chunk-65wb0g7d.js";import{listDaemons}from"./chunk-k784090q.js";import{verifyCredential}from"./chunk-fgw3hp2v.js";import{projectLabel}from"./chunk-1bywxgc5.js";import{defaultCloudUrl}from"./chunk-2z0k59hz.js";import{require_picocolors}from"./chunk-jrsknzjt.js";import{__toESM,defineCommand}from"./chunk-2smsg2ct.js";var import_picocolors=__toESM(require_picocolors(),1);var status_default=defineCommand({meta:{name:"status",description:"List the velloo canvas daemons running on this machine + cloud sign-in"},args:{},async run(){let daemons=await listDaemons();if(daemons.length===0)console.log("velloo: no canvas daemons running.");else for(let d of daemons){let label=await projectLabel(d.root)??d.root;console.log(`${d.canvasUrl}  ${label}  (pid ${d.pid}, since ${d.startedAt})`)}let cloudUrl=defaultCloudUrl(),cred=await loadCredential(cloudUrl);if(!cred){console.log(import_picocolors.default.dim(`cloud: not signed in (${cloudUrl}) \u2014 run \`velloo login\` to share.`));return}let email=await verifyCredential(cloudUrl,cred.token,3000);console.log(email?`cloud: signed in as ${email} (${cloudUrl})`:import_picocolors.default.dim(`cloud: stored credential for ${cred.email} (${cloudUrl}) \u2014 expired or cloud unreachable; \`velloo login\` to refresh.`))}});export{status_default as default};

package/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+// @bun
+import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-1yhc252b.js";import{TOOL_VERSION}from"./chunk-65wb0g7d.js";import{maybeNotifyAboutUpdate}from"./chunk-cep3ktr3.js";import{defineCommand,runMain}from"./chunk-2smsg2ct.js";var main=defineCommand({meta:{name:"velloo",version:TOOL_VERSION,description:"Local, agent-driven canvas for redesigning an existing React screen against the running app, then sharing the result with a team or external reviewer."},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", "--folder-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.1.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://github.com/velloo-design/velloo#readme",
   "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}
+    />
+  );
+}