better-design 0.15.1 → 0.19.0

package/dist/index.js

@@ -899,9 +899,119 @@ Default is create-design-system (above). For a named system: find-design-system(
   }
 });
 
+// ../shared/src/mcp/session-guidance.ts
+function topicFromDocId(docId) {
+  return docId.replace(/^(principle|foundational|doc)-/, "").trim();
+}
+function scopeToClient(calls, clientName) {
+  if (!clientName) return calls;
+  const sameClient = calls.filter((call) => call.clientName === clientName);
+  return sameClient.length > 0 ? sameClient : calls;
+}
+function summarizeSessionGuidance(calls, clientName) {
+  const topics = [];
+  const seen = /* @__PURE__ */ new Set();
+  let guidanceCalls = 0;
+  let reviewed = false;
+  for (const call of scopeToClient(calls, clientName)) {
+    if (REVIEW_TOOLS.has(call.tool)) {
+      reviewed = true;
+      continue;
+    }
+    if (!GUIDANCE_TOOLS.has(call.tool)) continue;
+    guidanceCalls += 1;
+    const raw = call.topic?.trim() || call.docIds.map(topicFromDocId).find(Boolean);
+    if (!raw) continue;
+    const topic = topicFromDocId(raw).toLowerCase();
+    if (!topic || seen.has(topic)) continue;
+    seen.add(topic);
+    topics.push(topic);
+  }
+  return { topics, reviewed, guidanceCalls };
+}
+function formatTopicList(topics) {
+  const named = topics.slice(0, MAX_NAMED_TOPICS);
+  if (named.length === 0) return "";
+  if (named.length === 1) return named[0];
+  return `${named.slice(0, -1).join(", ")} and ${named[named.length - 1]}`;
+}
+function reviewSectionForTopic(topic) {
+  const needle = topic.toLowerCase();
+  return REVIEW_SECTION_BY_TOPIC.find(({ match }) => match.test(needle))?.section ?? null;
+}
+function weightReviewRules(rules, topics) {
+  const sections = [...new Set(topics.map(reviewSectionForTopic).filter((s) => Boolean(s)))];
+  if (sections.length === 0) return { rules: [...rules], sections: [] };
+  const matches = (rule) => sections.some((section) => rule.id.toLowerCase().includes(section));
+  const first = rules.filter(matches);
+  if (first.length === 0 || first.length === rules.length) {
+    return { rules: [...rules], sections: [] };
+  }
+  return {
+    rules: [...first, ...rules.filter((rule) => !matches(rule))],
+    sections: sections.filter(
+      (section) => first.some((rule) => rule.id.toLowerCase().includes(section))
+    )
+  };
+}
+function guidancePreamble(topics, subject, orderedSections = []) {
+  if (topics.length === 0) return "";
+  const list = formatTopicList(topics);
+  const plural = topics.length > 1 ? "principles" : "principle";
+  const ordering = orderedSections.length ? ` The ${formatTopicList(orderedSections.map((s) => s.replace(/-/g, " ")))} rules are ordered first below.` : "";
+  return `Earlier this session you loaded the ${list} ${plural}. Check ${subject} against these first.${ordering}`;
+}
+function reviewNudge(session) {
+  if (session.reviewed || session.guidanceCalls === 0) return "";
+  return "You have loaded design guidance in this session and not reviewed the result yet. When the screen exists, call `get-review-rules` on the code, then `check-comprehension` on its copy, and fix every critical and serious finding before you present it.";
+}
+var MCP_SESSION_WINDOW_MS, GUIDANCE_TOOLS, REVIEW_TOOLS, SESSION_LOOP_TOOLS, NO_SESSION_GUIDANCE, MAX_NAMED_TOPICS, REVIEW_SECTION_BY_TOPIC;
+var init_session_guidance = __esm({
+  "../shared/src/mcp/session-guidance.ts"() {
+    "use strict";
+    MCP_SESSION_WINDOW_MS = 30 * 6e4;
+    GUIDANCE_TOOLS = /* @__PURE__ */ new Set([
+      "get-ui-principle",
+      "get-ux-principle",
+      "get-react-native-guide",
+      "get-three-js-guide",
+      "get-motion-guide"
+    ]);
+    REVIEW_TOOLS = /* @__PURE__ */ new Set([
+      "get-review-rules",
+      "check-comprehension"
+    ]);
+    SESSION_LOOP_TOOLS = /* @__PURE__ */ new Set([
+      ...GUIDANCE_TOOLS,
+      ...REVIEW_TOOLS
+    ]);
+    NO_SESSION_GUIDANCE = {
+      topics: [],
+      reviewed: false,
+      guidanceCalls: 0
+    };
+    MAX_NAMED_TOPICS = 4;
+    REVIEW_SECTION_BY_TOPIC = [
+      { match: /accessib|a11y|contrast|keyboard|screen-reader/, section: "accessibility" },
+      { match: /animation|motion|transition|spring|scroll|reveal|particle|canvas|hover|pointer|gesture|interaction/, section: "animation" },
+      // `\bform` on purpose: bare `form` also matches "performance", which the
+      // visual-design row below claims, and "information".
+      { match: /microcopy|copy|content|marketing|onboarding|error|notification|dialog|\bform|search|navigation|psycholog|behavior/, section: "content" },
+      { match: /hierarchy|spacing|layout|typograph|color|depth|surface|polish|image|grid|component|distill|bolder|quieter|performance/, section: "visual-design" }
+    ];
+  }
+});
+
 // ../shared/src/mcp/tools/shared.ts
 import { createHash } from "crypto";
 import { z } from "zod";
+function mcpClientName(server) {
+  try {
+    return server.server.getClientVersion?.()?.name || void 0;
+  } catch {
+    return void 0;
+  }
+}
 function codingHostName(server) {
   try {
     const name = server.server.getClientVersion?.()?.name;
@@ -932,6 +1042,24 @@ function buildKitOutputSchema(enableShopifyKit = true) {
     themeFiles: z.array(z.object({ path: z.string().min(1), content: z.string().min(1) })).optional().describe("Shopify target only. Theme files to write verbatim at each path: the per-system CSS asset, the Liquid snippets, and the theme editor sections.")
   });
 }
+async function loadSessionGuidance(provider, userId, clientName, now = Date.now()) {
+  if (!provider.getRecentGuidance) return NO_SESSION_GUIDANCE;
+  let timer;
+  try {
+    const calls = await Promise.race([
+      provider.getRecentGuidance(userId, now - MCP_SESSION_WINDOW_MS),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), SESSION_LOOKUP_TIMEOUT_MS);
+      })
+    ]);
+    if (!Array.isArray(calls) || calls.length === 0) return NO_SESSION_GUIDANCE;
+    return summarizeSessionGuidance(calls, clientName);
+  } catch {
+    return NO_SESSION_GUIDANCE;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 function extractOutputPreview(result) {
   const content = result?.content;
   if (!Array.isArray(content)) return void 0;
@@ -1037,10 +1165,11 @@ function truncateToTokens(text, maxTokens) {
 
 ...(truncated to ~${maxTokens} tokens)`;
 }
-var MAX_OUTPUT_PREVIEW, ICONIFY_FETCH_TIMEOUT_MS, ICONIFY_API_BASE, REGISTRY_BASE_URL, APP_BASE_URL, WIDGET_RESOURCE_DOMAINS, WIDGET_FRAME_DOMAINS, WIDGET_APP_DOMAIN, REQUIREMENTS_MD, ANTI_MOCKUP_MD, BUILD_TARGET_RULE, CODING_HOST_RE, PREVIEW_OUTPUT_SCHEMA, BUILD_KIT_OUTPUT_SCHEMA, CONTEXT_ARG, READ_ONLY_TOOL_ANNOTATIONS, SEARCH_TOOLS;
+var MAX_OUTPUT_PREVIEW, ICONIFY_FETCH_TIMEOUT_MS, ICONIFY_API_BASE, REGISTRY_BASE_URL, APP_BASE_URL, WIDGET_RESOURCE_DOMAINS, WIDGET_APP_DOMAIN, REQUIREMENTS_MD, ANTI_MOCKUP_MD, BUILD_TARGET_RULE, CODING_HOST_RE, PREVIEW_OUTPUT_SCHEMA, BUILD_KIT_OUTPUT_SCHEMA, CONTEXT_ARG, READ_ONLY_TOOL_ANNOTATIONS, SESSION_LOOKUP_TIMEOUT_MS, SEARCH_TOOLS;
 var init_shared = __esm({
   "../shared/src/mcp/tools/shared.ts"() {
     "use strict";
+    init_session_guidance();
     MAX_OUTPUT_PREVIEW = 1e3;
     ICONIFY_FETCH_TIMEOUT_MS = 1e4;
     ICONIFY_API_BASE = "https://api.iconify.design";
@@ -1050,7 +1179,6 @@ var init_shared = __esm({
       "https://fonts.googleapis.com",
       "https://fonts.gstatic.com"
     ];
-    WIDGET_FRAME_DOMAINS = [APP_BASE_URL];
     WIDGET_APP_DOMAIN = `${createHash("sha256").update(`${APP_BASE_URL}/api/mcp`).digest("hex").slice(0, 32)}.claudemcpcontent.com`;
     REQUIREMENTS_MD = `> **Requirements:** these components target **Tailwind v4**. The installed \`globals.css\` uses the v4 entry point (\`@import "tailwindcss"\`), so the project needs \`tailwindcss@^4\` with \`@tailwindcss/postcss\` in its PostCSS config (or the \`@tailwindcss/vite\` plugin). On a Tailwind v3 project, migrate to v4 first, otherwise the build throws the "trying to use tailwindcss directly as a PostCSS plugin" error.
 `;
@@ -1074,8 +1202,8 @@ The UI copy inside the screen follows the same restraint: short headlines (about
       status: z.string().describe("completed | error | pending | generating | selected"),
       name: z.string().describe("Display name of the design system or project."),
       viewUrl: z.string().optional().describe("Owner-facing Better Design page (the human 'Open' link). May require login."),
-      previewUrl: z.string().optional().describe("Public, cookieless showcase URL to embed in an iframe (sandboxed hosts can't carry the user's session). Falls back to viewUrl."),
-      shotUrl: z.string().optional().describe("Real screenshot of the showcase page, for hosts that can't iframe it."),
+      previewUrl: z.string().optional().describe("Public, cookieless showcase URL used to generate preview assets. Falls back to viewUrl."),
+      shotUrl: z.string().optional().describe("Real screenshot of the showcase page for the self-contained preview widget."),
       installCommand: z.string().optional().describe("shadcn install command, when complete."),
       installLibrary: z.enum(["base-ui", "radix", "mixed"]).optional().describe("Actual component library flavor installed by installCommand."),
       installNote: z.string().optional().describe("Important install flavor or fallback note for clients that read only structuredContent."),
@@ -1091,6 +1219,7 @@ The UI copy inside the screen follows the same restraint: short headlines (about
       destructiveHint: false,
       openWorldHint: false
     };
+    SESSION_LOOKUP_TIMEOUT_MS = 2e3;
     SEARCH_TOOLS = /* @__PURE__ */ new Set([
       "find-design-system",
       "get-ui-principle",
@@ -1106,6 +1235,541 @@ The UI copy inside the screen follows the same restraint: short headlines (about
   }
 });
 
+// ../shared/src/mcp/scaffold/motion-scaffold.ts
+var MOTION_SCAFFOLD_FILES, MOTION_SCAFFOLD_STEPS;
+var init_motion_scaffold = __esm({
+  "../shared/src/mcp/scaffold/motion-scaffold.ts"() {
+    "use strict";
+    MOTION_SCAFFOLD_FILES = [
+      {
+        path: "package.json",
+        contents: `{
+  "name": "motion",
+  "private": true,
+  "scripts": {
+    "dev": "remotion studio",
+    "music": "python3 scripts/make-music.py",
+    "render": "remotion render Video out/video.mp4 --concurrency=6",
+    "render:1080": "remotion render Video out/video-1080.mp4 --concurrency=6 --scale=1.5"
+  },
+  "dependencies": {
+    "@remotion/cli": "4.0.499",
+    "@remotion/google-fonts": "4.0.499",
+    "@remotion/layout-utils": "4.0.499",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "remotion": "4.0.499"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.0",
+    "typescript": "5.7.3"
+  }
+}
+`
+      },
+      {
+        path: "tsconfig.json",
+        contents: `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "lib": [
+      "ES2022",
+      "DOM"
+    ]
+  },
+  "include": [
+    "src"
+  ]
+}
+`
+      },
+      {
+        path: "remotion.config.ts",
+        contents: `import { Config } from "@remotion/cli/config";
+
+Config.setVideoImageFormat("jpeg");
+Config.setOverwriteOutput(true);
+`
+      },
+      {
+        path: ".gitignore",
+        contents: `node_modules/\\nout/\\npublic/music/\\n`
+      },
+      {
+        path: "src/index.ts",
+        contents: `import { registerRoot } from "remotion";
+import { RemotionRoot } from "./Root";
+
+registerRoot(RemotionRoot);
+`
+      },
+      {
+        path: "src/Root.tsx",
+        contents: `import React from "react";
+import { Composition } from "remotion";
+import { Video, TOTAL_FRAMES, FPS } from "./Video";
+
+export const RemotionRoot: React.FC = () => (
+  <Composition
+    id="Video"
+    component={Video}
+    durationInFrames={TOTAL_FRAMES}
+    fps={FPS}
+    width={1280}
+    height={720}
+  />
+);
+`
+      },
+      {
+        path: "src/Video.tsx",
+        contents: `import React from "react";
+import { AbsoluteFill, Audio, Series, staticFile } from "remotion";
+
+import { BeforeAfter } from "./scenes/BeforeAfter";
+import { DeviceFrame } from "./scenes/DeviceFrame";
+import { TitleCard } from "./scenes/TitleCard";
+import { color } from "./theme";
+
+export const FPS = 60;
+
+/**
+ * The running order, and the only place scene lengths live.
+ *
+ * Read the titles on their own. If they do not tell the story in order, no
+ * amount of animation will rescue it.
+ *
+ * At 120 BPM and 60fps a beat is 30 frames, so every length here is a multiple
+ * of 30 and the cuts land on the beat. scripts/make-music.py reads these
+ * numbers back out of this file, so changing one keeps the music in step.
+ */
+export const SCENES = [
+  {
+    id: "hook",
+    frames: 240,
+    node: <TitleCard title="Your product, in sixty seconds." />,
+  },
+  {
+    id: "problem",
+    frames: 270,
+    node: <TitleCard title="Here is the part people struggle with." muted />,
+  },
+  {
+    id: "product",
+    frames: 300,
+    node: <DeviceFrame caption="So we built this." />,
+  },
+  {
+    id: "difference",
+    frames: 330,
+    node: <BeforeAfter beforeLabel="Before" afterLabel="After" />,
+  },
+  {
+    id: "cta",
+    frames: 240,
+    node: <TitleCard title="Try it today." />,
+  },
+];
+
+export const TOTAL_FRAMES = SCENES.reduce((sum, scene) => sum + scene.frames, 0);
+
+export const Video: React.FC = () => (
+  <AbsoluteFill style={{ backgroundColor: color.background }}>
+    {/* Delete this line until you have run: bun run music */}
+    <Audio src={staticFile("music/bed.wav")} />
+    <Series>
+      {SCENES.map((scene) => (
+        <Series.Sequence key={scene.id} durationInFrames={scene.frames}>
+          {scene.node}
+        </Series.Sequence>
+      ))}
+    </Series>
+  </AbsoluteFill>
+);
+`
+      },
+      {
+        path: "src/theme.ts",
+        contents: `/**
+ * Replace these with your own design system's tokens so the film and the app
+ * are the same brand. If the project uses Better Design, copy the values
+ * straight out of globals.css.
+ */
+export const color = {
+  background: "oklch(0.98 0.004 90)",
+  foreground: "oklch(0.24 0.005 75)",
+  card: "oklch(1 0 0)",
+  muted: "oklch(0.94 0.006 86)",
+  mutedFg: "oklch(0.52 0.008 80)",
+  border: "oklch(0.9 0.008 85)",
+  accent: "oklch(0.62 0.2 256)",
+  accentFg: "oklch(1 0 0)",
+};
+
+export const radius = { sm: 8, md: 16, lg: 28 };
+
+export const shadow = {
+  card: "0 18px 40px oklch(0 0 0 / 0.10), 0 2px 6px oklch(0 0 0 / 0.06)",
+};
+
+/**
+ * Load a webfont through @remotion/google-fonts rather than a CSS import, so
+ * the render waits for it. A font that arrives late changes every text
+ * measurement in the frame.
+ */
+export const sans =
+  'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+
+export const type = {
+  title: { fontSize: 76, fontWeight: 600, letterSpacing: "-0.04em" },
+  caption: { fontSize: 28, fontWeight: 500, letterSpacing: "-0.01em" },
+  label: { fontSize: 20, fontWeight: 500, letterSpacing: "0" },
+};
+`
+      },
+      {
+        path: "src/scenes/TitleCard.tsx",
+        contents: `import React from "react";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+
+import { color, sans, type } from "../theme";
+
+/**
+ * One sentence, held still. Note the two things every scene here does:
+ * it starts visible enough to read on frame one, and it stops moving before
+ * the scene ends.
+ */
+export const TitleCard: React.FC<{ title: string; muted?: boolean }> = ({
+  title,
+  muted = false,
+}) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const enter = spring({ frame, fps, config: { damping: 26 } });
+  const rise = interpolate(enter, [0, 1], [18, 0]);
+  const fade = interpolate(frame, [0, 12], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  });
+
+  return (
+    <AbsoluteFill
+      style={{
+        alignItems: "center",
+        justifyContent: "center",
+        padding: 96,
+        fontFamily: sans,
+      }}
+    >
+      <h1
+        style={{
+          ...type.title,
+          margin: 0,
+          width: "100%",
+          textAlign: "center",
+          color: muted ? color.mutedFg : color.foreground,
+          opacity: fade,
+          transform: "translateY(" + rise + "px)",
+        }}
+      >
+        {title}
+      </h1>
+    </AbsoluteFill>
+  );
+};
+`
+      },
+      {
+        path: "src/scenes/DeviceFrame.tsx",
+        contents: `import React from "react";
+import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
+
+import { color, radius, sans, shadow, type } from "../theme";
+
+/**
+ * A screenshot inside a frame. Put your own UI where the placeholder is, and
+ * keep any cursor or callout INSIDE this transform, or it drifts off target
+ * the moment the scene scales.
+ */
+export const DeviceFrame: React.FC<{ caption: string }> = ({ caption }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+
+  const enter = spring({ frame, fps, config: { damping: 24 } });
+  const scale = interpolate(enter, [0, 1], [0.94, 1]);
+  const fade = interpolate(frame, [0, 10], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  });
+
+  return (
+    <AbsoluteFill
+      style={{
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 40,
+        fontFamily: sans,
+        opacity: fade,
+      }}
+    >
+      <div
+        style={{
+          width: 880,
+          height: 460,
+          borderRadius: radius.lg,
+          background: color.card,
+          border: "1px solid " + color.border,
+          boxShadow: shadow.card,
+          transform: "scale(" + scale + ")",
+          display: "grid",
+          placeItems: "center",
+          color: color.mutedFg,
+          ...type.label,
+        }}
+      >
+        Your screen here
+      </div>
+      <p style={{ ...type.caption, margin: 0, color: color.foreground }}>{caption}</p>
+    </AbsoluteFill>
+  );
+};
+`
+      },
+      {
+        path: "src/scenes/BeforeAfter.tsx",
+        contents: `import React from "react";
+import { AbsoluteFill, interpolate, useCurrentFrame } from "remotion";
+
+import { color, radius, sans, shadow, type } from "../theme";
+
+/**
+ * The comparison scene. It only works if both sides are on screen together
+ * long enough to read, so bring the second panel in early and hold both.
+ */
+export const BeforeAfter: React.FC<{
+  beforeLabel: string;
+  afterLabel: string;
+}> = ({ beforeLabel, afterLabel }) => {
+  const frame = useCurrentFrame();
+
+  const left = interpolate(frame, [0, 20], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  });
+  const right = interpolate(frame, [30, 55], [0, 1], {
+    extrapolateLeft: "clamp",
+    extrapolateRight: "clamp",
+  });
+
+  const panel = {
+    width: 500,
+    height: 380,
+    borderRadius: radius.md,
+    border: "1px solid " + color.border,
+    background: color.card,
+    boxShadow: shadow.card,
+    display: "grid",
+    placeItems: "center",
+    color: color.mutedFg,
+    ...type.label,
+  } as const;
+
+  return (
+    <AbsoluteFill
+      style={{
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 48,
+        flexDirection: "row",
+        fontFamily: sans,
+      }}
+    >
+      <div style={{ opacity: left, display: "grid", gap: 16, justifyItems: "center" }}>
+        <div style={panel}>Your old screen</div>
+        <span style={{ ...type.label, color: color.mutedFg }}>{beforeLabel}</span>
+      </div>
+      <div style={{ opacity: right, display: "grid", gap: 16, justifyItems: "center" }}>
+        <div style={{ ...panel, borderColor: color.accent }}>Your new screen</div>
+        <span style={{ ...type.label, color: color.foreground }}>{afterLabel}</span>
+      </div>
+    </AbsoluteFill>
+  );
+};
+`
+      },
+      {
+        path: "scripts/make-music.py",
+        contents: `"""
+Synthesises the backing track, so nothing is licensed from anywhere.
+
+120 BPM at 60fps is a beat every 30 frames. Scene lengths are read straight
+out of src/Video.tsx, so the swells cannot drift from the edit: change a scene
+length there, run this again, and the accents move with it.
+"""
+
+import math
+import re
+import struct
+import wave
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SR = 44_100
+FPS = 60
+BPM = 120
+BEAT = 60 / BPM
+
+SCENES = [
+    int(n)
+    for n in re.findall(r"frames: (\\d+)", (ROOT / "src" / "Video.tsx").read_text())
+]
+if not SCENES:
+    raise SystemExit("no \`frames: <n>\` entries found in src/Video.tsx")
+
+TOTAL = sum(SCENES) / FPS
+CUTS = []
+acc = 0
+for length in SCENES[:-1]:
+    acc += length
+    CUTS.append(acc / FPS)
+
+# A minor pentatonic pad. Swap these for any scale you like.
+CHORD = [220.00, 261.63, 329.63, 392.00]
+
+
+def envelope(t: float, attack: float, release: float, length: float) -> float:
+    if t < 0 or t > length:
+        return 0.0
+    if t < attack:
+        return t / attack
+    if t > length - release:
+        return max(0.0, (length - t) / release)
+    return 1.0
+
+
+samples = []
+for i in range(int(SR * TOTAL)):
+    t = i / SR
+    value = 0.0
+
+    # Pad: quiet, always there, gives the film a floor.
+    for n, freq in enumerate(CHORD):
+        value += math.sin(2 * math.pi * freq * t) * (0.05 / (n + 1))
+
+    # A pluck on every beat, louder on the downbeat.
+    beat_pos = t % BEAT
+    beat_index = int(t / BEAT)
+    accent = 1.0 if beat_index % 4 == 0 else 0.45
+    value += (
+        math.sin(2 * math.pi * CHORD[beat_index % len(CHORD)] * 2 * t)
+        * envelope(beat_pos, 0.005, 0.18, BEAT)
+        * 0.10
+        * accent
+    )
+
+    # A swell into every cut, so the edit and the music agree.
+    for cut in CUTS:
+        since = t - (cut - 0.6)
+        if 0 <= since <= 0.6:
+            value += math.sin(2 * math.pi * 110 * t) * (since / 0.6) * 0.12
+
+    samples.append(value)
+
+# Normalise, or it renders far too quiet under the picture.
+peak = max(abs(s) for s in samples) or 1.0
+gain = 0.89 / peak
+
+out = ROOT / "public" / "music"
+out.mkdir(parents=True, exist_ok=True)
+path = out / "bed.wav"
+
+with wave.open(str(path), "w") as f:
+    f.setnchannels(1)
+    f.setsampwidth(2)
+    f.setframerate(SR)
+    f.writeframes(
+        b"".join(struct.pack("<h", int(max(-1.0, min(1.0, s * gain)) * 32767)) for s in samples)
+    )
+
+print(f"wrote {path.name}: {TOTAL:.2f}s, {len(CUTS)} cuts")
+`
+      },
+      {
+        path: "README.md",
+        contents: `# motion
+
+The video for this project. Every frame is React, so a scene is reviewed and
+changed like any other component.
+
+## Run it
+
+\`\`\`bash
+bun install          # or npm install. The first run pulls a headless Chrome
+bun run music        # writes public/music/bed.wav
+bun run dev          # opens the studio, scrub and edit with hot reload
+bun run render       # writes out/video.mp4
+\`\`\`
+
+Rendering happens on your machine. Nothing is uploaded.
+
+## Where to start
+
+\`src/Video.tsx\` is the running order and the only place scene lengths live.
+Read the scene ids on their own: if they do not tell your story in order, fix
+that before touching any animation.
+
+\`src/theme.ts\` holds the colours and type. Replace them with your own design
+system's tokens so the film and the app are the same brand.
+
+\`src/scenes/\` has three patterns to copy: a title card, a screenshot in a
+frame, and a before and after.
+
+## Two rules worth keeping
+
+Scene lengths are multiples of 30 frames, which at 60fps and 120 BPM puts every
+cut on a beat. \`scripts/make-music.py\` reads those lengths back out of
+\`src/Video.tsx\`, so the music follows the edit rather than the other way round.
+
+A render that succeeds is not a render that is correct. Before you ship it,
+step through the frames:
+
+\`\`\`bash
+ffmpeg -i out/video.mp4 -vf fps=3 frames/%04d.png
+\`\`\`
+
+Sampling once a second is not enough. Check the first and last frame of every
+scene, which is where entry and exit animations fail.
+
+## Shipping it to the web
+
+\`\`\`bash
+ffmpeg -i out/video-1080.mp4 -vf scale=1280:-2 -c:v libx264 -crf 26 \\
+  -preset slow -movflags +faststart -c:a aac -b:a 96k web.mp4
+\`\`\`
+
+\`+faststart\` matters: without it the player waits for the whole file before it
+can begin.
+`
+      }
+    ];
+    MOTION_SCAFFOLD_STEPS = [
+      "Write every file in MOTION_SCAFFOLD_FILES into a `motion/` directory at the repo root. Keep it out of the app's workspace: the first install pulls a headless Chrome and is around 600 MB.",
+      "Replace the tokens in src/theme.ts with the project's own colours, radii and type, so the film and the app are the same brand.",
+      "Rewrite the scene list in src/Video.tsx for this product. Keep every length a multiple of 30 frames so the cuts stay on the beat.",
+      "Tell the user to run: bun install, then bun run music, then bun run render.",
+      "Do not claim the video is finished until they have watched it. A render that succeeds is not a render that is correct."
+    ].join("\n");
+  }
+});
+
 // ../shared/src/foundational-docs/topic-utils.ts
 function normalizePrincipleTopic(value) {
   return value.trim().toLowerCase().replace(/^principle-/, "").replace(/&/g, "and").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -1185,6 +1849,18 @@ function formatTopicNotFound(topic, principles, toolName, resourceLabel) {
     `Call \`${toolName}({})\` for the full index.`
   ].filter(Boolean).join("\n");
 }
+function appendReviewNudge(response, session) {
+  const nudge = reviewNudge(session);
+  if (!nudge) return response;
+  const [first, ...rest] = response.content;
+  if (!first) return response;
+  return {
+    ...response,
+    content: [{ ...first, text: `${first.text}
+
+${nudge}` }, ...rest]
+  };
+}
 async function runPrincipleTool(provider, area, label, toolName, args) {
   const { topic, query, maxTokens } = args;
   const resourceLabel = area === "react-native" || area === "three-js" || area === "motion" ? "Guides" : "Principles";
@@ -1262,14 +1938,22 @@ ${formatted}`;
     capture: { topResults: [] }
   };
 }
-function registerPrincipleTools({ server, provider, track }, { enableReactNativeGuide = true, enableThreeJsGuide = true } = {}) {
+async function runGuidanceTool(provider, userId, clientName, area, label, toolName, args) {
+  const [run, session] = await Promise.all([
+    runPrincipleTool(provider, area, label, toolName, args),
+    loadSessionGuidance(provider, userId, clientName)
+  ]);
+  return { ...run, response: appendReviewNudge(run.response, session) };
+}
+function registerPrincipleTools({ server, provider, track, userId }, { enableReactNativeGuide = true, enableThreeJsGuide = true } = {}) {
+  const clientName = () => mcpClientName(server);
   server.registerTool(
     "get-ui-principle",
     {
       title: "Get UI Design Principle",
       description: `Load visual UI design principles into context on-demand.
 
-Use this for visual surface decisions: hierarchy and emphasis, spacing/layout and grouping, typography, color, depth, images, accessibility, polish, and animation. For behavior, flows, forms, navigation, notifications, errors, search, onboarding, microcopy, rewards, behavior change, design process, or psychology/cognitive laws, use get-ux-principle instead.
+Use this for visual surface decisions: hierarchy and emphasis, spacing/layout and grouping, typography, color, depth, images, accessibility, polish, and animation. Building a shop, product page, or product imagery: load product-pages and product-imagery. For behavior, flows, forms, navigation, notifications, errors, search, onboarding, microcopy, rewards, behavior change, design process, or psychology/cognitive laws, use get-ux-principle instead.
 
 You can either:
 1. Request a specific topic or alias: get-ui-principle({ topic: "spacing" })
@@ -1278,7 +1962,7 @@ You can either:
 
 Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
       inputSchema: z2.object({
-        topic: z2.string().trim().min(1).max(120).optional().describe("Specific UI topic or alias to load, e.g. spacing, gestalt, hierarchy, blur test, accessibility, color, depth, animation."),
+        topic: z2.string().trim().min(1).max(120).optional().describe("Specific UI topic or alias to load, e.g. spacing, gestalt, hierarchy, blur test, accessibility, color, depth, animation, product-pages, product-imagery."),
         query: z2.string().trim().min(1).max(500).optional().describe("Natural language search query to find relevant principles."),
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
@@ -1288,7 +1972,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
     async ({ topic, query, maxTokens, context }) => {
       const start = Date.now();
       try {
-        const { response, capture } = await runPrincipleTool(provider, "ui", "UI", "get-ui-principle", { topic, query, maxTokens });
+        const { response, capture } = await runGuidanceTool(provider, userId, clientName(), "ui", "UI", "get-ui-principle", { topic, query, maxTokens });
         return trackSearch(track, "get-ui-principle", { ...capture, context }, start, response);
       } catch (error) {
         return trackSearch(
@@ -1309,7 +1993,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
       title: "Get UX Design Principle",
       description: `Load UX behavior and product-flow principles into context on-demand.
 
-Use this before implementing flows or interactive behavior: forms, navigation, notifications, errors, dialogs, search, onboarding, responsive behavior, microcopy, rewards and behavior change, design process and clarity audits, motion briefs, interaction patterns, mobile patterns, sound, anti-patterns, understanding users, and cognitive laws / psychology / behavioral science.
+Use this before implementing flows or interactive behavior: forms, navigation, notifications, errors, dialogs, search, onboarding, responsive behavior, microcopy, rewards and behavior change, design process and clarity audits, motion briefs, interaction patterns, mobile patterns, sound, anti-patterns, understanding users, and cognitive laws / psychology / behavioral science. Building a catalog, collection page, or product listing: load commerce-catalog. Building a cart, checkout, or payment step: load commerce-checkout.
 
 You can either:
 1. Request a specific topic: get-ux-principle({ topic: "behavior-change" })
@@ -1319,7 +2003,7 @@ You can either:
 
 Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
       inputSchema: z2.object({
-        topic: z2.string().trim().min(1).max(120).optional().describe("Specific UX topic or alias to load, e.g. forms, navigation, microcopy, reward design, behavior-change, clarity audit, motion brief, design-process, cognitive-laws, psychology."),
+        topic: z2.string().trim().min(1).max(120).optional().describe("Specific UX topic or alias to load, e.g. forms, navigation, microcopy, reward design, behavior-change, clarity audit, motion brief, design-process, cognitive-laws, psychology, commerce-catalog, commerce-checkout."),
         query: z2.string().trim().min(1).max(500).optional().describe("Natural language search query to find relevant UX principles."),
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
@@ -1329,7 +2013,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
     async ({ topic, query, maxTokens, context }) => {
       const start = Date.now();
       try {
-        const { response, capture } = await runPrincipleTool(provider, "ux", "UX", "get-ux-principle", { topic, query, maxTokens });
+        const { response, capture } = await runGuidanceTool(provider, userId, clientName(), "ux", "UX", "get-ux-principle", { topic, query, maxTokens });
         return trackSearch(track, "get-ux-principle", { ...capture, context }, start, response);
       } catch (error) {
         return trackSearch(
@@ -1375,8 +2059,10 @@ Prefer query search when you do not know the topic name. Use maxTokens to keep r
       async ({ topic, query, maxTokens, context }) => {
         const start = Date.now();
         try {
-          const { response, capture } = await runPrincipleTool(
+          const { response, capture } = await runGuidanceTool(
             provider,
+            userId,
+            clientName(),
             "react-native",
             "React Native",
             "get-react-native-guide",
@@ -1432,8 +2118,10 @@ Prefer query search when you do not know the topic name. Use maxTokens to keep r
       async ({ topic, query, maxTokens, context }) => {
         const start = Date.now();
         try {
-          const { response, capture } = await runPrincipleTool(
+          const { response, capture } = await runGuidanceTool(
             provider,
+            userId,
+            clientName(),
             "three-js",
             "Three.js",
             "get-three-js-guide",
@@ -1470,30 +2158,60 @@ Use this before writing a Remotion composition, and while debugging one. It cove
 
 The guidance is distilled from building a real 55-second product film, so it names the failures in the order you will hit them.
 
-This tool hands over guidance only. It does not render: that needs Remotion and a headless Chrome in the user's own project. Write the composition into their repo and let them render locally.
+Start with scaffold: true. It returns a complete Remotion project that already renders, so you adapt something working instead of inventing the layout, the render pipeline and the audio script.
+
+This tool does not render. Rendering needs Remotion and a headless Chrome in the user's own project, around 600 MB on first install. Write the files into their repo and let them run it.
 
 This complements the design tools: use get-ui-principle for visual decisions and get-ux-principle for product behavior.
 
 You can either:
-1. Request a known topic: get-motion-guide({ topic: "fundamentals" })
-2. Use an alias: get-motion-guide({ topic: "cut on the beat" })
-3. Search for the current task or problem: get-motion-guide({ query: "my animated word swap clips the longer word" })
-4. Get the full topic index: get-motion-guide({})
+1. Get the starter project: get-motion-guide({ scaffold: true })
+2. Request a known topic: get-motion-guide({ topic: "video-fundamentals" })
+3. Use an alias: get-motion-guide({ topic: "cut on the beat" })
+4. Search for the current task or problem: get-motion-guide({ query: "my animated word swap clips the longer word" })
+5. Get the full topic index: get-motion-guide({})
 
 Prefer query search when you do not know the topic name. Use maxTokens to keep responses focused (recommended: 5000-10000).`,
       inputSchema: z2.object({
-        topic: z2.string().trim().min(1).max(120).optional().describe("Specific motion topic or alias, e.g. fundamentals, text-and-layout, story-and-rhythm, verifying-a-render."),
+        scaffold: z2.boolean().optional().describe("Return a complete Remotion project that already renders, as files to write. Start here when building a video."),
+        topic: z2.string().trim().min(1).max(120).optional().describe("Specific motion topic or alias, e.g. video-fundamentals, text-and-layout, story-and-rhythm, verifying-a-render."),
         query: z2.string().trim().min(1).max(500).optional().describe("Natural language description of the video or animation task or problem."),
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
       }),
       annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
-    async ({ topic, query, maxTokens, context }) => {
+    async ({ scaffold, topic, query, maxTokens, context }) => {
       const start = Date.now();
+      if (scaffold) {
+        const files = MOTION_SCAFFOLD_FILES.map(
+          (file) => `--- ${file.path} ---
+${file.contents}`
+        ).join("\n");
+        return trackSearch(
+          track,
+          "get-motion-guide",
+          { query, topic: "scaffold", topResults: [], context },
+          start,
+          {
+            content: [
+              {
+                type: "text",
+                text: `A Remotion project that already renders. Write these files, then follow the steps.
+
+${MOTION_SCAFFOLD_STEPS}
+
+${files}`
+              }
+            ]
+          }
+        );
+      }
       try {
-        const { response, capture } = await runPrincipleTool(
+        const { response, capture } = await runGuidanceTool(
           provider,
+          userId,
+          clientName(),
           "motion",
           "Motion",
           "get-motion-guide",
@@ -1542,6 +2260,7 @@ You MUST call this after writing UI code to self-review your output, then fix ev
 - Microcopy details: pluralization, improvised unit glyphs, empty states without a next action
 - Template layouts: gradient hero + eyebrow pill, left-border callout boxes
 - Reward feedback: confirm the outcome, surface proportional user value, and avoid decorative over-reward
+- Prose tells in shipped paragraphs (hero, about, pricing, changelog, docs): banned words (delve, leverage, robust, cutting-edge, elevate), binary contrasts ("It's not X, it's Y"), throat-clearing and faux-insight openers, colon reveals, puffery and unsourced "experts agree", fake-profound kickers and recap endings, synonym cycling, emoji headings and mid-sentence bold
 
 **Comprehension (would someone outside the team understand it?):**
 - Mom test: insider vocabulary, unexplained acronyms, sentences too long to follow
@@ -1560,7 +2279,11 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
     async ({ category = "all", maxTokens, context }) => {
       const start = Date.now();
       try {
-        const rules = await provider.getReviewRules(category);
+        const [allRules, session] = await Promise.all([
+          provider.getReviewRules(category),
+          loadSessionGuidance(provider, userId, clientName())
+        ]);
+        const { rules, sections } = weightReviewRules(allRules, session.topics);
         const topResults = rules.map((rule) => ({ id: rule.id }));
         if (rules.length === 0) {
           return trackSearch(
@@ -1574,9 +2297,12 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
         const rulesOutput = rules.map((rule) => `# ${rule.title}
 
 ${rule.content}`).join("\n\n---\n\n");
+        const preamble = guidancePreamble(session.topics, "the build", sections);
         let text = `# Code Review Rules
 
-${rulesOutput}`;
+${preamble ? `${preamble}
+
+` : ""}${rulesOutput}`;
         if (maxTokens) text = truncateToTokens(text, maxTokens);
         return trackSearch(
           track,
@@ -1603,8 +2329,10 @@ var SEARCH_RESULT_PREVIEW_CHARS;
 var init_principle_tools = __esm({
   "../shared/src/mcp/tools/principle-tools.ts"() {
     "use strict";
+    init_motion_scaffold();
     init_topic_utils();
     init_shared();
+    init_session_guidance();
     SEARCH_RESULT_PREVIEW_CHARS = 4e3;
   }
 });
@@ -2084,7 +2812,7 @@ var init_comprehension = __esm({
 
 // ../shared/src/mcp/tools/comprehension-tools.ts
 import { z as z3 } from "zod";
-function registerComprehensionTools({ server, track }) {
+function registerComprehensionTools({ server, provider, track, userId }) {
   server.registerTool(
     "check-comprehension",
     {
@@ -2118,7 +2846,12 @@ Use knownTerms for words your audience genuinely knows, so the check stops flagg
       const start = Date.now();
       const report = analyzeComprehension(args);
       const hasCopy = Boolean(report.copy.headline) || report.copy.body.length > 0 || report.copy.actions.length > 0;
-      const text = hasCopy ? formatComprehensionReport(report) : NOTHING_TO_CHECK;
+      const body = hasCopy ? formatComprehensionReport(report) : NOTHING_TO_CHECK;
+      const session = await loadSessionGuidance(provider, userId, mcpClientName(server));
+      const preamble = guidancePreamble(session.topics, "this copy");
+      const text = preamble ? `${preamble}
+
+${body}` : body;
       track(
         "check-comprehension",
         {
@@ -2139,6 +2872,7 @@ var init_comprehension_tools = __esm({
     "use strict";
     init_comprehension();
     init_shared();
+    init_session_guidance();
     NOTHING_TO_CHECK = `# Comprehension check
 
 No user-facing copy was found. Pass the screen's copy directly:
@@ -2367,7 +3101,7 @@ Examples:
 - find-icons({ query: "home", libraryId: "phosphor" })
 - find-icons({ query: "settings", libraryId: "tabler" })
 
-Returns icons formatted for use with Iconify React. If you pass a variant, Better Design will try standard Iconify naming first, such as \`home-bold\`, then fall back to alternate naming and the bare icon name.`,
+Every name returned exists in the library, so pass them to \`install-icons\` verbatim. A \`variant\` only re-orders the results, putting the names that carry that variant first; it never rewrites a name.`,
     inputSchema: z4.object({
       query: z4.string().describe("What icon you need (e.g., 'home', 'settings', 'user')"),
       libraryId: z4.string().describe("The icon library ID from find-icon-library"),
@@ -2740,6 +3474,21 @@ context in the supporting line or after the title. Skip the generated-template s
 gradient hero with an uppercase eyebrow pill, centered three-card feature grid,
 left-border callout boxes, walls of text.
 
+**Count the copy before you present.** This is a check to run, not advice to weigh.
+On the first view: at most 60 visible words, at most 25 separate text fragments, one
+headline of about 6 words, and at most one supporting line of about 15 words per
+section. Count them. If you are over, delete copy; do not shrink the type to fit and
+do not move the words into a tooltip. A section that needs three sentences to explain
+itself is a section whose layout is wrong.
+
+**Labels are sentence case, never letter-spaced capitals.** Do not style section
+labels, stat captions, table column headers, card headers, or badges as tiny spaced
+capitals (\`text-xs uppercase tracking-widest\`, with or without \`font-mono\`). It is
+the single fastest generated-UI tell, and it costs legibility at exactly the size
+where legibility is scarcest. Use sentence case at the DS's own label size and muted
+color. Keep \`font-mono\` for code, IDs, keyboard shortcuts, and figures that must
+align in a column.
+
 **Hierarchy is pass/fail.** Give the first view one P0 task and at most one P1
 summary; move P2 history, standings, detailed metadata, and empty-state chrome
 below it or behind a tab/disclosure. Unless the user explicitly asks for a dense
@@ -2763,7 +3512,8 @@ After writing UI, self-review with
 `;
     DS_ESLINT_CONFIG = `// Better Design \u2014 design-system guardrail (flat ESLint config fragment).
 // Flags raw HTML primitives in feature code when the installed DS ships an
-// equivalent in components/ui/*. Wire it into eslint.config.mjs:
+// equivalent in components/ui/*, plus the uppercase micro-label tell.
+// Wire it into eslint.config.mjs:
 //
 //   import dsGuardrail from "./.better-design/eslint-design-system.mjs"; // better-design-guardrail
 //   export default [ ...dsGuardrail, /* ...your config */ ];
@@ -2776,6 +3526,7 @@ const banned = [
   { selector: "JSXOpeningElement[name.name='input']", message: "Use <Input> from @/components/ui/input instead of a raw <input>." },
   { selector: "JSXOpeningElement[name.name='select']", message: "Use <Select> from @/components/ui/select instead of a raw <select>." },
   { selector: "JSXOpeningElement[name.name='textarea']", message: "Use <Textarea> from @/components/ui/textarea instead of a raw <textarea>." },
+  { selector: "JSXAttribute[name.name='className'] Literal[value=/(^|[ ])uppercase([ ]|$)/][value=/(^|[ ])tracking-[^ ]+([ ]|$)/]", message: "Letter-spaced capitals are a generated-UI tell. Use sentence case at the design system's own label size; keep font-mono for code, IDs, and aligned figures." },
 ];
 
 export default [
@@ -2927,12 +3678,14 @@ function buildDsHtmlKit({ name, tokensCss, viewUrl, source, componentKit }) {
     '- Status colors: the `ds-badge-safe|warn|danger|unknown|verified` classes are colour modifiers, so add them ALONGSIDE the base `ds-badge`, for example `<span class="ds-badge ds-badge-safe">Sesame-free</span>`. They map to the system\'s own status tokens. Reach for these instead of hand-writing a colored badge from a raw token.',
     "- Filters, toggles and any tappable pill use `ds-chip` (or `ds-btn`) rendered as a real `<button>`, never a `ds-badge` span. Badges are read-only status labels.",
     '- Make the mock WORK, not just render: wire a few lines of vanilla JS so every control has a VISIBLE EFFECT. Filter chips toggle `aria-pressed` (the kit styles `ds-chip[aria-pressed="true"]` as selected) AND actually filter: tag each list item with `data-tags="..."` and hide items that do not match the pressed chips. Search inputs filter the list on `input`. A control that changes nothing reads as broken.',
-    "- Custom classes are for LAYOUT only (position, spacing, grid). Never restyle a `ds-*` component's geometry or surface (border-radius, borders, shadows, fills) \u2014 those carry this system's identity. If a component looks wrong, use a different `ds-*` component, do not reshape it.",
+    "- Custom classes are for LAYOUT only (position, spacing, grid). Never restyle a `ds-*` component's geometry or surface (border-radius, borders, shadows, fills) \u2014 those carry this system's identity. If a component looks wrong, use a different `ds-*` component, do not reshape it. An asset you draw yourself (an inline `<svg>` or an illustration block) is NOT a `ds-*` component: style it freely, as long as every colour comes from these tokens.",
     "- Cards in a grid must stay aligned: the kit pins `ds-card-footer` to the card bottom so rows of cards keep equal footer lines even when a badge row wraps \u2014 do not override that. Keep wrap-prone rows (badges, chips) in the same slot on every card so nothing reads as misaligned.",
     '- Build any layout you want with these tokens, do not invent new colors. For the full React component set in a real project, call `get-design-system-kit` with `target: "react"` instead.',
     "",
     "## Keep it tight",
-    "Build the screens the user actually asked for (one, unless they asked for more) and compose the `ds-*` components above. Do not hand-roll a pile of bespoke decorative CSS (illustrative art, faux maps, gradients, glassmorphism panels, radial-glow backgrounds): reach for the `ds-*` classes and these tokens first. Skip a long write-up: ship the artifact with a one-line note, no multi-paragraph explanation or trailing follow-up questions.",
+    "Build the screens the user actually asked for (one, unless they asked for more) and compose the `ds-*` components above.",
+    BESPOKE_ASSET_POLICY,
+    "Skip a long write-up: ship the artifact with a one-line note, no multi-paragraph explanation or trailing follow-up questions.",
     ...componentKit?.excluded?.length ? [
       "",
       "## Not in this kit (use the real components)",
@@ -2942,7 +3695,7 @@ function buildDsHtmlKit({ name, tokensCss, viewUrl, source, componentKit }) {
 Full live showcase: ${viewUrl}` : ""
   ].join("\n");
 }
-var MINIMUM_TEXT_CONTRAST, HOVER_POLICY, INLINE_TEXT_COLOR_POLICY, HOST_ISOLATION_CSS_TEMPLATE, INLINE_COMPOSITION_POLICY, INLINE_HIERARCHY_POLICY, DS_KIT_CSS, DS_KIT_EXAMPLE_HTML, HTML_KIT_CONDUCT_MD;
+var MINIMUM_TEXT_CONTRAST, HOVER_POLICY, INLINE_TEXT_COLOR_POLICY, HOST_ISOLATION_CSS_TEMPLATE, BESPOKE_ASSET_POLICY, INLINE_COMPOSITION_POLICY, INLINE_HIERARCHY_POLICY, DS_KIT_CSS, DS_KIT_EXAMPLE_HTML, HTML_KIT_CONDUCT_MD;
 var init_html_kit = __esm({
   "../shared/src/mcp/html-kit.ts"() {
     "use strict";
@@ -2955,6 +3708,13 @@ var init_html_kit = __esm({
     ].join(" ");
     HOST_ISOLATION_CSS_TEMPLATE = `APP_ROOT{color:var(--foreground,oklch(0.2 0 0));background:var(--background,oklch(1 0 0))}
 APP_ROOT :where(h1,h2,h3,h4,h5,h6,p,strong,label,legend,li,dt,dd,small):not(.ds-supporting):not(.ds-card-desc):not(.ds-muted){color:inherit!important}`;
+    BESPOKE_ASSET_POLICY = [
+      "Cut GENERIC decoration: faux maps, gradient washes, glassmorphism panels, radial-glow backgrounds. Those attach to no particular product, so they read as filler.",
+      "A bespoke asset is the opposite and it is welcome. ONE illustration, section seam or piece of hero art, drawn from what this product actually does, is what makes a page look authored instead of generated.",
+      "Apply this test before you keep it: could this asset sit unchanged on a competitor's page? If yes, cut it. If no, keep it.",
+      "Draw it with these tokens, and reuse its visual language (its drawing style, palette, grid and line weight) for every later asset so the set reads as one family rather than clip art from different sources.",
+      "An asset you draw yourself, an inline `<svg>` or an illustration block, is NOT a `ds-*` component: style it freely, as long as every colour comes from these tokens."
+    ].join(" ");
     INLINE_COMPOSITION_POLICY = [
       "Start with the primary user moment and make it the largest, highest-contrast composition in the first view; supporting data must read as secondary.",
       "Keep one visible identity block per level. Do not stack an app logo and title directly above a second logo and title for the same experience; make a pool, league, or workspace name subordinate context inside the primary composition instead of another header.",
@@ -2987,6 +3747,11 @@ APP_ROOT :where(h1,h2,h3,h4,h5,h6,p,strong,label,legend,li,dt,dd,small):not(.ds-
 .ds .ds-section-title{font-family:inherit;font-size:1.25rem;font-weight:600;line-height:1.2;letter-spacing:-.01em;margin:0;color:var(--foreground,oklch(0.2 0 0))}
 .ds .ds-supporting{font-size:.875rem;font-weight:400;line-height:1.5;color:var(--muted-foreground,oklch(0.55 0 0));margin:0}
 .ds a{color:var(--primary,oklch(0.45 0.15 264));text-decoration:none}
+/* A link styled as a button keeps the button's own label colour. The .ds a rule
+   above is specificity (0,1,1) and beat .ds-btn-primary at (0,1,0), so every
+   anchor call to action painted its label in the fill colour. [BD-449] */
+.ds a.ds-btn{color:inherit}
+.ds a.ds-btn:hover{text-decoration:none}
 .ds p{margin:0 0 1em}
 .ds-muted{color:var(--muted-foreground,oklch(0.55 0 0))}
 
@@ -3127,6 +3892,9 @@ APP_ROOT :where(h1,h2,h3,h4,h5,h6,p,strong,label,legend,li,dt,dd,small):not(.ds-
       "## Hierarchy and information budget (pass/fail)",
       INLINE_HIERARCHY_POLICY,
       "",
+      "## Draw one asset that only this product could carry",
+      BESPOKE_ASSET_POLICY,
+      "",
       "## Compose the screen, do not decorate the canvas",
       INLINE_COMPOSITION_POLICY,
       "",
@@ -3149,18 +3917,40 @@ function fence2(lang, body) {
 ${body}
 \`\`\``;
 }
+function pointerSafeMaterialCss(css) {
+  const lines = css?.trim().split("\n");
+  if (!lines?.length) return void 0;
+  const hoverRules = lines.filter((line) => line.includes(":hover"));
+  const baseRules = lines.filter((line) => !line.includes(":hover"));
+  if (hoverRules.length) {
+    baseRules.push(`@media (hover:hover) and (pointer:fine){${hoverRules.join("\n")}}`);
+  }
+  return baseRules.join("\n").trim() || void 0;
+}
+function primaryButtonTextCss(css) {
+  if (!css) return void 0;
+  let foreground;
+  for (const match of css.matchAll(/\.ds-btn(?:-primary)?\s*\{([^}]*)\}/g)) {
+    for (const color of match[1]?.matchAll(/(?:^|;)\s*color\s*:\s*([^;}]+)/g) ?? []) {
+      foreground = color[1]?.trim() ?? foreground;
+    }
+  }
+  return foreground ? `.ds.ds-embed .ds-btn-primary{color:${foreground}!important;-webkit-text-fill-color:currentColor}` : void 0;
+}
 function buildDsShopifyFiles(input) {
-  const materialCss = input.componentKit?.css?.trim();
+  const materialCss = pointerSafeMaterialCss(input.componentKit?.css);
+  const primaryTextCss = primaryButtonTextCss(materialCss);
   const assetCss = [
     compactTokensCss(input.tokensCss),
     DS_KIT_CSS,
     DS_SHOPIFY_CSS,
-    ...materialCss ? [materialCss] : []
+    ...materialCss ? [materialCss] : [],
+    ...primaryTextCss ? [primaryTextCss] : []
   ].join("\n\n");
   return [{ path: "assets/ds-kit.css", content: assetCss }, ...SNIPPETS];
 }
-function buildDsShopifyKit({ name, tokensCss, viewUrl, source, componentKit }) {
-  const files = buildDsShopifyFiles({ tokensCss, componentKit });
+function buildDsShopifyKit({ name, tokensCss, viewUrl, source, componentKit, themeFiles }) {
+  const files = themeFiles ?? buildDsShopifyFiles({ tokensCss, componentKit });
   const sourceLine = source?.kind === "catalog" ? `Source designSystemId: \`${source.designSystemId}\`` : source?.kind === "project" ? `Source projectId: \`${source.projectId}\`` : null;
   const fileBlocks = files.flatMap((f) => [
     `### \`${f.path}\``,
@@ -3171,7 +3961,7 @@ function buildDsShopifyKit({ name, tokensCss, viewUrl, source, componentKit }) {
   return [
     `# ${name}: Shopify theme kit`,
     "",
-    "Full design system for an existing Online Store 2.0 theme: one CSS asset carries this system's real tokens and component material, and the Liquid snippets, sections, and alternate templates cover a complete storefront (header, footer, hero, product page, collection page, content sections) with no JavaScript. Write each file to the path in its heading.",
+    "Full design system for an Online Store 2.0 theme: one CSS asset carries this system's real tokens and component material, while the Liquid snippets, global header/footer groups, and primary storefront templates compose the full store with no JavaScript. Write each file to the path in its heading.",
     ...sourceLine ? ["", sourceLine] : [],
     "",
     SHOPIFY_KIT_CONDUCT_MD,
@@ -3181,57 +3971,150 @@ function buildDsShopifyKit({ name, tokensCss, viewUrl, source, componentKit }) {
     ...fileBlocks,
     "## After installing",
     "- Preview an unpublished copy of the theme first; never edit the live theme directly.",
-    "- The kit styles parts of a storefront; page composition, cart mechanics, and checkout stay with the theme.",
+    "- The kit owns the storefront composition and cart page; Shopify continues to own checkout.",
     ...viewUrl ? ["", `Full live showcase: ${viewUrl}`] : []
   ].join("\n");
 }
-var DS_SHOPIFY_CSS, SNIPPET_BADGE, SNIPPET_PRICE, SNIPPET_BUY_BUTTON, SNIPPET_VARIANT_SELECT, SNIPPET_PAGINATION, SNIPPET_PRODUCT_CARD, SNIPPET_ANNOUNCEMENT, SNIPPET_NEWSLETTER, SECTION_FAQ, SECTION_FEATURED_COLLECTION, SECTION_HEADER, SECTION_FOOTER, SECTION_HERO, SECTION_RICH_TEXT, SECTION_IMAGE_WITH_TEXT, SECTION_MAIN_PRODUCT, SECTION_MAIN_COLLECTION, SECTION_CONTACT, SECTION_MULTICOLUMN, TEMPLATE_PRODUCT_JSON, TEMPLATE_COLLECTION_JSON, SNIPPETS, SHOPIFY_KIT_CONDUCT_MD;
+var DS_SHOPIFY_CSS, SNIPPET_BADGE, SNIPPET_PRICE, SNIPPET_BUY_BUTTON, SNIPPET_VARIANT_SELECT, SNIPPET_PAGINATION, SNIPPET_ICON, SNIPPET_PRODUCT_CARD, SNIPPET_ANNOUNCEMENT, SNIPPET_NEWSLETTER, SECTION_FAQ, SECTION_FEATURED_COLLECTION, SECTION_HEADER, SECTION_FOOTER, SECTION_HERO, SECTION_RICH_TEXT, SECTION_IMAGE_WITH_TEXT, SECTION_MAIN_PRODUCT, SECTION_MAIN_COLLECTION, SECTION_CONTACT, SECTION_MULTICOLUMN, SECTION_MAIN_PAGE, SECTION_MAIN_CART, SECTION_MAIN_SEARCH, SECTION_MAIN_404, TEMPLATE_INDEX_JSON, TEMPLATE_PRODUCT_JSON, TEMPLATE_PAGE_JSON, TEMPLATE_CART_JSON, TEMPLATE_SEARCH_JSON, TEMPLATE_404_JSON, HEADER_GROUP_JSON, FOOTER_GROUP_JSON, TEMPLATE_COLLECTION_JSON, SNIPPETS, SHOPIFY_KIT_CONDUCT_MD;
 var init_shopify_kit = __esm({
   "../shared/src/mcp/shopify-kit.ts"() {
     "use strict";
     init_html_kit();
-    DS_SHOPIFY_CSS = `.ds.ds-embed{background:transparent}
-.ds-announce{background:var(--primary,oklch(0.25 0.01 260));color:var(--primary-foreground,oklch(1 0 0));text-align:center;padding:.5rem 1rem;font-size:.8125rem}
+    DS_SHOPIFY_CSS = `html:root{font-size:100%;background:var(--background,oklch(1 0 0));color:var(--foreground,oklch(0.2 0 0))}
+body{margin:0;background:var(--background,oklch(1 0 0));color:var(--foreground,oklch(0.2 0 0));font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:1rem;line-height:1.5;letter-spacing:normal;text-rendering:optimizeLegibility;-webkit-font-smoothing:antialiased}
+body.gradient,body.color-background-1,main#MainContent,.content-for-layout{background:var(--background,oklch(1 0 0));color:var(--foreground,oklch(0.2 0 0))}
+body :where(button,input,select,textarea){font:inherit}
+body :where(.gradient,.color-background-1,.color-background-2){background:var(--background,oklch(1 0 0));color:var(--foreground,oklch(0.2 0 0))}
+body :where(.button,.shopify-payment-button__button){border-radius:var(--radius-md,var(--radius,0.5rem));background:var(--primary,oklch(0.25 0.01 260));color:var(--primary-foreground,oklch(0.98 0 0));box-shadow:var(--shadow-sm,none)}
+body :where(.field__input,.select__select,.customer .field input,.customer select){border-radius:var(--radius-md,var(--radius,0.5rem));background:var(--input,var(--background,oklch(1 0 0)));color:var(--foreground,oklch(0.2 0 0))}
+body :where(.card,.card__inner,.product__media,.cart-item__image-container){border-radius:var(--radius-lg,var(--radius,0.75rem))}
+.ds.ds-embed{background:transparent;font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:1rem;letter-spacing:normal}
+.ds-container{width:min(calc(100% - 2.5rem),76rem);max-width:76rem;margin-inline:auto;padding:0}
+.ds-section{padding-block:clamp(3rem,7vw,6rem)}
+.ds-section-compact{padding-block:clamp(2rem,4vw,3.5rem)}
+.ds-section-head{display:flex;align-items:end;justify-content:space-between;gap:1.5rem;margin-bottom:clamp(1.5rem,3vw,2.5rem)}
+.ds-section-head .ds-section-title{font-size:clamp(1.65rem,3vw,2.5rem)}
+.ds-section-copy{max-width:42rem;color:var(--muted-foreground,oklch(0.45 0.01 260))}
+.ds-display,.ds-section-title,.ds-card-title{text-wrap:balance}
+.ds-section-copy,.ds-supporting,.ds-card-desc{text-wrap:pretty}
+.ds.ds-announce{background:var(--primary,oklch(0.25 0.01 260));color:var(--primary-foreground,oklch(0.98 0 0));text-align:center;padding:.55rem 1rem;font-size:.8125rem}
 .ds-announce p{margin:0}
 .ds-announce a{color:inherit;text-decoration:underline}
-.ds-price{display:inline-flex;align-items:baseline;gap:.5rem;flex-wrap:wrap}
-.ds-price-current{font-weight:600;color:var(--foreground,oklch(0.2 0 0))}
-.ds-price-compare{color:var(--muted-foreground,oklch(0.55 0.01 260))}
-.ds-card-media{display:block}
-.ds-card-media img{display:block;width:100%;height:auto}
+.ds-price{display:inline-flex;align-items:baseline;gap:.6rem;flex-wrap:wrap}
+.ds-price-current{font-size:1.35rem;font-weight:700;letter-spacing:-.02em;color:var(--foreground,oklch(0.2 0 0))}
+.ds-price-compare{color:var(--muted-foreground,oklch(0.45 0.01 260))}
+.ds.ds-embed .ds-btn{min-height:2.75rem;white-space:nowrap;text-decoration:none}
+.ds.ds-embed .ds-btn-primary{color:var(--primary-foreground,oklch(0.98 0 0))!important;-webkit-text-fill-color:currentColor}
+.ds-card-media{display:block;overflow:hidden;background:var(--muted,oklch(0.95 0.01 90));aspect-ratio:4/5}
+.ds-card-media img,.ds-card-media svg{display:block;width:100%;height:100%;object-fit:cover}
+.ds-product-card{height:100%}
+.ds-product-card .ds-card-body{padding:1.1rem 1.25rem .65rem}
+.ds-product-card .ds-card-footer{padding:.75rem 1.25rem 1.25rem;border:0}
 .ds-product-card .ds-card-title a{color:inherit;text-decoration:none}
-.ds-faq-item{border-bottom:1px solid var(--border,oklch(0.9 0.01 260));padding:.25rem 0}
-.ds-faq-item summary{cursor:pointer;padding:.75rem 0;font-weight:600;color:var(--foreground,oklch(0.2 0 0))}
-.ds-faq-answer{padding:0 0 1rem}
-.ds-grid{display:grid;grid-template-columns:repeat(var(--ds-cols,4),1fr);gap:1rem}
-@media (max-width:749px){.ds-grid{grid-template-columns:repeat(2,1fr)}}
-.ds-newsletter .ds-control-row{margin-top:.75rem}
+.ds-product-card .ds-supporting{margin-bottom:.25rem}
+.ds-faq{max-width:52rem}
+.ds-faq-item.ds-card{display:block;padding:.25rem 1.25rem;margin:.75rem 0}
+.ds-faq-item summary{cursor:pointer;padding:1.15rem 0;font-weight:600;color:var(--foreground,oklch(0.2 0 0))}
+.ds-faq-answer{padding:0 0 1.25rem;color:var(--muted-foreground,oklch(0.45 0.01 260))}
+.ds-grid{display:grid;grid-template-columns:repeat(var(--ds-cols,4),minmax(0,1fr));gap:clamp(1rem,2vw,1.75rem)}
+.ds-grid-empty{grid-column:1/-1}
+.ds-newsletter .ds-control-row{margin-top:1rem}
 .ds-buy-form{margin:0;display:grid;gap:.75rem;justify-items:start}
-.ds-featured{padding:2rem 0}
+.ds-buy-form .ds-btn{min-width:min(100%,16rem)}
+.ds-featured{display:block}
 .ds-qty{width:6rem}
-.ds-header{display:flex;align-items:center;gap:1.5rem;padding:.85rem 1.5rem;background:var(--background,oklch(1 0 0));border-bottom:1px solid var(--border,oklch(0.9 0.01 260))}
-.ds-header-brand{font-weight:700;font-size:1.05rem;color:var(--foreground,oklch(0.2 0 0));text-decoration:none}
-.ds-header-logo{display:block;max-height:2rem;width:auto}
-.ds-header-nav{display:flex;flex:1;gap:1.1rem;flex-wrap:wrap}
-.ds-header-nav a{color:var(--foreground,oklch(0.2 0 0));text-decoration:none;font-size:.9rem}
-.ds-footer{display:flex;gap:2rem;flex-wrap:wrap;justify-content:space-between;align-items:center;padding:2rem 1.5rem;background:var(--background,oklch(1 0 0));border-top:1px solid var(--border,oklch(0.9 0.01 260))}
-.ds-footer nav{display:flex;gap:1rem;flex-wrap:wrap}
-.ds-footer a{color:var(--muted-foreground,oklch(0.55 0.01 260));text-decoration:none;font-size:.875rem}
-.ds-hero{display:grid;gap:1.25rem;padding:2.5rem 0}
-.ds-hero img{display:block;width:100%;height:auto}
-.ds-hero-actions{display:flex;gap:.75rem;flex-wrap:wrap}
-.ds-image-text{display:grid;gap:1.5rem;align-items:center;padding:2rem 0}
-.ds-product-layout{display:grid;gap:2rem;padding:2rem 0}
-.ds-product-media img{display:block;width:100%;height:auto}
-.ds-product-thumbs{display:grid;grid-template-columns:repeat(4,1fr);gap:.5rem;margin-top:.5rem}
-.ds-product-info{display:grid;gap:1rem;align-content:start}
-.ds-product-page{padding:2rem 0}
-.ds-collection-page{padding:2rem 0}
-.ds-pagination{display:block;text-align:center;margin:1.75rem 0 0}
-.ds-pagination .page,.ds-pagination .next,.ds-pagination .prev{display:inline-block;padding:.35rem .7rem}
+.ds.ds-header-shell{position:relative;z-index:20;background:color-mix(in oklab,var(--background,oklch(1 0 0)) 90%,transparent);padding:1rem 0}
+.ds-header-shell.is-sticky{position:sticky;top:0;backdrop-filter:blur(1rem)}
+.ds-header.ds-card{min-height:4.75rem;display:grid;grid-template-columns:auto 1fr auto;align-items:center;gap:2rem;padding:0 1.25rem;overflow:visible}
+.ds-header-brand{font-weight:700;font-size:1.1rem;letter-spacing:-.02em;color:var(--foreground,oklch(0.2 0 0));text-decoration:none;white-space:nowrap}
+.ds-header-logo{display:block;max-height:2.25rem;width:auto}
+.ds-header-nav{display:flex;justify-content:center;gap:clamp(1rem,2.5vw,2rem);min-width:0}
+.ds-header-link,.ds-header-nav a{color:var(--foreground,oklch(0.2 0 0));text-decoration:none;font-size:.9rem;font-weight:500}
+.ds-header-link:focus-visible,.ds-header-nav a:focus-visible,.ds-footer a:focus-visible{outline:2px solid var(--ring,var(--primary,oklch(0.45 0.15 264)));outline-offset:.3rem;border-radius:var(--radius-sm,.25rem)}
+.ds-header-actions{display:flex;align-items:center;justify-content:flex-end;gap:1rem}
+.ds-cart-link{display:inline-flex;align-items:center;gap:.35rem}
+.ds-cart-count{display:inline-grid;place-items:center;min-width:1.35rem;height:1.35rem;padding:0 .3rem;border-radius:999px;background:var(--primary,oklch(0.25 0.01 260));color:var(--primary-foreground,oklch(0.98 0 0));font-size:.7rem;font-weight:700}
+.ds-mobile-nav{display:none}
+.ds-mobile-nav summary{list-style:none;cursor:pointer}
+.ds-mobile-nav summary::-webkit-details-marker{display:none}
+.ds-mobile-nav-panel{position:absolute;inset-inline:0;top:calc(100% + .5rem);padding:1.25rem;display:grid;gap:1rem;background:var(--card,var(--background,oklch(1 0 0)));border:1px solid var(--border,oklch(0.88 0.01 260));border-radius:var(--radius-xl,var(--radius,1rem));box-shadow:var(--shadow-lg,var(--shadow-md,none))}
+.ds.ds-footer{background:var(--background,oklch(1 0 0));padding-block:1.25rem 2rem}
+.ds-footer-panel.ds-card{display:block;padding:clamp(2rem,5vw,4rem)}
+.ds-footer-grid{display:grid;grid-template-columns:minmax(14rem,1.4fr) repeat(2,minmax(10rem,1fr));gap:clamp(2rem,5vw,5rem)}
+.ds-footer-brand{max-width:28rem}
+.ds-footer-title{font-size:.8rem;font-weight:700;text-transform:uppercase;letter-spacing:.08em;margin:0 0 1rem}
+.ds-footer nav{display:grid;gap:.7rem}
+.ds-footer a{color:var(--muted-foreground,oklch(0.45 0.01 260));text-decoration:none;font-size:.9rem}
+.ds-footer-bottom{display:flex;align-items:center;justify-content:space-between;gap:1.5rem;margin-top:3rem;padding-top:1.5rem;border-top:1px solid var(--border,oklch(0.88 0.01 260))}
+.ds-policy-list,.ds-payment-list{list-style:none;padding:0;margin:0;display:flex;align-items:center;gap:.75rem;flex-wrap:wrap}
+.ds-payment-icon{display:block;width:2.25rem;height:auto}
+.ds.ds-hero-section{background:var(--background,oklch(1 0 0));overflow:hidden;padding-block:1.25rem clamp(3rem,7vw,6rem)}
+.ds-hero{display:grid;grid-template-columns:minmax(0,.85fr) minmax(0,1.15fr);align-items:center;gap:clamp(2.5rem,7vw,7rem);padding-block:clamp(2rem,5vw,4.5rem)}
+.ds-hero.ds-hero-single{grid-template-columns:minmax(0,42rem);justify-content:start}
+.ds-hero-content{display:grid;gap:1.25rem;align-content:center;max-width:38rem}
+.ds-hero .ds-display{font-size:clamp(2.6rem,6vw,5.5rem);line-height:.98}
+.ds-hero .ds-supporting{font-size:clamp(1rem,1.5vw,1.2rem);max-width:35rem}
+.ds-hero-media{position:relative;order:2;min-width:0}
+.ds-hero-media-has-image:before,.ds-hero-media-has-image:after{content:"";position:absolute;z-index:-1;border-radius:var(--radius-3xl,var(--radius-xl,var(--radius,1rem)));pointer-events:none}
+.ds-hero-media-has-image:before{width:32%;height:28%;inset:-1rem auto auto -1rem;background:var(--pop-blue,transparent)}
+.ds-hero-media-has-image:after{width:28%;height:24%;inset:auto -1rem -1rem auto;background:var(--pop-orange,transparent)}
+.ds-hero-media img{display:block;width:100%;height:clamp(24rem,50vw,42rem);object-fit:cover;border-radius:var(--radius-3xl,var(--radius-xl,var(--radius,1rem)));background:var(--muted,oklch(0.95 0.01 90))}
+.ds-hero-media>.ds-media-empty{min-height:clamp(24rem,50vw,42rem)}
+.ds-hero-actions{display:flex;align-items:center;gap:.75rem;flex-wrap:wrap}
+.ds-hero-trust{font-size:.8rem;color:var(--muted-foreground,oklch(0.45 0.01 260));margin:0}
+.ds-image-text{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:clamp(2rem,6vw,6rem);align-items:center}
+.ds-image-text.ds-image-text-single{grid-template-columns:minmax(0,42rem)}
+.ds-image-text-media.ds-card{display:block}
+.ds-image-text-media img{display:block;width:100%;height:clamp(20rem,45vw,38rem);object-fit:cover;background:var(--muted,oklch(0.95 0.01 90))}
+.ds-rich-text{max-width:52rem;text-align:center}
+.ds-rich-text .ds-section-copy{margin-inline:auto}
+.ds-rich-text .ds-btn{margin-top:1.25rem}
+.ds-value-panel.ds-card{display:grid;grid-template-columns:repeat(var(--ds-cols,3),minmax(0,1fr));overflow:hidden}
+.ds-value-item{padding:clamp(1.35rem,3vw,2rem)}
+.ds-value-item+.ds-value-item{border-left:1px solid var(--border,oklch(0.88 0.01 260))}
+.ds-value-title-row{display:flex;align-items:center;gap:.75rem}
+.ds-icon{display:block;width:1.25rem;height:1.25rem;flex:none}
+.ds-icon-tile{display:grid;place-items:center;flex:0 0 auto;width:2.5rem;height:2.5rem;border-radius:var(--radius-lg,var(--radius,1rem));background:var(--secondary,oklch(0.93 0.01 90));color:var(--secondary-foreground,var(--foreground,oklch(.31 .006 75)))}
+.ds-icon-tile-blue{background:var(--pop-blue,var(--secondary,oklch(0.93 0.01 90)));color:var(--pop-blue-foreground,var(--foreground,oklch(.31 .006 75)))}
+.ds-icon-tile-orange{background:var(--pop-orange,var(--secondary,oklch(0.93 0.01 90)));color:var(--pop-orange-foreground,var(--foreground,oklch(.31 .006 75)))}
+.ds-icon-tile-green{background:var(--pop-green,var(--secondary,oklch(0.93 0.01 90)));color:var(--pop-green-foreground,var(--foreground,oklch(.31 .006 75)))}
+.ds-product-layout{display:grid;grid-template-columns:minmax(0,1.1fr) minmax(20rem,.9fr);gap:clamp(2rem,6vw,6rem);padding-block:clamp(3rem,7vw,6rem)}
+.ds-product-media-main.ds-card{display:block}
+.ds-product-media-main img{display:block;width:100%;height:auto;min-height:30rem;max-height:46rem;object-fit:cover;background:var(--muted,oklch(0.95 0.01 90))}
+.ds-product-media-main>.ds-media-empty{min-height:30rem}
+.ds-product-thumbs{display:grid;grid-template-columns:repeat(4,1fr);gap:.75rem;margin-top:.75rem}
+.ds-product-thumbs img{display:block;width:100%;aspect-ratio:1;object-fit:cover;border-radius:var(--radius-md,var(--radius,.5rem))}
+.ds-product-info{display:grid;gap:1.25rem;align-content:start}
+.ds-product-info.ds-card{padding:clamp(1.5rem,4vw,3rem)}
+.ds-product-info .ds-display{font-size:clamp(2rem,4vw,3.75rem)}
+.ds-product-description{color:var(--muted-foreground,oklch(0.42 0.01 260))}
+.ds-page-content.ds-card{display:block;padding:clamp(1.5rem,4vw,3rem)}
+.ds-contact-form.ds-card{display:grid;gap:1rem;max-width:42rem;margin-top:2rem;padding:clamp(1.5rem,4vw,3rem)}
+.ds-product-page,.ds-collection-page,.ds-page,.ds-cart-page,.ds-search-page{padding-block:clamp(3rem,7vw,6rem)}
+.ds-collection-head,.ds-page-head{display:grid;gap:1rem;margin-bottom:clamp(2rem,5vw,4rem);max-width:52rem}
+.ds-collection-head .ds-display,.ds-page-head .ds-display{font-size:clamp(2.4rem,5vw,4.75rem)}
+.ds-cart-list{display:grid;gap:1rem;margin:2rem 0;padding:0;list-style:none}
+.ds-cart-item.ds-card{display:grid;grid-template-columns:7rem minmax(0,1fr) auto;gap:1.25rem;align-items:center;padding:1rem}
+.ds-cart-item img{display:block;width:7rem;aspect-ratio:1;object-fit:cover;border-radius:var(--radius-md,var(--radius,.5rem))}
+.ds-cart-item .ds-media-empty{min-height:7rem;padding:.75rem}
+.ds-cart-summary.ds-card{display:grid;justify-items:end;gap:1rem;margin-left:auto;max-width:28rem;padding:1.5rem;text-align:right}
+.ds-search-form.ds-card{display:grid;grid-template-columns:minmax(0,32rem) auto;gap:.75rem;align-items:end;width:max-content;max-width:100%;margin:2rem 0 3rem;padding:1.25rem}
+.ds-empty{display:grid;justify-items:start;gap:1rem;padding-block:2rem}
+.ds-empty.ds-card{padding:1.5rem}
+.ds-media-empty{display:grid;place-items:center;align-content:center;gap:.75rem;width:100%;min-height:18rem;padding:2rem;text-align:center;background:var(--secondary,var(--muted,oklch(0.94 0.01 90)));color:var(--muted-foreground,oklch(.55 .009 80))}
+.ds-media-empty .ds-icon{width:1.5rem;height:1.5rem}
+.ds-media-empty-title{margin:0;color:var(--foreground,oklch(.31 .006 75));font-weight:600}
+.ds-media-empty-copy{max-width:22rem;margin:0;font-size:.875rem}
+.ds-pagination{display:block;text-align:center;margin:2.5rem 0 0}
+.ds-pagination .page,.ds-pagination .next,.ds-pagination .prev{display:inline-block;padding:.45rem .75rem}
 .ds-pagination a{color:var(--foreground,oklch(0.2 0 0))}
 .ds-pagination .current{font-weight:700;color:var(--primary,oklch(0.25 0.01 260))}
-@media (min-width:750px){.ds-product-layout{grid-template-columns:1fr 1fr}.ds-image-text{grid-template-columns:1fr 1fr}}`;
+@media (max-width:989px){.ds-header.ds-card{grid-template-columns:auto 1fr auto;gap:1rem}.ds-mobile-nav{display:block}.ds-header-brand{justify-self:center}.ds-header-nav{display:none}.ds-header-actions .ds-header-link:not(.ds-cart-link){display:none}.ds-hero{grid-template-columns:1fr}.ds-hero-media{order:2}.ds-hero-media img{height:clamp(20rem,80vw,34rem)}.ds-value-panel.ds-card{grid-template-columns:1fr}.ds-value-item+.ds-value-item{border-left:0;border-top:1px solid var(--border,oklch(0.88 0.01 260))}.ds-footer-grid{grid-template-columns:1fr 1fr}.ds-footer-brand{grid-column:1/-1}.ds-product-layout{grid-template-columns:1fr}}
+@media (max-width:749px){.ds-section-head{display:grid}.ds-grid{grid-template-columns:repeat(2,minmax(0,1fr))}.ds-header.ds-card{min-height:4rem}.ds-header-shell.is-sticky{position:relative}.ds-hero .ds-display{font-size:clamp(2.4rem,13vw,4rem)}.ds-image-text{grid-template-columns:1fr}.ds-footer-panel.ds-card{padding:2rem 1.25rem}.ds-footer-grid{grid-template-columns:1fr}.ds-footer-brand{grid-column:auto}.ds-footer-bottom{align-items:flex-start;flex-direction:column}.ds-cart-item.ds-card{grid-template-columns:5rem minmax(0,1fr)}.ds-cart-item img{width:5rem}.ds-cart-item .ds-media-empty{min-height:5rem}.ds-cart-item-total{grid-column:2}.ds-search-form.ds-card{grid-template-columns:1fr;width:100%}.ds-search-form .ds-btn{width:100%}}
+@media (max-width:479px){.ds-grid{grid-template-columns:1fr}.ds-header-actions{gap:.6rem}.ds-cart-link>span:first-child{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}}
+@media (pointer:coarse){.ds-mobile-nav summary,.ds-header-actions a{display:inline-flex;align-items:center;min-width:44px;min-height:44px}}
+@media (hover:hover) and (pointer:fine){.ds-header-link:hover,.ds-header-nav a:hover,.ds-footer a:hover{text-decoration:underline;text-underline-offset:.25rem}.ds-card-media img{transition:transform .3s ease}.ds-card-media:hover img{transform:scale(1.025)}}
+@media (prefers-reduced-motion:reduce){html{scroll-behavior:auto}.ds-card-media img{transition:none}}`;
     SNIPPET_BADGE = `{% comment %}
   Status label. Usage: {% render 'ds-badge', label: 'New' %}
   Optional tone: primary | outline | safe | warn | danger | unknown | verified
@@ -3256,7 +4139,7 @@ var init_shopify_kit = __esm({
   <span class="ds-price-current">{{ ds_price | money }}</span>
   {%- if ds_compare_at > ds_price -%}
     <s class="ds-price-compare">{{ ds_compare_at | money }}</s>
-    {% render 'ds-badge', label: 'Sale', tone: 'primary' %}
+    {% render 'ds-badge', label: 'Sale', tone: 'warn' %}
   {%- endif -%}
 </span>`;
     SNIPPET_BUY_BUTTON = `{% comment %}
@@ -3307,6 +4190,21 @@ var init_shopify_kit = __esm({
   {{ paginate | default_pagination }}
 </nav>
 {%- endif -%}`;
+    SNIPPET_ICON = `{% comment %}
+  Iconoir storefront icons (MIT License), installed through Better Design.
+  Usage: {% render 'ds-icon', icon: 'delivery' %}
+  Available: quality | delivery | support | image.
+{% endcomment %}
+{%- case icon -%}
+  {%- when 'quality' -%}
+    <svg class="ds-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" aria-hidden="true" focusable="false"><path d="m8.5 11.5 3 3 5-5"/><path d="M5 18 3.13 4.913a.996.996 0 0 1 .774-1.114l7.662-1.703a2 2 0 0 1 .868 0L20.096 3.8c.51.113.848.596.774 1.114L19 18c-.07.495-.5 3.5-7 3.5S5.07 18.495 5 18"/></svg>
+  {%- when 'delivery' -%}
+    <svg class="ds-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-width="1.5" aria-hidden="true" focusable="false"><path stroke-linejoin="round" stroke-miterlimit="1.5" d="M8 19a2 2 0 1 0 0-4 2 2 0 0 0 0 4m10 0a2 2 0 1 0 0-4 2 2 0 0 0 0 4"/><path d="M10.05 17H15V6.6a.6.6 0 0 0-.6-.6H1m4.65 11H3.6a.6.6 0 0 1-.6-.6v-4.9"/><path stroke-linejoin="round" d="M2 9h4"/><path d="M15 9h5.61a.6.6 0 0 1 .548.356l1.79 4.028a.6.6 0 0 1 .052.243V16.4a.6.6 0 0 1-.6.6h-1.9M15 17h1"/></svg>
+  {%- when 'support' -%}
+    <svg class="ds-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" aria-hidden="true" focusable="false"><path d="M8 10h8m-8 4h4m0 8c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12c0 1.821.487 3.53 1.338 5L2.5 21.5l4.5-.838A9.96 9.96 0 0 0 12 22"/></svg>
+  {%- else -%}
+    <svg class="ds-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" aria-hidden="true" focusable="false"><path d="M21 3.6v16.8a.6.6 0 0 1-.6.6H3.6a.6.6 0 0 1-.6-.6V3.6a.6.6 0 0 1 .6-.6h16.8a.6.6 0 0 1 .6.6"/><path d="m3 16 7-3 11 5m-5-8a2 2 0 1 1 0-4 2 2 0 0 1 0 4"/></svg>
+{%- endcase -%}`;
     SNIPPET_PRODUCT_CARD = `{% comment %}
   Product tile for grids. Usage: {% render 'ds-product-card', product: product %}
   Optional: show_vendor: true, enable_quick_add: true
@@ -3316,11 +4214,14 @@ var init_shopify_kit = __esm({
     {%- if product.featured_image -%}
       {%- assign ds_image_alt = product.featured_image.alt | default: product.title -%}
       {{ product.featured_image | image_url: width: 900 | image_tag: widths: '360, 540, 720, 900', sizes: '(min-width: 990px) 25vw, 50vw', alt: ds_image_alt }}
+    {%- else -%}
+      <span class="ds-media-empty" role="img" aria-label="Image unavailable">{% render 'ds-icon', icon: 'image' %}</span>
     {%- endif -%}
   </a>
   <div class="ds-card-body">
-    {%- if show_vendor -%}<p class="ds-supporting">{{ product.vendor }}</p>{%- endif -%}
     <h3 class="ds-card-title"><a href="{{ product.url }}">{{ product.title }}</a></h3>
+    {%- comment -%}Vendor sits under the title: a label above a heading is banned house style.{%- endcomment -%}
+    {%- if show_vendor -%}<p class="ds-supporting">{{ product.vendor }}</p>{%- endif -%}
     {% render 'ds-price', product: product %}
   </div>
   {%- if enable_quick_add -%}
@@ -3379,17 +4280,17 @@ var init_shopify_kit = __esm({
   FAQ accordion using the browser's native details element. Merchants add it
   from the theme editor as "DS FAQ".
 {% endcomment %}
-<div class="ds ds-embed ds-container ds-faq">
-  {%- if section.settings.heading != blank -%}
-    <h2 class="ds-section-title">{{ section.settings.heading }}</h2>
-  {%- endif -%}
+<section class="ds ds-embed ds-section">
+<div class="ds-container ds-faq">
+  {%- if section.settings.heading != blank -%}<div class="ds-section-head"><h2 class="ds-section-title">{{ section.settings.heading }}</h2></div>{%- endif -%}
   {%- for block in section.blocks -%}
-    <details class="ds-faq-item" {{ block.shopify_attributes }}>
+    <details class="ds-card ds-faq-item" {{ block.shopify_attributes }}>
       <summary>{{ block.settings.question }}</summary>
       <div class="ds-faq-answer">{{ block.settings.answer }}</div>
     </details>
   {%- endfor -%}
 </div>
+</section>
 {% schema %}
 {
   "name": "DS FAQ",
@@ -3414,19 +4315,28 @@ var init_shopify_kit = __esm({
   Product grid from a merchant-chosen collection. Merchants add it from the
   theme editor as "DS Featured collection".
 {% endcomment %}
-{%- assign ds_collection = section.settings.collection -%}
-<div class="ds ds-embed ds-container ds-featured">
-  {%- if section.settings.heading != blank -%}
-    <h2 class="ds-section-title">{{ section.settings.heading }}</h2>
-  {%- endif -%}
+{%- assign ds_collection = section.settings.collection | default: collections.all -%}
+{%- if ds_collection.products_count > 0 or request.design_mode -%}
+<section class="ds ds-embed ds-section">
+<div class="ds-container ds-featured">
+  <div class="ds-section-head">
+    {%- if section.settings.heading != blank -%}<h2 class="ds-section-title">{{ section.settings.heading }}</h2>{%- endif -%}
+    {%- if section.settings.show_view_all -%}<a class="ds-header-link" href="{{ ds_collection.url | default: routes.all_products_collection_url }}">View all products</a>{%- endif -%}
+  </div>
   <div class="ds-grid" style="--ds-cols: {{ section.settings.columns_desktop }}">
     {%- for product in ds_collection.products limit: section.settings.products_to_show -%}
       {% render 'ds-product-card', product: product, show_vendor: section.settings.show_vendor, enable_quick_add: section.settings.enable_quick_add %}
     {%- else -%}
-      <p class="ds-supporting">Choose a collection in the theme editor.</p>
+      <div class="ds-card ds-empty ds-grid-empty">
+        <span class="ds-icon-tile ds-icon-tile-blue">{% render 'ds-icon', icon: 'image' %}</span>
+        <h3 class="ds-card-title">Add products to this collection</h3>
+        <p class="ds-card-desc">Real product images, titles, and prices will appear here.</p>
+      </div>
     {%- endfor -%}
   </div>
 </div>
+</section>
+{%- endif -%}
 {% schema %}
 {
   "name": "DS Featured collection",
@@ -3436,90 +4346,189 @@ var init_shopify_kit = __esm({
     { "type": "range", "id": "products_to_show", "min": 2, "max": 12, "step": 1, "default": 4, "label": "Products to show" },
     { "type": "range", "id": "columns_desktop", "min": 2, "max": 5, "step": 1, "default": 4, "label": "Columns on desktop" },
     { "type": "checkbox", "id": "show_vendor", "label": "Show vendor", "default": false },
-    { "type": "checkbox", "id": "enable_quick_add", "label": "Enable quick add", "default": false }
+    { "type": "checkbox", "id": "enable_quick_add", "label": "Enable quick add", "default": false },
+    { "type": "checkbox", "id": "show_view_all", "label": "Show view all link", "default": true }
   ],
   "presets": [{ "name": "DS Featured collection" }]
 }
 {% endschema %}`;
     SECTION_HEADER = `{% comment %}
-  Site header. Merchants add it to the theme's header group in the editor.
+  Complete storefront header, including announcement, responsive navigation,
+  search, account, and cart. The generated header group installs it globally.
 {% endcomment %}
-<header class="ds ds-embed ds-header">
-  <a class="ds-header-brand" href="{{ routes.root_url }}">
-    {%- if section.settings.logo -%}
-      {{ section.settings.logo | image_url: width: 300 | image_tag: alt: shop.name, class: 'ds-header-logo' }}
-    {%- else -%}
-      {{ shop.name }}
-    {%- endif -%}
-  </a>
-  <nav class="ds-header-nav" aria-label="Main">
-    {%- for link in section.settings.menu.links -%}
-      <a href="{{ link.url }}"{% if link.current %} aria-current="page"{% endif %}>{{ link.title }}</a>
-    {%- endfor -%}
-  </nav>
-  <a class="ds-btn ds-btn-outline" href="{{ routes.cart_url }}">Cart ({{ cart.item_count }})</a>
-</header>
+{%- if section.settings.announcement_text != blank -%}
+  {% render 'ds-announcement', text: section.settings.announcement_text, link: section.settings.announcement_link, link_label: section.settings.announcement_link_label %}
+{%- endif -%}
+<div class="ds ds-embed ds-header-shell{% if section.settings.sticky %} is-sticky{% endif %}">
+  <header class="ds-container ds-card ds-header">
+    <details class="ds-mobile-nav">
+      <summary class="ds-header-link" aria-label="Open navigation menu">Menu</summary>
+      <nav class="ds-mobile-nav-panel" aria-label="Mobile">
+        {%- for link in section.settings.menu.links -%}
+          <a class="ds-header-link" href="{{ link.url }}"{% if link.current %} aria-current="page"{% endif %}>{{ link.title }}</a>
+        {%- endfor -%}
+        {%- if section.settings.show_search -%}<a class="ds-header-link" href="{{ routes.search_url }}">Search</a>{%- endif -%}
+        {%- if shop.customer_accounts_enabled and section.settings.show_account -%}<a class="ds-header-link" href="{{ routes.account_url }}">Account</a>{%- endif -%}
+      </nav>
+    </details>
+    <a class="ds-header-brand" href="{{ routes.root_url }}">
+      {%- if section.settings.logo -%}
+        {{ section.settings.logo | image_url: width: 360 | image_tag: widths: '180, 240, 360', alt: shop.name, class: 'ds-header-logo' }}
+      {%- else -%}
+        {{ shop.name }}
+      {%- endif -%}
+    </a>
+    <nav class="ds-header-nav" aria-label="Main">
+      {%- for link in section.settings.menu.links -%}
+        <a href="{{ link.url }}"{% if link.current %} aria-current="page"{% endif %}>{{ link.title }}</a>
+      {%- endfor -%}
+    </nav>
+    <div class="ds-header-actions">
+      {%- if section.settings.show_search -%}<a class="ds-header-link" href="{{ routes.search_url }}">Search</a>{%- endif -%}
+      {%- if shop.customer_accounts_enabled and section.settings.show_account -%}<a class="ds-header-link" href="{{ routes.account_url }}">Account</a>{%- endif -%}
+      <a class="ds-header-link ds-cart-link" href="{{ routes.cart_url }}"><span>Cart</span><span class="ds-cart-count">{{ cart.item_count }}</span></a>
+    </div>
+  </header>
+</div>
 {% schema %}
 {
   "name": "DS Header",
   "settings": [
     { "type": "image_picker", "id": "logo", "label": "Logo" },
-    { "type": "link_list", "id": "menu", "label": "Menu", "default": "main-menu" }
+    { "type": "link_list", "id": "menu", "label": "Menu", "default": "main-menu" },
+    { "type": "text", "id": "announcement_text", "label": "Announcement", "default": "Free shipping and easy returns" },
+    { "type": "text", "id": "announcement_link_label", "label": "Announcement link label" },
+    { "type": "url", "id": "announcement_link", "label": "Announcement link" },
+    { "type": "checkbox", "id": "show_search", "label": "Show search", "default": true },
+    { "type": "checkbox", "id": "show_account", "label": "Show account", "default": true },
+    { "type": "checkbox", "id": "sticky", "label": "Sticky header", "default": true }
   ],
   "presets": [{ "name": "DS Header" }]
 }
 {% endschema %}`;
     SECTION_FOOTER = `{% comment %}
-  Site footer. Merchants add it to the theme's footer group in the editor.
+  Complete storefront footer with navigation, newsletter, policies, and
+  payment methods. The generated footer group installs it globally.
 {% endcomment %}
 <footer class="ds ds-embed ds-footer">
-  <span class="ds-header-brand">{{ shop.name }}</span>
-  <nav aria-label="Footer">
-    {%- for link in section.settings.menu.links -%}
-      <a href="{{ link.url }}">{{ link.title }}</a>
-    {%- endfor -%}
-  </nav>
-  <span class="ds-supporting">&copy; {{ 'now' | date: '%Y' }} {{ shop.name }}</span>
+  <div class="ds-container ds-card ds-footer-panel">
+    <div class="ds-footer-grid">
+      <div class="ds-footer-brand">
+        <a class="ds-header-brand" href="{{ routes.root_url }}">{{ shop.name }}</a>
+        {%- if section.settings.text != blank -%}<div class="ds-section-copy">{{ section.settings.text }}</div>{%- endif -%}
+        {%- if section.settings.show_newsletter -%}
+          {% render 'ds-newsletter', id: section.id, heading: section.settings.newsletter_heading, button_label: section.settings.newsletter_button_label %}
+        {%- endif -%}
+      </div>
+      <div>
+        <h2 class="ds-footer-title">{{ section.settings.menu_heading }}</h2>
+        <nav aria-label="{{ section.settings.menu_heading | escape }}">
+          {%- for link in section.settings.menu.links -%}<a href="{{ link.url }}">{{ link.title }}</a>{%- endfor -%}
+        </nav>
+      </div>
+      <div>
+        <h2 class="ds-footer-title">{{ section.settings.secondary_menu_heading }}</h2>
+        <nav aria-label="{{ section.settings.secondary_menu_heading | escape }}">
+          {%- for link in section.settings.secondary_menu.links -%}<a href="{{ link.url }}">{{ link.title }}</a>{%- endfor -%}
+        </nav>
+      </div>
+    </div>
+    <div class="ds-footer-bottom">
+      <div>
+        <p class="ds-supporting">&copy; {{ 'now' | date: '%Y' }} {{ shop.name }}</p>
+        {%- if section.settings.show_policies -%}
+          <ul class="ds-policy-list" role="list">
+            {%- for policy in shop.policies -%}{%- if policy != blank -%}<li><a href="{{ policy.url }}">{{ policy.title }}</a></li>{%- endif -%}{%- endfor -%}
+          </ul>
+        {%- endif -%}
+      </div>
+      {%- if section.settings.show_payment_icons -%}
+        <ul class="ds-payment-list" role="list" aria-label="Accepted payment methods">
+          {%- for type in shop.enabled_payment_types -%}<li>{{ type | payment_type_svg_tag: class: 'ds-payment-icon' }}</li>{%- endfor -%}
+        </ul>
+      {%- endif -%}
+    </div>
+  </div>
 </footer>
 {% schema %}
 {
   "name": "DS Footer",
   "settings": [
-    { "type": "link_list", "id": "menu", "label": "Menu", "default": "footer" }
+    { "type": "richtext", "id": "text", "label": "Store description", "default": "<p>Thoughtful products, clear service, and a storefront designed around what matters.</p>" },
+    { "type": "text", "id": "menu_heading", "label": "Menu heading", "default": "Shop" },
+    { "type": "link_list", "id": "menu", "label": "Menu", "default": "main-menu" },
+    { "type": "text", "id": "secondary_menu_heading", "label": "Secondary menu heading", "default": "Help" },
+    { "type": "link_list", "id": "secondary_menu", "label": "Secondary menu", "default": "footer" },
+    { "type": "checkbox", "id": "show_newsletter", "label": "Show newsletter", "default": true },
+    { "type": "text", "id": "newsletter_heading", "label": "Newsletter heading", "default": "Get product news and useful updates" },
+    { "type": "text", "id": "newsletter_button_label", "label": "Newsletter button label", "default": "Subscribe" },
+    { "type": "checkbox", "id": "show_policies", "label": "Show policies", "default": true },
+    { "type": "checkbox", "id": "show_payment_icons", "label": "Show payment icons", "default": true }
   ],
   "presets": [{ "name": "DS Footer" }]
 }
 {% endschema %}`;
     SECTION_HERO = `{% comment %}
-  Hero with image, heading, supporting line, and up to 2 actions.
+  Product-led hero. A selected product supplies its image, price, and link;
+  otherwise the section falls back to the first all-products item.
 {% endcomment %}
-<div class="ds ds-embed ds-container ds-hero">
-  {%- if section.settings.image -%}
-    {%- assign ds_image_alt = section.settings.heading | strip_html -%}
-    {{ section.settings.image | image_url: width: 1600 | image_tag: widths: '750, 1100, 1600', sizes: '100vw', alt: ds_image_alt }}
-  {%- endif -%}
-  <h2 class="ds-display">{{ section.settings.heading }}</h2>
-  {%- if section.settings.text != blank -%}<p class="ds-supporting">{{ section.settings.text }}</p>{%- endif -%}
-  <div class="ds-hero-actions">
-    {%- if section.settings.button_label != blank -%}
-      <a class="ds-btn ds-btn-primary" href="{{ section.settings.button_link }}">{{ section.settings.button_label }}</a>
-    {%- endif -%}
-    {%- if section.settings.secondary_label != blank -%}
-      <a class="ds-btn ds-btn-outline" href="{{ section.settings.secondary_link }}">{{ section.settings.secondary_label }}</a>
-    {%- endif -%}
+{%- liquid
+  assign ds_product = section.settings.product
+  if ds_product == blank
+    assign ds_product = collections.all.products.first
+  endif
+  assign ds_has_hero_image = false
+  if section.settings.image or ds_product.featured_image
+    assign ds_has_hero_image = true
+  endif
+  assign ds_show_hero_media = ds_has_hero_image
+  if request.design_mode
+    assign ds_show_hero_media = true
+  endif
+  assign ds_button_link = section.settings.button_link | default: ds_product.url | default: routes.all_products_collection_url
+-%}
+<section class="ds ds-embed ds-hero-section">
+  <div class="ds-container ds-hero{% unless ds_show_hero_media %} ds-hero-single{% endunless %}">
+    <div class="ds-hero-content">
+      {%- if request.page_type == 'index' -%}<h1 class="ds-display">{{ section.settings.heading }}</h1>{%- else -%}<h2 class="ds-display">{{ section.settings.heading }}</h2>{%- endif -%}
+      {%- if section.settings.text != blank -%}<p class="ds-supporting">{{ section.settings.text }}</p>{%- endif -%}
+      {%- if ds_product != blank -%}{% render 'ds-price', product: ds_product %}{%- endif -%}
+      <div class="ds-hero-actions">
+        {%- if section.settings.button_label != blank -%}<a class="ds-btn ds-btn-primary" href="{{ ds_button_link }}">{{ section.settings.button_label }}</a>{%- endif -%}
+        {%- if section.settings.secondary_label != blank -%}<a class="ds-btn ds-btn-outline" href="{{ section.settings.secondary_link }}">{{ section.settings.secondary_label }}</a>{%- endif -%}
+      </div>
+      {%- if section.settings.trust_text != blank -%}<p class="ds-hero-trust">{{ section.settings.trust_text }}</p>{%- endif -%}
+    </div>
+    {%- if ds_show_hero_media -%}<div class="ds-hero-media{% if ds_has_hero_image %} ds-hero-media-has-image{% endif %}">
+      {%- if section.settings.image -%}
+        {%- assign ds_image_alt = section.settings.heading | strip_html -%}
+        {{ section.settings.image | image_url: width: 1600 | image_tag: widths: '600, 900, 1200, 1600', sizes: '(min-width: 990px) 55vw, 100vw', alt: ds_image_alt }}
+      {%- elsif ds_product.featured_image -%}
+        {%- assign ds_image_alt = ds_product.featured_image.alt | default: ds_product.title -%}
+        {{ ds_product.featured_image | image_url: width: 1600 | image_tag: widths: '600, 900, 1200, 1600', sizes: '(min-width: 990px) 55vw, 100vw', alt: ds_image_alt }}
+      {%- else -%}
+        <div class="ds-card ds-media-empty">
+          <span class="ds-icon-tile ds-icon-tile-blue">{% render 'ds-icon', icon: 'image' %}</span>
+          <p class="ds-media-empty-title">Choose a hero image</p>
+          <p class="ds-media-empty-copy">Select an image or featured product in this section.</p>
+        </div>
+      {%- endif -%}
+    </div>{%- endif -%}
   </div>
-</div>
+</section>
 {% schema %}
 {
   "name": "DS Hero",
   "settings": [
+    { "type": "product", "id": "product", "label": "Featured product" },
     { "type": "image_picker", "id": "image", "label": "Image" },
-    { "type": "inline_richtext", "id": "heading", "label": "Heading", "default": "Tell your story" },
-    { "type": "text", "id": "text", "label": "Supporting line" },
-    { "type": "text", "id": "button_label", "label": "Button label", "default": "Shop now" },
+    { "type": "inline_richtext", "id": "heading", "label": "Heading", "default": "Made for every day" },
+    { "type": "text", "id": "text", "label": "Supporting line", "default": "Useful products, thoughtful details, and clear service." },
+    { "type": "text", "id": "button_label", "label": "Button label", "default": "Shop the collection" },
     { "type": "url", "id": "button_link", "label": "Button link" },
     { "type": "text", "id": "secondary_label", "label": "Secondary button label" },
-    { "type": "url", "id": "secondary_link", "label": "Secondary button link" }
+    { "type": "url", "id": "secondary_link", "label": "Secondary button link" },
+    { "type": "text", "id": "trust_text", "label": "Trust line", "default": "Secure checkout. Easy returns. Human support." }
   ],
   "presets": [{ "name": "DS Hero" }]
 }
@@ -3527,13 +4536,15 @@ var init_shopify_kit = __esm({
     SECTION_RICH_TEXT = `{% comment %}
   Heading plus rich text, with an optional button.
 {% endcomment %}
-<div class="ds ds-embed ds-container" style="padding:2rem 0">
+<section class="ds ds-embed ds-section">
+<div class="ds-container ds-rich-text">
   {%- if section.settings.heading != blank -%}<h2 class="ds-section-title">{{ section.settings.heading }}</h2>{%- endif -%}
-  <div>{{ section.settings.text }}</div>
+  <div class="ds-section-copy">{{ section.settings.text }}</div>
   {%- if section.settings.button_label != blank -%}
-    <p><a class="ds-btn ds-btn-secondary" href="{{ section.settings.button_link }}">{{ section.settings.button_label }}</a></p>
+    <a class="ds-btn ds-btn-secondary" href="{{ section.settings.button_link }}">{{ section.settings.button_label }}</a>
   {%- endif -%}
 </div>
+</section>
 {% schema %}
 {
   "name": "DS Rich text",
@@ -3549,23 +4560,38 @@ var init_shopify_kit = __esm({
     SECTION_IMAGE_WITH_TEXT = `{% comment %}
   Image beside heading, text, and an optional button.
 {% endcomment %}
-<div class="ds ds-embed ds-container ds-image-text">
+{%- assign ds_story_product = section.settings.product | default: collections.all.products[1] | default: collections.all.products.first -%}
+<section class="ds ds-embed ds-section">
+<div class="ds-container ds-image-text{% unless section.settings.image or ds_story_product.featured_image or request.design_mode %} ds-image-text-single{% endunless %}">
+  {%- if section.settings.image or ds_story_product.featured_image or request.design_mode -%}<div class="ds-card ds-image-text-media">
   {%- if section.settings.image -%}
     {%- assign ds_image_alt = section.settings.heading | strip_html -%}
     {{ section.settings.image | image_url: width: 900 | image_tag: widths: '480, 720, 900', sizes: '(min-width: 750px) 50vw, 100vw', alt: ds_image_alt }}
+  {%- elsif ds_story_product.featured_image -%}
+    {%- assign ds_image_alt = ds_story_product.featured_image.alt | default: ds_story_product.title -%}
+    {{ ds_story_product.featured_image | image_url: width: 1200 | image_tag: widths: '480, 720, 900, 1200', sizes: '(min-width: 750px) 50vw, 100vw', alt: ds_image_alt }}
+  {%- else -%}
+    <div class="ds-media-empty">
+      <span class="ds-icon-tile ds-icon-tile-orange">{% render 'ds-icon', icon: 'image' %}</span>
+      <p class="ds-media-empty-title">Choose a story image</p>
+      <p class="ds-media-empty-copy">Select an image or product for this section.</p>
+    </div>
   {%- endif -%}
+  </div>{%- endif -%}
   <div class="ds-product-info">
     <h2 class="ds-section-title">{{ section.settings.heading }}</h2>
-    <div>{{ section.settings.text }}</div>
+    <div class="ds-section-copy">{{ section.settings.text }}</div>
     {%- if section.settings.button_label != blank -%}
       <p><a class="ds-btn ds-btn-primary" href="{{ section.settings.button_link }}">{{ section.settings.button_label }}</a></p>
     {%- endif -%}
   </div>
 </div>
+</section>
 {% schema %}
 {
   "name": "DS Image with text",
   "settings": [
+    { "type": "product", "id": "product", "label": "Product image fallback" },
     { "type": "image_picker", "id": "image", "label": "Image" },
     { "type": "inline_richtext", "id": "heading", "label": "Heading", "default": "Pair text with an image" },
     { "type": "richtext", "id": "text", "label": "Text" },
@@ -3582,10 +4608,14 @@ var init_shopify_kit = __esm({
 <div class="ds ds-embed ds-container ds-product-page">
   <div class="ds-product-layout">
     <div class="ds-product-media">
+      <div class="ds-card ds-product-media-main">
       {%- if product.featured_image -%}
         {%- assign ds_image_alt = product.featured_image.alt | default: product.title -%}
         {{ product.featured_image | image_url: width: 1200 | image_tag: widths: '480, 720, 960, 1200', sizes: '(min-width: 750px) 50vw, 100vw', alt: ds_image_alt }}
+      {%- else -%}
+        <div class="ds-media-empty" role="img" aria-label="Product image unavailable">{% render 'ds-icon', icon: 'image' %}</div>
       {%- endif -%}
+      </div>
       {%- if product.images.size > 1 -%}
         <div class="ds-product-thumbs">
           {%- for image in product.images offset: 1 limit: 4 -%}
@@ -3595,12 +4625,13 @@ var init_shopify_kit = __esm({
         </div>
       {%- endif -%}
     </div>
-    <div class="ds-product-info">
-      {%- if section.settings.show_vendor -%}<p class="ds-supporting">{{ product.vendor }}</p>{%- endif -%}
+    <div class="ds-card ds-product-info">
       <h1 class="ds-display">{{ product.title }}</h1>
+      {%- comment -%}Vendor sits under the title: a label above a heading is banned house style.{%- endcomment -%}
+      {%- if section.settings.show_vendor -%}<p class="ds-supporting">{{ product.vendor }}</p>{%- endif -%}
       {% render 'ds-price', variant: product.selected_or_first_available_variant %}
       {% render 'ds-buy-button', product: product, show_quantity: section.settings.show_quantity %}
-      <div>{{ product.description }}</div>
+      <div class="ds-product-description">{{ product.description }}</div>
     </div>
   </div>
 </div>
@@ -3620,9 +4651,11 @@ var init_shopify_kit = __esm({
 {% endcomment %}
 {% paginate collection.products by section.settings.products_per_page %}
 <div class="ds ds-embed ds-container ds-collection-page">
-  <h1 class="ds-display">{{ collection.title }}</h1>
-  {%- if collection.description != blank -%}<div class="ds-supporting">{{ collection.description }}</div>{%- endif -%}
-  <div class="ds-grid" style="--ds-cols: {{ section.settings.columns_desktop }}; margin-top: 1.5rem">
+  <div class="ds-collection-head">
+    <h1 class="ds-display">{{ collection.title }}</h1>
+    {%- if collection.description != blank -%}<div class="ds-section-copy">{{ collection.description }}</div>{%- endif -%}
+  </div>
+  <div class="ds-grid" style="--ds-cols: {{ section.settings.columns_desktop }}">
     {%- for product in collection.products -%}
       {% render 'ds-product-card', product: product, show_vendor: section.settings.show_vendor, enable_quick_add: section.settings.enable_quick_add %}
     {%- else -%}
@@ -3647,9 +4680,10 @@ var init_shopify_kit = __esm({
     SECTION_CONTACT = `{% comment %}
   Contact form posting to Shopify's contact endpoint. No JavaScript.
 {% endcomment %}
-<div class="ds ds-embed ds-container" style="max-width:36rem;padding:2rem 0">
+<section class="ds ds-embed ds-section">
+<div class="ds-container ds-page">
   <h2 class="ds-section-title">{{ section.settings.heading }}</h2>
-  {% form 'contact' %}
+  {% form 'contact', class: 'ds-card ds-contact-form' %}
     {%- if form.posted_successfully? -%}
       <p role="status">Thanks for your message. We reply within one business day.</p>
     {%- else -%}
@@ -3670,6 +4704,7 @@ var init_shopify_kit = __esm({
     {%- endif -%}
   {% endform %}
 </div>
+</section>
 {% schema %}
 {
   "name": "DS Contact",
@@ -3682,19 +4717,22 @@ var init_shopify_kit = __esm({
     SECTION_MULTICOLUMN = `{% comment %}
   Row of text cards, for value props or feature callouts.
 {% endcomment %}
-<div class="ds ds-embed ds-container" style="padding:2rem 0">
-  {%- if section.settings.heading != blank -%}<h2 class="ds-section-title">{{ section.settings.heading }}</h2>{%- endif -%}
-  <div class="ds-grid" style="--ds-cols: {{ section.settings.columns_desktop }}">
+<section class="ds ds-embed ds-section-compact">
+<div class="ds-container">
+  {%- if section.settings.heading != blank -%}<div class="ds-section-head"><h2 class="ds-section-title">{{ section.settings.heading }}</h2></div>{%- endif -%}
+  <div class="ds-card ds-value-panel" style="--ds-cols: {{ section.settings.columns_desktop }}">
     {%- for block in section.blocks -%}
-      <div class="ds-card" {{ block.shopify_attributes }}>
-        <div class="ds-card-body">
-          <h3 class="ds-card-title">{{ block.settings.heading }}</h3>
+      <div class="ds-value-item" {{ block.shopify_attributes }}>
+          <div class="ds-value-title-row">
+            {%- if block.settings.icon != 'none' -%}<span class="ds-icon-tile {% cycle 'ds-icon-tile-blue', 'ds-icon-tile-orange', 'ds-icon-tile-green' %}">{% render 'ds-icon', icon: block.settings.icon %}</span>{%- endif -%}
+            <h3 class="ds-card-title">{{ block.settings.heading }}</h3>
+          </div>
           <p class="ds-card-desc">{{ block.settings.text }}</p>
-        </div>
       </div>
     {%- endfor -%}
   </div>
 </div>
+</section>
 {% schema %}
 {
   "name": "DS Multicolumn",
@@ -3707,6 +4745,7 @@ var init_shopify_kit = __esm({
       "type": "column",
       "name": "Column",
       "settings": [
+        { "type": "select", "id": "icon", "label": "Icon", "default": "quality", "options": [{ "value": "quality", "label": "Quality" }, { "value": "delivery", "label": "Delivery" }, { "value": "support", "label": "Support" }, { "value": "none", "label": "None" }] },
         { "type": "text", "id": "heading", "label": "Heading" },
         { "type": "text", "id": "text", "label": "Text" }
       ]
@@ -3716,27 +4755,231 @@ var init_shopify_kit = __esm({
   "presets": [{ "name": "DS Multicolumn", "blocks": [{ "type": "column" }, { "type": "column" }, { "type": "column" }] }]
 }
 {% endschema %}`;
-    TEMPLATE_PRODUCT_JSON = `{
-  "sections": {
-    "main": {
-      "type": "ds-main-product",
-      "settings": {}
-    }
-  },
-  "order": ["main"]
-}`;
-    TEMPLATE_COLLECTION_JSON = `{
-  "sections": {
-    "main": {
-      "type": "ds-main-collection",
-      "settings": {}
-    }
-  },
+    SECTION_MAIN_PAGE = `{% comment %}
+  Default content page, styled by the selected design system.
+{% endcomment %}
+<main class="ds ds-embed ds-container ds-page">
+  <header class="ds-page-head"><h1 class="ds-display">{{ page.title }}</h1></header>
+  <div class="ds-card ds-page-content ds-product-description">{{ page.content }}</div>
+</main>
+{% schema %}
+{
+  "name": "DS Page",
+  "enabled_on": { "templates": ["page"] }
+}
+{% endschema %}`;
+    SECTION_MAIN_CART = `{% comment %}
+  Native cart page. Quantity changes post through Shopify without JavaScript.
+{% endcomment %}
+<main class="ds ds-embed ds-container ds-cart-page">
+  <header class="ds-page-head"><h1 class="ds-display">Your cart</h1></header>
+  {%- if cart.item_count > 0 -%}
+    <form action="{{ routes.cart_url }}" method="post">
+      <ul class="ds-cart-list" role="list">
+        {%- for item in cart.items -%}
+          <li class="ds-card ds-cart-item">
+            <a href="{{ item.url }}" aria-label="{{ item.product.title | escape }}">
+              {%- if item.image -%}
+                {%- assign ds_cart_alt = item.image.alt | default: item.product.title -%}
+                {{ item.image | image_url: width: 280 | image_tag: widths: '140, 210, 280', alt: ds_cart_alt }}
+              {%- else -%}
+                <span class="ds-media-empty" role="img" aria-label="Image unavailable">{% render 'ds-icon', icon: 'image' %}</span>
+              {%- endif -%}
+            </a>
+            <div>
+              <h2 class="ds-card-title"><a href="{{ item.url }}">{{ item.product.title }}</a></h2>
+              {%- unless item.product.has_only_default_variant -%}<p class="ds-supporting">{{ item.variant.title }}</p>{%- endunless -%}
+              <label class="ds-label" for="ds-cart-quantity-{{ item.index | plus: 1 }}">Quantity</label>
+              <input class="ds-input ds-qty" id="ds-cart-quantity-{{ item.index | plus: 1 }}" type="number" name="updates[]" value="{{ item.quantity }}" min="0">
+              <a class="ds-header-link" href="{{ item.url_to_remove }}">Remove</a>
+            </div>
+            <strong class="ds-cart-item-total">{{ item.final_line_price | money }}</strong>
+          </li>
+        {%- endfor -%}
+      </ul>
+      <div class="ds-card ds-cart-summary">
+        <p class="ds-supporting">Taxes and shipping calculated at checkout.</p>
+        <div class="ds-price"><span>Subtotal</span><span class="ds-price-current">{{ cart.total_price | money }}</span></div>
+        <div class="ds-hero-actions">
+          <button class="ds-btn ds-btn-outline" type="submit" name="update">Update cart</button>
+          <button class="ds-btn ds-btn-primary" type="submit" name="checkout">Checkout</button>
+        </div>
+      </div>
+    </form>
+  {%- else -%}
+    <div class="ds-card ds-empty"><p class="ds-section-copy">Your cart is empty.</p><a class="ds-btn ds-btn-primary" href="{{ routes.all_products_collection_url }}">Continue shopping</a></div>
+  {%- endif -%}
+</main>
+{% schema %}
+{
+  "name": "DS Cart",
+  "enabled_on": { "templates": ["cart"] }
+}
+{% endschema %}`;
+    SECTION_MAIN_SEARCH = `{% comment %}
+  Search page with native Shopify query handling and paginated results.
+{% endcomment %}
+<main class="ds ds-embed ds-container ds-search-page">
+  <header class="ds-page-head"><h1 class="ds-display">Search</h1></header>
+  <form class="ds-card ds-search-form" action="{{ routes.search_url }}" method="get" role="search">
+    <div>
+      <label class="ds-label" for="ds-search-query-{{ section.id }}">What are you looking for?</label>
+      <input class="ds-input" id="ds-search-query-{{ section.id }}" type="search" name="q" value="{{ search.terms | escape }}" autocomplete="off">
+    </div>
+    <button class="ds-btn ds-btn-primary" type="submit">Search</button>
+  </form>
+  {%- if search.performed -%}
+    {% paginate search.results by section.settings.results_per_page %}
+      <div class="ds-section-head"><h2 class="ds-section-title">{{ search.results_count }} results</h2></div>
+      <div class="ds-grid" style="--ds-cols: {{ section.settings.columns_desktop }}">
+        {%- for item in search.results -%}
+          {%- if item.object_type == 'product' -%}
+            {% render 'ds-product-card', product: item %}
+          {%- else -%}
+            <article class="ds-card"><div class="ds-card-body"><h3 class="ds-card-title"><a href="{{ item.url }}">{{ item.title }}</a></h3><p class="ds-card-desc">{{ item.content | strip_html | truncatewords: 24 }}</p></div></article>
+          {%- endif -%}
+        {%- else -%}
+          <div class="ds-card ds-empty ds-grid-empty"><p class="ds-section-copy">No results found. Try a shorter or more general search.</p><a class="ds-btn ds-btn-outline" href="{{ routes.all_products_collection_url }}">Browse all products</a></div>
+        {%- endfor -%}
+      </div>
+      {% render 'ds-pagination', paginate: paginate %}
+    {% endpaginate %}
+  {%- endif -%}
+</main>
+{% schema %}
+{
+  "name": "DS Search",
+  "settings": [
+    { "type": "range", "id": "results_per_page", "min": 4, "max": 24, "step": 4, "default": 12, "label": "Results per page" },
+    { "type": "range", "id": "columns_desktop", "min": 2, "max": 4, "step": 1, "default": 4, "label": "Columns on desktop" }
+  ],
+  "enabled_on": { "templates": ["search"] }
+}
+{% endschema %}`;
+    SECTION_MAIN_404 = `{% comment %}
+  Compact not-found page with a clear recovery action.
+{% endcomment %}
+<main class="ds ds-embed ds-container ds-page">
+  <div class="ds-card ds-empty">
+    <h1 class="ds-display">Page not found</h1>
+    <p class="ds-section-copy">The page may have moved or the link may be incorrect.</p>
+    <a class="ds-btn ds-btn-primary" href="{{ routes.all_products_collection_url }}">Browse all products</a>
+  </div>
+</main>
+{% schema %}
+{
+  "name": "DS 404",
+  "enabled_on": { "templates": ["404"] }
+}
+{% endschema %}`;
+    TEMPLATE_INDEX_JSON = `{
+  "sections": {
+    "hero": {
+      "type": "ds-hero",
+      "settings": {
+        "heading": "Made for every day",
+        "text": "Useful products, thoughtful details, and clear service.",
+        "button_label": "Shop the collection",
+        "button_link": "shopify://collections/all",
+        "trust_text": "Secure checkout. Easy returns. Human support."
+      }
+    },
+    "featured": {
+      "type": "ds-featured-collection",
+      "settings": { "heading": "Featured products", "collection": "all", "products_to_show": 4, "columns_desktop": 4, "show_view_all": true }
+    },
+    "story": {
+      "type": "ds-image-with-text",
+      "settings": {
+        "heading": "Useful by design",
+        "text": "<p>Every product should earn its place. Use this section to explain the materials, choices, or details that make yours worth choosing.</p>",
+        "button_label": "Explore the collection",
+        "button_link": "shopify://collections/all"
+      }
+    },
+    "values": {
+      "type": "ds-multicolumn",
+      "blocks": {
+        "quality": { "type": "column", "settings": { "icon": "quality", "heading": "Made to last", "text": "Explain the quality customers can see and feel." } },
+        "delivery": { "type": "column", "settings": { "icon": "delivery", "heading": "Clear delivery", "text": "Set useful expectations for shipping and returns." } },
+        "support": { "type": "column", "settings": { "icon": "support", "heading": "Human support", "text": "Tell customers where to get a real answer." } }
+      },
+      "block_order": ["quality", "delivery", "support"],
+      "settings": { "heading": "What you can expect", "columns_desktop": 3 }
+    },
+    "faq": {
+      "type": "ds-faq",
+      "blocks": {
+        "shipping": { "type": "item", "settings": { "question": "When will my order arrive?", "answer": "<p>Add your delivery timing and tracking details here.</p>" } },
+        "returns": { "type": "item", "settings": { "question": "What is your return policy?", "answer": "<p>Summarize the return window and the first step for starting a return.</p>" } },
+        "support": { "type": "item", "settings": { "question": "How can I contact you?", "answer": "<p>Add the fastest support channel and expected reply time.</p>" } }
+      },
+      "block_order": ["shipping", "returns", "support"],
+      "settings": { "heading": "Questions, answered" }
+    }
+  },
+  "order": ["hero", "featured", "story", "values", "faq"]
+}`;
+    TEMPLATE_PRODUCT_JSON = `{
+  "sections": {
+    "main": {
+      "type": "ds-main-product",
+      "settings": {}
+    }
+  },
+  "order": ["main"]
+}`;
+    TEMPLATE_PAGE_JSON = `{
+  "sections": { "main": { "type": "ds-main-page", "settings": {} } },
+  "order": ["main"]
+}`;
+    TEMPLATE_CART_JSON = `{
+  "sections": { "main": { "type": "ds-main-cart", "settings": {} } },
+  "order": ["main"]
+}`;
+    TEMPLATE_SEARCH_JSON = `{
+  "sections": { "main": { "type": "ds-main-search", "settings": {} } },
+  "order": ["main"]
+}`;
+    TEMPLATE_404_JSON = `{
+  "sections": { "main": { "type": "ds-main-404", "settings": {} } },
+  "order": ["main"]
+}`;
+    HEADER_GROUP_JSON = `{
+  "name": "Header group",
+  "type": "header",
+  "sections": {
+    "ds_header": {
+      "type": "ds-header",
+      "settings": { "menu": "main-menu", "announcement_text": "Free shipping and easy returns", "show_search": true, "show_account": true, "sticky": true }
+    }
+  },
+  "order": ["ds_header"]
+}`;
+    FOOTER_GROUP_JSON = `{
+  "name": "Footer group",
+  "type": "footer",
+  "sections": {
+    "ds_footer": {
+      "type": "ds-footer",
+      "settings": { "menu": "main-menu", "secondary_menu": "footer", "show_newsletter": true, "show_policies": true, "show_payment_icons": true }
+    }
+  },
+  "order": ["ds_footer"]
+}`;
+    TEMPLATE_COLLECTION_JSON = `{
+  "sections": {
+    "main": {
+      "type": "ds-main-collection",
+      "settings": {}
+    }
+  },
   "order": ["main"]
 }`;
     SNIPPETS = [
       { path: "snippets/ds-badge.liquid", content: SNIPPET_BADGE },
       { path: "snippets/ds-price.liquid", content: SNIPPET_PRICE },
+      { path: "snippets/ds-icon.liquid", content: SNIPPET_ICON },
       { path: "snippets/ds-variant-select.liquid", content: SNIPPET_VARIANT_SELECT },
       { path: "snippets/ds-buy-button.liquid", content: SNIPPET_BUY_BUTTON },
       { path: "snippets/ds-product-card.liquid", content: SNIPPET_PRODUCT_CARD },
@@ -3754,15 +4997,32 @@ var init_shopify_kit = __esm({
       { path: "sections/ds-featured-collection.liquid", content: SECTION_FEATURED_COLLECTION },
       { path: "sections/ds-main-product.liquid", content: SECTION_MAIN_PRODUCT },
       { path: "sections/ds-main-collection.liquid", content: SECTION_MAIN_COLLECTION },
+      { path: "sections/ds-main-page.liquid", content: SECTION_MAIN_PAGE },
+      { path: "sections/ds-main-cart.liquid", content: SECTION_MAIN_CART },
+      { path: "sections/ds-main-search.liquid", content: SECTION_MAIN_SEARCH },
+      { path: "sections/ds-main-404.liquid", content: SECTION_MAIN_404 },
+      { path: "sections/header-group.json", content: HEADER_GROUP_JSON },
+      { path: "sections/footer-group.json", content: FOOTER_GROUP_JSON },
+      { path: "templates/index.json", content: TEMPLATE_INDEX_JSON },
+      { path: "templates/product.json", content: TEMPLATE_PRODUCT_JSON },
+      { path: "templates/collection.json", content: TEMPLATE_COLLECTION_JSON },
+      { path: "templates/page.json", content: TEMPLATE_PAGE_JSON },
+      { path: "templates/cart.json", content: TEMPLATE_CART_JSON },
+      { path: "templates/search.json", content: TEMPLATE_SEARCH_JSON },
+      { path: "templates/404.json", content: TEMPLATE_404_JSON },
       { path: "templates/product.ds.json", content: TEMPLATE_PRODUCT_JSON },
       { path: "templates/collection.ds.json", content: TEMPLATE_COLLECTION_JSON }
     ];
     SHOPIFY_KIT_CONDUCT_MD = [
       "## Install into the merchant's theme (mandatory order)",
-      "1. Write `assets/ds-kit.css` into the theme's `assets/` directory, every `snippets/ds-*.liquid` file into `snippets/`, every `sections/ds-*.liquid` file into `sections/`, and the `templates/*.ds.json` files into `templates/`. Copy file contents VERBATIM; retyped Liquid silently drops this system's material.",
-      "2. Load the stylesheet once in `layout/theme.liquid`, before `</head>`: `{{ 'ds-kit.css' | asset_url | stylesheet_tag }}`.",
-      '3. Merchants place everything from the theme editor: "DS Header" and "DS Footer" go into the theme\'s header and footer section groups; "DS Hero", "DS Featured collection", "DS Multicolumn", "DS Image with text", "DS Rich text", "DS Contact", and "DS FAQ" appear in the Add section list on any page. Any snippet also works from the built-in Custom Liquid section with one `{% render %}` line.',
-      "4. For fully branded product and collection pages, assign the `product.ds` and `collection.ds` templates to products and collections in the admin. They render `ds-main-product` and `ds-main-collection`, which include a native no-JavaScript variant dropdown and pagination.",
+      "1. Duplicate the merchant's theme and work only in the unpublished copy. This full-store kit replaces the default header/footer groups and primary storefront templates; never install it directly on the live theme.",
+      "2. Write every returned file to its exact path. That includes the CSS asset, snippets, Liquid sections, `sections/header-group.json`, `sections/footer-group.json`, and the primary `templates/*.json` files. Copy contents VERBATIM; retyped Liquid silently drops this system's material.",
+      "3. Load the stylesheet once in `layout/theme.liquid`, before `</head>`: `{{ 'ds-kit.css' | asset_url | stylesheet_tag }}`.",
+      "4. In `layout/theme.liquid`, confirm the theme renders `{% sections 'header-group' %}` and `{% sections 'footer-group' %}`; the generated group files become global only through those calls.",
+      "   - If the theme uses different group names, rename the generated group files and call them with `{% sections '<group-name>' %}`.",
+      "   - If it renders header/footer sections directly, replace those calls with the generated group calls, or use `{% section 'ds-header' %}` and `{% section 'ds-footer' %}` without group-editor support.",
+      "5. The generated index, product, collection, page, cart, search, and 404 templates make the selected system the storefront default; `product.ds` and `collection.ds` remain available as alternate templates for compatibility.",
+      "6. Open the unpublished theme editor. Select a featured product or hero image, replace the starter copy, verify menus and policies, then review desktop and mobile before publishing.",
       "",
       "## Class contract (pass/fail)",
       "- Do not rename `ds-*` classes and do not strip the `ds ds-embed` wrapper a snippet renders on its root; the wrapper scopes this system's tokens and keeps the background transparent inside existing theme sections.",
@@ -3782,6 +5042,43 @@ var init_shopify_kit = __esm({
   }
 });
 
+// ../shared/src/registry-css.ts
+function parseCssVars(css) {
+  const out = { theme: {}, light: {}, dark: {} };
+  const matchBlock = (selector) => {
+    const re = new RegExp(`${selector}\\s*\\{([^}]*)\\}`, "g");
+    const blocks = [];
+    let m;
+    while (m = re.exec(css)) blocks.push(m[1]);
+    return blocks.join("\n");
+  };
+  const extract = (body) => {
+    const result = {};
+    const clean = body.replace(/\/\*[\s\S]*?\*\//g, "");
+    const declRe = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
+    let m;
+    while (m = declRe.exec(clean)) {
+      result[m[1]] = m[2].replace(/\s+/g, " ").trim();
+    }
+    return result;
+  };
+  out.light = extract(matchBlock(":root"));
+  out.dark = extract(matchBlock("\\.dark"));
+  return out;
+}
+function mirrorSingleTheme(vars) {
+  const hasLight = Object.keys(vars.light).length > 0;
+  const hasDark = Object.keys(vars.dark).length > 0;
+  if (hasLight && !hasDark) return { ...vars, dark: { ...vars.light } };
+  if (hasDark && !hasLight) return { ...vars, light: { ...vars.dark } };
+  return vars;
+}
+var init_registry_css = __esm({
+  "../shared/src/registry-css.ts"() {
+    "use strict";
+  }
+});
+
 // ../shared/src/mcp/preview-widget-sdk.generated.ts
 var PREVIEW_WIDGET_SDK_JS;
 var init_preview_widget_sdk_generated = __esm({
@@ -4446,6 +5743,26 @@ function decodeArbitrary(raw) {
   const v = raw.replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
   return v && !/[{}<>;]/.test(v) ? v : null;
 }
+function ringWidthRule(width) {
+  return `--tw-ring-shadow:var(--tw-ring-inset,) 0 0 0 calc(${width} + var(--tw-ring-offset-width)) var(--tw-ring-color,currentcolor);box-shadow:${RING_BOX_SHADOW}`;
+}
+function inferArbitraryKind(value) {
+  if (IMAGE_FUNCTIONS.test(value)) return "image";
+  if (COLOR_FUNCTIONS.test(value)) return "color";
+  if (LENGTH_VALUE.test(value) || MATH_VALUE.test(value)) return "length";
+  if (/^-?(?:\d*\.)?\d+$/.test(value)) return "number";
+  return null;
+}
+function resolveArbitraryDeclaration(prefix, rawValue) {
+  const spec = ARBITRARY_KINDS[prefix];
+  if (!spec) return null;
+  const hinted = rawValue.match(/^([a-z][a-z-]*):([\s\S]+)$/i);
+  const hintKind = hinted ? HINT_KIND[hinted[1].toLowerCase()] : void 0;
+  const value = hintKind ? hinted[2].trim() : rawValue;
+  const kind = hintKind ?? inferArbitraryKind(value);
+  const property = kind ? spec.props[kind] : void 0;
+  return property ? { property, value, kind } : { property: spec.fallback, value, kind: spec.fallbackKind };
+}
 function animateModifier(base) {
   const spin = {
     "animate-spin": "animation:spin 1s linear infinite",
@@ -4511,13 +5828,23 @@ function translateBase(base) {
   if (arb) {
     const val = decodeArbitrary(arb[2]);
     if (val) {
+      const withAlpha = (v) => arb[3] ? `color-mix(in oklab, ${v} ${arb[3]}%, transparent)` : v;
+      const resolved = resolveArbitraryDeclaration(arb[1], val);
+      if (resolved?.property === "--tw-ring-width") return ringWidthRule(resolved.value);
+      if (resolved) {
+        const value = resolved.kind === "color" ? withAlpha(resolved.value) : resolved.value;
+        return `${resolved.property}:${value}`;
+      }
+      const composed = ARBITRARY_COMPOSED[arb[1]];
+      if (composed) return composed(val);
+      const multi = ARBITRARY_PROPS_MULTI[arb[1]];
+      if (multi) return multi.map((p) => `${p}:${val}`).join(";");
       const prop = ARBITRARY_PROP[arb[1]];
       if (prop) return `${prop}:${val}`;
       const colorProp = COLOR_PROP[arb[1]];
-      if (colorProp) {
-        const v = arb[3] ? `color-mix(in oklab, ${val} ${arb[3]}%, transparent)` : val;
-        return `${colorProp}:${v}`;
-      }
+      if (colorProp) return `${colorProp}:${withAlpha(val)}`;
+      const negated = arb[1].startsWith("-") ? ARBITRARY_PROP[arb[1].slice(1)] : void 0;
+      if (negated) return `${negated}:calc(${val} * -1)`;
     }
   }
   const rside = base.match(/^rounded-(t|r|b|l|tl|tr|br|bl)(?:-(.+))?$/);
@@ -4619,7 +5946,7 @@ function splitVariants(cls) {
   out.push(cur);
   return out;
 }
-var BREAKPOINTS, KNOWN_EMPTY, PALETTE, FONT_FAMILY, FLEX_EXTRA, TW_DEFAULTS, ESCAPE_RE, STATE_VARIANTS, GROUP_PEER, PSEUDO_ELEMENTS, SPACING_PROP, SIZE_PROP, COLOR_PROP, SEMANTIC_TOKENS, RADIUS, RADIUS_SIDE, FONT_SIZE, FONT_WEIGHT, STATIC, ARBITRARY_PROP, MAX_W_SCALE;
+var BREAKPOINTS, KNOWN_EMPTY, PALETTE, FONT_FAMILY, FLEX_EXTRA, TW_DEFAULTS, ESCAPE_RE, STATE_VARIANTS, GROUP_PEER, PSEUDO_ELEMENTS, SPACING_PROP, SIZE_PROP, COLOR_PROP, SEMANTIC_TOKENS, RADIUS, RADIUS_SIDE, FONT_SIZE, FONT_WEIGHT, STATIC, ARBITRARY_PROP, ARBITRARY_PROPS_MULTI, FILTER_CHAIN, BACKDROP_CHAIN, RING_BOX_SHADOW, TRANSITION_TAIL, ARBITRARY_COMPOSED, HINT_KIND, ARBITRARY_KINDS, COLOR_FUNCTIONS, IMAGE_FUNCTIONS, LENGTH_VALUE, MATH_VALUE, MAX_W_SCALE;
 var init_tw_translate = __esm({
   "../shared/src/mcp/tw-translate.ts"() {
     "use strict";
@@ -5047,15 +6374,12 @@ var init_tw_translate = __esm({
       "rounded-xs": "border-radius:var(--radius-xs, 0.125rem)"
     };
     ARBITRARY_PROP = {
-      bg: "background",
-      text: "color",
       w: "width",
       h: "height",
       "min-w": "min-width",
       "max-w": "max-width",
       "min-h": "min-height",
       "max-h": "max-height",
-      size: "width",
       p: "padding",
       px: "padding-inline",
       py: "padding-block",
@@ -5072,8 +6396,6 @@ var init_tw_translate = __esm({
       ml: "margin-left",
       gap: "gap",
       rounded: "border-radius",
-      shadow: "box-shadow",
-      border: "border-width",
       top: "top",
       left: "left",
       right: "right",
@@ -5084,14 +6406,93 @@ var init_tw_translate = __esm({
       opacity: "opacity",
       z: "z-index",
       grid: "grid-template-columns",
-      "font": "font-size",
       "aspect": "aspect-ratio",
-      // transition props (transition-[background-color,box-shadow]) + timing
-      transition: "transition-property",
       duration: "transition-duration",
       delay: "transition-delay",
       ease: "transition-timing-function"
     };
+    ARBITRARY_PROPS_MULTI = {
+      size: ["width", "height"]
+    };
+    FILTER_CHAIN = "var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)";
+    BACKDROP_CHAIN = "var(--tw-backdrop-blur,) var(--tw-backdrop-brightness,) var(--tw-backdrop-contrast,) var(--tw-backdrop-grayscale,) var(--tw-backdrop-hue-rotate,) var(--tw-backdrop-invert,) var(--tw-backdrop-opacity,) var(--tw-backdrop-saturate,) var(--tw-backdrop-sepia,)";
+    RING_BOX_SHADOW = "var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow)";
+    TRANSITION_TAIL = "transition-timing-function:cubic-bezier(0.4,0,0.2,1);transition-duration:150ms";
+    ARBITRARY_COMPOSED = {
+      blur: (v) => `--tw-blur:blur(${v});filter:${FILTER_CHAIN}`,
+      "backdrop-blur": (v) => `--tw-backdrop-blur:blur(${v});-webkit-backdrop-filter:${BACKDROP_CHAIN};backdrop-filter:${BACKDROP_CHAIN}`,
+      "drop-shadow": (v) => `--tw-drop-shadow:drop-shadow(${v});filter:${FILTER_CHAIN}`,
+      scale: (v) => `--tw-scale-x:${v};--tw-scale-y:${v};--tw-scale-z:${v};scale:var(--tw-scale-x) var(--tw-scale-y)`,
+      origin: (v) => `transform-origin:${v}`,
+      "underline-offset": (v) => `text-underline-offset:${v}`,
+      // Tailwind's `transition-[a,b]` still applies the default duration and easing;
+      // emitting only transition-property leaves every transition at 0s.
+      transition: (v) => `transition-property:${v};${TRANSITION_TAIL}`
+    };
+    HINT_KIND = {
+      color: "color",
+      image: "image",
+      url: "image",
+      length: "length",
+      "line-width": "length",
+      percentage: "length",
+      size: "length",
+      "bg-size": "length",
+      "absolute-size": "length",
+      "relative-size": "length",
+      "family-name": "family",
+      "generic-name": "family",
+      number: "number",
+      integer: "number",
+      ratio: "number",
+      angle: "number",
+      position: "position"
+    };
+    ARBITRARY_KINDS = {
+      bg: {
+        fallback: "background-color",
+        fallbackKind: "color",
+        props: {
+          color: "background-color",
+          image: "background-image",
+          length: "background-size",
+          position: "background-position"
+        }
+      },
+      text: { fallback: "color", fallbackKind: "color", props: { color: "color", length: "font-size" } },
+      font: {
+        fallback: "font-weight",
+        fallbackKind: "number",
+        props: { family: "font-family", number: "font-weight", length: "font-size" }
+      },
+      border: { fallback: "border-color", fallbackKind: "color", props: { color: "border-color", length: "border-width" } },
+      "border-x": { fallback: "border-inline-color", fallbackKind: "color", props: { color: "border-inline-color", length: "border-inline-width" } },
+      "border-y": { fallback: "border-block-color", fallbackKind: "color", props: { color: "border-block-color", length: "border-block-width" } },
+      "border-t": { fallback: "border-top-color", fallbackKind: "color", props: { color: "border-top-color", length: "border-top-width" } },
+      "border-r": { fallback: "border-right-color", fallbackKind: "color", props: { color: "border-right-color", length: "border-right-width" } },
+      "border-b": { fallback: "border-bottom-color", fallbackKind: "color", props: { color: "border-bottom-color", length: "border-bottom-width" } },
+      "border-l": { fallback: "border-left-color", fallbackKind: "color", props: { color: "border-left-color", length: "border-left-width" } },
+      divide: { fallback: "border-color", fallbackKind: "color", props: { color: "border-color", length: "border-width" } },
+      outline: { fallback: "outline-color", fallbackKind: "color", props: { color: "outline-color", length: "outline-width" } },
+      // `--tw-ring-width` is not a real Tailwind variable: it marks the ring-WIDTH
+      // branch so the caller can emit the composed ring box-shadow instead of a
+      // declaration. `ring-[<color>]` still sets the ring color.
+      ring: { fallback: "--tw-ring-color", fallbackKind: "color", props: { color: "--tw-ring-color", length: "--tw-ring-width" } },
+      // The kit has no Tailwind shadow-var machinery, so a shadow value goes straight
+      // onto box-shadow; only the color hint targets the tint var.
+      shadow: { fallback: "box-shadow", fallbackKind: "length", props: { color: "--tw-shadow-color" } },
+      stroke: { fallback: "stroke", fallbackKind: "color", props: { color: "stroke", length: "stroke-width", number: "stroke-width" } },
+      fill: { fallback: "fill", fallbackKind: "color", props: { color: "fill" } },
+      decoration: {
+        fallback: "text-decoration-color",
+        fallbackKind: "color",
+        props: { color: "text-decoration-color", length: "text-decoration-thickness" }
+      }
+    };
+    COLOR_FUNCTIONS = /^(?:#[0-9a-f]{3,8}$|(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix)\()/i;
+    IMAGE_FUNCTIONS = /^(?:url\(|(?:repeating-)?(?:linear|radial|conic)-gradient\(|image-set\(|cross-fade\()/i;
+    LENGTH_VALUE = /^-?(?:\d*\.)?\d+(?:px|rem|em|%|vh|vw|vmin|vmax|svh|lvh|dvh|svw|lvw|dvw|ch|ex|cap|ic|lh|pt|pc|cm|mm|q|in)$/i;
+    MATH_VALUE = /^(?:calc|clamp|min|max)\(/i;
     MAX_W_SCALE = {
       xs: "20rem",
       sm: "24rem",
@@ -5168,47 +6569,73 @@ function decodeArbitrary2(raw) {
   const value = raw.replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
   return value && !/[<>{};]/.test(value) ? value : null;
 }
-function restingValue(scope, cssProp, utilPrefixes) {
+function restingDeclaration(scope, cssProp, utilPrefixes) {
   for (const prefix of utilPrefixes) {
     const m = scope.match(new RegExp(`(?<![\\w:.\\-])${prefix}-\\[([^\\]]+)\\]`));
     if (m) {
       const v = decodeArbitrary2(m[1]);
-      if (v) return v;
+      if (v) return resolveArbitraryDeclaration(prefix, v) ?? { property: cssProp, value: v };
     }
   }
   const pm = scope.match(new RegExp(`(?<!:)\\[${cssProp}:([^\\]]+)\\]`));
-  return pm ? decodeArbitrary2(pm[1]) : null;
+  const decoded = pm ? decodeArbitrary2(pm[1]) : null;
+  return decoded ? { property: cssProp, value: decoded } : null;
+}
+function restingValue(scope, cssProp, utilPrefixes) {
+  const declaration = restingDeclaration(scope, cssProp, utilPrefixes);
+  return declaration?.property === cssProp ? declaration.value : null;
 }
 function variantBody(content, name) {
   const vi = content.search(/variant\s*:\s*\{/);
   const hay = vi !== -1 ? content.slice(vi) : content;
+  const key = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const m = hay.match(
-    new RegExp(`[\\s{,]${name}\\s*:\\s*([\\s\\S]*?)(?:\\n\\s*[A-Za-z_][\\w-]*\\s*:|\\n\\s*\\},)`)
+    new RegExp(
+      `[\\s{,](?:${key}|["']${key}["'])\\s*:\\s*([\\s\\S]*?)(?:\\n\\s*(?:[A-Za-z_][\\w-]*|["'][^"']+["'])\\s*:|\\n\\s*\\},)`
+    )
   );
   return m ? m[1] : null;
 }
+function declaredDefaultVariantBody(content) {
+  const defaults = content.match(/defaultVariants\s*:\s*\{([\s\S]*?)\}/)?.[1];
+  const declaredDefault = defaults?.match(/\bvariant\s*:\s*["']([^"']+)["']/)?.[1];
+  return (declaredDefault ? variantBody(content, declaredDefault) : null) ?? variantBody(content, "default");
+}
+function canonicalButtonVariantBody(content) {
+  return declaredDefaultVariantBody(content) ?? variantBody(content, "primary");
+}
 function componentDepthCss(files) {
   const btn = files.find((f) => f.path && /(^|\/)button\.(tsx|jsx)$/.test(f.path));
   if (!btn?.content) return "";
   const content = btn.content;
-  const scope = variantBody(content, "primary") ?? variantBody(content, "default") ?? content;
+  const scope = canonicalButtonVariantBody(content) ?? content;
   const shadow = /(?:^|\s|"|')shadow-none(?=\s|"|'|$)/.test(scope) ? "none" : restingValue(scope, "box-shadow", ["shadow"]);
-  const background = restingValue(scope, "background", ["bg"]) ?? restingValue(scope, "background-image", []);
+  const background = restingDeclaration(scope, "background", ["bg"]) ?? restingDeclaration(scope, "background-image", []);
   const sel = ".bd-btn-primary, .bd-view, .ds-btn-primary";
   const rules = [];
   if (shadow) rules.push(`${sel} { box-shadow: ${shadow}; }`);
-  if (background) rules.push(`${sel} { background: ${background}; }`);
+  if (background) rules.push(`${sel} { ${background.property}: ${background.value}; }`);
   return rules.join("\n");
 }
+function arbitrary(scope, re) {
+  const m = scope.match(re);
+  if (!m) return null;
+  const value = m[1].replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
+  return value && !/[<>{};]/.test(value) ? value : null;
+}
+function checkedTrackBackground(source) {
+  const utility = arbitrary(source, /data-\[state=checked\]:bg-\[([^\]]+)\]/);
+  if (utility) {
+    return resolveArbitraryDeclaration("bg", utility) ?? { property: "background", value: utility };
+  }
+  const image = arbitrary(source, /data-\[state=checked\]:\[background-image:([^\]]+)\]/);
+  if (image) return { property: "background-image", value: image };
+  const shorthand = arbitrary(source, /data-\[state=checked\]:\[background:([^\]]+)\]/);
+  return shorthand ? { property: "background", value: shorthand } : null;
+}
 function buildDsComponentCss(files) {
   const contentOf = (re) => stripComments2(files.find((f) => f.path && re.test(f.path))?.content ?? "");
   const has = (name) => Boolean(contentOf(new RegExp(`(^|/)${name}\\.(tsx|jsx)$`)));
-  const arbitrary = (scope, re) => {
-    const m = scope.match(re);
-    if (!m) return null;
-    const value = m[1].replace(/(?<!\\)_/g, " ").replace(/\\_/g, "_").trim();
-    return value && !/[<>{};]/.test(value) ? value : null;
-  };
   const rules = [componentRadiusCss(files), componentDepthCss(files)];
   const covered = /* @__PURE__ */ new Set();
   for (const name of ["button", "input", "alert", "avatar", "table", "tabs", "progress"]) {
@@ -5223,9 +6650,9 @@ function buildDsComponentCss(files) {
   const sw = contentOf(/(^|\/)switch\.(tsx|jsx)$/);
   if (sw) {
     covered.add("switch");
-    const bg = arbitrary(sw, /data-\[state=checked\]:bg-\[([^\]]+)\]/) ?? arbitrary(sw, /data-\[state=checked\]:\[background(?:-image)?:([^\]]+)\]/);
+    const bg = checkedTrackBackground(sw);
     const shadow = arbitrary(sw, /data-\[state=checked\]:shadow-\[([^\]]+)\]/) ?? arbitrary(sw, /data-\[state=checked\]:\[box-shadow:([^\]]+)\]/);
-    if (bg) rules.push(`.ds-switch-track.on { background: ${bg}; }`);
+    if (bg) rules.push(`.ds-switch-track.on { ${bg.property}: ${bg.value}; }`);
     if (shadow) rules.push(`.ds-switch-track.on { box-shadow: ${shadow}; }`);
   }
   const badge = contentOf(/(^|\/)badge\.(tsx|jsx)$/);
@@ -5311,10 +6738,11 @@ function translatedKitComponentCss(contentOf, covered) {
   const button = contentOf(/(^|\/)button\.(tsx|jsx)$/);
   if (button) {
     emit(".ds-btn", cvaBase(button), "button");
-    emit(".ds-btn-primary", variantBody(button, "primary") ? quotedStrings(variantBody(button, "primary")) : variantBody(button, "default") ? quotedStrings(variantBody(button, "default")) : null);
+    const canonical = canonicalButtonVariantBody(button);
+    emit(".ds .ds-btn-primary", canonical ? quotedStrings(canonical) : null);
     for (const v of ["secondary", "outline", "ghost"]) {
       const body = variantBody(button, v);
-      if (body) emit(`.ds-btn-${v}`, quotedStrings(body));
+      if (body) emit(`.ds .ds-btn-${v}`, quotedStrings(body));
     }
   }
   const shared = contentOf(/(^|\/)_shared\.(ts|tsx)$/);
@@ -5459,15 +6887,13 @@ ${PREVIEW_BASE_CSS}
 .bd-app { padding: 16px; }
 .bd-cta-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 12px 16px; background: var(--card, var(--background, oklch(1 0 0))); border-top: 1px solid var(--border, oklch(0.92 0 0)); }
 .bd-cta-name { font-weight: 600; font-size: 14px; color: var(--foreground, oklch(0.2 0 0)); font-family: var(--font-serif, var(--font-sans, ui-sans-serif)); }
-.bd-cta { font: inherit; font-size: 14px; font-weight: 700; text-decoration: none; color: var(--primary, oklch(0.45 0 0)); display: inline-flex; align-items: center; gap: 6px; }
-.bd-cta:hover { opacity: 0.7; }
+.bd-cta { min-height: 44px; padding-inline: 4px; font: inherit; font-size: 14px; font-weight: 700; text-decoration: none; color: var(--primary, oklch(0.45 0 0)); display: inline-flex; align-items: center; gap: 6px; }
 .bd-cta-actions { display: inline-flex; align-items: center; gap: 14px; }
-.bd-expand { font: inherit; font-size: 13px; font-weight: 600; cursor: pointer; background: none; border: 0; padding: 0; color: var(--muted-foreground, oklch(0.5 0 0)); display: inline-flex; align-items: center; gap: 5px; }
-.bd-expand:hover { color: var(--foreground, oklch(0.2 0 0)); }
+.bd-expand { min-height: 44px; font: inherit; font-size: 13px; font-weight: 600; cursor: pointer; background: none; border: 0; padding: 0 4px; color: var(--muted-foreground, oklch(0.5 0 0)); display: inline-flex; align-items: center; gap: 5px; }
+.bd-cta:focus-visible, .bd-expand:focus-visible, .bd-nav-item:focus-visible { outline: 2px solid var(--ring, var(--primary, oklch(0.55 0.15 264))); outline-offset: 2px; }
 .bd-progress { padding: 6px 16px 12px; }
-/* Fullscreen: the DS preview rendered IN-WIDGET (token-driven), full-bleed. No
-   iframe \u2014 claude.ai's sandbox blocks nested cross-origin frames and the
-   ext-apps model is in-widget rendering. requestDisplayMode just grants room. */
+/* Fullscreen: the DS preview rendered in the widget, full-bleed. The host's
+   requestDisplayMode capability only grants more room. */
 .bd-fs { position: fixed; inset: 0; display: flex; flex-direction: column; background: var(--background, oklch(1 0 0)); }
 .bd-fs-bar { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 10px 16px; border-bottom: 1px solid var(--border, oklch(0.92 0 0)); background: var(--card, var(--background, oklch(1 0 0))); flex: none; }
 .bd-fs-body { flex: 1; overflow-y: auto; padding: 20px; max-width: 860px; width: 100%; margin: 0 auto; }
@@ -5514,14 +6940,14 @@ ${DS_KIT_CSS}
 .bd-nav-card, .bd-pal-card { border: 1px solid var(--border, oklch(0.9 0 0)); border-radius: 8px; background: var(--card, var(--background, oklch(1 0 0))); overflow: clip; }
 .bd-nav-h, .bd-pal-h { padding: 10px 12px; border-bottom: 1px solid var(--border, oklch(0.9 0 0)); font-size: 10px; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--muted-foreground, oklch(0.5 0 0)); opacity: 0.6; }
 .bd-nav-list { display: flex; flex-direction: column; gap: 1px; padding: 6px 6px 8px; }
-.bd-nav-item { display: flex; align-items: center; gap: 8px; width: 100%; text-align: left; padding: 5px 8px; font: inherit; font-size: 12px; font-weight: 400; color: var(--muted-foreground, oklch(0.5 0 0)); background: transparent; border-radius: 5px; border: none; cursor: pointer; line-height: 1.4; }
-.bd-nav-item:hover, .bd-nav-item.active { font-weight: 500; color: var(--foreground, oklch(0.2 0 0)); background: var(--muted, oklch(0.95 0 0)); }
+.bd-nav-item { min-height: 44px; display: flex; align-items: center; gap: 8px; width: 100%; text-align: left; padding: 8px; font: inherit; font-size: 12px; font-weight: 400; color: var(--muted-foreground, oklch(0.5 0 0)); background: transparent; border-radius: 5px; border: none; cursor: pointer; line-height: 1.4; }
+.bd-nav-item.active { font-weight: 500; color: var(--foreground, oklch(0.2 0 0)); background: var(--muted, oklch(0.95 0 0)); }
 .bd-nav-dot { width: 5px; height: 5px; border-radius: 50%; flex-shrink: 0; background: var(--border, oklch(0.85 0 0)); }
 .bd-nav-item.active .bd-nav-dot { background: var(--primary, oklch(0.45 0.15 264)); }
 /* SectionHeader (component-showcase.tsx:1659-1680). */
 .bd-sh { margin-bottom: 20px; margin-top: 64px; padding-top: 48px; border-top: 1px solid var(--border, oklch(0.9 0 0)); }
 .bd-sh.first { margin-top: 28px; padding-top: 0; border-top: none; }
-.bd-sh-t { font-size: 11px; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted-foreground, oklch(0.5 0 0)); }
+.bd-sh-t { margin: 0; font-size: 11px; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted-foreground, oklch(0.5 0 0)); }
 /* Grid (component-showcase.tsx:1565-1571 \u2014 cols-1 / sm:2 / xl:3, gap-3 = 12px).
    Own class (not the vignette's .bd-grid) + explicit responsive columns capped
    at 3, so the fullscreen main never renders a 4th column. [BD-117] */
@@ -5541,26 +6967,18 @@ ${DS_KIT_CSS}
 .bd-show-scroll { max-height: 420px; overflow: hidden; position: relative; -webkit-mask-image: linear-gradient(to bottom, #000 86%, transparent); mask-image: linear-gradient(to bottom, #000 86%, transparent); }
 .bd-fs .bd-show-scroll { max-height: none; overflow: visible; -webkit-mask-image: none; mask-image: none; }
 .bd-fs .bd-main { max-width: 920px; }
-/* Real-page iframe (ChatGPT). Inline = capped height + footer; fullscreen =
-   full viewport + a Back bar. The iframe shows the actual /design-systems/<id>
-   page (?embed=1, no app nav), so the components are real, not approximated. */
-.bd-frame-wrap { display: flex; flex-direction: column; background: var(--background, oklch(1 0 0)); }
-.bd-frame { width: 100%; border: 0; display: block; background: var(--background, oklch(1 0 0)); height: 460px; }
-.bd-frame-wrap.bd-fs { position: fixed; inset: 0; height: 100vh; }
-.bd-frame-wrap.bd-fs .bd-frame { flex: 1; height: auto; }
-/* Real-page screenshot (claude.ai, which can't iframe). Inline = capped + fade;
-   fullscreen = scrollable. [BD-136] */
+/* Real-page screenshot. Inline = capped + fade; fullscreen = scrollable. */
 .bd-shot-wrap { min-height: 240px; max-height: 540px; overflow: hidden; position: relative; background: var(--card, var(--background, oklch(0.97 0 0))); -webkit-mask-image: linear-gradient(to bottom, #000 90%, transparent); mask-image: linear-gradient(to bottom, #000 90%, transparent); }
-.bd-shot-wrap.bd-fs { min-height: 0; max-height: 100vh; overflow: auto; -webkit-mask-image: none; mask-image: none; }
+.bd-fs > .bd-shot-wrap { min-height: 0; max-height: none; flex: 1; overflow: auto; -webkit-mask-image: none; mask-image: none; }
 .bd-shot { display: block; width: 100%; height: auto; }
-.bd-frame-foot { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 9px 14px; border-top: 1px solid var(--border, oklch(0.92 0 0)); background: var(--card, var(--background, oklch(1 0 0))); }
-.bd-cta-name { font-weight: 600; font-size: 13px; color: var(--foreground, oklch(0.2 0 0)); }
+.bd-preview-foot { display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 9px 14px; border-top: 1px solid var(--border, oklch(0.92 0 0)); background: var(--card, var(--background, oklch(1 0 0))); }
+.bd-cta-name { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; font-size: 13px; color: var(--foreground, oklch(0.2 0 0)); }
 .bd-cta-actions { display: inline-flex; align-items: center; gap: 14px; }
-/* claude.ai link-out card (can't iframe). */
-.bd-link-card { padding: 22px 20px; display: flex; flex-direction: column; gap: 6px; align-items: flex-start; }
-.bd-link-title { font-size: 17px; font-weight: 600; color: var(--foreground, oklch(0.2 0 0)); }
-.bd-link-desc { font-size: 13px; color: var(--muted-foreground, oklch(0.5 0 0)); margin: 0 0 6px; }
-.bd-cta-lg { font-size: 14px; padding: 9px 16px; border-radius: var(--radius-md, 8px); background: var(--primary, oklch(0.45 0.15 264)); color: var(--primary-foreground, oklch(1 0 0)); }
+@media (hover: hover) and (pointer: fine) {
+  .bd-cta:hover { opacity: 0.7; }
+  .bd-expand:hover { color: var(--foreground, oklch(0.2 0 0)); }
+  .bd-nav-item:hover { font-weight: 500; color: var(--foreground, oklch(0.2 0 0)); background: var(--muted, oklch(0.95 0 0)); }
+}
 </style>
 <style id="bd-tokens"></style>
 </head>
@@ -5582,7 +7000,7 @@ ${DS_KIT_CSS}
     return String(s == null ? "" : s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
   }
 
-  // Only http(s) URLs are safe to use as an iframe src / link href; reject
+  // Only http(s) URLs are safe to use as image or link targets; reject
   // javascript:/data:/etc. so a hostile MCP payload can't inject a scheme that
   // executes in the widget sandbox. Returns "" for anything else.
   function safeUrl(u) {
@@ -5631,12 +7049,12 @@ ${DS_KIT_CSS}
     return showcaseSections().map(function (s, i) {
       var cards = s[2].map(function (it) {
         return '<div class="bd-dc" data-name="' + esc(it[0].toLowerCase()) + '">' +
-          '<div class="bd-dc-demo">' + it[1] + '</div>' +
+          '<div class="bd-dc-demo" inert aria-hidden="true">' + it[1] + '</div>' +
           '<div class="bd-dc-foot">' + esc(it[0]) + '</div>' +
         '</div>';
       }).join("");
       return '<section class="bd-sec" data-sec="' + esc(s[0]) + '">' +
-        '<div class="bd-sh' + (i === 0 ? " first" : "") + '"><div class="bd-sh-t">' + esc(s[1]) + '</div></div>' +
+        '<div class="bd-sh' + (i === 0 ? " first" : "") + '"><h2 class="bd-sh-t">' + esc(s[1]) + '</h2></div>' +
         '<div class="bd-show-grid">' + cards + '</div>' +
       '</section>';
     }).join("");
@@ -5655,7 +7073,7 @@ ${DS_KIT_CSS}
   // for each semantic color token. Fullscreen only (CSS). [BD-117]
   function paletteHtml() {
     var TOK = [["Background", "background"], ["Foreground", "foreground"], ["Primary", "primary"], ["Secondary", "secondary"], ["Accent", "accent"], ["Muted", "muted"], ["Card", "card"], ["Border", "border"], ["Destructive", "destructive"], ["Ring", "ring"]];
-    return '<aside class="bd-pal"><div class="bd-pal-card"><div class="bd-pal-h">Tokens</div><div class="bd-pal-list">' +
+    return '<aside class="bd-pal"><div class="bd-pal-card"><div class="bd-pal-h">Colors</div><div class="bd-pal-list">' +
       TOK.map(function (t) {
         return '<div class="bd-tok"><span class="bd-tok-sw" style="background: var(--' + t[1] + ', transparent)"></span>' + esc(t[0]) + '</div>';
       }).join("") + '</div></div></aside>';
@@ -5663,7 +7081,7 @@ ${DS_KIT_CSS}
 
   // The full showcase. Mirrors the real page: a header (h1 + description), then a
   // 3-column layout (left nav + main sections + right palette). Same render on
-  // BOTH hosts (no iframe). Inline caps the height + hides asides via CSS exactly
+  // every host. Inline caps the height + hides asides via CSS exactly
   // like the real page below lg/xl; fullscreen shows everything. [BD-117]
   function showcaseBody(out, full) {
     var nm = esc(out.name || "Design system");
@@ -5721,7 +7139,7 @@ ${DS_KIT_CSS}
       de.removeProperty("--font-serif");
       de.removeProperty("--font-mono");
     } else if (hostFontsPayload && applyHostFontsFn) {
-      try { applyHostFontsFn(hostFontsPayload); } catch (e) {}
+      try { applyHostFontsFn(hostFontsPayload); } catch (e) { /* best-effort: host font apply; fallback fonts stand */ }
     }
   }
 
@@ -5732,15 +7150,15 @@ ${DS_KIT_CSS}
     // mode field = declined); only switch to what it actually granted.
     var apply = function (m) { displayMode = m || displayMode; if (lastOut) render(lastOut); };
     try {
-      if (bdApp && bdApp.requestDisplayMode) {
-        bdApp.requestDisplayMode({ mode: mode }).then(function (r) { apply(r && r.mode); }, function () {});
-        return;
-      }
       if (window.openai && window.openai.requestDisplayMode) {
         Promise.resolve(window.openai.requestDisplayMode({ mode: mode })).then(function (r) { apply(r && r.mode); }, function () {});
         return;
       }
-    } catch (e) {}
+      if (bdApp && bdApp.requestDisplayMode) {
+        bdApp.requestDisplayMode({ mode: mode }).then(function (r) { apply(r && r.mode); }, function () {});
+        return;
+      }
+    } catch (e) { /* best-effort: bridge threw; apply the mode locally below */ }
     apply(mode);
   }
 
@@ -5771,91 +7189,32 @@ ${DS_KIT_CSS}
     return !!(modes && modes.indexOf && modes.indexOf("fullscreen") !== -1);
   }
 
-  // ChatGPT (OpenAI Apps) honors frameDomains, so we can iframe our own origin;
-  // claude.ai hardcodes frame-src and ignores frameDomains (anthropics/claude-ai
-  // -mcp#40), so it can never iframe \u2014 there we link out instead. [BD-117]
-  //
-  // Identify ChatGPT by window.openai ALONE. Do NOT also test !bdApp: bdApp is
-  // our OWN inlined MCP-Apps client (window.__bdMcp), instantiated
-  // unconditionally on every host, so it is always set after first paint. The
-  // old check (window.openai AND not bdApp) therefore flipped to false on every
-  // re-render (Fullscreen, set_globals), wrongly showing the claude.ai link card
-  // on ChatGPT. window.openai is absent on claude.ai, so it is the right signal.
-  function canIframe() {
-    return !!window.openai;
-  }
-
-  // The real page, with ?embed=1 so it renders the showcase WITHOUT the app nav
-  // (clean component showcase to embed). [BD-117]
-  function embedUrl(view) {
-    if (!view) return "";
-    return view + (view.indexOf("?") === -1 ? "?embed=1" : "&embed=1");
-  }
-
-  // Embed the REAL /design-systems/<id> (or /projects/<id>) page \u2014 the actual
-  // React components, not a token approximation. Inline = capped height + a
-  // footer (Fullscreen + Open). Fullscreen = full-bleed iframe with NO header of
-  // our own: both hosts render a native close button in fullscreen (ChatGPT's
-  // top bar, claude.ai's native header), so our own Back bar was redundant and
-  // visually broken (misaligned, disliked chevron). [BD-136]
-  // embed = the PUBLIC, cookieless URL we iframe (the sandbox carries no
-  // session cookie, so an owner-scoped page would 404 inside it). open = the
-  // owner-facing page for the human "Open" link (they have the cookie). [BD-164]
-  function iframeBody(out, embed, open, full) {
-    var nm = esc(out.name || "Design system");
-    var frame = '<iframe class="bd-frame" src="' + esc(embedUrl(embed)) + '" title="' + nm + ' showcase" referrerpolicy="no-referrer-when-downgrade"></iframe>';
-    if (full) {
-      return '<div class="bd-frame-wrap bd-fs">' + frame + '</div>';
-    }
-    var openHref = open || embed;
-    return '<div class="bd-frame-wrap">' + frame +
-      '<div class="bd-frame-foot"><span class="bd-cta-name">' + nm + '</span><span class="bd-cta-actions">' +
-        (canFullscreen() ? '<button class="bd-expand" data-bd-fullscreen type="button">Fullscreen' + ICON_EXPAND + '</button>' : "") +
-        '<a class="bd-cta" data-bd-open href="' + esc(openHref) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a>' +
-      '</span></div>' +
-    '</div>';
-  }
-
-  // claude.ai can't iframe \u2014 surface the REAL page as a browser link (no
-  // approximation, just not embedded). [BD-117]
-  function linkBody(out, view) {
-    var nm = esc(out.name || "Design system");
-    return '<div class="bd-link-card">' +
-      '<div class="bd-link-title">' + nm + '</div>' +
-      '<p class="bd-link-desc">Open the live showcase to see every component, styled by this system.</p>' +
-      '<a class="bd-cta bd-cta-lg" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open live showcase' + ICON_EXTERNAL + '</a>' +
-    '</div>';
-  }
-
-  // The name + Fullscreen + Open footer, shared by the iframe / screenshot /
-  // token previews. Name left, actions right (CSS handles the split). [BD-136]
-  function footHtml(out) {
+  // The name + Fullscreen + Open footer shared by screenshot and token previews.
+  function footHtml(out, full) {
     var view = safeUrl(out.viewUrl);
-    return '<div class="bd-frame-foot"><span class="bd-cta-name">' + esc(out.name || "Design system") + '</span><span class="bd-cta-actions">' +
-      (canFullscreen() ? '<button class="bd-expand" data-bd-fullscreen type="button">Fullscreen' + ICON_EXPAND + '</button>' : "") +
-      (view ? '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a>' : "") +
+    return '<div class="bd-preview-foot"><span class="bd-cta-name">' + esc(out.name || "Design system") + '</span><span class="bd-cta-actions">' +
+      (!full && canFullscreen() ? '<button class="bd-expand" data-bd-fullscreen type="button">Fullscreen' + ICON_EXPAND + '</button>' : "") +
+      (view ? '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open showcase' + ICON_EXTERNAL + '</a>' : "") +
     '</span></div>';
   }
 
-  // A REAL screenshot of the showcase page (server-rendered via Cloudflare
-  // Browser Rendering), shown where the page can't be iframed (claude.ai). Real
-  // components + real CSS, just a flat image. inline = capped + fade; fullscreen
-  // = scrollable. Falls back to the token render if the image fails. [BD-136]
-  function shotBody(out, full) {
-    return '<div class="bd-shot-wrap' + (full ? " bd-fs" : "") + '">' +
+  // A real screenshot of the showcase page, server-rendered via Cloudflare
+  // Browser Rendering. Inline is capped; fullscreen is scrollable. It falls
+  // back to the token render if the image fails. [BD-316]
+  function shotBody(out) {
+    return '<div class="bd-shot-wrap">' +
       '<img class="bd-shot" data-bd-shot src="' + esc(safeUrl(out.shotUrl)) + '" alt="' + esc(out.name || "Design system") + ' showcase" />' +
     '</div>';
   }
 
-  // If the screenshot 404s / errors, drop to the token render so claude.ai still
-  // shows a preview rather than a broken image. [BD-136]
+  // If the screenshot 404s or errors, show the token render instead.
   function wireShotFallback() {
     var img = root.querySelector("[data-bd-shot]");
     if (!img) return;
     img.addEventListener("error", function () { shotFailed = true; if (lastOut) render(lastOut); });
     // The screenshot loads async; its real height only exists after it decodes.
-    // claude.ai reads the widget's documentElement height from the DOM, so re-pin
-    // the iframe height once the image has dimensions (a cached image may already
+    // Some hosts read documentElement height from the DOM, so re-pin the widget
+    // height once the image has dimensions (a cached image may already
     // be complete before this runs). [BD-136]
     img.addEventListener("load", scheduleResize);
     if (img.complete && img.naturalHeight) scheduleResize();
@@ -5868,43 +7227,30 @@ ${DS_KIT_CSS}
     syncHostFonts();
     // Only an http(s) URL is usable; reject any other scheme up front.
     var view = safeUrl(out.viewUrl);
-    // The iframe must load a PUBLIC, cookieless URL (the sandbox has no session
-    // cookie). previewUrl points at /preview/<fragmentId>; fall back to view if
-    // the host didn't supply one (e.g. catalog DSes, whose view is public). [BD-164]
-    var embed = safeUrl(out.previewUrl) || view;
     var isError = out.status === "error";
     var generating = out.status && out.status !== "completed" && !isError;
     var completed = !isError && !generating;
-    // claude.ai (can't iframe): prefer a REAL screenshot; fall back to the token
-    // render if there's no shotUrl or the image failed to load.
-    var useShot = !shotFailed && !!safeUrl(out.shotUrl);
-
-    // ChatGPT's fullscreen "Open in <app>" button defaults to the iframe's
-    // current path, which is now the PUBLIC /preview page. Repoint it at the
-    // owner's editable /projects/<id> (they have the session cookie on the web,
-    // so it loads for them) so fullscreen Open still reaches their project. [BD-164]
+    // Prefer the real screenshot on wide hosts. On compact hosts a desktop
+    // screenshot scales into unreadable text, so use the responsive token UI.
+    var useShot = window.innerWidth >= 640 && !shotFailed && !!safeUrl(out.shotUrl);
+
+    // Keep the host-provided "Open in <app>" action pointed at the owner-facing
+    // project, where the user's browser session is available. [BD-164]
     if (completed && view && window.openai && window.openai.setOpenInAppUrl) {
-      try { window.openai.setOpenInAppUrl({ href: view }); } catch (e) {}
+      try { window.openai.setOpenInAppUrl({ href: view }); } catch (e) { /* best-effort: optional host chrome; the in-card link still works */ }
     }
 
-    // Fullscreen: ChatGPT iframes the real page; claude.ai shows the full
-    // screenshot (scrollable) or the token showcase. [BD-136]
+    // Fullscreen remains self-contained: show the full screenshot or token UI.
     if (displayMode === "fullscreen" && completed) {
-      if (canIframe() && embed) { root.innerHTML = iframeBody(out, embed, view, true); return; }
-      if (useShot) { root.innerHTML = '<div class="bd-card-shell bd-fs">' + shotBody(out, true) + footHtml(out) + '</div>'; wireShotFallback(); }
+      if (useShot) { root.innerHTML = '<div class="bd-card-shell bd-fs">' + shotBody(out) + footHtml(out, true) + '</div>'; wireShotFallback(); }
       else { root.innerHTML = showcaseBody(out, true); wireShowcase(); }
       return;
     }
 
-    // Inline completed: ChatGPT = real-page iframe; claude.ai = real screenshot
-    // (capped) or token showcase, + a footer (Fullscreen + Open). [BD-136]
+    // Inline completed: capped screenshot or token showcase, plus clear actions.
     if (completed) {
-      if (canIframe() && embed) {
-        root.innerHTML = '<div class="bd-card-shell">' + iframeBody(out, embed, view, false) + '</div>';
-        return;
-      }
-      var body = useShot ? shotBody(out, false) : showcaseBody(out, false);
-      root.innerHTML = '<div class="bd-card-shell">' + body + footHtml(out) + '</div>';
+      var body = useShot ? shotBody(out) : showcaseBody(out, false);
+      root.innerHTML = '<div class="bd-card-shell">' + body + footHtml(out, false) + '</div>';
       if (useShot) wireShotFallback();
       return;
     }
@@ -5916,7 +7262,7 @@ ${DS_KIT_CSS}
     var hero = errorBody(out);
     var cta = view
       ? '<div class="bd-cta-row"><span class="bd-cta-name">' + esc(out.name || "Design system") + '</span>' +
-          '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open' + ICON_EXTERNAL + '</a></div>'
+          '<a class="bd-cta" data-bd-open href="' + esc(view) + '" target="_blank" rel="noopener">Open showcase' + ICON_EXTERNAL + '</a></div>'
       : "";
     root.innerHTML = '<div class="bd-card-shell">' + hero + cta + "</div>";
   }
@@ -5925,9 +7271,9 @@ ${DS_KIT_CSS}
   // The MCP Apps client emits ui/notifications/size-changed (ResizeObserver on
   // documentElement + body); ChatGPT honors that and auto-sizes its widget.
   // claude.ai web does NOT honor size-changed \u2014 it reads the widget's
-  // documentElement height straight from the DOM and pins the iframe to whatever
-  // inline height the document carries. With no explicit height the iframe stays
-  // at 0 (verified live: a single size-changed{0,0} then the iframe sits at 0px;
+  // documentElement height straight from the DOM and pins the widget to whatever
+  // inline height the document carries. With no explicit height the widget stays
+  // at 0 (verified live: a single size-changed{0,0} then the host clips it;
   // claude-ai-mcp#69). So on the DOM-reading hosts we set
   // document.documentElement.style.height ourselves, AFTER content + the async
   // screenshot have real height. [BD-136]
@@ -5965,14 +7311,14 @@ ${DS_KIT_CSS}
     if (typeof MutationObserver === "function") {
       new MutationObserver(scheduleResize).observe(root, { childList: true, subtree: true });
     }
-  } catch (e) {}
+  } catch (e) { /* best-effort: sandbox without MutationObserver; the height pin just updates less often */ }
   try {
     if (typeof ResizeObserver === "function") {
       new ResizeObserver(scheduleResize).observe(root);
     }
-  } catch (e) {}
+  } catch (e) { /* best-effort: sandbox without ResizeObserver; the height pin just updates less often */ }
 
-  // The widget runs in a sandboxed iframe (claude.ai); a bare <a target=_blank>
+  // The widget runs in a sandboxed host; a bare <a target=_blank>
   // cannot open a tab or navigate the top frame, so the CTA looks dead. Route the
   // click through the host: MCP Apps app.openLink({url}) or OpenAI Apps
   // openai.openExternal({href}). Falls through to the native anchor for hosts
@@ -5982,19 +7328,18 @@ ${DS_KIT_CSS}
     var t = e.target;
     if (!t || !t.closest) return;
     if (t.closest("[data-bd-fullscreen]")) { e.preventDefault(); setDisplayMode("fullscreen"); return; }
-    if (t.closest("[data-bd-collapse]")) { e.preventDefault(); setDisplayMode("inline"); return; }
     var a = t.closest("a[data-bd-open]");
     if (!a) return;
     var url = a.getAttribute("href");
     if (!url) return;
-    if (bdApp && bdApp.openLink) {
+    if (window.openai && window.openai.openExternal) {
       e.preventDefault();
-      try { bdApp.openLink({ url: url }); } catch (err) {}
+      try { window.openai.openExternal({ href: url }); } catch (err) { /* best-effort: host declined openExternal; nothing else can open the link */ }
       return;
     }
-    if (window.openai && window.openai.openExternal) {
+    if (bdApp && bdApp.openLink) {
       e.preventDefault();
-      try { window.openai.openExternal({ href: url }); } catch (err) {}
+      try { bdApp.openLink({ url: url }); } catch (err) { /* best-effort: host declined openLink; nothing else can open the link */ }
     }
   });
 
@@ -6041,9 +7386,9 @@ ${DS_KIT_CSS}
           // this every later host-context-changed (theme/font) would rebuild the
           // DOM and lose scroll + active-section state in fullscreen. [BD-117]
           else if (ctx && ctx.availableDisplayModes && !sawDisplayModes && lastOut) { sawDisplayModes = true; render(lastOut); }
-        } catch (e) {}
+        } catch (e) { /* best-effort: a malformed host context must not kill the widget; keep the last rendered state */ }
       };
-      if (app.connect) app.connect().catch(function () {});
+      if (app.connect) app.connect().catch(function () { /* best-effort: a host that refuses the connect handshake still shows the static fallback */ });
     }
   } catch (e) { /* host without MCP Apps support; OpenAI bridge or static text covers it */ }
 })();
@@ -6053,8 +7398,132 @@ ${DS_KIT_CSS}
   }
 });
 
-// ../shared/src/mcp/tools/design-system-tools.ts
+// ../shared/src/mcp/shopify-primitives.ts
 import { z as z5 } from "zod";
+function exportedStringConstants(files) {
+  const constants = /* @__PURE__ */ new Map();
+  const declaration = /export\s+const\s+([A-Za-z_$][\w$]*)(?:\s*:[^=;]+)?\s*=\s*([\s\S]*?);/g;
+  const literal = /"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'/g;
+  for (const { content } of files) {
+    for (const match of content.matchAll(declaration)) {
+      const expression = match[2] ?? "";
+      const values = [...expression.matchAll(literal)].map(
+        (part) => (part[1] ?? part[2] ?? "").replace(/\\([\\"'])/g, "$1")
+      );
+      const residue = expression.replace(literal, "").replace(/\+/g, "").trim();
+      if (values.length && !residue) constants.set(match[1], values.join(""));
+    }
+  }
+  return constants;
+}
+function importedMaterialNames(content, constants) {
+  const names = /* @__PURE__ */ new Set();
+  for (const match of content.matchAll(localImport)) {
+    for (const item of (match[3] ?? "").split(",")) {
+      const imported = item.trim().split(/\s+as\s+/)[0];
+      if (imported && constants.has(imported)) names.add(imported);
+    }
+  }
+  return names;
+}
+function replaceMaterialNames(source, names, constants) {
+  let result = source;
+  for (const name of names) {
+    result = result.replace(
+      new RegExp(`\\b${name.replace(/[$]/g, "\\$")}\\b`, "g"),
+      JSON.stringify(constants.get(name))
+    );
+  }
+  return result;
+}
+function materializeFile(file, constants) {
+  const names = importedMaterialNames(file.content, constants);
+  if (!names.size) return file;
+  let cursor = 0;
+  let content = "";
+  for (const match of file.content.matchAll(localImport)) {
+    content += replaceMaterialNames(file.content.slice(cursor, match.index), names, constants);
+    content += match[0];
+    cursor = (match.index ?? 0) + match[0].length;
+  }
+  content += replaceMaterialNames(file.content.slice(cursor), names, constants);
+  return { ...file, content };
+}
+function materializeImportedMaterial(files) {
+  const constants = exportedStringConstants(files);
+  if (!constants.size) return files;
+  return files.map((file) => materializeFile(file, constants));
+}
+function globalsSource(files) {
+  return files.find(({ path: path5 }) => /(^|\/)globals\.css$/.test(path5))?.content ?? "";
+}
+function staticKitSource(files) {
+  return files.find(({ path: path5 }) => /(^|\/)static-kit\.css$/.test(path5))?.content.trim() ?? "";
+}
+function buildShopifyTokensCss(files) {
+  const globals = globalsSource(files);
+  if (!globals.trim()) {
+    throw new Error("Shopify primitives require a globals.css token source");
+  }
+  const vars = mirrorSingleTheme(parseCssVars(globals));
+  const { fontVars, fontImport } = extractFontCss(globals);
+  return [
+    fontImport,
+    cssFromRegistryVars(vars),
+    fontVars,
+    extractRadiusScaleCss(globals),
+    extractShadowScaleCss(globals),
+    componentRadiusCss(files),
+    componentDepthCss(files)
+  ].filter(Boolean).join("\n");
+}
+function buildShopifyPrimitiveSet(files) {
+  const materializedFiles = materializeImportedMaterial(files);
+  const tokensCss = buildShopifyTokensCss(materializedFiles);
+  const componentKit = buildDsComponentCss(materializedFiles);
+  const staticKitCss = staticKitSource(materializedFiles);
+  const material = staticKitCss ? { ...componentKit, css: `${componentKit.css}
+${staticKitCss}` } : componentKit;
+  const themeFiles = buildDsShopifyFiles({ tokensCss, componentKit: material });
+  return shopifyPrimitiveSetSchema.parse({
+    contractVersion: SHOPIFY_PRIMITIVE_CONTRACT_VERSION,
+    tokensCss,
+    componentMaterialCss: material.css,
+    coveredSourcePrimitives: componentKit.covered,
+    sourcePrimitivesWithShopifyAdapters: componentKit.excluded,
+    themeFiles
+  });
+}
+function parseShopifyPrimitiveSet(value) {
+  const parsed = shopifyPrimitiveSetSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+var SHOPIFY_PRIMITIVE_CONTRACT_VERSION, shopifyThemeFileSchema, shopifyPrimitiveSetSchema, localImport;
+var init_shopify_primitives = __esm({
+  "../shared/src/mcp/shopify-primitives.ts"() {
+    "use strict";
+    init_registry_css();
+    init_preview_html();
+    init_shopify_kit();
+    SHOPIFY_PRIMITIVE_CONTRACT_VERSION = 1;
+    shopifyThemeFileSchema = z5.object({
+      path: z5.string().min(1),
+      content: z5.string().min(1)
+    });
+    shopifyPrimitiveSetSchema = z5.object({
+      contractVersion: z5.literal(SHOPIFY_PRIMITIVE_CONTRACT_VERSION),
+      tokensCss: z5.string().min(1),
+      componentMaterialCss: z5.string(),
+      coveredSourcePrimitives: z5.array(z5.string()),
+      sourcePrimitivesWithShopifyAdapters: z5.array(z5.string()),
+      themeFiles: z5.array(shopifyThemeFileSchema).min(1)
+    });
+    localImport = /(^|\n)(\s*import\s*\{([^}]*)\}\s*from\s*["']\.\.?\/[^"']+["'];?)/g;
+  }
+});
+
+// ../shared/src/mcp/tools/design-system-tools.ts
+import { z as z6 } from "zod";
 function installCommandWithInit(installCommand) {
   return `${SHADCN_INIT_IF_MISSING}
 
@@ -6092,7 +7561,34 @@ async function fetchProjectTokensCss(projectId, apiFetch, authContext) {
     if (!res.ok) return null;
     const json = await res.json();
     return { tokensCss: tokensCssFromRegistry(json), name: json.name, files: json.files ?? [] };
-  } catch {
+  } catch (err) {
+    console.warn(`fetchProjectTokensCss(${projectId}) failed`, err);
+    return null;
+  }
+}
+function parseProjectShopifyPrimitives(projectId, name, value) {
+  const primitives = parseShopifyPrimitiveSet(value);
+  if (!primitives) return null;
+  return {
+    name: typeof name === "string" ? name : `Project ${projectId.slice(0, 8)}`,
+    primitives
+  };
+}
+async function fetchProjectShopifyPrimitives(projectId, apiFetch, authContext) {
+  try {
+    const res = await apiFetch(
+      `${APP_BASE_URL}/api/projects/${projectId}/shopify/all.json`,
+      { headers: authHeaders(authContext) }
+    );
+    if (!res.ok) return null;
+    const json = await res.json();
+    return parseProjectShopifyPrimitives(
+      projectId,
+      json.name,
+      json.shopifyPrimitives
+    );
+  } catch (err) {
+    console.warn(`fetchProjectShopifyPrimitives(${projectId}) failed`, err);
     return null;
   }
 }
@@ -6133,25 +7629,50 @@ function completedShopifyKitStructuredContent(name, viewUrl, tokensCss, themeFil
     tokensCss
   };
 }
+function completedShopifyKitResult(name, viewUrl, source, primitives) {
+  const { tokensCss, themeFiles } = primitives;
+  return {
+    content: [{
+      type: "text",
+      text: buildDsShopifyKit({ name, tokensCss, viewUrl, source, themeFiles })
+    }],
+    structuredContent: completedShopifyKitStructuredContent(
+      name,
+      viewUrl,
+      tokensCss,
+      themeFiles
+    )
+  };
+}
 async function fetchCatalog(designSystemId) {
   try {
     const [globalsRes, ...componentResults] = await Promise.all([
       fetch(`${REGISTRY_BASE_URL}/${designSystemId}/globals.json`),
       ...CATALOG_KIT_COMPONENTS.map(
-        (c) => fetch(`${REGISTRY_BASE_URL}/${designSystemId}/${c}.json`).catch(() => null)
+        (c) => fetch(`${REGISTRY_BASE_URL}/${designSystemId}/${c}.json`).catch((err) => {
+          console.warn(`catalog component fetch failed: ${designSystemId}/${c}`, err);
+          return null;
+        })
       )
     ]);
     if (!globalsRes.ok) return { tokensCss: "", files: [] };
     const globals = REGISTRY_ITEM_SCHEMA.safeParse(await globalsRes.json());
     if (!globals.success) return { tokensCss: "", files: [] };
     const files = [...globals.data.files ?? []];
-    for (const res of componentResults) {
-      if (!res?.ok) continue;
+    for (const [i, res] of componentResults.entries()) {
+      if (!res) continue;
+      if (!res.ok) {
+        console.warn(
+          `catalog component unavailable: ${designSystemId}/${CATALOG_KIT_COMPONENTS[i]} (HTTP ${res.status})`
+        );
+        continue;
+      }
       const item = REGISTRY_ITEM_SCHEMA.safeParse(await res.json().catch(() => null));
       if (item.success && item.data.files) files.push(...item.data.files);
     }
     return { tokensCss: tokensCssFromRegistry({ cssVars: globals.data.cssVars, files }), files };
-  } catch {
+  } catch (error) {
+    console.warn(`catalog registry fetch failed for ${designSystemId}`, error);
     return { tokensCss: "", files: [] };
   }
 }
@@ -6179,8 +7700,8 @@ function registerDesignSystemTools({
   authContext,
   apiFetch = globalThis.fetch
 }, { enableShopifyKit = true } = {}) {
-  const searchInputSchema = z5.object({
-    query: z5.string().describe(
+  const searchInputSchema = z6.object({
+    query: z6.string().describe(
       "The user's app, UI, industry, or visual direction. Examples: 'World Cup betting app for friends', 'warm editorial ecommerce', or 'professional fintech dashboard'."
     )
   });
@@ -6399,31 +7920,24 @@ ${fence3}` }],
   }) => tracked("get-design-system-kit", { target: "shopify", designSystemId, projectId, context }, async () => {
     if (projectId) {
       const viewUrl2 = `${APP_BASE_URL}/projects/${projectId}`;
-      const result = await fetchProjectTokensCss(projectId, apiFetch, authContext);
-      if (!result?.tokensCss) {
+      const providerResult = await provider.getProjectShopifyPrimitives?.(projectId);
+      const result = providerResult ? parseProjectShopifyPrimitives(
+        projectId,
+        providerResult.name,
+        providerResult.shopifyPrimitives
+      ) : await fetchProjectShopifyPrimitives(projectId, apiFetch, authContext);
+      if (!result) {
         return {
-          content: [{ type: "text", text: `Could not load tokens for project "${projectId}". It may still be generating, or the id is wrong. Check ${viewUrl2}.` }],
+          content: [{ type: "text", text: `Shopify version unavailable. Project "${projectId}" has no maintained Shopify primitive set yet. It may still be generating, belong to another account, or predate Shopify persistence. Check ${viewUrl2}.` }],
           structuredContent: { status: "error", name: `Project ${projectId.slice(0, 8)}`, viewUrl: viewUrl2, tokensCss: "" }
         };
       }
-      const componentKit2 = buildDsComponentCss(result.files);
-      const name = result.name ?? `Project ${projectId.slice(0, 8)}`;
-      const text2 = buildDsShopifyKit({
-        name,
-        tokensCss: result.tokensCss,
-        viewUrl: viewUrl2,
-        source: { kind: "project", projectId },
-        componentKit: componentKit2
-      });
-      return {
-        content: [{ type: "text", text: text2 }],
-        structuredContent: completedShopifyKitStructuredContent(
-          name,
-          viewUrl2,
-          result.tokensCss,
-          buildDsShopifyFiles({ tokensCss: result.tokensCss, componentKit: componentKit2 })
-        )
-      };
+      return completedShopifyKitResult(
+        result.name,
+        viewUrl2,
+        { kind: "project", projectId },
+        result.primitives
+      );
     }
     if (!designSystemId) {
       return {
@@ -6431,7 +7945,10 @@ ${fence3}` }],
         structuredContent: { status: "error", name: "Missing design system", tokensCss: "" }
       };
     }
-    const ds = await provider.getDesignSystemById(designSystemId, { includeComponents: false });
+    const ds = await provider.getDesignSystemById(designSystemId, {
+      includeComponents: false,
+      includeShopifyPrimitives: true
+    });
     if (!ds) {
       return {
         content: [{ type: "text", text: `Design system "${designSystemId}" not found. Call find-design-system first to get a valid id, or pass a projectId for a generated system.` }],
@@ -6439,30 +7956,20 @@ ${fence3}` }],
       };
     }
     const viewUrl = `${APP_BASE_URL}/design-systems/${designSystemId}`;
-    const { tokensCss, files } = await fetchCatalog(designSystemId);
-    if (!tokensCss) {
+    const primitives = parseShopifyPrimitiveSet(ds.metadata.shopifyPrimitives);
+    if (!primitives) {
+      const text = ds.metadata.shopifyAccess === "denied" ? `Shopify target unavailable. The Shopify kit is a private pilot and this API key is not in it, so the stored theme for "${designSystemId}" was withheld. Nothing is wrong with the design system. Ask for pilot access, or use target "react" or "html". See ${viewUrl}.` : `Shopify version unavailable. Design system "${designSystemId}" has no maintained Shopify primitive set. Shopify output is unavailable until that system is seeded and certified; no generic fallback was returned. See ${viewUrl}.`;
       return {
-        content: [{ type: "text", text: `Could not load tokens for "${designSystemId}". The full live showcase is at ${viewUrl}.` }],
+        content: [{ type: "text", text }],
         structuredContent: { status: "error", name: ds.metadata.title, viewUrl, tokensCss: "" }
       };
     }
-    const componentKit = buildDsComponentCss(files);
-    const text = buildDsShopifyKit({
-      name: ds.metadata.title,
-      tokensCss,
+    return completedShopifyKitResult(
+      ds.metadata.title,
       viewUrl,
-      source: { kind: "catalog", designSystemId },
-      componentKit
-    });
-    return {
-      content: [{ type: "text", text }],
-      structuredContent: completedShopifyKitStructuredContent(
-        ds.metadata.title,
-        viewUrl,
-        tokensCss,
-        buildDsShopifyFiles({ tokensCss, componentKit })
-      )
-    };
+      { kind: "catalog", designSystemId },
+      primitives
+    );
   });
   server.registerTool(
     "get-design-system-kit",
@@ -6494,22 +8001,22 @@ existing setup; otherwise use the default Base UI. Both flavors install to the
 same components/ui/ paths.
 
 ${BUILD_TARGET_RULE}`,
-      inputSchema: z5.object({
+      inputSchema: z6.object({
         // Off-pilot callers must not see the target at all, not merely be refused it.
-        target: z5.enum(
+        target: z6.enum(
           enableShopifyKit ? ["react", "html", "shopify"] : ["react", "html"]
         ).describe(`Required build target. Use "react" for any host with filesystem + terminal; use "html" only for inline chat canvases/artifacts.${enableShopifyKit ? ' Use "shopify" for Shopify stores and themes.' : ""}`),
-        designSystemId: z5.string().min(1).optional().describe(`Catalog design system ID from find-design-system. Required for target react; for target${enableShopifyKit ? "s html and shopify" : " html"} pass this or projectId.`),
-        projectId: z5.string().min(1).optional().describe(`Generated project ID from create-design-system / get-design-system-status. Supported with target${enableShopifyKit ? 's "html" and "shopify"' : ' "html"'}.`),
-        component: z5.union([z5.string(), z5.array(z5.string())]).optional().describe("React target only. Pass only when the user asks to inspect specific component source code. Omit to scaffold the entire design system."),
-        library: z5.enum(["radix", "base-ui"]).optional().describe('React target only, default "base-ui". Pass "radix" when the project already uses Radix primitives.'),
+        designSystemId: z6.string().min(1).optional().describe(`Catalog design system ID from find-design-system. Required for target react; for target${enableShopifyKit ? "s html and shopify" : " html"} pass this or projectId.`),
+        projectId: z6.string().min(1).optional().describe(`Generated project ID from create-design-system / get-design-system-status. Supported with target${enableShopifyKit ? 's "html" and "shopify"' : ' "html"'}.`),
+        component: z6.union([z6.string(), z6.array(z6.string())]).optional().describe("React target only. Pass only when the user asks to inspect specific component source code. Omit to scaffold the entire design system."),
+        library: z6.enum(["radix", "base-ui"]).optional().describe('React target only, default "base-ui". Pass "radix" when the project already uses Radix primitives.'),
         context: CONTEXT_ARG
       }),
       outputSchema: buildKitOutputSchema(enableShopifyKit),
       annotations: READ_ONLY_TOOL_ANNOTATIONS
       // This tool returns build instructions, not a visual preview. Attaching
-      // the preview template makes ChatGPT render a nested showcase iframe;
-      // when that iframe is unavailable the user sees a large blank card even
+      // the preview template makes ChatGPT render a large visual card;
+      // when that preview is unavailable the user sees a large blank card even
       // though the kit succeeded. preview-design-system remains the dedicated
       // interactive preview path. [BD-240]
     },
@@ -6723,15 +8230,18 @@ _${installNote}_`,
 
 **Use this on any "build/make me <app>" request, even when the user never mentions design or branding** (a design system IS the app's brand). But DON'T jump straight here: first call \`find-design-system\` with the app description, show the user the top ~4 matches, and ask which to start from (passed here as \`baseDesignSystemId\`) or whether to go fully custom. Then derive the \`prompt\` from the app (name, domain, vibe), generate, show it with \`get-design-system-status\`, and build with that brand. Also use it when the user explicitly wants a **custom** design system instead of installing an existing one via \`get-design-system-kit\`.
 
+**When the user has an existing brand** (their site, Figma file, or stylesheet): run \`extract-design-system\` or \`extract-from-url\` first and pass the resulting token sheet (the fenced \`\`\`css block, verbatim: the \`:root { ... }\` and optional \`.dark { ... }\` blocks) as \`brandCss\`. The generation is then pinned to that brand: no catalog aesthetic is retrieved, the sheet's colors, fonts and radii override everything, and later design-system switches are refused. Copy the block exactly; do not retype or trim it.
+
 How it works:
 1. Sends the user's prompt to Better Design's generation pipeline (same flow the web chat input uses) and returns IMMEDIATELY with the project id + project URL.
 2. Generation runs in the background and typically takes 1-3 minutes.
 3. Call \`get-design-system-status\` with the returned project id (wait ~60 seconds first) to get the live preview URL and the final \`npx shadcn add <registry-url>\` install command once it completes.
 
 Share the project URL with the user right away so they can watch the generation live.`,
-      inputSchema: z5.object({
-        prompt: z5.string().min(1).max(1e4).describe("Describe the design system the user wants. E.g. 'A warm, minimal design system for a personal finance app, soft pastels, rounded corners' or 'A brutalist developer tool aesthetic with sharp edges and monospace type'."),
-        baseDesignSystemId: z5.string().optional().describe("Optional. The catalog id the USER picked from the `find-design-system` matches you showed them, used to bias generation toward that aesthetic (e.g. a theme tweak on top of Linear). Leave empty only when the user chose fully custom.")
+      inputSchema: z6.object({
+        prompt: z6.string().min(1).max(1e4).describe("Describe the design system the user wants. E.g. 'A warm, minimal design system for a personal finance app, soft pastels, rounded corners' or 'A brutalist developer tool aesthetic with sharp edges and monospace type'."),
+        baseDesignSystemId: z6.string().optional().describe("Optional. The catalog id the USER picked from the `find-design-system` matches you showed them, used to bias generation toward that aesthetic (e.g. a theme tweak on top of Linear). Leave empty only when the user chose fully custom."),
+        brandCss: z6.string().max(5e4).optional().describe("Optional. The user's extracted brand token sheet, verbatim: the fenced css block from extract-design-system / extract-from-url (`:root { --background: ...; }` plus optional `.dark { ... }`). When set, generation builds FROM this brand instead of a catalog look-alike, and baseDesignSystemId is ignored (a catalog base would leak its identity past the brand tokens).")
       }),
       annotations: {
         readOnlyHint: false,
@@ -6739,7 +8249,7 @@ Share the project URL with the user right away so they can watch the generation
         openWorldHint: false
       }
     },
-    async ({ prompt, baseDesignSystemId }) => tracked("create-design-system", { query: prompt, hasBase: Boolean(baseDesignSystemId) }, async () => {
+    async ({ prompt, baseDesignSystemId, brandCss }) => tracked("create-design-system", { query: prompt, hasBase: Boolean(baseDesignSystemId), hasBrand: Boolean(brandCss) }, async () => {
       const startUrl = `${APP_BASE_URL}/api/projects/anonymous`;
       let projectId;
       const requestHeaders = { "Content-Type": "application/json" };
@@ -6753,7 +8263,8 @@ Share the project URL with the user right away so they can watch the generation
           headers: requestHeaders,
           body: JSON.stringify({
             value: prompt,
-            ...baseDesignSystemId ? { designSystemId: baseDesignSystemId } : {}
+            ...baseDesignSystemId ? { designSystemId: baseDesignSystemId } : {},
+            ...brandCss ? { brandCss } : {}
           })
         });
         if (!startRes.ok) {
@@ -6774,10 +8285,10 @@ Share the project URL with the user right away so they can watch the generation
         "",
         `Project id: \`${projectId}\``,
         "",
-        ...authContext ? [`Saved to your Better Design account. Watch it generate live:`] : [`Watch it generate live:`],
+        ...authContext ? [`Saved to your Better Design account. Watch it generate live (sign in with the account that created it, this link is private to you):`] : [`Watch it generate live:`],
         projectUrl,
         "",
-        `Generation takes 1-3 minutes. Share the project link with the user now, wait ~60 seconds, then call \`get-design-system-status\` with the project id to get the live preview URL and the final install command.`,
+        `Generation takes 1-3 minutes. Wait ~60 seconds, then call \`get-design-system-status\` with the project id: it returns a shareable preview link that opens without signing in, plus the final install command. Give the user that link, not this one.`,
         inlineBuildMd(projectId)
       ];
       return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -6819,10 +8330,17 @@ npx shadcn@latest add ${registryUrl}
         }
       } catch {
       }
+      const previewUrl = project.previewFragmentId ? `${APP_BASE_URL}/preview/${project.previewFragmentId}` : projectUrl;
+      const shareLines = project.previewFragmentId ? [
+        `Shareable preview, opens without signing in:`,
+        previewUrl,
+        ""
+      ] : [];
       const lines = [
         `# Design system ready`,
         "",
-        ...authContext ? [`Saved to your Better Design account. View, preview, and re-grab the install command anytime here:`] : [`View and preview your design system anytime here:`],
+        ...shareLines,
+        ...authContext ? [`Saved to your Better Design account. View, edit, and re-grab the install command here (sign in with the account that created it, this link is private to you):`] : [`View and preview your design system anytime here:`],
         projectUrl,
         "",
         `Project id: \`${projectId}\``,
@@ -6838,7 +8356,6 @@ npx shadcn@latest add ${registryUrl}
         "",
         `Now help the user finish, don't stop here. No icon library has been picked yet: call \`find-icon-library\` (query from the brand's personality), SHOW them the closest matches and let them pick one, then \`install-icons\`. After that, ask if they want to start building components.`
       ];
-      const previewUrl = project.previewFragmentId ? `${APP_BASE_URL}/preview/${project.previewFragmentId}` : projectUrl;
       const shotUrl = project.previewFragmentId ? `${APP_BASE_URL}/api/og/preview?fragment=${project.previewFragmentId}` : void 0;
       return {
         content: [{ type: "text", text: lines.join("\n") }],
@@ -6876,8 +8393,8 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
   const statusConfig = {
     title: "Get Design System Generation Status",
     description: `Check on a design system generation started with 'create-design-system'. Returns progress while generating, and the live preview URL + the \`npx shadcn add\` install command once complete. Generation typically takes 1-3 minutes; poll every ~30 seconds until it reports ready. Once ready, ask the user what's next (icon library, install, or build) instead of stopping.`,
-    inputSchema: z5.object({
-      projectId: z5.string().min(1).describe("The project id returned by create-design-system."),
+    inputSchema: z6.object({
+      projectId: z6.string().min(1).describe("The project id returned by create-design-system."),
       context: CONTEXT_ARG
     }),
     outputSchema: PREVIEW_OUTPUT_SCHEMA,
@@ -6900,8 +8417,8 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
     {
       title: "Preview a Design System",
       description: `Show the user a visual preview of a design system from the catalog (use the id from 'find-design-system'). Returns a token-true HTML preview: palette, typography, buttons, card, input, badge, plus a link to the full live showcase. Use this when the user wants to SEE a design system before installing it.`,
-      inputSchema: z5.object({
-        designSystemId: z5.string().min(1).describe("Design system id from find-design-system, e.g. 'linear', 'editorial-warm'."),
+      inputSchema: z6.object({
+        designSystemId: z6.string().min(1).describe("Design system id from find-design-system, e.g. 'linear', 'editorial-warm'."),
         context: CONTEXT_ARG
       }),
       outputSchema: PREVIEW_OUTPUT_SCHEMA,
@@ -6951,8 +8468,7 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
           status: "completed",
           name: ds.metadata.title,
           viewUrl,
-          // Real screenshot of the showcase, for hosts that can't iframe it
-          // (claude.ai). The widget shows this as the inline image. [BD-136]
+          // Real screenshot of the showcase for the self-contained widget.
           shotUrl: `${APP_BASE_URL}/api/og/preview?id=${encodeURIComponent(designSystemId)}`,
           tokensCss
         }
@@ -6967,55 +8483,26 @@ var init_design_system_tools = __esm({
     init_guardrails();
     init_html_kit();
     init_shopify_kit();
+    init_shopify_primitives();
     init_preview_html();
     init_shared();
-    REGISTRY_ITEM_SCHEMA = z5.object({
-      cssVars: z5.object({
-        light: z5.record(z5.string(), z5.string()).optional(),
-        dark: z5.record(z5.string(), z5.string()).optional(),
-        theme: z5.record(z5.string(), z5.string()).optional()
+    REGISTRY_ITEM_SCHEMA = z6.object({
+      cssVars: z6.object({
+        light: z6.record(z6.string(), z6.string()).optional(),
+        dark: z6.record(z6.string(), z6.string()).optional(),
+        theme: z6.record(z6.string(), z6.string()).optional()
       }).optional(),
-      files: z5.array(z5.object({ path: z5.string().optional(), content: z5.string().optional() })).optional()
+      files: z6.array(z6.object({ path: z6.string().optional(), content: z6.string().optional() })).optional()
     });
     SHADCN_INIT_IF_MISSING = "[ -f components.json ] || npx shadcn@latest init -d -y";
     SAFE_COMPONENT_NAME_RE = /^[a-z0-9][a-z0-9-]*$/i;
     CATALOG_KIT_COMPONENTS = ["button", "input", "card", "badge", "switch"];
-    DS_INDEX_SCHEMA = z5.object({
-      baseComponents: z5.array(z5.object({ name: z5.string() })).optional()
+    DS_INDEX_SCHEMA = z6.object({
+      baseComponents: z6.array(z6.object({ name: z6.string() })).optional()
     });
   }
 });
 
-// ../shared/src/registry-css.ts
-function parseCssVars(css) {
-  const out = { theme: {}, light: {}, dark: {} };
-  const matchBlock = (selector) => {
-    const re = new RegExp(`${selector}\\s*\\{([^}]*)\\}`, "g");
-    const blocks = [];
-    let m;
-    while (m = re.exec(css)) blocks.push(m[1]);
-    return blocks.join("\n");
-  };
-  const extract = (body) => {
-    const result = {};
-    const clean = body.replace(/\/\*[\s\S]*?\*\//g, "");
-    const declRe = /--([a-zA-Z0-9_-]+)\s*:\s*([^;]+);/g;
-    let m;
-    while (m = declRe.exec(clean)) {
-      result[m[1]] = m[2].replace(/\s+/g, " ").trim();
-    }
-    return result;
-  };
-  out.light = extract(matchBlock(":root"));
-  out.dark = extract(matchBlock("\\.dark"));
-  return out;
-}
-var init_registry_css = __esm({
-  "../shared/src/registry-css.ts"() {
-    "use strict";
-  }
-});
-
 // ../shared/src/mcp/color-to-oklch.ts
 function clamp01(n) {
   return Math.min(1, Math.max(0, n));
@@ -7077,6 +8564,16 @@ function parseRgb(value) {
     a: parseAlpha(alpha)
   });
 }
+function parseBareTriplet(value) {
+  const parts = value.split(",").map((p) => p.trim());
+  if (parts.length !== 3 && parts.length !== 4) return null;
+  if (!parts.every((p) => /^\d{1,3}(\.\d+)?$/.test(p))) return null;
+  const [r, g, b] = parts.map(Number);
+  if (![r, g, b].every((n) => n >= 0 && n <= 255)) return null;
+  const a = parts.length === 4 ? Number(parts[3]) : 1;
+  if (a < 0 || a > 1) return null;
+  return finiteRgba({ r: r / 255, g: g / 255, b: b / 255, a });
+}
 function hueToRgb(p, q, t) {
   let tt = t;
   if (tt < 0) tt += 1;
@@ -7163,6 +8660,7 @@ function toOklch(value) {
   if (v.startsWith("#")) rgba = parseHex(v);
   else if (/^rgba?\(/i.test(v)) rgba = parseRgb(v);
   else if (/^hsla?\(/i.test(v)) rgba = parseHsl(v);
+  else if (v.includes(",")) rgba = parseBareTriplet(v);
   return rgba ? rgbaToOklch(rgba) : null;
 }
 var NAMED_HEX, PASSTHROUGH_KEYWORDS, NON_COLOR_KEYWORDS;
@@ -7361,7 +8859,7 @@ function normalizeMap(raw) {
   }
   return { tokens, kinds };
 }
-function extractDesignSystem(css, name) {
+function collectCssVars(css) {
   const { light: rootLight, dark: rootDark } = parseCssVars(css);
   const themeVars = extractThemeBlock(css);
   const mergedLight = {};
@@ -7369,8 +8867,11 @@ function extractDesignSystem(css, name) {
     mergedLight[denamespace(k)] = v;
   }
   Object.assign(mergedLight, rootLight);
-  const light = normalizeMap(mergedLight);
-  const dark = normalizeMap(rootDark);
+  return { light: mergedLight, dark: rootDark };
+}
+function buildExtractionResult(raw, name) {
+  const light = normalizeMap(raw.light);
+  const dark = normalizeMap(raw.dark);
   const hasLight = Object.keys(light.tokens).length > 0;
   const hasDark = Object.keys(dark.tokens).length > 0;
   const themeMode = hasLight && hasDark ? "dual" : hasDark ? "dark" : hasLight ? "light" : "none";
@@ -7435,6 +8936,8 @@ function formatExtraction(result) {
   };
   const meta = [
     result.name ? `**Source:** ${result.name}` : null,
+    result.sources && result.sources.length > 1 ? `**Merged from:** ${result.sources.join(", ")}` : null,
+    result.aliased && result.aliased.length ? `**Vendor names mapped:** ${result.aliased.map(([f, t]) => `--${f} \u2192 --${t}`).join(", ")}` : null,
     `**Theme:** ${modeLabel[result.themeMode]}`,
     `**Tokens extracted:** ${result.tokenCount}`,
     `**Colors normalized to oklch.**`
@@ -7461,7 +8964,7 @@ function formatExtraction(result) {
   }
   sections.push(
     "## Token sheet (oklch-normalized, paste into globals.css)\n\n```css\n" + blocks.join("\n\n") + "\n```",
-    "## How to use\n- Style new components against these tokens (`bg-background`, `text-foreground`, `bg-primary`, `border-border`, `ring-ring`) so they match the existing app.\n- To turn this into a full Better Design system, pass the palette to `create-design-system` as the brand description."
+    "## How to use\n- Style new components against these tokens (`bg-background`, `text-foreground`, `bg-primary`, `border-border`, `ring-ring`) so they match the existing app.\n- To turn this into a full Better Design system, pass the token sheet above (the fenced css block, verbatim) to `create-design-system` as `brandCss`. Generation then builds FROM this brand instead of a catalog look-alike."
   );
   return sections.join("\n\n");
 }
@@ -7512,9 +9015,198 @@ var init_extract_design_system = __esm({
   }
 });
 
+// ../shared/src/mcp/brand-sources.ts
+function inferSourceKind(content) {
+  const t = content.trim();
+  if (!t.startsWith("{") && !t.startsWith("[")) return "css";
+  let parsed;
+  try {
+    parsed = JSON.parse(t);
+  } catch {
+    return "css";
+  }
+  if (t.includes('"$value"')) return "tokens";
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    const keys = Object.keys(parsed);
+    if (keys.some((k) => COMPUTED_ROLES.has(k))) return "computed";
+  }
+  return "tokens";
+}
+function buildRoleSampleScript() {
+  const entries = Object.keys(ROLE_MAP).map((role) => {
+    const selector = ROLE_SELECTORS[role];
+    const propList = JSON.stringify(Object.keys(ROLE_MAP[role]));
+    return `    ${role}: pick(document.querySelector(${JSON.stringify(selector)}), ${propList}),`;
+  }).join("\n");
+  return `(() => {
+  const pick = (el, props) => {
+    if (!el) return null;
+    const cs = getComputedStyle(el);
+    return Object.fromEntries(props.map((p) => [p, cs[p]]));
+  };
+  return {
+${entries}
+  };
+})()`;
+}
+function parseJsonOrNull(content) {
+  try {
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+function computedToVars(content) {
+  const out = {};
+  const roles = parseJsonOrNull(content);
+  if (!roles || typeof roles !== "object") return out;
+  for (const [role, styles] of Object.entries(roles)) {
+    if (!COMPUTED_ROLES.has(role) || !styles || typeof styles !== "object") continue;
+    const map = ROLE_MAP[role];
+    for (const [prop, token] of Object.entries(map)) {
+      const value = styles[prop];
+      if (typeof value === "string" && value.trim()) out[token] = value.trim();
+    }
+  }
+  if (out.border) out.input = out.border;
+  return out;
+}
+function figmaColorToRgbString(v) {
+  const { r, g, b, a } = v;
+  if (typeof r !== "number" || typeof g !== "number" || typeof b !== "number") return null;
+  const to255 = (n) => Math.round(Math.min(1, Math.max(0, n)) * 255);
+  const alpha = typeof a === "number" && a < 1 ? `, ${a}` : "";
+  return `rgb(${to255(r)}, ${to255(g)}, ${to255(b)}${alpha})`;
+}
+function kebab(part) {
+  return part.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+function tokensToVars(content) {
+  const out = {};
+  const walk = (node, path5) => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return;
+    const obj = node;
+    const value = "$value" in obj ? obj.$value : "value" in obj && "type" in obj ? obj.value : void 0;
+    if (value !== void 0) {
+      const name = path5.map(kebab).join("-");
+      if (!name) return;
+      if (typeof value === "string" || typeof value === "number") {
+        out[name] = String(value);
+      } else if (Array.isArray(value) && value.every((x) => typeof x === "string")) {
+        out[name] = value.join(", ");
+      } else if (value && typeof value === "object") {
+        const rgb = figmaColorToRgbString(value);
+        if (rgb) out[name] = rgb;
+      }
+      return;
+    }
+    for (const [k, v] of Object.entries(obj)) {
+      if (k.startsWith("$")) continue;
+      walk(v, [...path5, k]);
+    }
+  };
+  walk(parseJsonOrNull(content), []);
+  return out;
+}
+function applyAliases(vars) {
+  const applied = [];
+  for (const [from, to] of SEMANTIC_ALIASES) {
+    if (vars[from] !== void 0 && vars[to] === void 0) {
+      vars[to] = vars[from];
+      applied.push([from, to]);
+    }
+  }
+  return applied;
+}
+function extractFromSources(sources, name) {
+  const light = {};
+  const dark = {};
+  for (const source of sources) {
+    const kind = source.kind ?? inferSourceKind(source.content);
+    if (kind === "css") {
+      const parsed = collectCssVars(source.content);
+      Object.assign(light, parsed.light);
+      Object.assign(dark, parsed.dark);
+    } else if (kind === "computed") {
+      Object.assign(light, computedToVars(source.content));
+    } else {
+      Object.assign(light, tokensToVars(source.content));
+    }
+  }
+  const aliased = applyAliases(light);
+  for (const pair of applyAliases(dark)) {
+    if (!aliased.some(([f, t]) => f === pair[0] && t === pair[1])) aliased.push(pair);
+  }
+  const result = buildExtractionResult({ light, dark }, name);
+  result.sources = sources.map((s) => s.name);
+  if (aliased.length) result.aliased = aliased;
+  return result;
+}
+var ROLE_MAP, COMPUTED_ROLES, ROLE_SELECTORS, SEMANTIC_ALIASES;
+var init_brand_sources = __esm({
+  "../shared/src/mcp/brand-sources.ts"() {
+    "use strict";
+    init_extract_design_system();
+    ROLE_MAP = {
+      body: { backgroundColor: "background", color: "foreground", fontFamily: "font-sans" },
+      heading: { fontFamily: "font-heading" },
+      // The link color is the closest rendered stand-in for an accent. On sites
+      // where links reuse the primary, the alias fill leaves primary untouched, so
+      // this can only add information, never fight the button's own sample.
+      link: { color: "accent" },
+      button: {
+        backgroundColor: "primary",
+        color: "primary-foreground",
+        borderRadius: "radius-button"
+      },
+      input: { borderColor: "border", borderRadius: "radius-input" },
+      card: {
+        backgroundColor: "card",
+        color: "card-foreground",
+        borderRadius: "radius-card",
+        boxShadow: "shadow-card"
+      }
+    };
+    COMPUTED_ROLES = new Set(Object.keys(ROLE_MAP));
+    ROLE_SELECTORS = {
+      body: "body",
+      heading: "h1,h2",
+      link: "a[href]",
+      button: "button,[role=button],.btn,input[type=submit]",
+      input: "input:not([type=hidden]),textarea,select",
+      card: "[class*=card]"
+    };
+    SEMANTIC_ALIASES = [
+      ["color-background", "background"],
+      ["color-foreground", "foreground"],
+      ["color-button", "primary"],
+      ["color-button-text", "primary-foreground"],
+      ["color-secondary-button", "secondary"],
+      ["color-secondary-button-text", "secondary-foreground"],
+      ["color-link", "accent"],
+      ["font-body-family", "font-sans"],
+      ["button", "primary"],
+      ["button-text", "primary-foreground"]
+    ];
+  }
+});
+
 // ../shared/src/mcp/tools/extract-tools.ts
-import { z as z6 } from "zod";
-function registerExtractTools({ server, tracked }) {
+import { z as z7 } from "zod";
+function authHeaders2(authContext) {
+  if (!authContext) return {};
+  const bearer2 = authContext.kind === "api-key" ? authContext.apiKey : authContext.accessToken;
+  return { Authorization: `Bearer ${bearer2}` };
+}
+function redactUrl(raw) {
+  try {
+    const u = new URL(raw);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return "[redacted]";
+  }
+}
+function registerExtractTools({ server, tracked, authContext, apiFetch = globalThis.fetch }) {
   server.registerTool(
     "extract-design-system",
     {
@@ -7525,32 +9217,100 @@ Use this when the user says "match our existing style", "use our design system",
 
 How to use it: read the project's \`globals.css\` (or wherever the design tokens / CSS custom properties live, e.g. a Tailwind v4 \`@theme\` block) and pass its full contents as \`css\`. The MCP server cannot read your filesystem, so you must paste the text.
 
-Returns: the semantic palette (primary, background, foreground, accent, border, ring, etc.), radius, fonts, and shadow scale, plus a pasteable token sheet with every color normalized to \`oklch()\`. Handles hex, rgb()/rgba(), hsl()/hsla(), named colors, and existing oklch values, across \`:root\`, \`.dark\`, and \`@theme\` blocks.`,
-      inputSchema: z6.object({
-        css: z6.string().trim().min(1).max(2e5).describe("Full contents of the project's globals.css (or any CSS holding the design tokens / CSS custom properties)."),
-        name: z6.string().trim().min(1).max(120).optional().describe("Optional label for the extracted system, e.g. the app or repo name."),
-        maxTokens: z6.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates the token sheet to fit.")
+Returns: the semantic palette (primary, background, foreground, accent, border, ring, etc.), radius, fonts, and shadow scale, plus a pasteable token sheet with every color normalized to \`oklch()\`. Handles hex, rgb()/rgba(), hsl()/hsla(), named colors, bare Shopify "r,g,b" triplets, and existing oklch values, across \`:root\`, \`.dark\`, and \`@theme\` blocks.
+
+Beyond pasted CSS, \`sources\` accepts any mix of inputs and merges them (later sources win):
+- kind "css": any stylesheet text, same as the \`css\` param.
+- kind "computed": a JSON sample of rendered styles read off the LIVE site, which beats variable-name guessing because it records what elements actually look like. Gather it by running this in the site's browser console and passing the printed JSON:
+\`\`\`js
+JSON.stringify(${buildRoleSampleScript()})
+\`\`\`
+- kind "tokens": a design-tokens JSON export ($value entries, W3C format or the Figma variables API shape with 0..1 rgb floats).
+
+Common vendor names (Shopify's --color-button family) are mapped into empty semantic slots automatically and the mapping is reported in the output.`,
+      inputSchema: z7.object({
+        css: z7.string().trim().min(1).max(2e5).optional().describe("Full contents of the project's globals.css (or any CSS holding the design tokens / CSS custom properties). Optional when `sources` is given."),
+        sources: z7.array(z7.object({
+          name: z7.string().trim().min(1).max(120).describe("Label for this source, e.g. 'globals.css', 'live site sample', 'figma variables'."),
+          kind: z7.enum(["css", "computed", "tokens"]).optional().describe("Omit to infer: JSON with $value entries is tokens, JSON keyed by UI roles is computed, anything else is CSS."),
+          content: z7.string().trim().min(1).max(2e5)
+        })).max(10).optional().describe("Any mix of brand sources, merged in order (later sources win). See the tool description for how to gather each kind."),
+        name: z7.string().trim().min(1).max(120).optional().describe("Optional label for the extracted system, e.g. the app or repo name."),
+        maxTokens: z7.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates the token sheet to fit.")
       }),
       annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
-    async ({ css, name, maxTokens }) => tracked("extract-design-system", { name: name ?? null }, async () => {
-      const result = extractDesignSystem(css, name);
+    async ({ css, sources, name, maxTokens }) => tracked("extract-design-system", { name: name ?? null, sourceCount: (sources?.length ?? 0) + (css ? 1 : 0) }, async () => {
+      const all = [
+        ...css ? [{ name: "pasted css", kind: "css", content: css }] : [],
+        ...sources ?? []
+      ];
+      if (all.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: "Nothing to extract: pass `css`, or one or more `sources`."
+          }]
+        };
+      }
+      const result = extractFromSources(all, name);
       let text = formatExtraction(result);
       if (maxTokens) text = truncateToTokens(text, maxTokens);
       return { content: [{ type: "text", text }] };
     })
   );
+  server.registerTool(
+    "extract-from-url",
+    {
+      title: "Extract Design System From a Live Site",
+      description: `Point Better Design at a URL and get the site's brand back as an oklch token sheet, without pasting anything.
+
+Use this when the user names their site ("match uclips.eu", "use our website's style") or hands you any public URL whose look should be reused. Server side, Better Design fetches the page's stylesheets AND renders the page in a headless browser to sample what role elements actually look like (body, heading, link, button, input, card), then merges both, rendered truth last. That reads the brand even when the site's variable names are unrecognizable.
+
+Slow by nature (a real browser loads the page): expect 10 to 45 seconds. For CSS the user already has locally, prefer extract-design-system, which is instant.`,
+      inputSchema: z7.object({
+        url: z7.string().trim().min(8).max(2048).describe("Public http(s) URL of the page to read, usually the homepage."),
+        name: z7.string().trim().min(1).max(120).optional().describe("Optional label for the extracted system. Defaults to the site's hostname."),
+        maxTokens: z7.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates the token sheet to fit.")
+      }),
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
+    },
+    async ({ url, name, maxTokens }) => tracked("extract-from-url", { query: redactUrl(url) }, async () => {
+      const params = new URLSearchParams({ url });
+      if (name) params.set("name", name);
+      const res = await apiFetch(`${APP_BASE_URL}/api/v1/brand-extract/from-url?${params}`, {
+        headers: authHeaders2(authContext),
+        signal: AbortSignal.timeout(9e4)
+      });
+      if (!res.ok) {
+        const body2 = await res.json().catch(() => ({}));
+        return {
+          content: [{
+            type: "text",
+            text: `Could not extract from that URL (HTTP ${res.status}). ${body2.message ?? ""}`.trim()
+          }]
+        };
+      }
+      const body = await res.json();
+      let text = body.notes?.length ? `> ${body.notes.join("\n> ")}
+
+${body.markdown}` : body.markdown;
+      if (maxTokens) text = truncateToTokens(text, maxTokens);
+      return { content: [{ type: "text", text }] };
+    })
+  );
 }
 var init_extract_tools = __esm({
   "../shared/src/mcp/tools/extract-tools.ts"() {
     "use strict";
     init_shared();
     init_extract_design_system();
+    init_brand_sources();
   }
 });
 
 // ../shared/src/mcp/tools/illustration-tools.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function fail(message) {
   return {
     content: [{ type: "text", text: message }],
@@ -7571,7 +9331,7 @@ function registerIllustrationTools({
   authContext,
   apiFetch = globalThis.fetch
 }) {
-  const authHeaders2 = () => {
+  const authHeaders3 = () => {
     const headers = { "Content-Type": "application/json" };
     if (authContext) {
       const bearer2 = authContext.kind === "api-key" ? authContext.apiKey : authContext.accessToken;
@@ -7596,11 +9356,11 @@ How to call it:
 4. Stop when \`faults\` is empty.
 
 Markup carrying script, event handlers, remote references, or styles that reach outside the drawing is refused rather than cleaned, so the drawing you fix is the drawing you sent.`,
-      inputSchema: z7.object({
-        svg: z7.string().min(1).describe("The complete svg element you drew."),
-        intent: z7.string().min(1).describe('What it is meant to be, in plain words. For example "an open inbox tray with letters".'),
-        animated: z7.boolean().optional().describe("Set when the drawing was meant to move, so the motion checks apply."),
-        reviewToken: z7.string().optional().describe("The token from a previous review of this drawing. Reviews it again free.")
+      inputSchema: z8.object({
+        svg: z8.string().min(1).describe("The complete svg element you drew."),
+        intent: z8.string().min(1).describe('What it is meant to be, in plain words. For example "an open inbox tray with letters".'),
+        animated: z8.boolean().optional().describe("Set when the drawing was meant to move, so the motion checks apply."),
+        reviewToken: z8.string().optional().describe("The token from a previous review of this drawing. Reviews it again free.")
       }),
       outputSchema: REVIEW_OUTPUT_SCHEMA,
       annotations: READ_ONLY_TOOL_ANNOTATIONS
@@ -7617,7 +9377,7 @@ Markup carrying script, event handlers, remote references, or styles that reach
         try {
           const res = await apiFetch(`${APP_BASE_URL}/api/illustrations/review`, {
             method: "POST",
-            headers: authHeaders2(),
+            headers: authHeaders3(),
             signal: AbortSignal.timeout(6e4),
             body: JSON.stringify({ svg, intent, animated: animated ?? false, reviewToken })
           });
@@ -7669,16 +9429,16 @@ var init_illustration_tools = __esm({
     init_shared();
     REVIEW_OUTPUT_SCHEMA = {
       /** Empty when nothing is visibly wrong. */
-      faults: z7.array(z7.string()),
+      faults: z8.array(z8.string()),
       /** Group ids in paint order, the parts an animation can target. */
-      layers: z7.array(z7.string()),
+      layers: z8.array(z8.string()),
       /** False when the markup was refused; faults says why. */
-      reviewed: z7.boolean(),
+      reviewed: z8.boolean(),
       /** True when the drawing could not be rendered, so only structure was checked. */
-      unseen: z7.boolean(),
+      unseen: z8.boolean(),
       /** Pass this back to review the same drawing again without spending another credit. */
-      reviewToken: z7.string(),
-      message: z7.string()
+      reviewToken: z8.string(),
+      message: z8.string()
     };
   }
 });
@@ -7715,15 +9475,13 @@ var init_preview_resource = __esm({
         prefersBorder: true,
         csp: {
           connectDomains: [APP_BASE_URL, ...WIDGET_RESOURCE_DOMAINS],
-          resourceDomains: [APP_BASE_URL, ...WIDGET_RESOURCE_DOMAINS],
-          frameDomains: WIDGET_FRAME_DOMAINS
+          resourceDomains: [APP_BASE_URL, ...WIDGET_RESOURCE_DOMAINS]
         },
         domain: WIDGET_APP_DOMAIN
       },
       "openai/widgetCSP": {
         connect_domains: [APP_BASE_URL, ...WIDGET_RESOURCE_DOMAINS],
         resource_domains: [APP_BASE_URL, ...WIDGET_RESOURCE_DOMAINS],
-        frame_domains: WIDGET_FRAME_DOMAINS,
         redirect_domains: [APP_BASE_URL]
       }
     };
@@ -7731,9 +9489,9 @@ var init_preview_resource = __esm({
 });
 
 // ../shared/src/mcp/tools.ts
-function registerAllTools(server, provider, onToolUsage, authContext, options = {}, apiFetch = globalThis.fetch) {
+function registerAllTools(server, provider, onToolUsage, authContext, options = {}, apiFetch = globalThis.fetch, userId) {
   const { track, tracked } = createTracking(server, onToolUsage);
-  const deps = { server, provider, track, tracked, authContext, apiFetch };
+  const deps = { server, provider, track, tracked, authContext, apiFetch, userId };
   registerPrincipleTools(deps, options);
   registerComprehensionTools(deps);
   registerIconTools(deps);
@@ -7761,9 +9519,22 @@ var init_tools = __esm({
 var mcp_exports = {};
 __export(mcp_exports, {
   BUILD_TARGET_RULE: () => BUILD_TARGET_RULE,
+  GUIDANCE_TOOLS: () => GUIDANCE_TOOLS,
   INSTRUCTIONS: () => INSTRUCTIONS,
+  MCP_SESSION_WINDOW_MS: () => MCP_SESSION_WINDOW_MS,
+  REVIEW_TOOLS: () => REVIEW_TOOLS,
   SEARCH_TOOLS: () => SEARCH_TOOLS,
-  createMcpServer: () => createMcpServer
+  SESSION_LOOP_TOOLS: () => SESSION_LOOP_TOOLS,
+  SHOPIFY_PRIMITIVE_CONTRACT_VERSION: () => SHOPIFY_PRIMITIVE_CONTRACT_VERSION,
+  buildShopifyPrimitiveSet: () => buildShopifyPrimitiveSet,
+  createMcpServer: () => createMcpServer,
+  formatTopicList: () => formatTopicList,
+  guidancePreamble: () => guidancePreamble,
+  parseShopifyPrimitiveSet: () => parseShopifyPrimitiveSet,
+  reviewNudge: () => reviewNudge,
+  reviewSectionForTopic: () => reviewSectionForTopic,
+  summarizeSessionGuidance: () => summarizeSessionGuidance,
+  weightReviewRules: () => weightReviewRules
 });
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 function createMcpServer(options) {
@@ -7776,7 +9547,8 @@ function createMcpServer(options) {
     enableReactNativeGuide = true,
     enableThreeJsGuide = true,
     enableShopifyKit = true,
-    apiFetch = globalThis.fetch
+    apiFetch = globalThis.fetch,
+    userId
   } = options;
   const server = new McpServer(
     { name, version },
@@ -7792,7 +9564,8 @@ function createMcpServer(options) {
       enableThreeJsGuide,
       enableShopifyKit
     },
-    apiFetch
+    apiFetch,
+    userId
   );
   return server;
 }
@@ -7803,7 +9576,9 @@ var init_mcp = __esm({
     init_tools();
     init_tools();
     init_instructions();
+    init_session_guidance();
     init_shared();
+    init_shopify_primitives();
   }
 });
 
@@ -7813,7 +9588,9 @@ __export(api_client_exports, {
   getDesignSystem: () => getDesignSystem,
   getDesignSystemComponents: () => getDesignSystemComponents,
   getPrinciple: () => getPrinciple,
+  getProjectShopifyPrimitives: () => getProjectShopifyPrimitives,
   getReviewRules: () => getReviewRules,
+  getSessionGuidance: () => getSessionGuidance,
   listPrinciples: () => listPrinciples,
   searchDesignSystems: () => searchDesignSystems,
   searchIconLibraries: () => searchIconLibraries,
@@ -7848,11 +9625,14 @@ async function searchDesignSystems(query, limit = 5) {
     `/v1/design-systems/search?q=${encodeURIComponent(query)}&limit=${limit}`
   );
 }
-async function getDesignSystem(id, includeHtml = false) {
-  const params = includeHtml ? "?includeHtml=true" : "";
-  return request(
-    `/v1/design-systems/${encodeURIComponent(id)}${params}`
-  );
+async function getDesignSystem(id, options = {}) {
+  const params = new URLSearchParams();
+  if (options.includeHtml) params.set("includeHtml", "true");
+  if (options.includeShopifyPrimitives) {
+    params.set("includeShopifyPrimitives", "true");
+  }
+  const query = params.size ? `?${params}` : "";
+  return request(`/v1/design-systems/${encodeURIComponent(id)}${query}`);
 }
 async function getDesignSystemComponents(id, names, includeCode = true) {
   const params = new URLSearchParams();
@@ -7863,6 +9643,9 @@ async function getDesignSystemComponents(id, names, includeCode = true) {
     `/v1/design-systems/${encodeURIComponent(id)}/components${query}`
   );
 }
+async function getProjectShopifyPrimitives(projectId) {
+  return request(`/projects/${encodeURIComponent(projectId)}/shopify/all.json`);
+}
 async function listPrinciples(area) {
   const params = area ? `?area=${area}` : "";
   return request(`/v1/principles${params}`);
@@ -7894,13 +9677,20 @@ async function getReviewRules(category = "all") {
   const params = category !== "all" ? `?category=${encodeURIComponent(category)}` : "";
   return request(`/v1/review-rules${params}`);
 }
+async function getSessionGuidance(windowMs) {
+  const params = new URLSearchParams({ windowMs: String(Math.round(windowMs)) });
+  return request(`/v1/session-guidance?${params}`);
+}
 function postAlert(body) {
   fetch(`${API_URL2}/api/internal/alert`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body),
     signal: AbortSignal.timeout(5e3)
-  }).catch(() => {
+  }).then((res) => {
+    if (!res.ok) console.warn(`postAlert failed: HTTP ${res.status}`);
+  }).catch((err) => {
+    console.warn("postAlert failed", err);
   });
 }
 function trackToolUsage(tool, params, context = {}) {
@@ -7957,17 +9747,36 @@ function createHttpDataProvider() {
       return results;
     },
     async getDesignSystemById(id, options = {}) {
-      const systemRes = await getDesignSystem(id, options.includeHtml);
+      const systemRes = await getDesignSystem(id, {
+        includeHtml: options.includeHtml,
+        includeShopifyPrimitives: options.includeShopifyPrimitives
+      });
       const componentsRes = options.includeComponents === false ? { components: [] } : await getDesignSystemComponents(
         id,
         options.componentNames,
         options.includeComponentCode
       );
       return {
-        metadata: systemRes.metadata,
+        // Spread the field only when the API sent it. Assigning it
+        // unconditionally would put `shopifyAccess: undefined` on every
+        // response, so `"shopifyAccess" in metadata` reads true for callers who
+        // never asked about Shopify, breaking the absent-unless-requested
+        // contract the field documents. [BD-421]
+        metadata: {
+          ...systemRes.metadata,
+          ...systemRes.shopifyAccess === void 0 ? {} : { shopifyAccess: systemRes.shopifyAccess }
+        },
         components: componentsRes.components
       };
     },
+    async getProjectShopifyPrimitives(projectId) {
+      try {
+        return await getProjectShopifyPrimitives(projectId);
+      } catch (err) {
+        console.warn(`getProjectShopifyPrimitives(${projectId}) failed`, err);
+        return null;
+      }
+    },
     async listPrinciples(area) {
       const { principles } = await listPrinciples(area);
       return principles;
@@ -7975,7 +9784,8 @@ function createHttpDataProvider() {
     async getPrincipleByTopic(topic, area) {
       try {
         return await getPrinciple(topic, area);
-      } catch {
+      } catch (err) {
+        console.warn(`getPrincipleByTopic(${topic}) failed`, err);
         return null;
       }
     },
@@ -7987,6 +9797,23 @@ function createHttpDataProvider() {
       const { rules } = await getReviewRules(category);
       return rules;
     },
+    /**
+     * Session-aware review [BD-495]. The stdio client never learns its own user
+     * id, so the argument is ignored and the API resolves the caller from the
+     * API key. Any failure, including an older server without the endpoint,
+     * resolves to an empty session so the review tools answer as they did
+     * before.
+     */
+    async getRecentGuidance(_userId, sinceMs) {
+      try {
+        const requested = Date.now() - sinceMs;
+        const windowMs = Math.min(Math.max(requested, 1), MCP_SESSION_WINDOW_MS);
+        const { calls } = await getSessionGuidance(windowMs);
+        return calls;
+      } catch {
+        return [];
+      }
+    },
     async searchIconLibraries(query, limit = 5) {
       const { results } = await searchIconLibraries(query, limit);
       return results;
@@ -8013,6 +9840,7 @@ function createHttpDataProvider() {
 var init_http_data_provider = __esm({
   "src/lib/http-data-provider.ts"() {
     "use strict";
+    init_mcp();
     init_api_client();
   }
 });
@@ -8060,11 +9888,7 @@ __export(mcp_debug_log_exports, {
   mcpDebugLogPath: () => mcpDebugLogPath
 });
 function mcpDebugLogPath() {
-  try {
-    return typeof process !== "undefined" ? process.env?.MCP_DEBUG_LOG : void 0;
-  } catch {
-    return void 0;
-  }
+  return typeof process !== "undefined" ? process.env?.MCP_DEBUG_LOG : void 0;
 }
 function mcpDebugLog(entry) {
   const path5 = mcpDebugLogPath();