@stackable-labs/mcp-app-extension 1.2.0 → 1.4.0

package/dist/index.js

@@ -2801,6 +2801,324 @@ narrow widths:
 `;
 };
 
+// ../../sdk/extension/ai-docs/src/generators/tailwind-utilities.ts
+var SAFELIST_DIRECTIVES = [
+  "m-{0,0.5,1,1.5,2,2.5,3,3.5,4,5,6,7,8,9,10,11,12,14,16}",
+  "mx-{0,1,2,3,4,5,6,8,10,12,16,auto} my-{0,1,2,3,4,5,6,8,10,12,16}",
+  "mt-{0,1,2,3,4,5,6,8,10,12,16} mb-{0,1,2,3,4,5,6,8,10,12,16}",
+  "ml-{0,1,2,3,4,5,6,8,10,12,16,auto} mr-{0,1,2,3,4,5,6,8,10,12,16,auto}",
+  "p-{0,0.5,1,1.5,2,2.5,3,3.5,4,5,6,7,8,9,10,11,12,14,16}",
+  "px-{0,1,2,3,4,5,6,8,10,12,16} py-{0,1,2,3,4,5,6,8,10,12,16}",
+  "pt-{0,1,2,3,4,5,6,8,10,12,16} pb-{0,1,2,3,4,5,6,8,10,12,16}",
+  "pl-{0,1,2,3,4,5,6,8,10,12,16} pr-{0,1,2,3,4,5,6,8,10,12,16}",
+  "gap-{0,1,2,3,4,5,6,8,10,12} gap-x-{0,1,2,3,4,5,6,8} gap-y-{0,1,2,3,4,5,6,8}",
+  "text-{xs,sm,base,lg,xl,2xl}",
+  "font-{light,normal,medium,semibold,bold,extrabold}",
+  "uppercase lowercase capitalize normal-case",
+  "tracking-{tight,normal,wide,wider,widest}",
+  "leading-{none,tight,snug,normal,relaxed,loose}",
+  "opacity-{0,5,10,20,25,30,40,50,60,70,75,80,90,95,100}",
+  "block inline inline-block flex inline-flex grid hidden",
+  "flex-{1,auto,initial,none,row,col,wrap,nowrap,row-reverse,col-reverse}",
+  "justify-{start,end,center,between,around,evenly}",
+  "items-{start,end,center,baseline,stretch}",
+  "self-{auto,start,end,center,stretch,baseline}",
+  "w-{0,full,auto,screen,1/2,1/3,2/3,1/4,3/4,1,2,3,4,5,6,8,10,12,16,20,24,32,48}",
+  "h-{0,full,auto,screen,1/2,1/3,2/3,1/4,3/4,1,2,3,4,5,6,8,10,12,16,20,24,32,48}",
+  "min-w-{0,full,fit,min,max} max-w-{none,xs,sm,md,lg,xl,2xl,3xl,4xl,5xl,full,fit}",
+  "aspect-{auto,square,video} aspect-[9/16]",
+  "rounded-{none,sm,md,lg,xl,2xl,3xl,full}",
+  "border border-{0,2,4,8} border-{x,y,t,b,l,r}",
+  "cursor-{pointer,default,not-allowed,wait,text,move,help}",
+  "overflow-{auto,hidden,visible,scroll}",
+  "overflow-x-{auto,hidden,scroll} overflow-y-{auto,hidden,scroll}",
+  "transition transition-{none,all,colors,opacity,transform}",
+  "duration-{75,100,150,200,300,500,700,1000} ease-{linear,in,out,in-out}",
+  "shadow-{sm,md,lg,xl,2xl,none,inner}",
+  "relative absolute fixed sticky static",
+  "z-{0,10,20,30,40,50,auto}",
+  "text-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "bg-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "border-{zinc,slate,gray}-{100,200,300,400} border-transparent",
+  "hover:opacity-{50,75,80,90,100}",
+  "hover:text-{zinc,slate,gray,neutral}-{500,600,700,800,900}",
+  "hover:text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "hover:bg-{zinc,slate,gray,neutral}-{50,100,200}",
+  "hover:bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "focus:outline-none focus:ring-2 focus:ring-offset-2",
+  "disabled:opacity-50 disabled:cursor-not-allowed",
+  "dark:text-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "dark:text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "dark:bg-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "dark:bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "dark:border-{zinc,slate,gray}-{600,700,800,900} dark:border-transparent",
+  "dark:hover:text-{zinc,slate,gray}-{50,100,200,300,400}",
+  "dark:hover:bg-{zinc,slate,gray}-{700,800,900}"
+];
+var INLINE_DIRECTIVE_RE = /@source\s+inline\(\s*'([^']+)'\s*\)\s*;/g;
+var expand = (token) => {
+  const m = token.match(/\{([^{}]+)\}/);
+  if (!m) {
+    return [token];
+  }
+  const head = token.slice(0, m.index);
+  const tail = token.slice(m.index + m[0].length);
+  const out = [];
+  for (const opt of m[1].split(",")) {
+    out.push(...expand(head + opt + tail));
+  }
+  return out;
+};
+var stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, "");
+var parseSafelist = (css) => {
+  const stripped = stripComments(css);
+  const classes = [];
+  for (const match of stripped.matchAll(INLINE_DIRECTIVE_RE)) {
+    for (const tok of match[1].split(/\s+/)) {
+      if (tok) {
+        classes.push(...expand(tok));
+      }
+    }
+  }
+  return classes;
+};
+var classifyFamily = (cls) => {
+  if (cls.startsWith("dark:hover:text-")) return "Dark \u2014 hover text";
+  if (cls.startsWith("dark:hover:bg-")) return "Dark \u2014 hover background";
+  if (cls.startsWith("dark:text-")) return "Dark \u2014 text color";
+  if (cls.startsWith("dark:bg-")) return "Dark \u2014 background color";
+  if (cls.startsWith("dark:border-")) return "Dark \u2014 border color";
+  if (cls.startsWith("hover:opacity-")) return "Hover \u2014 opacity";
+  if (cls.startsWith("hover:text-")) return "Hover \u2014 text color";
+  if (cls.startsWith("hover:bg-")) return "Hover \u2014 background color";
+  if (cls.startsWith("focus:")) return "Focus";
+  if (cls.startsWith("disabled:")) return "Disabled";
+  if (/^(m|mx|my|mt|mb|ml|mr)-/.test(cls)) {
+    return "Margin";
+  }
+  if (/^(p|px|py|pt|pb|pl|pr)-/.test(cls)) {
+    return "Padding";
+  }
+  if (/^gap(-x|-y)?-/.test(cls)) {
+    return "Gap";
+  }
+  if (/^(min-w|max-w|min-h|max-h)-/.test(cls)) {
+    return "Sizing constraints";
+  }
+  if (/^(w|h)-/.test(cls)) {
+    return "Width / Height";
+  }
+  if (/^text-(xs|sm|base|lg|xl|2xl)$/.test(cls)) {
+    return "Text size";
+  }
+  if (/^text-([a-z]+)-(\d+)$/.test(cls)) {
+    return "Text color";
+  }
+  if (/^font-/.test(cls)) {
+    return "Font weight";
+  }
+  if (["uppercase", "lowercase", "capitalize", "normal-case"].includes(cls)) {
+    return "Text transform";
+  }
+  if (/^tracking-/.test(cls)) {
+    return "Letter spacing (tracking)";
+  }
+  if (/^leading-/.test(cls)) {
+    return "Line height (leading)";
+  }
+  if (/^bg-([a-z]+)-(\d+)$/.test(cls)) {
+    return "Background color";
+  }
+  if (/^border-([a-z]+)-(\d+)$/.test(cls) || cls === "border-transparent") {
+    return "Border color";
+  }
+  if (/^(block|inline|inline-block|flex|inline-flex|grid|hidden)$/.test(cls)) {
+    return "Display";
+  }
+  if (/^flex-/.test(cls)) {
+    return "Flex";
+  }
+  if (/^justify-/.test(cls)) {
+    return "Justify content";
+  }
+  if (/^items-/.test(cls)) {
+    return "Align items";
+  }
+  if (/^self-/.test(cls)) {
+    return "Align self";
+  }
+  if (/^aspect-/.test(cls)) {
+    return "Aspect ratio";
+  }
+  if (/^opacity-/.test(cls)) {
+    return "Opacity";
+  }
+  if (/^rounded(-|$)/.test(cls)) {
+    return "Border radius";
+  }
+  if (/^border(-|$)/.test(cls) && !/^border-([a-z]+)-(\d+)$/.test(cls) && cls !== "border-transparent") {
+    return "Border width";
+  }
+  if (/^cursor-/.test(cls)) {
+    return "Cursor";
+  }
+  if (/^overflow(-|$)/.test(cls)) {
+    return "Overflow";
+  }
+  if (/^transition(-|$)/.test(cls) || /^duration-/.test(cls) || /^ease-/.test(cls)) {
+    return "Transition";
+  }
+  if (/^shadow(-|$)/.test(cls)) {
+    return "Box shadow";
+  }
+  if (/^(relative|absolute|fixed|sticky|static)$/.test(cls)) {
+    return "Position";
+  }
+  if (/^z-/.test(cls)) {
+    return "Z-index";
+  }
+  return "Other";
+};
+var SECTIONS = [
+  {
+    title: "Utility families",
+    families: [
+      "Margin",
+      "Padding",
+      "Gap",
+      "Width / Height",
+      "Sizing constraints",
+      "Aspect ratio",
+      "Display",
+      "Flex",
+      "Justify content",
+      "Align items",
+      "Align self",
+      "Position",
+      "Z-index",
+      "Overflow",
+      "Text size",
+      "Font weight",
+      "Text transform",
+      "Letter spacing (tracking)",
+      "Line height (leading)",
+      "Text color",
+      "Background color",
+      "Border color",
+      "Border width",
+      "Border radius",
+      "Opacity",
+      "Box shadow",
+      "Cursor",
+      "Transition",
+      "Other"
+    ]
+  },
+  {
+    title: "State variants",
+    families: [
+      "Focus",
+      "Disabled",
+      "Hover \u2014 opacity",
+      "Hover \u2014 text color",
+      "Hover \u2014 background color"
+    ]
+  },
+  {
+    title: "Theme variants",
+    families: [
+      "Dark \u2014 text color",
+      "Dark \u2014 background color",
+      "Dark \u2014 border color",
+      "Dark \u2014 hover text",
+      "Dark \u2014 hover background"
+    ]
+  }
+];
+var groupBySection = (classes) => {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const cls of classes) {
+    const family = classifyFamily(cls);
+    const arr = buckets.get(family) ?? [];
+    arr.push(cls);
+    buckets.set(family, arr);
+  }
+  return SECTIONS.map((section) => ({
+    title: section.title,
+    families: section.families.filter((label) => buckets.has(label)).map((label) => ({
+      label,
+      classes: buckets.get(label).sort((a2, b2) => a2.localeCompare(b2, void 0, { numeric: true }))
+    }))
+  })).filter((s) => s.families.length > 0);
+};
+var renderFamilySection = (group) => {
+  const lines = [];
+  lines.push(`### ${group.label} (${group.classes.length})`);
+  lines.push("");
+  const formatted = group.classes.map((c) => `\`${c}\``).join(", ");
+  lines.push(formatted);
+  lines.push("");
+  return lines.join("\n");
+};
+var generateTailwindUtilities = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Tailwind utility classes pre-emitted in the embedded widget bundle that extensions can use without shipping their own CSS",
+    globs: ["packages/extension/src/**/*.tsx"]
+  });
+  const css = SAFELIST_DIRECTIVES.map((d2) => `@source inline('${d2}');`).join("\n");
+  const classes = parseSafelist(css);
+  const sectionsData = groupBySection(classes);
+  const familyCount = sectionsData.reduce((sum, s) => sum + s.families.length, 0);
+  const sectionsMd = sectionsData.map((section) => {
+    const familyBlocks = section.families.map(renderFamilySection).join("\n");
+    return `## ${section.title}
+
+${familyBlocks}`;
+  }).join("\n");
+  return `${fm}
+
+# Supported Tailwind Utilities
+
+Stackable extensions render inside the embedded widget's Shadow Root via the platform and ship **zero custom CSS by design** \u2014 they rely entirely on the platforms's bundled stylesheet for their visual styling. To keep that bundle small while still covering the common needs of extension UI, the platform pre-emits a curated subset of Tailwind v4 utility classes via a safelist. The classes listed below are guaranteed to be available in any extension that uses them.
+
+Total: **${classes.length} utility classes** across **${familyCount} families**.
+
+## Using utilities
+
+Apply them via the \`className\` prop on \`ui.*\` components:
+
+\`\`\`tsx
+<ui.Card className="mt-4 p-6">
+  <ui.Stack className="gap-3">
+    <ui.Text className="text-lg font-semibold uppercase tracking-wide">Title</ui.Text>
+    <ui.Text className="text-zinc-600">Body copy</ui.Text>
+  </ui.Stack>
+</ui.Card>
+\`\`\`
+
+Always prefer:
+- Component variants (\`<ui.Button variant="primary">\`) over color overrides
+- Layout components (\`<ui.Stack>\`, \`<ui.Inline>\`) over manual flexbox class chains
+- The semantic color tokens (\`text-foreground\`, \`bg-background\`) which adapt to the host theme
+
+## Safelist limits
+
+The safelist is intentionally a fixed list, **NOT the full Tailwind catalog** to provide UI consistency and reduce bundle size. Anything beyond what is listed below will be missing from the platform stylesheet at runtime \u2014 the class will appear in your DOM but the corresponding CSS rule will not exist, and the style will silently no-op. In particular:
+
+- **Arbitrary values are NOT supported** in general (e.g. \`w-[123px]\`, \`bg-[#1a1a1a]\`, \`text-[15px]\`). The single exception is \`aspect-[9/16]\` (portrait video). For any other arbitrary value, use the named utility closest to your target.
+- **Off-list color shades** (e.g. \`bg-cyan-500\`, \`text-rose-500\`) are not pre-emitted. The supported color set below is curated for visual consistency with the host theme.
+- **Off-list ladder values** (e.g. \`mt-32\`, \`text-4xl\`, \`w-128\`) are not pre-emitted. The ladders below cover sizes appropriate for the embedded widget's narrow viewport.
+
+If you need something that's not on this list, file an issue with your use case \u2014 the safelist is curated, not frozen.
+
+${sectionsMd}
+`;
+};
+
 // ../../sdk/extension/ai-docs/src/generators/store-and-navigation.ts
 var generateStoreAndNavigation = () => {
   const fm = frontmatter({
@@ -3740,6 +4058,12 @@ var SKILLS = [
     type: "knowledge",
     content: () => generateStylingAndTheming()
   },
+  {
+    id: "tailwind-utilities",
+    description: "Tailwind utility classes pre-emitted in the embedded widget bundle (margin, padding, sizing, color, layout, typography, state variants). Use when picking className values for extension UI \u2014 anything outside this list will silently no-op at runtime.",
+    type: "knowledge",
+    content: () => generateTailwindUtilities()
+  },
   {
     id: "instance-settings",
     description: "Instance Settings: declaring settingsSchema in your extension manifest, the install-time admin form, and reading regular values via useSettings() vs secure values via {{settings.x}} placeholders in data.fetch. Use when adding per-Instance configuration to an extension.",
@@ -3840,7 +4164,7 @@ var SKILLS = [
     id: "deploy",
     description: "Build the production bundle, host it on Netlify / Vercel / Cloudflare Pages / S3+CloudFront, and register your Bundle URL with Stackable via the admin dashboard or CLI. Use when shipping an extension after validation passes.",
     type: "action",
-    // TODO: T3 #24 — remove `scopes: ['docs']` once `cli deploy` is implemented so Studio's
+    // TODO: cli deploy — remove `scopes: ['docs']` once `cli deploy` is implemented so Studio's
     // AI assistant in the future should be able invoke the deploy flow (not just describe it).
     scopes: ["docs"],
     content: () => generateDeployExtensionCommand()

package/dist/server.js

@@ -2794,6 +2794,324 @@ narrow widths:
 `;
 };
 
+// ../../sdk/extension/ai-docs/src/generators/tailwind-utilities.ts
+var SAFELIST_DIRECTIVES = [
+  "m-{0,0.5,1,1.5,2,2.5,3,3.5,4,5,6,7,8,9,10,11,12,14,16}",
+  "mx-{0,1,2,3,4,5,6,8,10,12,16,auto} my-{0,1,2,3,4,5,6,8,10,12,16}",
+  "mt-{0,1,2,3,4,5,6,8,10,12,16} mb-{0,1,2,3,4,5,6,8,10,12,16}",
+  "ml-{0,1,2,3,4,5,6,8,10,12,16,auto} mr-{0,1,2,3,4,5,6,8,10,12,16,auto}",
+  "p-{0,0.5,1,1.5,2,2.5,3,3.5,4,5,6,7,8,9,10,11,12,14,16}",
+  "px-{0,1,2,3,4,5,6,8,10,12,16} py-{0,1,2,3,4,5,6,8,10,12,16}",
+  "pt-{0,1,2,3,4,5,6,8,10,12,16} pb-{0,1,2,3,4,5,6,8,10,12,16}",
+  "pl-{0,1,2,3,4,5,6,8,10,12,16} pr-{0,1,2,3,4,5,6,8,10,12,16}",
+  "gap-{0,1,2,3,4,5,6,8,10,12} gap-x-{0,1,2,3,4,5,6,8} gap-y-{0,1,2,3,4,5,6,8}",
+  "text-{xs,sm,base,lg,xl,2xl}",
+  "font-{light,normal,medium,semibold,bold,extrabold}",
+  "uppercase lowercase capitalize normal-case",
+  "tracking-{tight,normal,wide,wider,widest}",
+  "leading-{none,tight,snug,normal,relaxed,loose}",
+  "opacity-{0,5,10,20,25,30,40,50,60,70,75,80,90,95,100}",
+  "block inline inline-block flex inline-flex grid hidden",
+  "flex-{1,auto,initial,none,row,col,wrap,nowrap,row-reverse,col-reverse}",
+  "justify-{start,end,center,between,around,evenly}",
+  "items-{start,end,center,baseline,stretch}",
+  "self-{auto,start,end,center,stretch,baseline}",
+  "w-{0,full,auto,screen,1/2,1/3,2/3,1/4,3/4,1,2,3,4,5,6,8,10,12,16,20,24,32,48}",
+  "h-{0,full,auto,screen,1/2,1/3,2/3,1/4,3/4,1,2,3,4,5,6,8,10,12,16,20,24,32,48}",
+  "min-w-{0,full,fit,min,max} max-w-{none,xs,sm,md,lg,xl,2xl,3xl,4xl,5xl,full,fit}",
+  "aspect-{auto,square,video} aspect-[9/16]",
+  "rounded-{none,sm,md,lg,xl,2xl,3xl,full}",
+  "border border-{0,2,4,8} border-{x,y,t,b,l,r}",
+  "cursor-{pointer,default,not-allowed,wait,text,move,help}",
+  "overflow-{auto,hidden,visible,scroll}",
+  "overflow-x-{auto,hidden,scroll} overflow-y-{auto,hidden,scroll}",
+  "transition transition-{none,all,colors,opacity,transform}",
+  "duration-{75,100,150,200,300,500,700,1000} ease-{linear,in,out,in-out}",
+  "shadow-{sm,md,lg,xl,2xl,none,inner}",
+  "relative absolute fixed sticky static",
+  "z-{0,10,20,30,40,50,auto}",
+  "text-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "bg-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "border-{zinc,slate,gray}-{100,200,300,400} border-transparent",
+  "hover:opacity-{50,75,80,90,100}",
+  "hover:text-{zinc,slate,gray,neutral}-{500,600,700,800,900}",
+  "hover:text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "hover:bg-{zinc,slate,gray,neutral}-{50,100,200}",
+  "hover:bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "focus:outline-none focus:ring-2 focus:ring-offset-2",
+  "disabled:opacity-50 disabled:cursor-not-allowed",
+  "dark:text-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "dark:text-{red,green,blue,amber,emerald,sky,indigo}-{500,600,700}",
+  "dark:bg-{zinc,slate,gray,neutral}-{50,100,200,300,400,500,600,700,800,900}",
+  "dark:bg-{red,green,blue,amber,emerald}-{50,100,500,600}",
+  "dark:border-{zinc,slate,gray}-{600,700,800,900} dark:border-transparent",
+  "dark:hover:text-{zinc,slate,gray}-{50,100,200,300,400}",
+  "dark:hover:bg-{zinc,slate,gray}-{700,800,900}"
+];
+var INLINE_DIRECTIVE_RE = /@source\s+inline\(\s*'([^']+)'\s*\)\s*;/g;
+var expand = (token) => {
+  const m = token.match(/\{([^{}]+)\}/);
+  if (!m) {
+    return [token];
+  }
+  const head = token.slice(0, m.index);
+  const tail = token.slice(m.index + m[0].length);
+  const out = [];
+  for (const opt of m[1].split(",")) {
+    out.push(...expand(head + opt + tail));
+  }
+  return out;
+};
+var stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, "");
+var parseSafelist = (css) => {
+  const stripped = stripComments(css);
+  const classes = [];
+  for (const match of stripped.matchAll(INLINE_DIRECTIVE_RE)) {
+    for (const tok of match[1].split(/\s+/)) {
+      if (tok) {
+        classes.push(...expand(tok));
+      }
+    }
+  }
+  return classes;
+};
+var classifyFamily = (cls) => {
+  if (cls.startsWith("dark:hover:text-")) return "Dark \u2014 hover text";
+  if (cls.startsWith("dark:hover:bg-")) return "Dark \u2014 hover background";
+  if (cls.startsWith("dark:text-")) return "Dark \u2014 text color";
+  if (cls.startsWith("dark:bg-")) return "Dark \u2014 background color";
+  if (cls.startsWith("dark:border-")) return "Dark \u2014 border color";
+  if (cls.startsWith("hover:opacity-")) return "Hover \u2014 opacity";
+  if (cls.startsWith("hover:text-")) return "Hover \u2014 text color";
+  if (cls.startsWith("hover:bg-")) return "Hover \u2014 background color";
+  if (cls.startsWith("focus:")) return "Focus";
+  if (cls.startsWith("disabled:")) return "Disabled";
+  if (/^(m|mx|my|mt|mb|ml|mr)-/.test(cls)) {
+    return "Margin";
+  }
+  if (/^(p|px|py|pt|pb|pl|pr)-/.test(cls)) {
+    return "Padding";
+  }
+  if (/^gap(-x|-y)?-/.test(cls)) {
+    return "Gap";
+  }
+  if (/^(min-w|max-w|min-h|max-h)-/.test(cls)) {
+    return "Sizing constraints";
+  }
+  if (/^(w|h)-/.test(cls)) {
+    return "Width / Height";
+  }
+  if (/^text-(xs|sm|base|lg|xl|2xl)$/.test(cls)) {
+    return "Text size";
+  }
+  if (/^text-([a-z]+)-(\d+)$/.test(cls)) {
+    return "Text color";
+  }
+  if (/^font-/.test(cls)) {
+    return "Font weight";
+  }
+  if (["uppercase", "lowercase", "capitalize", "normal-case"].includes(cls)) {
+    return "Text transform";
+  }
+  if (/^tracking-/.test(cls)) {
+    return "Letter spacing (tracking)";
+  }
+  if (/^leading-/.test(cls)) {
+    return "Line height (leading)";
+  }
+  if (/^bg-([a-z]+)-(\d+)$/.test(cls)) {
+    return "Background color";
+  }
+  if (/^border-([a-z]+)-(\d+)$/.test(cls) || cls === "border-transparent") {
+    return "Border color";
+  }
+  if (/^(block|inline|inline-block|flex|inline-flex|grid|hidden)$/.test(cls)) {
+    return "Display";
+  }
+  if (/^flex-/.test(cls)) {
+    return "Flex";
+  }
+  if (/^justify-/.test(cls)) {
+    return "Justify content";
+  }
+  if (/^items-/.test(cls)) {
+    return "Align items";
+  }
+  if (/^self-/.test(cls)) {
+    return "Align self";
+  }
+  if (/^aspect-/.test(cls)) {
+    return "Aspect ratio";
+  }
+  if (/^opacity-/.test(cls)) {
+    return "Opacity";
+  }
+  if (/^rounded(-|$)/.test(cls)) {
+    return "Border radius";
+  }
+  if (/^border(-|$)/.test(cls) && !/^border-([a-z]+)-(\d+)$/.test(cls) && cls !== "border-transparent") {
+    return "Border width";
+  }
+  if (/^cursor-/.test(cls)) {
+    return "Cursor";
+  }
+  if (/^overflow(-|$)/.test(cls)) {
+    return "Overflow";
+  }
+  if (/^transition(-|$)/.test(cls) || /^duration-/.test(cls) || /^ease-/.test(cls)) {
+    return "Transition";
+  }
+  if (/^shadow(-|$)/.test(cls)) {
+    return "Box shadow";
+  }
+  if (/^(relative|absolute|fixed|sticky|static)$/.test(cls)) {
+    return "Position";
+  }
+  if (/^z-/.test(cls)) {
+    return "Z-index";
+  }
+  return "Other";
+};
+var SECTIONS = [
+  {
+    title: "Utility families",
+    families: [
+      "Margin",
+      "Padding",
+      "Gap",
+      "Width / Height",
+      "Sizing constraints",
+      "Aspect ratio",
+      "Display",
+      "Flex",
+      "Justify content",
+      "Align items",
+      "Align self",
+      "Position",
+      "Z-index",
+      "Overflow",
+      "Text size",
+      "Font weight",
+      "Text transform",
+      "Letter spacing (tracking)",
+      "Line height (leading)",
+      "Text color",
+      "Background color",
+      "Border color",
+      "Border width",
+      "Border radius",
+      "Opacity",
+      "Box shadow",
+      "Cursor",
+      "Transition",
+      "Other"
+    ]
+  },
+  {
+    title: "State variants",
+    families: [
+      "Focus",
+      "Disabled",
+      "Hover \u2014 opacity",
+      "Hover \u2014 text color",
+      "Hover \u2014 background color"
+    ]
+  },
+  {
+    title: "Theme variants",
+    families: [
+      "Dark \u2014 text color",
+      "Dark \u2014 background color",
+      "Dark \u2014 border color",
+      "Dark \u2014 hover text",
+      "Dark \u2014 hover background"
+    ]
+  }
+];
+var groupBySection = (classes) => {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const cls of classes) {
+    const family = classifyFamily(cls);
+    const arr = buckets.get(family) ?? [];
+    arr.push(cls);
+    buckets.set(family, arr);
+  }
+  return SECTIONS.map((section) => ({
+    title: section.title,
+    families: section.families.filter((label) => buckets.has(label)).map((label) => ({
+      label,
+      classes: buckets.get(label).sort((a2, b2) => a2.localeCompare(b2, void 0, { numeric: true }))
+    }))
+  })).filter((s) => s.families.length > 0);
+};
+var renderFamilySection = (group) => {
+  const lines = [];
+  lines.push(`### ${group.label} (${group.classes.length})`);
+  lines.push("");
+  const formatted = group.classes.map((c) => `\`${c}\``).join(", ");
+  lines.push(formatted);
+  lines.push("");
+  return lines.join("\n");
+};
+var generateTailwindUtilities = () => {
+  const fm = frontmatter({
+    root: false,
+    targets: ["*"],
+    description: "Tailwind utility classes pre-emitted in the embedded widget bundle that extensions can use without shipping their own CSS",
+    globs: ["packages/extension/src/**/*.tsx"]
+  });
+  const css = SAFELIST_DIRECTIVES.map((d2) => `@source inline('${d2}');`).join("\n");
+  const classes = parseSafelist(css);
+  const sectionsData = groupBySection(classes);
+  const familyCount = sectionsData.reduce((sum, s) => sum + s.families.length, 0);
+  const sectionsMd = sectionsData.map((section) => {
+    const familyBlocks = section.families.map(renderFamilySection).join("\n");
+    return `## ${section.title}
+
+${familyBlocks}`;
+  }).join("\n");
+  return `${fm}
+
+# Supported Tailwind Utilities
+
+Stackable extensions render inside the embedded widget's Shadow Root via the platform and ship **zero custom CSS by design** \u2014 they rely entirely on the platforms's bundled stylesheet for their visual styling. To keep that bundle small while still covering the common needs of extension UI, the platform pre-emits a curated subset of Tailwind v4 utility classes via a safelist. The classes listed below are guaranteed to be available in any extension that uses them.
+
+Total: **${classes.length} utility classes** across **${familyCount} families**.
+
+## Using utilities
+
+Apply them via the \`className\` prop on \`ui.*\` components:
+
+\`\`\`tsx
+<ui.Card className="mt-4 p-6">
+  <ui.Stack className="gap-3">
+    <ui.Text className="text-lg font-semibold uppercase tracking-wide">Title</ui.Text>
+    <ui.Text className="text-zinc-600">Body copy</ui.Text>
+  </ui.Stack>
+</ui.Card>
+\`\`\`
+
+Always prefer:
+- Component variants (\`<ui.Button variant="primary">\`) over color overrides
+- Layout components (\`<ui.Stack>\`, \`<ui.Inline>\`) over manual flexbox class chains
+- The semantic color tokens (\`text-foreground\`, \`bg-background\`) which adapt to the host theme
+
+## Safelist limits
+
+The safelist is intentionally a fixed list, **NOT the full Tailwind catalog** to provide UI consistency and reduce bundle size. Anything beyond what is listed below will be missing from the platform stylesheet at runtime \u2014 the class will appear in your DOM but the corresponding CSS rule will not exist, and the style will silently no-op. In particular:
+
+- **Arbitrary values are NOT supported** in general (e.g. \`w-[123px]\`, \`bg-[#1a1a1a]\`, \`text-[15px]\`). The single exception is \`aspect-[9/16]\` (portrait video). For any other arbitrary value, use the named utility closest to your target.
+- **Off-list color shades** (e.g. \`bg-cyan-500\`, \`text-rose-500\`) are not pre-emitted. The supported color set below is curated for visual consistency with the host theme.
+- **Off-list ladder values** (e.g. \`mt-32\`, \`text-4xl\`, \`w-128\`) are not pre-emitted. The ladders below cover sizes appropriate for the embedded widget's narrow viewport.
+
+If you need something that's not on this list, file an issue with your use case \u2014 the safelist is curated, not frozen.
+
+${sectionsMd}
+`;
+};
+
 // ../../sdk/extension/ai-docs/src/generators/store-and-navigation.ts
 var generateStoreAndNavigation = () => {
   const fm = frontmatter({
@@ -3733,6 +4051,12 @@ var SKILLS = [
     type: "knowledge",
     content: () => generateStylingAndTheming()
   },
+  {
+    id: "tailwind-utilities",
+    description: "Tailwind utility classes pre-emitted in the embedded widget bundle (margin, padding, sizing, color, layout, typography, state variants). Use when picking className values for extension UI \u2014 anything outside this list will silently no-op at runtime.",
+    type: "knowledge",
+    content: () => generateTailwindUtilities()
+  },
   {
     id: "instance-settings",
     description: "Instance Settings: declaring settingsSchema in your extension manifest, the install-time admin form, and reading regular values via useSettings() vs secure values via {{settings.x}} placeholders in data.fetch. Use when adding per-Instance configuration to an extension.",
@@ -3833,7 +4157,7 @@ var SKILLS = [
     id: "deploy",
     description: "Build the production bundle, host it on Netlify / Vercel / Cloudflare Pages / S3+CloudFront, and register your Bundle URL with Stackable via the admin dashboard or CLI. Use when shipping an extension after validation passes.",
     type: "action",
-    // TODO: T3 #24 — remove `scopes: ['docs']` once `cli deploy` is implemented so Studio's
+    // TODO: cli deploy — remove `scopes: ['docs']` once `cli deploy` is implemented so Studio's
     // AI assistant in the future should be able invoke the deploy flow (not just describe it).
     scopes: ["docs"],
     content: () => generateDeployExtensionCommand()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/mcp-app-extension",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "bin": {
     "mcp-app-extension": "./dist/index.js"