velloo 0.6.0 → 0.7.0

package/{chunk-tbd6wn3q.js → chunk-ykpctq15.js}

@@ -1,5 +1,5 @@
 // @bun
-import{isCancel,confirm,select}from"./chunk-80fjfyha.js";import{designNameIssue}from"./chunk-8cj4swpr.js";import{managedDesignId,localDesignOf,removeLocalDesign,recordedDesignName,designRenameConflict,followDesignRename,loadDesignFolder}from"./chunk-yfvc8d2g.js";import"./chunk-chtv0yj6.js";import"./chunk-1gkeepkm.js";import{agentRootCandidates}from"./chunk-rjjc9vam.js";import"./chunk-t6qr2ay9.js";import{daemonRoot,readLock,isLive,stopDaemon}from"./chunk-azeqkms7.js";import{fail}from"./chunk-s23gtejf.js";import"./chunk-1td6z6ey.js";import"./chunk-ff0jfn0v.js";import"./chunk-p93x4pn2.js";import{displayPath}from"./chunk-hf4adxe0.js";import"./chunk-mfch0b0t.js";import"./chunk-rk238m15.js";import{recordedAppRoot,planAppRootChange,applyAppRootChange,promptAppRootChoice,planRelocation,relocateDesign,runInit2}from"./chunk-ab8fga32.js";import"./chunk-2ba6edh8.js";import{repinAgentConfigs,migrateFolder2}from"./chunk-xtwx2p9g.js";import"./chunk-pjtg3wnm.js";import"./chunk-k423dkjz.js";import"./chunk-8vam2893.js";import"./chunk-jsvkqae2.js";import{findManifest,manifestListing,findDesigns,unregisterDesign,isWithin,writeDesignName,registerLocalDesign,DESIGN_ARG_DESCRIPTION,hasDesignConfig,DESIGN_ID_ARG,resolveDesign,checkoutDesigns}from"./chunk-8vgpffn7.js";import"./chunk-hjc5eg5c.js";import{require_picocolors}from"./chunk-jrsknzjt.js";import{__toESM,defineCommand}from"./chunk-2smsg2ct.js";import{randomUUID}from"crypto";import{existsSync,realpathSync}from"fs";import{readdir,rm}from"fs/promises";import{join,relative,resolve}from"path";var import_picocolors=__toESM(require_picocolors(),1);async function countJson(dir,skipSuffix){try{return(await readdir(dir)).filter((f)=>f.endsWith(".json")&&!(skipSuffix&&f.endsWith(skipSuffix))).length}catch{return 0}}async function daemonState(folder){let rec=await readLock(daemonRoot(folder));if(!rec)return"stopped";return await isLive(rec)?`running :${rec.canvasPort}`:"stopped"}var list=defineCommand({meta:{name:"list",description:"List the repo's designs"},async run(){let cwd=resolve("."),found=await findDesigns(cwd).catch((err)=>{fail("design list",err.message)});if(!found||found.designs.length===0){let only=await resolveDesign(void 0,"design list",{requireConfig:!0,cwd,takesDesign:!1,onFail:(message)=>fail("design list",message)}),name=recordedDesignName(only)??"(unnamed)",owner=await manifestListing(only).catch(()=>null);if(owner&&owner.dir!==cwd){console.log(`velloo design: "${name}" (${relative(cwd,only)||only}) is listed in \`${relative(cwd,owner.path)}\`. Run \`velloo design list\` from \`${relative(cwd,owner.dir)||"."}\` to see that project's designs.`);return}console.log("velloo design: 1 design (no velloo.json yet)"),console.log(`  ${import_picocolors.default.dim("1")}  ${import_picocolors.default.bold(name)}  ${relative(cwd,only)||only}  ${await daemonState(only)}`),console.log(import_picocolors.default.dim("  `velloo design add` creates a second design and lists both."));return}let base=found.repo?.dir??found.local[0]?.root??cwd,rows=[];for(let design of found.designs){let live=design.exists&&!design.outsideRepo;rows.push({name:found.conflicts.has(design.name)?`${design.name} (duplicate)`:design.name,path:design.local?`${displayPath(design.root)} (local)`:relative(base,design.root)||".",boards:live?await countJson(join(design.root,"boards"),".notes.json"):0,state:design.outsideRepo?import_picocolors.default.yellow("outside the repo"):live?await daemonState(design.root):import_picocolors.default.yellow("missing"),live})}let pad=(text,width)=>text+" ".repeat(Math.max(0,width-Bun.stringWidth(text))),width=Math.max(...rows.map((r)=>Bun.stringWidth(r.name))),pathWidth=Math.max(...rows.map((r)=>Bun.stringWidth(r.path))),idWidth=String(rows.length).length;console.log(`velloo design: ${rows.length} in ${base}`);for(let[index,row]of rows.entries()){let marker=row.name===found.defaultDesign?import_picocolors.default.cyan("\u25CF"):" ",id=import_picocolors.default.dim(String(index+1).padStart(idWidth)),boards=row.live?`${row.boards} board${row.boards===1?"":"s"}`:"\u2014";console.log(`  ${id} ${marker} ${import_picocolors.default.bold(pad(row.name,width))}  ${import_picocolors.default.dim(pad(row.path,pathWidth))}  ${boards.padEnd(9)}  ${row.state}`)}console.log(import_picocolors.default.dim("  Pass a number as --id to the other `velloo design` commands."));for(let[name,designs]of found.conflicts)console.log(import_picocolors.default.yellow(`  ! ${designs.length} designs are named "${name}" \u2014 rename one with \`velloo design rename <path> <new-name>\`.`))}}),add=defineCommand({meta:{name:"add",description:"Create another design in this repo (the init wizard, folder pre-chosen)"},args:{path:{type:"positional",required:!1,description:"Where the new design folder goes, relative to the repo (asked when omitted)"},external:{type:"boolean",description:"Create in Velloo-managed external storage"},nonInteractive:{type:"boolean",description:"Use defaults without prompting"},connect:{type:"boolean",default:!0,description:"Wire project agents"},library:{type:"string",description:"Component library (default: the sibling folder's)"},name:{type:"string",description:"The design's name (default: derived from its folder)"}},async run({args}){await runInit2({addFolder:!0,external:args.external,nonInteractive:args.nonInteractive,connect:args.connect,...args.path?{designFolder:args.path}:{},...args.library?{library:args.library}:{},...args.name?{name:args.name}:{}})}}),remove=defineCommand({meta:{name:"remove",description:"Remove a design \u2014 one outside the repo can keep its files (asked, or --delete-content)"},args:{design:{type:"positional",required:!1,description:DESIGN_ARG_DESCRIPTION},id:DESIGN_ID_ARG,deleteContent:{type:"boolean",description:"Also delete the files of a design outside the repo (with --yes, or to skip the question)"},yes:{type:"boolean",description:"Skip the confirmation (required without an interactive terminal)"}},async run({args}){let cwd=resolve("."),folder=await resolveDesign(args.design,"design remove",{id:args.id,interactive:!0,requireConfig:!0,cwd}),local=localDesignOf(folder);if(!Boolean(process.stdin.isTTY)&&args.yes!==!0)fail("design remove","refusing to delete a design folder without --yes");let boards=await countJson(join(folder,"boards"),".notes.json"),screens=await countJson(join(folder,"screens"),".annotations.json"),name=recordedDesignName(folder)??folder;console.log(`velloo design: ${name} (${folder})`),console.log(import_picocolors.default.dim(`  ${boards} board${boards===1?"":"s"}, ${screens} screen${screens===1?"":"s"}`));let keepContent=local!==null&&args.deleteContent!==!0;if(args.yes!==!0)if(local&&args.deleteContent!==!0){let managed=managedDesignId(folder)!==null,choice=await select({message:"Remove this design?",initialValue:managed?"delete":"keep",options:[{value:"delete",label:"Delete it and its files",hint:managed?"in Velloo's storage":folder},{value:"keep",label:"Forget it, keep the files",hint:folder},{value:"cancel",label:"Cancel"}]});if(isCancel(choice)||choice==="cancel"){console.log(import_picocolors.default.dim("  Nothing changed."));return}keepContent=choice==="keep"}else{let approved=await confirm({message:"Delete this design folder and everything in it?",initialValue:!1});if(isCancel(approved)||!approved){console.log(import_picocolors.default.dim("  Nothing changed."));return}}if(await stopDaemon(daemonRoot(folder)))console.log(import_picocolors.default.dim("  Stopped its canvas."));let dropped=local?null:await unregisterDesign(folder,cwd).catch((err)=>fail("design remove",err.message));if(local)await removeLocalDesign(local.id);if(!keepContent)await rm(folder,{recursive:!0,force:!0});if(console.log(`velloo design: ${keepContent?"retained content at":"removed"} ${folder}`),local)console.log(import_picocolors.default.dim(`  Forgot the local design "${name}".`));if(dropped?.name)console.log(import_picocolors.default.dim(dropped.removedManifest?`  Dropped "${dropped.name}" \u2014 velloo.json listed no other designs, so it's gone too.`:`  Dropped "${dropped.name}" from velloo.json.`))}}),move=defineCommand({meta:{name:"move",description:"Preview moving a design between the repository, managed storage and another directory; --yes applies"},args:{design:{type:"positional",required:!1,description:DESIGN_ARG_DESCRIPTION},id:DESIGN_ID_ARG,external:{type:"boolean",description:"Move to managed storage (a local design)"},to:{type:"string",description:"New directory \u2014 inside the repository it goes in velloo.json, outside it is local"},yes:{type:"boolean",description:"Apply the displayed move"}},async run({args}){let source=await resolveDesign(args.design,"design move",{id:args.id,interactive:!0,requireConfig:!0}),plan=await planRelocation(source,resolve("."),args.to,args.external===!0).catch((err)=>fail("design move",err.message)),local="a local design on this machine",recorded=plan.sourceManifestPath?plan.destinationLocal?`velloo.json path "${plan.sourceManifestPath}" \u2192 ${"a local design on this machine"}`:`velloo.json path "${plan.sourceManifestPath}" \u2192 "${plan.destinationManifestPath}"`:plan.destinationLocal?"stays a local design on this machine":`${"a local design on this machine"} \u2192 velloo.json path "${plan.destinationManifestPath}"`;if(console.log(`Source: ${plan.source}
+import{isCancel,confirm,select}from"./chunk-80fjfyha.js";import{designNameIssue}from"./chunk-5x4nw0zz.js";import{managedDesignId,localDesignOf,removeLocalDesign,recordedDesignName,designRenameConflict,followDesignRename,loadDesignFolder}from"./chunk-brnkprt5.js";import"./chunk-ex36z3b3.js";import"./chunk-bys7pqdb.js";import{agentRootCandidates}from"./chunk-4y2xy1kf.js";import"./chunk-3m28pvzr.js";import{daemonRoot,readLock,isLive,stopDaemon}from"./chunk-xzf52wvn.js";import{fail}from"./chunk-s23gtejf.js";import"./chunk-eh2xp4v6.js";import"./chunk-acsv6m3n.js";import"./chunk-p93x4pn2.js";import{displayPath}from"./chunk-mdgwdqnq.js";import"./chunk-b8vcbbrg.js";import"./chunk-s84vxcdv.js";import{recordedAppRoot,planAppRootChange,applyAppRootChange,promptAppRootChoice,planRelocation,relocateDesign,runInit2}from"./chunk-g8xrwjvq.js";import"./chunk-kkvf0xk2.js";import{repinAgentConfigs,migrateFolder2}from"./chunk-0vaff40g.js";import"./chunk-pjtg3wnm.js";import"./chunk-5yhnnhkd.js";import"./chunk-vs8j3x6t.js";import"./chunk-82x2jkfq.js";import{findManifest,manifestListing,findDesigns,unregisterDesign,isWithin,writeDesignName,registerLocalDesign,DESIGN_ARG_DESCRIPTION,hasDesignConfig,DESIGN_ID_ARG,resolveDesign,checkoutDesigns}from"./chunk-64pex3mw.js";import"./chunk-abr2hgay.js";import{require_picocolors}from"./chunk-jrsknzjt.js";import{__toESM,defineCommand}from"./chunk-2smsg2ct.js";import{randomUUID}from"crypto";import{existsSync,realpathSync}from"fs";import{readdir,rm}from"fs/promises";import{join,relative,resolve}from"path";var import_picocolors=__toESM(require_picocolors(),1);async function countJson(dir,skipSuffix){try{return(await readdir(dir)).filter((f)=>f.endsWith(".json")&&!(skipSuffix&&f.endsWith(skipSuffix))).length}catch{return 0}}async function daemonState(folder){let rec=await readLock(daemonRoot(folder));if(!rec)return"stopped";return await isLive(rec)?`running :${rec.canvasPort}`:"stopped"}var list=defineCommand({meta:{name:"list",description:"List the repo's designs"},async run(){let cwd=resolve("."),found=await findDesigns(cwd).catch((err)=>{fail("design list",err.message)});if(!found||found.designs.length===0){let only=await resolveDesign(void 0,"design list",{requireConfig:!0,cwd,takesDesign:!1,onFail:(message)=>fail("design list",message)}),name=recordedDesignName(only)??"(unnamed)",owner=await manifestListing(only).catch(()=>null);if(owner&&owner.dir!==cwd){console.log(`velloo design: "${name}" (${relative(cwd,only)||only}) is listed in \`${relative(cwd,owner.path)}\`. Run \`velloo design list\` from \`${relative(cwd,owner.dir)||"."}\` to see that project's designs.`);return}console.log("velloo design: 1 design (no velloo.json yet)"),console.log(`  ${import_picocolors.default.dim("1")}  ${import_picocolors.default.bold(name)}  ${relative(cwd,only)||only}  ${await daemonState(only)}`),console.log(import_picocolors.default.dim("  `velloo design add` creates a second design and lists both."));return}let base=found.repo?.dir??found.local[0]?.root??cwd,rows=[];for(let design of found.designs){let live=design.exists&&!design.outsideRepo;rows.push({name:found.conflicts.has(design.name)?`${design.name} (duplicate)`:design.name,path:design.local?`${displayPath(design.root)} (local)`:relative(base,design.root)||".",boards:live?await countJson(join(design.root,"boards"),".notes.json"):0,state:design.outsideRepo?import_picocolors.default.yellow("outside the repo"):live?await daemonState(design.root):import_picocolors.default.yellow("missing"),live})}let pad=(text,width)=>text+" ".repeat(Math.max(0,width-Bun.stringWidth(text))),width=Math.max(...rows.map((r)=>Bun.stringWidth(r.name))),pathWidth=Math.max(...rows.map((r)=>Bun.stringWidth(r.path))),idWidth=String(rows.length).length;console.log(`velloo design: ${rows.length} in ${base}`);for(let[index,row]of rows.entries()){let marker=row.name===found.defaultDesign?import_picocolors.default.cyan("\u25CF"):" ",id=import_picocolors.default.dim(String(index+1).padStart(idWidth)),boards=row.live?`${row.boards} board${row.boards===1?"":"s"}`:"\u2014";console.log(`  ${id} ${marker} ${import_picocolors.default.bold(pad(row.name,width))}  ${import_picocolors.default.dim(pad(row.path,pathWidth))}  ${boards.padEnd(9)}  ${row.state}`)}console.log(import_picocolors.default.dim("  Pass a number as --id to the other `velloo design` commands."));for(let[name,designs]of found.conflicts)console.log(import_picocolors.default.yellow(`  ! ${designs.length} designs are named "${name}" \u2014 rename one with \`velloo design rename <path> <new-name>\`.`))}}),add=defineCommand({meta:{name:"add",description:"Create another design in this repo (the init wizard, folder pre-chosen)"},args:{path:{type:"positional",required:!1,description:"Where the new design folder goes, relative to the repo (asked when omitted)"},external:{type:"boolean",description:"Create in Velloo-managed external storage"},nonInteractive:{type:"boolean",description:"Use defaults without prompting"},connect:{type:"boolean",default:!0,description:"Wire project agents"},library:{type:"string",description:"Component library (default: the sibling folder's)"},name:{type:"string",description:"The design's name (default: derived from its folder)"}},async run({args}){await runInit2({addFolder:!0,external:args.external,nonInteractive:args.nonInteractive,connect:args.connect,...args.path?{designFolder:args.path}:{},...args.library?{library:args.library}:{},...args.name?{name:args.name}:{}})}}),remove=defineCommand({meta:{name:"remove",description:"Remove a design \u2014 one outside the repo can keep its files (asked, or --delete-content)"},args:{design:{type:"positional",required:!1,description:DESIGN_ARG_DESCRIPTION},id:DESIGN_ID_ARG,deleteContent:{type:"boolean",description:"Also delete the files of a design outside the repo (with --yes, or to skip the question)"},yes:{type:"boolean",description:"Skip the confirmation (required without an interactive terminal)"}},async run({args}){let cwd=resolve("."),folder=await resolveDesign(args.design,"design remove",{id:args.id,interactive:!0,requireConfig:!0,cwd}),local=localDesignOf(folder);if(!Boolean(process.stdin.isTTY)&&args.yes!==!0)fail("design remove","refusing to delete a design folder without --yes");let boards=await countJson(join(folder,"boards"),".notes.json"),screens=await countJson(join(folder,"screens"),".annotations.json"),name=recordedDesignName(folder)??folder;console.log(`velloo design: ${name} (${folder})`),console.log(import_picocolors.default.dim(`  ${boards} board${boards===1?"":"s"}, ${screens} screen${screens===1?"":"s"}`));let keepContent=local!==null&&args.deleteContent!==!0;if(args.yes!==!0)if(local&&args.deleteContent!==!0){let managed=managedDesignId(folder)!==null,choice=await select({message:"Remove this design?",initialValue:managed?"delete":"keep",options:[{value:"delete",label:"Delete it and its files",hint:managed?"in Velloo's storage":folder},{value:"keep",label:"Forget it, keep the files",hint:folder},{value:"cancel",label:"Cancel"}]});if(isCancel(choice)||choice==="cancel"){console.log(import_picocolors.default.dim("  Nothing changed."));return}keepContent=choice==="keep"}else{let approved=await confirm({message:"Delete this design folder and everything in it?",initialValue:!1});if(isCancel(approved)||!approved){console.log(import_picocolors.default.dim("  Nothing changed."));return}}if(await stopDaemon(daemonRoot(folder)))console.log(import_picocolors.default.dim("  Stopped its canvas."));let dropped=local?null:await unregisterDesign(folder,cwd).catch((err)=>fail("design remove",err.message));if(local)await removeLocalDesign(local.id);if(!keepContent)await rm(folder,{recursive:!0,force:!0});if(console.log(`velloo design: ${keepContent?"retained content at":"removed"} ${folder}`),local)console.log(import_picocolors.default.dim(`  Forgot the local design "${name}".`));if(dropped?.name)console.log(import_picocolors.default.dim(dropped.removedManifest?`  Dropped "${dropped.name}" \u2014 velloo.json listed no other designs, so it's gone too.`:`  Dropped "${dropped.name}" from velloo.json.`))}}),move=defineCommand({meta:{name:"move",description:"Preview moving a design between the repository, managed storage and another directory; --yes applies"},args:{design:{type:"positional",required:!1,description:DESIGN_ARG_DESCRIPTION},id:DESIGN_ID_ARG,external:{type:"boolean",description:"Move to managed storage (a local design)"},to:{type:"string",description:"New directory \u2014 inside the repository it goes in velloo.json, outside it is local"},yes:{type:"boolean",description:"Apply the displayed move"}},async run({args}){let source=await resolveDesign(args.design,"design move",{id:args.id,interactive:!0,requireConfig:!0}),plan=await planRelocation(source,resolve("."),args.to,args.external===!0).catch((err)=>fail("design move",err.message)),local="a local design on this machine",recorded=plan.sourceManifestPath?plan.destinationLocal?`velloo.json path "${plan.sourceManifestPath}" \u2192 ${"a local design on this machine"}`:`velloo.json path "${plan.sourceManifestPath}" \u2192 "${plan.destinationManifestPath}"`:plan.destinationLocal?"stays a local design on this machine":`${"a local design on this machine"} \u2192 velloo.json path "${plan.destinationManifestPath}"`;if(console.log(`Source: ${plan.source}
 Destination: ${plan.destination}
 Design "${plan.designName}": ${recorded}`),!args.yes){console.log("Preview only. Add --yes to apply the move.");return}await relocateDesign(plan),console.log(`Moved ${plan.designName} to ${plan.destination}. Run velloo connect to refresh existing agent guidance.`)}});async function renameThroughCanvas(folder,name){let rec=await readLock(daemonRoot(folder));if(!rec||!await isLive(rec))return!1;let res;try{res=await fetch(`http://127.0.0.1:${rec.canvasPort}/api/mutate/update_design_name`,{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({name}),signal:AbortSignal.timeout(1e4)})}catch(err){fail("design rename",`the running canvas didn't answer (${err.message}).`)}if(res.ok)return!0;let body=await res.json().catch(()=>null);fail("design rename",body?.error?.message??`the running canvas refused (HTTP ${res.status}).`)}var rename=defineCommand({meta:{name:"rename",description:"Rename a design"},args:{design:{type:"positional",required:!1,description:"The design to rename \u2014 its current name or its folder path (or use --id)"},name:{type:"positional",required:!1,description:"The new name"},id:DESIGN_ID_ARG},async run({args}){let cwd=resolve("."),newName=args.id!==void 0&&args.name===void 0?args.design:args.name,target=args.id!==void 0&&args.name===void 0?void 0:args.design;if(newName===void 0)fail("design rename","pass the design and its new name: `velloo design rename <design> <new name>`.");let folder=await resolveDesign(target,"design rename",{id:args.id,requireConfig:!0,cwd}),previous=recordedDesignName(folder);if(previous===newName){console.log(import_picocolors.default.dim(`  Already named "${newName}" \u2014 nothing changed.`));return}let conflict=await designRenameConflict(folder,newName).catch((err)=>fail("design rename",err.message));if(conflict)fail("design rename",conflict);if(!await renameThroughCanvas(folder,newName)){if(await writeDesignName(folder,newName),previous&&await followDesignRename(folder,previous,newName))console.log(import_picocolors.default.dim(`  velloo.json defaultDesign \u2192 "${newName}"`))}console.log(`velloo design: renamed ${previous?`"${previous}" `:""}to "${newName}".`);let repinned=previous?await repinAgentConfigs({projectRoots:await agentRootCandidates(folder),designFolder:folder,names:[previous]}).catch(()=>[]):[];for(let path of repinned)console.log(import_picocolors.default.dim(`  ${relative(cwd,path)||path}: no longer names the design`))}}),upgrade=defineCommand({meta:{name:"upgrade",description:"Migrate a design to this Velloo's format, without upgrading Velloo itself"},args:{design:{type:"positional",required:!1,description:DESIGN_ARG_DESCRIPTION},id:DESIGN_ID_ARG,all:{type:"boolean",description:"Migrate every design in this checkout"},"dry-run":{type:"boolean",default:!1,description:"Show what would change without writing"},skills:{type:"boolean",default:!0,description:"Also refresh the installed agent skills / plugin / rules to this velloo's versions"}},async run({args}){if(args.all&&(args.design||args.id!==void 0))fail("design upgrade","pass a design or --all, not both.");let folders=args.all?await checkoutDesigns(resolve(".")):[await resolveDesign(args.design,"design upgrade",{id:args.id,interactive:!0,requireConfig:!0})];if(folders.length===0)fail("design upgrade","no designs here \u2014 `velloo init` creates one.");for(let folder of folders)await migrateFolder2(folder,{dryRun:args["dry-run"],skills:args.skills})}}),bind=defineCommand({meta:{name:"bind",description:"Attach a design folder outside this checkout to it, on this machine only"},args:{design:{type:"positional",required:!0,description:"The design folder (in managed storage or anywhere outside the checkout)"},name:{type:"string",description:"Rename the design as it is bound"},yes:{type:"boolean",description:"Confirm the local binding"}},async run({args}){let cwd=resolve("."),folder=resolve(args.design);if(!await hasDesignConfig(folder))fail("design bind",`${folder} is not a velloo design folder (no .design/config.json).`);let root=cwd;if(isWithin(root,folder))fail("design bind",`${folder} is inside this checkout (${root}); a design here belongs in velloo.json \u2014 see \`velloo design add\`.`);let name=args.name??recordedDesignName(folder);if(!name)fail("design bind",`${folder} has no design name \u2014 run \`velloo upgrade ${folder}\` first.`);let issue=designNameIssue(name);if(issue)fail("design bind",`invalid --name ${JSON.stringify(name)} \u2014 ${issue}`);let clash=(await findDesigns(root).catch((err)=>fail("design bind",err.message)))?.designs.find((d)=>d.name===name&&!(existsSync(d.root)&&realpathSync(d.root)===realpathSync(folder)));if(clash)fail("design bind",`a design named "${name}" already exists at ${clash.root} \u2014 pass --name to bind this one under another.`);let existing=localDesignOf(folder),appRoot=existing?join(root,relative(existing.root,existing.appRoot)):root,listed=(await findManifest(cwd).catch(()=>null))?.folders.some((path)=>existsSync(path)&&realpathSync(path)===realpathSync(folder));if(console.log(`Design: ${name} (${folder})
 Checkout: ${root}

package/{chunk-74yxy75r.js → chunk-zv17t1n7.js}

@@ -1,3 +1,3 @@
 // @bun
-import{loadDesignFolder,liveExtensions,LiveBundler,hostAssetRequest,resolveProviders,findHostTailwindConfig,TailwindJit,createCaptureMount,extraThemeBlock}from"./chunk-yfvc8d2g.js";import{join,sep}from"path";var LIVE_BUNDLE_PATH="/live/bundle.js";async function withAssetServer(folder,liveCode,fn,routes={}){let{bundle,host}=routes,assetsRoot=join(folder,"assets"),server=Bun.serve({port:0,hostname:"127.0.0.1",async fetch(req){let url=new URL(req.url),stored=host?.(req);if(stored)return stored;let mounted=bundle?await bundle(url):null;if(mounted!==null)return new Response(mounted,{headers:{"Content-Type":"text/javascript","Access-Control-Allow-Origin":"*"}});if(liveCode!==null&&url.pathname===LIVE_BUNDLE_PATH)return new Response(liveCode,{headers:{"Content-Type":"text/javascript"}});if(url.pathname.startsWith("/assets/")){let fsPath=join(folder,decodeURIComponent(url.pathname));if(fsPath.startsWith(assetsRoot+sep)){let file=Bun.file(fsPath);if(await file.exists())return new Response(file)}}let hostAsset=host&&hostAssetRequest(req),fromHost=hostAsset?host(hostAsset):null;if(fromHost)return fromHost;return new Response("not found",{status:404})}});try{return await fn(`http://127.0.0.1:${server.port}/`)}finally{server.stop(!0)}}import{join as join2}from"path";function createOneShotLiveBundler(root,config){if(Object.keys(liveExtensions(config.extensions)).length===0)return null;return new LiveBundler(root,()=>config,()=>liveExtensions(config.extensions),!0,!0)}async function buildLiveModule(bundler){let bundle=await bundler.build();return{code:bundle.code.length>0?bundle.code:null,warnings:bundle.errors.map((error)=>`live-island: ${error.message}`)}}async function loadPipeline(folderPath){let design=await loadDesignFolder(folderPath),config=design.config,{providers,defaultProvider}=await resolveProviders(config,folderPath),capture=createCaptureMount(design,providers,defaultProvider),liveBundler=createOneShotLiveBundler(folderPath,config),jit=new TailwindJit(Object.values(providers),join2(folderPath,"screens"),void 0,()=>extraThemeBlock(design),()=>[...liveBundler?.hostSourceDirs()??[],...capture.sourceDirs()],()=>findHostTailwindConfig(folderPath,config.hostApp),config.styling?.framework),snapshotCss=await jit.build(),live;return{folderPath,design,config,providers,defaultProvider,jit,snapshotCss,capture,liveModule(){return live??=liveBundler?buildLiveModule(liveBundler):Promise.resolve({code:null,warnings:[]}),live}}}
+import{loadDesignFolder,liveExtensions,LiveBundler,hostAssetRequest,resolveProviders,findHostTailwindConfig,TailwindJit,createCaptureMount,extraThemeBlock}from"./chunk-brnkprt5.js";import{join,sep}from"path";var LIVE_BUNDLE_PATH="/live/bundle.js";async function withAssetServer(folder,liveCode,fn,routes={}){let{bundle,host}=routes,assetsRoot=join(folder,"assets"),server=Bun.serve({port:0,hostname:"127.0.0.1",async fetch(req){let url=new URL(req.url),stored=host?.(req);if(stored)return stored;let mounted=bundle?await bundle(url):null;if(mounted!==null)return new Response(mounted,{headers:{"Content-Type":"text/javascript","Access-Control-Allow-Origin":"*"}});if(liveCode!==null&&url.pathname===LIVE_BUNDLE_PATH)return new Response(liveCode,{headers:{"Content-Type":"text/javascript"}});if(url.pathname.startsWith("/assets/")){let fsPath=join(folder,decodeURIComponent(url.pathname));if(fsPath.startsWith(assetsRoot+sep)){let file=Bun.file(fsPath);if(await file.exists())return new Response(file)}}let hostAsset=host&&hostAssetRequest(req),fromHost=hostAsset?host(hostAsset):null;if(fromHost)return fromHost;return new Response("not found",{status:404})}});try{return await fn(`http://127.0.0.1:${server.port}/`)}finally{server.stop(!0)}}import{join as join2}from"path";function createOneShotLiveBundler(root,config){if(Object.keys(liveExtensions(config.extensions)).length===0)return null;return new LiveBundler(root,()=>config,()=>liveExtensions(config.extensions),!0,!0)}async function buildLiveModule(bundler){let bundle=await bundler.build();return{code:bundle.code.length>0?bundle.code:null,warnings:bundle.errors.map((error)=>`live-island: ${error.message}`)}}async function loadPipeline(folderPath){let design=await loadDesignFolder(folderPath),config=design.config,{providers,defaultProvider}=await resolveProviders(config,folderPath),capture=createCaptureMount(design,providers,defaultProvider),liveBundler=createOneShotLiveBundler(folderPath,config),jit=new TailwindJit(Object.values(providers),join2(folderPath,"screens"),void 0,()=>extraThemeBlock(design),()=>[...liveBundler?.hostSourceDirs()??[],...capture.sourceDirs()],()=>findHostTailwindConfig(folderPath,config.hostApp),config.styling?.framework),snapshotCss=await jit.build(),live;return{folderPath,design,config,providers,defaultProvider,jit,snapshotCss,capture,liveModule(){return live??=liveBundler?buildLiveModule(liveBundler):Promise.resolve({code:null,warnings:[]}),live}}}
 export{LIVE_BUNDLE_PATH,withAssetServer,createOneShotLiveBundler,buildLiveModule,loadPipeline};

package/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
 // @bun
-import"./chunk-s23gtejf.js";import{COMMANDS}from"./chunk-ff0jfn0v.js";import{TOOL_VERSION}from"./chunk-t6qr2ay9.js";import{maybeNotifyAboutUpdate}from"./chunk-rk238m15.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-acsv6m3n.js";import{TOOL_VERSION}from"./chunk-3m28pvzr.js";import{maybeNotifyAboutUpdate}from"./chunk-s84vxcdv.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

@@ -80,7 +80,9 @@ const runtime = join(runtimeRoot, "bin", process.platform === "win32" ? "bun.exe
 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)], {
+// `--no-install`: Bun must never answer an import from its global cache or
+// fetch a package to do it — see BUN_RUNTIME_FLAGS in src/bun-runtime.ts.
+const child = spawnSync(runtime, ["--no-install", app, ...process.argv.slice(2)], {
   stdio: "inherit",
   env: {
     ...process.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velloo",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/pkgs/helpers/src/box.tsx

@@ -9,13 +9,19 @@ 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]*$/;
+/**
+ * An element name: an HTML tag, or one of SVG's camelCase ones
+ * (`linearGradient`, `clipPath`). Shared by everything that has to agree on
+ * what `as` may hold — compose's lowering, each `Box`, and codegen — because a
+ * tag one of them accepts and another doesn't renders as a `div`.
+ */
+export const ELEMENT_TAG = /^[a-z][a-zA-Z0-9]*$/;
 
+// Restrict `as` to an element 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.
 export function Box({ as, className, ...props }: React.ComponentProps<"div"> & { as?: string }) {
-  const tag = typeof as === "string" && TAG.test(as) ? as : "div";
+  const tag = typeof as === "string" && ELEMENT_TAG.test(as) ? as : "div";
   return createElement(tag, { "data-slot": "box", className: cn(className), ...props });
 }

package/pkgs/helpers/src/descriptors.ts

@@ -233,6 +233,12 @@ export const HELPER_DESCRIPTORS: readonly ComponentDescriptor[] = [
     props: [
       { name: "content", type: "string | undefined", optional: true, control: "string" },
       { name: "viewBox", type: "string | undefined", optional: true, control: "string" },
+      {
+        name: "preserveAspectRatio",
+        type: "string | undefined",
+        optional: true,
+        control: "string",
+      },
       { name: "color", type: "string | undefined", optional: true, control: "color" },
     ],
     example: {

package/pkgs/helpers/src/icon.tsx

@@ -27,11 +27,13 @@ function lookup(name: string): IconNode | undefined {
   return viaPascal === undefined ? undefined : ICON_NODES[viaPascal];
 }
 
-const FALLBACK = lookup("HelpCircle");
-
 export function Icon({ name, className, size = 16, strokeWidth = 2, ...props }: IconProps) {
   const hit = lookup(name);
-  const node = hit ?? FALLBACK;
+  // Looked up here, not once at module level: a call at the top of this file
+  // is a side effect to a bundler, which then keeps the module — and the 0.6 MB
+  // of icon data behind it — in every bundle that imports anything at all from
+  // the helpers index, `Icon` on the screen or not.
+  const node = hit ?? lookup("HelpCircle");
   if (!node) return null;
   const tint = hit ? className : cn("text-[var(--color-fg-muted)]", className);
   return (

package/pkgs/helpers/src/index.ts

@@ -1,4 +1,4 @@
-export { Box } from "./box.tsx";
+export { Box, ELEMENT_TAG } from "./box.tsx";
 export { cn, mergeTailwind } from "./cn.ts";
 export { HELPER_DESCRIPTORS, helperDescriptors } from "./descriptors.ts";
 export { Divider, type DividerProps } from "./divider.tsx";
@@ -29,4 +29,4 @@ export {
 export { Prose, type ProseProps } from "./prose.tsx";
 export { helpersRegistry } from "./registry.ts";
 export { SVG, type SVGProps } from "./svg.tsx";
-export { Text, type TextProps } from "./text.tsx";
+export { Text, type TextProps, TextRunContext, textTag } from "./text.tsx";

package/pkgs/helpers/src/text.tsx

@@ -3,14 +3,38 @@ import { textClasses } from "@velloo/schema/typeset";
 import * as React from "react";
 import { cn } from "./cn.ts";
 
-export interface TextProps extends React.HTMLAttributes<HTMLParagraphElement> {
+export interface TextProps extends React.HTMLAttributes<HTMLElement> {
   /** Visual weight. Selects a rung of the theme's type ladder plus a tone. */
   variant?: "default" | "muted" | "small" | "lead";
 }
 
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(
-  ({ variant = "default", className, ...props }, ref) => (
-    <p ref={ref} className={cn(textClasses(variant), className)} {...props} />
-  ),
+/**
+ * True beneath a `Text`. A paragraph cannot hold a paragraph: an HTML parser
+ * ends the outer `<p>` where the inner one starts, so markup that is rendered
+ * on the server and parsed again (a screenshot, a comparison) lays the inner
+ * text out as a sibling, while the same tree mounted on the client keeps it
+ * nested. A `Text` inside a `Text` is a run of that paragraph, so it renders
+ * the element a run is — and every path draws the same line.
+ */
+export const TextRunContext = React.createContext(false);
+
+/** The element a `Text` renders: a paragraph, or a run inside one. */
+export function textTag(run: boolean): "p" | "span" {
+  return run ? "span" : "p";
+}
+
+export const Text = React.forwardRef<HTMLElement, TextProps>(
+  ({ variant, className, ...props }, ref) => {
+    const run = React.useContext(TextRunContext);
+    return (
+      <TextRunContext.Provider value={true}>
+        {React.createElement(textTag(run), {
+          ref,
+          className: cn(textClasses(variant, run), className) || undefined,
+          ...props,
+        })}
+      </TextRunContext.Provider>
+    );
+  },
 );
 Text.displayName = "Text";

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

@@ -838,6 +838,7 @@ export const ANTD_MANIFEST: Manifest = [
     [
       { name: "content", type: "string", optional: false, control: "string" },
       { name: "viewBox", type: "string", optional: false, control: "string" },
+      { name: "preserveAspectRatio", type: "string", optional: true, control: "string" },
     ],
     "Raw inline SVG markup.",
   ),

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

@@ -403,6 +403,7 @@ export const CHAKRA_MANIFEST: Manifest = [
     [
       { name: "content", type: "string", optional: false, control: "string" },
       { name: "viewBox", type: "string", optional: false, control: "string" },
+      { name: "preserveAspectRatio", type: "string", optional: true, control: "string" },
     ],
     "Raw inline SVG markup.",
   ),

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

@@ -250,6 +250,7 @@ export const MUI_MANIFEST: Manifest = [
     [
       { name: "content", type: "string", optional: false, control: "string" },
       { name: "viewBox", type: "string", optional: false, control: "string" },
+      { name: "preserveAspectRatio", type: "string", optional: true, control: "string" },
     ],
     "Raw inline SVG markup.",
   ),

package/pkgs/provider-none/src/components-inline.tsx

@@ -1,12 +1,7 @@
+import { ELEMENT_TAG, TextRunContext, textTag } from "@velloo/helpers";
 import { headingInlineStyle, textInlineStyle } from "@velloo/schema/typeset";
 import * as React from "react";
-import {
-  BOX_TAG,
-  type ButtonProps,
-  type ContainerProps,
-  type InputProps,
-  type StackProps,
-} from "./components.tsx";
+import type { ButtonProps, ContainerProps, InputProps, StackProps } from "./components.tsx";
 
 /**
  * Inline-styled variants of the no-library primitives, for a `none`-CSS folder
@@ -38,7 +33,10 @@ export const Box = React.forwardRef<
   HTMLDivElement,
   React.HTMLAttributes<HTMLDivElement> & { as?: string }
 >(({ as, ...rest }, ref) =>
-  React.createElement(typeof as === "string" && BOX_TAG.test(as) ? as : "div", { ref, ...rest }),
+  React.createElement(typeof as === "string" && ELEMENT_TAG.test(as) ? as : "div", {
+    ref,
+    ...rest,
+  }),
 );
 Box.displayName = "Box";
 
@@ -201,13 +199,21 @@ export const Heading = React.forwardRef<HTMLHeadingElement, HeadingProps>(
 );
 Heading.displayName = "Heading";
 
-interface TextProps extends React.HTMLAttributes<HTMLParagraphElement> {
+interface TextProps extends React.HTMLAttributes<HTMLElement> {
   variant?: "default" | "muted" | "small" | "lead";
 }
 
-export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(
-  ({ variant = "default", style, ...rest }, ref) => (
-    <p ref={ref} style={merge(textInlineStyle(variant), style)} {...rest} />
-  ),
-);
+// A `Text` inside a `Text` is a run of it — see `TextRunContext`.
+export const Text = React.forwardRef<HTMLElement, TextProps>(({ variant, style, ...rest }, ref) => {
+  const run = React.useContext(TextRunContext);
+  return (
+    <TextRunContext.Provider value={true}>
+      {React.createElement(textTag(run), {
+        ref,
+        style: merge(textInlineStyle(variant, run), style),
+        ...rest,
+      })}
+    </TextRunContext.Provider>
+  );
+});
 Text.displayName = "Text";

package/pkgs/provider-none/src/components.tsx

@@ -3,6 +3,7 @@ import {
   BUTTON_VARIANT_CLASS,
   CARD_CLASS,
   CONTAINER_WIDTH_CLASS,
+  ELEMENT_TAG,
   INPUT_CLASS,
   STACK_ALIGN_CLASS,
   STACK_JUSTIFY_CLASS,
@@ -23,12 +24,9 @@ import * as React from "react";
 
 interface DivProps extends React.HTMLAttributes<HTMLDivElement> {}
 
-/** `as` takes a lowercase HTML tag only — anything else renders the div. */
-export const BOX_TAG = /^[a-z][a-z0-9]*$/;
-
 export const Box = React.forwardRef<HTMLDivElement, DivProps & { as?: string }>(
   ({ as, className, ...rest }, ref) =>
-    React.createElement(typeof as === "string" && BOX_TAG.test(as) ? as : "div", {
+    React.createElement(typeof as === "string" && ELEMENT_TAG.test(as) ? as : "div", {
       ref,
       className: clsx(className),
       ...rest,

package/pkgs/schema/src/config.ts

@@ -106,6 +106,9 @@ export const HostAppSchema = z.object({
 
 export type HostApp = z.infer<typeof HostAppSchema>;
 
+/** The CSS framework a folder styles with. See `ConfigSchema.styling`. */
+export const StylingSchema = z.object({ framework: z.enum(["tailwind", "none"]) });
+
 /**
  * Folder config. Multi-library: a folder registers N libraries by id
  * and pins one as the default; each screen optionally declares which
@@ -186,7 +189,7 @@ export const ConfigSchema = z
      * server rejects a folder whose CSS framework no registered library
      * supports (e.g. shadcn + none).
      */
-    styling: z.object({ framework: z.enum(["tailwind", "none"]) }).optional(),
+    styling: StylingSchema.optional(),
     /** Host app location for the live-island bundler. See `HostAppSchema`. */
     hostApp: HostAppSchema.optional(),
     /**

package/pkgs/schema/src/index.ts

@@ -53,6 +53,7 @@ export {
   HostAppSchema,
   type Library,
   LibrarySchema,
+  StylingSchema,
   type ViewportPreset,
   ViewportPresetSchema,
 } from "./config.ts";
@@ -99,6 +100,7 @@ export {
   isParamRef,
   isRepoNode,
   isSnippetInstance,
+  isTextNode,
   type Node,
   NodeIdSchema,
   NodeSchema,
@@ -110,6 +112,7 @@ export {
   repoImportIssue,
   repoKey,
   type SnippetInstance,
+  type TextNode,
 } from "./node.ts";
 export {
   type EmitAsNode,

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

@@ -4,10 +4,12 @@ import {
   isComponentNode,
   isParamRef,
   isSnippetInstance,
+  isTextNode,
   type Node,
   type ParamRef,
   type RepoComponentRef,
   type SnippetInstance,
+  type TextNode,
 } from "./node.ts";
 
 /**
@@ -46,7 +48,7 @@ export type EmitAsNode = ComponentNode & { $emitAs: EmitAsRef };
  * The order of the `$`-keys is the contract, stated here once and nowhere
  * else: `$snippet`, then `$param`, then a component — where an identity
  * (`$repo`) beats an emit-time facade (`$emitAs`) beats a synthetic ref beats
- * a plain name. A malformed value carrying both `$snippet` and `$ref` is a
+ * a plain name — then `$text`. A malformed value carrying both `$snippet` and `$ref` is a
  * snippet instance, as every walker has always read it.
  */
 export type NodeShape =
@@ -56,6 +58,8 @@ export type NodeShape =
   | { kind: "named"; node: ComponentNode; ref: string }
   | { kind: "snippet"; node: SnippetInstance }
   | { kind: "param"; node: ParamRef }
+  /** A run of text beside elements: a bare text node, no element of its own. */
+  | { kind: "text"; node: TextNode; text: string }
   /** Not a node at all — a raw scalar or object sitting in a node position. */
   | { kind: "invalid"; value: unknown };
 
@@ -79,6 +83,7 @@ export function nodeShape(value: unknown): NodeShape {
     }
     return { kind: "named", node, ref: node.$ref };
   }
+  if (isTextNode(node)) return { kind: "text", node, text: node.$text };
   return { kind: "invalid", value };
 }
 

package/pkgs/schema/src/node.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 /**
- * A node tree is a discriminated union over three shapes, distinguished by
+ * A node tree is a discriminated union over four shapes, distinguished by
  * which `$`-prefixed key is present:
  *
  * - `ComponentNode` — a real shadcn / velloo component (`{ $ref }`).
@@ -13,6 +13,11 @@ import { z } from "zod";
  *   substituted with the corresponding instance arg at render time. May
  *   appear as a child node OR anywhere inside a `props` value via the
  *   normal JSON walk during substitution.
+ * - `TextNode` — `{ $text }`. A run of text sitting beside elements
+ *   (`<li>Remote <a>Apply</a></li>`). It renders as a bare text node, with no
+ *   element of its own, so no selector in the app's stylesheet can tell the
+ *   design's DOM from the app's. Text that is a component's *whole* content
+ *   stays in `props.children`.
  *
  * Optional fields are spelled `?: T | undefined` rather than `?: T`. Under
  * `exactOptionalPropertyTypes` those differ, but not for a shape that round-
@@ -116,7 +121,11 @@ export type ParamRef = {
   $param: string;
 };
 
-export type Node = ComponentNode | SnippetInstance | ParamRef;
+export type TextNode = {
+  $text: string;
+};
+
+export type Node = ComponentNode | SnippetInstance | ParamRef | TextNode;
 
 export function isComponentNode(n: Node): n is ComponentNode {
   return typeof (n as { $ref?: unknown }).$ref === "string";
@@ -130,6 +139,10 @@ export function isParamRef(n: Node): n is ParamRef {
   return typeof (n as { $param?: unknown }).$param === "string";
 }
 
+export function isTextNode(n: Node): n is TextNode {
+  return typeof (n as { $text?: unknown }).$text === "string";
+}
+
 /**
  * Format constraint for `$id` values. Must start with a letter; the rest
  * is letters / digits / dashes / underscores. Matches typical anchor
@@ -147,18 +160,16 @@ export const NodeIdSchema = z
 
 /**
  * A bare string/number in a `children` array is a common first-try shape
- * ("just put the label here"). Rather than reject it — `children` renders
- * nodes only — auto-wrap it into an inline `Box as="span"` so it renders as
- * text without stacking. Wrapping (vs. allowing scalars through) keeps
- * `children` typed `Node[]` for every downstream consumer. The styled-run
- * idiom (a mixed array in the `children` *prop*) is still preferred for rich
- * text; this just removes a needless failure.
+ * ("just put the label here"), and it means what it says: text. It becomes a
+ * text node rather than being rejected, which keeps `children` typed `Node[]`
+ * for every downstream consumer. An empty string is nothing to hold.
  */
-function wrapScalarChild(item: string | number | Node): Node {
-  if (typeof item === "string" || typeof item === "number") {
-    return { $ref: "Box", props: { as: "span", children: item } };
-  }
-  return item;
+function scalarChildren(items: (string | number | Node)[]): Node[] {
+  return items.flatMap((item): Node[] => {
+    if (typeof item !== "string" && typeof item !== "number") return [item];
+    const text = String(item);
+    return text === "" ? [] : [{ $text: text }];
+  });
 }
 
 const EmitAsSchema = z.object({
@@ -209,7 +220,7 @@ const ComponentNodeSchema: z.ZodType<ComponentNode> = z.lazy(() =>
     props: z.record(z.string(), z.unknown()).optional(),
     children: z
       .array(z.union([z.string(), z.number(), NodeSchema]))
-      .transform((items) => items.map(wrapScalarChild))
+      .transform(scalarChildren)
       .optional(),
     $emitAs: EmitAsSchema.optional(),
     $repo: RepoComponentRefSchema.optional(),
@@ -267,10 +278,14 @@ const ParamRefSchema: z.ZodType<ParamRef> = z.object({
   $param: z.string().min(1),
 });
 
+const TextNodeSchema: z.ZodType<TextNode> = z.strictObject({
+  $text: z.string().min(1),
+});
+
 /**
  * Key-routed parse instead of `z.union`: a malformed node yields the
  * issues of the *one* branch its `$`-key selects (with a full path),
- * not a three-branch union explosion. The MCP layer surfaces these
+ * not a four-branch union explosion. The MCP layer surfaces these
  * issues verbatim to agents, so error shape is part of the tool UX.
  */
 export const NodeSchema: z.ZodType<Node> = z
@@ -280,7 +295,7 @@ export const NodeSchema: z.ZodType<Node> = z
       ctx.addIssue({
         code: "custom",
         message:
-          'node must be an object with one of "$ref" (component), "$snippet" (instance), or "$param" (param ref)',
+          'node must be an object with one of "$ref" (component), "$snippet" (instance), "$param" (param ref), or "$text" (text beside elements)',
       });
       return z.NEVER;
     }
@@ -292,12 +307,14 @@ export const NodeSchema: z.ZodType<Node> = z
           ? SnippetInstanceSchema
           : typeof v.$param === "string"
             ? ParamRefSchema
-            : null;
+            : typeof v.$text === "string"
+              ? TextNodeSchema
+              : null;
     if (!branch) {
       ctx.addIssue({
         code: "custom",
         message:
-          'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), or "$param" (param ref, snippet bodies only)',
+          'node needs exactly one of "$ref" (component), "$snippet" (snippet instance), "$param" (param ref, snippet bodies only), or "$text" (text beside elements)',
       });
       return z.NEVER;
     }
@@ -332,6 +349,6 @@ export const NodeSchema: z.ZodType<Node> = z
  * have to narrow by node kind first.
  */
 export function nodeId(n: Node): string | undefined {
-  if (isParamRef(n)) return undefined;
+  if (isParamRef(n) || isTextNode(n)) return undefined;
   return (n as { $id?: string }).$id;
 }

package/pkgs/schema/src/snippet-resolve.ts

@@ -48,7 +48,7 @@ function isTruthy(v: unknown): boolean {
   return true;
 }
 
-/** A `$param` that substituted to a scalar where a child node was expected. */
+/** A `$param` that substituted to a boolean or null where a child node was expected. */
 export interface InvalidParamPlacement {
   param: string;
   /** typeof the resolved value (or "null") — for a precise error message. */
@@ -63,13 +63,17 @@ export interface InvalidParamPlacement {
  * Unknown param names are collected in `missing` (the offending
  * substitution resolves to undefined) rather than thrown.
  *
- * `invalid` collects scalar params dropped into a *node* position — a
- * component node's own `children` array, where only subtrees render. This
- * is the classic mis-wire (a `string` param used as a child instead of as
- * a prop value); flagging it lets the renderer name the param and point at
- * the fix instead of failing opaquely deep in React. A `children` *prop*
- * value (`props.children`) is plain content, not a node position, so a
- * scalar param there is correct and never flagged.
+ * A string or number param in a *node* position — a component node's own
+ * `children` array — is the text it holds, and becomes a text node, exactly
+ * as a bare string written there does (`scalarChildren` in node.ts). It was a
+ * refusal before text nodes existed, and one that only surfaced at the next
+ * render: the write was accepted, and the screenshot after it failed. An
+ * empty string is nothing to hold.
+ *
+ * `invalid` collects what is left: a boolean or null param in a node position,
+ * which is a flag wired where content goes. A `children` *prop* value
+ * (`props.children`) is plain content, not a node position, so any scalar
+ * param there is correct and never flagged.
  */
 export function substituteSnippetParams(
   value: unknown,
@@ -92,11 +96,13 @@ export function substituteSnippetParams(
       const resolved = args[name];
       // An omitted optional param resolves to nothing — never a mis-wire.
       if (resolved === OMITTED) return DROP;
-      if (inNodePosition && (resolved === null || typeof resolved !== "object")) {
-        invalid.push({ param: name, valueType: resolved === null ? "null" : typeof resolved });
-        return undefined;
+      if (!inNodePosition || (resolved !== null && typeof resolved === "object")) return resolved;
+      if (typeof resolved === "string" || typeof resolved === "number") {
+        const text = String(resolved);
+        return text === "" ? DROP : { $text: text };
       }
-      return resolved;
+      invalid.push({ param: name, valueType: resolved === null ? "null" : typeof resolved });
+      return undefined;
     }
     if (typeof (v as { $if?: unknown }).$if === "string") {
       const cond = v as { $if: string; eq?: unknown; then?: unknown; else?: unknown };

package/pkgs/schema/src/svg-sanitize.ts

@@ -76,6 +76,9 @@ const ALLOWED_ELEMENTS: ReadonlyMap<string, string> = new Map(
   ].map((name) => [name.toLowerCase(), name]),
 );
 
+/** The static SVG elements, by their canonical (camelCase) names. */
+export const SVG_ELEMENT_NAMES: ReadonlySet<string> = new Set(ALLOWED_ELEMENTS.values());
+
 /**
  * Elements whose presence means the input tried to run or load something.
  * They are dropped like any unknown element; naming them is what lets