@vibeframe/mcp-server 0.57.3 → 0.58.0

package/dist/index.js

@@ -7126,9 +7126,9 @@ var init_project_builder = __esm({
   }
 });
 
-// ../../node_modules/.pnpm/esbuild@0.24.2/node_modules/esbuild/lib/main.js
+// ../../node_modules/.pnpm/esbuild@0.27.3/node_modules/esbuild/lib/main.js
 var require_main = __commonJS({
-  "../../node_modules/.pnpm/esbuild@0.24.2/node_modules/esbuild/lib/main.js"(exports, module) {
+  "../../node_modules/.pnpm/esbuild@0.27.3/node_modules/esbuild/lib/main.js"(exports, module) {
     "use strict";
     var __defProp3 = Object.defineProperty;
     var __getOwnPropDesc3 = Object.getOwnPropertyDescriptor;
@@ -7333,25 +7333,31 @@ is not a problem with esbuild. You need to fix your environment instead.
     var quote = JSON.stringify;
     var buildLogLevelDefault = "warning";
     var transformLogLevelDefault = "silent";
-    function validateTarget(target) {
-      validateStringValue(target, "target");
-      if (target.indexOf(",") >= 0) throw new Error(`Invalid target: ${target}`);
-      return target;
+    function validateAndJoinStringArray(values, what) {
+      const toJoin = [];
+      for (const value of values) {
+        validateStringValue(value, what);
+        if (value.indexOf(",") >= 0) throw new Error(`Invalid ${what}: ${value}`);
+        toJoin.push(value);
+      }
+      return toJoin.join(",");
     }
     var canBeAnything = () => null;
     var mustBeBoolean = (value) => typeof value === "boolean" ? null : "a boolean";
     var mustBeString = (value) => typeof value === "string" ? null : "a string";
     var mustBeRegExp = (value) => value instanceof RegExp ? null : "a RegExp object";
     var mustBeInteger = (value) => typeof value === "number" && value === (value | 0) ? null : "an integer";
+    var mustBeValidPortNumber = (value) => typeof value === "number" && value === (value | 0) && value >= 0 && value <= 65535 ? null : "a valid port number";
     var mustBeFunction = (value) => typeof value === "function" ? null : "a function";
     var mustBeArray = (value) => Array.isArray(value) ? null : "an array";
+    var mustBeArrayOfStrings = (value) => Array.isArray(value) && value.every((x) => typeof x === "string") ? null : "an array of strings";
     var mustBeObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? null : "an object";
     var mustBeEntryPoints = (value) => typeof value === "object" && value !== null ? null : "an array or an object";
     var mustBeWebAssemblyModule = (value) => value instanceof WebAssembly.Module ? null : "a WebAssembly.Module";
     var mustBeObjectOrNull = (value) => typeof value === "object" && !Array.isArray(value) ? null : "an object or null";
     var mustBeStringOrBoolean = (value) => typeof value === "string" || typeof value === "boolean" ? null : "a string or a boolean";
     var mustBeStringOrObject = (value) => typeof value === "string" || typeof value === "object" && value !== null && !Array.isArray(value) ? null : "a string or an object";
-    var mustBeStringOrArray = (value) => typeof value === "string" || Array.isArray(value) ? null : "a string or an array";
+    var mustBeStringOrArrayOfStrings = (value) => typeof value === "string" || Array.isArray(value) && value.every((x) => typeof x === "string") ? null : "a string or an array of strings";
     var mustBeStringOrUint8Array = (value) => typeof value === "string" || value instanceof Uint8Array ? null : "a string or a Uint8Array";
     var mustBeStringOrURL = (value) => typeof value === "string" || value instanceof URL ? null : "a string or a URL";
     function getFlag3(object, keys2, key2, mustBeFn) {
@@ -7415,7 +7421,7 @@ is not a problem with esbuild. You need to fix your environment instead.
       let legalComments = getFlag3(options, keys2, "legalComments", mustBeString);
       let sourceRoot = getFlag3(options, keys2, "sourceRoot", mustBeString);
       let sourcesContent = getFlag3(options, keys2, "sourcesContent", mustBeBoolean);
-      let target = getFlag3(options, keys2, "target", mustBeStringOrArray);
+      let target = getFlag3(options, keys2, "target", mustBeStringOrArrayOfStrings);
       let format4 = getFlag3(options, keys2, "format", mustBeString);
       let globalName = getFlag3(options, keys2, "globalName", mustBeString);
       let mangleProps = getFlag3(options, keys2, "mangleProps", mustBeRegExp);
@@ -7426,8 +7432,8 @@ is not a problem with esbuild. You need to fix your environment instead.
       let minifyWhitespace = getFlag3(options, keys2, "minifyWhitespace", mustBeBoolean);
       let minifyIdentifiers = getFlag3(options, keys2, "minifyIdentifiers", mustBeBoolean);
       let lineLimit = getFlag3(options, keys2, "lineLimit", mustBeInteger);
-      let drop = getFlag3(options, keys2, "drop", mustBeArray);
-      let dropLabels = getFlag3(options, keys2, "dropLabels", mustBeArray);
+      let drop = getFlag3(options, keys2, "drop", mustBeArrayOfStrings);
+      let dropLabels = getFlag3(options, keys2, "dropLabels", mustBeArrayOfStrings);
       let charset = getFlag3(options, keys2, "charset", mustBeString);
       let treeShaking = getFlag3(options, keys2, "treeShaking", mustBeBoolean);
       let ignoreAnnotations = getFlag3(options, keys2, "ignoreAnnotations", mustBeBoolean);
@@ -7440,17 +7446,15 @@ is not a problem with esbuild. You need to fix your environment instead.
       let define2 = getFlag3(options, keys2, "define", mustBeObject);
       let logOverride = getFlag3(options, keys2, "logOverride", mustBeObject);
       let supported = getFlag3(options, keys2, "supported", mustBeObject);
-      let pure = getFlag3(options, keys2, "pure", mustBeArray);
+      let pure = getFlag3(options, keys2, "pure", mustBeArrayOfStrings);
       let keepNames = getFlag3(options, keys2, "keepNames", mustBeBoolean);
       let platform = getFlag3(options, keys2, "platform", mustBeString);
       let tsconfigRaw = getFlag3(options, keys2, "tsconfigRaw", mustBeStringOrObject);
+      let absPaths = getFlag3(options, keys2, "absPaths", mustBeArrayOfStrings);
       if (legalComments) flags.push(`--legal-comments=${legalComments}`);
       if (sourceRoot !== void 0) flags.push(`--source-root=${sourceRoot}`);
       if (sourcesContent !== void 0) flags.push(`--sources-content=${sourcesContent}`);
-      if (target) {
-        if (Array.isArray(target)) flags.push(`--target=${Array.from(target).map(validateTarget).join(",")}`);
-        else flags.push(`--target=${validateTarget(target)}`);
-      }
+      if (target) flags.push(`--target=${validateAndJoinStringArray(Array.isArray(target) ? target : [target], "target")}`);
       if (format4) flags.push(`--format=${format4}`);
       if (globalName) flags.push(`--global-name=${globalName}`);
       if (platform) flags.push(`--platform=${platform}`);
@@ -7464,9 +7468,10 @@ is not a problem with esbuild. You need to fix your environment instead.
       if (treeShaking !== void 0) flags.push(`--tree-shaking=${treeShaking}`);
       if (ignoreAnnotations) flags.push(`--ignore-annotations`);
       if (drop) for (let what of drop) flags.push(`--drop:${validateStringValue(what, "drop")}`);
-      if (dropLabels) flags.push(`--drop-labels=${Array.from(dropLabels).map((what) => validateStringValue(what, "dropLabels")).join(",")}`);
-      if (mangleProps) flags.push(`--mangle-props=${mangleProps.source}`);
-      if (reserveProps) flags.push(`--reserve-props=${reserveProps.source}`);
+      if (dropLabels) flags.push(`--drop-labels=${validateAndJoinStringArray(dropLabels, "drop label")}`);
+      if (absPaths) flags.push(`--abs-paths=${validateAndJoinStringArray(absPaths, "abs paths")}`);
+      if (mangleProps) flags.push(`--mangle-props=${jsRegExpToGoRegExp(mangleProps)}`);
+      if (reserveProps) flags.push(`--reserve-props=${jsRegExpToGoRegExp(reserveProps)}`);
       if (mangleQuoted !== void 0) flags.push(`--mangle-quoted=${mangleQuoted}`);
       if (jsx) flags.push(`--jsx=${jsx}`);
       if (jsxFactory) flags.push(`--jsx-factory=${jsxFactory}`);
@@ -7515,11 +7520,11 @@ is not a problem with esbuild. You need to fix your environment instead.
       let outdir = getFlag3(options, keys2, "outdir", mustBeString);
       let outbase = getFlag3(options, keys2, "outbase", mustBeString);
       let tsconfig = getFlag3(options, keys2, "tsconfig", mustBeString);
-      let resolveExtensions = getFlag3(options, keys2, "resolveExtensions", mustBeArray);
-      let nodePathsInput = getFlag3(options, keys2, "nodePaths", mustBeArray);
-      let mainFields = getFlag3(options, keys2, "mainFields", mustBeArray);
-      let conditions = getFlag3(options, keys2, "conditions", mustBeArray);
-      let external = getFlag3(options, keys2, "external", mustBeArray);
+      let resolveExtensions = getFlag3(options, keys2, "resolveExtensions", mustBeArrayOfStrings);
+      let nodePathsInput = getFlag3(options, keys2, "nodePaths", mustBeArrayOfStrings);
+      let mainFields = getFlag3(options, keys2, "mainFields", mustBeArrayOfStrings);
+      let conditions = getFlag3(options, keys2, "conditions", mustBeArrayOfStrings);
+      let external = getFlag3(options, keys2, "external", mustBeArrayOfStrings);
       let packages = getFlag3(options, keys2, "packages", mustBeString);
       let alias = getFlag3(options, keys2, "alias", mustBeObject);
       let loader = getFlag3(options, keys2, "loader", mustBeObject);
@@ -7528,7 +7533,7 @@ is not a problem with esbuild. You need to fix your environment instead.
       let entryNames = getFlag3(options, keys2, "entryNames", mustBeString);
       let chunkNames = getFlag3(options, keys2, "chunkNames", mustBeString);
       let assetNames = getFlag3(options, keys2, "assetNames", mustBeString);
-      let inject = getFlag3(options, keys2, "inject", mustBeArray);
+      let inject = getFlag3(options, keys2, "inject", mustBeArrayOfStrings);
       let banner = getFlag3(options, keys2, "banner", mustBeObject);
       let footer = getFlag3(options, keys2, "footer", mustBeObject);
       let entryPoints = getFlag3(options, keys2, "entryPoints", mustBeEntryPoints);
@@ -7550,37 +7555,13 @@ is not a problem with esbuild. You need to fix your environment instead.
       if (outbase) flags.push(`--outbase=${outbase}`);
       if (tsconfig) flags.push(`--tsconfig=${tsconfig}`);
       if (packages) flags.push(`--packages=${packages}`);
-      if (resolveExtensions) {
-        let values = [];
-        for (let value of resolveExtensions) {
-          validateStringValue(value, "resolve extension");
-          if (value.indexOf(",") >= 0) throw new Error(`Invalid resolve extension: ${value}`);
-          values.push(value);
-        }
-        flags.push(`--resolve-extensions=${values.join(",")}`);
-      }
+      if (resolveExtensions) flags.push(`--resolve-extensions=${validateAndJoinStringArray(resolveExtensions, "resolve extension")}`);
       if (publicPath) flags.push(`--public-path=${publicPath}`);
       if (entryNames) flags.push(`--entry-names=${entryNames}`);
       if (chunkNames) flags.push(`--chunk-names=${chunkNames}`);
       if (assetNames) flags.push(`--asset-names=${assetNames}`);
-      if (mainFields) {
-        let values = [];
-        for (let value of mainFields) {
-          validateStringValue(value, "main field");
-          if (value.indexOf(",") >= 0) throw new Error(`Invalid main field: ${value}`);
-          values.push(value);
-        }
-        flags.push(`--main-fields=${values.join(",")}`);
-      }
-      if (conditions) {
-        let values = [];
-        for (let value of conditions) {
-          validateStringValue(value, "condition");
-          if (value.indexOf(",") >= 0) throw new Error(`Invalid condition: ${value}`);
-          values.push(value);
-        }
-        flags.push(`--conditions=${values.join(",")}`);
-      }
+      if (mainFields) flags.push(`--main-fields=${validateAndJoinStringArray(mainFields, "main field")}`);
+      if (conditions) flags.push(`--conditions=${validateAndJoinStringArray(conditions, "condition")}`);
       if (external) for (let name of external) flags.push(`--external:${validateStringValue(name, "external")}`);
       if (alias) {
         for (let old in alias) {
@@ -7777,8 +7758,8 @@ is not a problem with esbuild. You need to fix your environment instead.
         if (isFirstPacket) {
           isFirstPacket = false;
           let binaryVersion = String.fromCharCode(...bytes);
-          if (binaryVersion !== "0.24.2") {
-            throw new Error(`Cannot start service: Host version "${"0.24.2"}" does not match binary version ${quote(binaryVersion)}`);
+          if (binaryVersion !== "0.27.3") {
+            throw new Error(`Cannot start service: Host version "${"0.27.3"}" does not match binary version ${quote(binaryVersion)}`);
           }
           return;
         }
@@ -8120,11 +8101,13 @@ is not a problem with esbuild. You need to fix your environment instead.
             watch: (options2 = {}) => new Promise((resolve44, reject) => {
               if (!streamIn.hasFS) throw new Error(`Cannot use the "watch" API in this environment`);
               const keys2 = {};
+              const delay = getFlag3(options2, keys2, "delay", mustBeInteger);
               checkForInvalidFlags(options2, keys2, `in watch() call`);
               const request22 = {
                 command: "watch",
                 key: buildKey
               };
+              if (delay) request22.delay = delay;
               sendRequest(refs3, request22, (error2) => {
                 if (error2) reject(new Error(error2));
                 else resolve44(void 0);
@@ -8133,12 +8116,13 @@ is not a problem with esbuild. You need to fix your environment instead.
             serve: (options2 = {}) => new Promise((resolve44, reject) => {
               if (!streamIn.hasFS) throw new Error(`Cannot use the "serve" API in this environment`);
               const keys2 = {};
-              const port = getFlag3(options2, keys2, "port", mustBeInteger);
+              const port = getFlag3(options2, keys2, "port", mustBeValidPortNumber);
               const host = getFlag3(options2, keys2, "host", mustBeString);
               const servedir = getFlag3(options2, keys2, "servedir", mustBeString);
               const keyfile = getFlag3(options2, keys2, "keyfile", mustBeString);
               const certfile = getFlag3(options2, keys2, "certfile", mustBeString);
               const fallback2 = getFlag3(options2, keys2, "fallback", mustBeString);
+              const cors = getFlag3(options2, keys2, "cors", mustBeObject);
               const onRequest = getFlag3(options2, keys2, "onRequest", mustBeFunction);
               checkForInvalidFlags(options2, keys2, `in serve() call`);
               const request22 = {
@@ -8152,6 +8136,13 @@ is not a problem with esbuild. You need to fix your environment instead.
               if (keyfile !== void 0) request22.keyfile = keyfile;
               if (certfile !== void 0) request22.certfile = certfile;
               if (fallback2 !== void 0) request22.fallback = fallback2;
+              if (cors) {
+                const corsKeys = {};
+                const origin = getFlag3(cors, corsKeys, "origin", mustBeStringOrArrayOfStrings);
+                checkForInvalidFlags(cors, corsKeys, `on "cors" object`);
+                if (Array.isArray(origin)) request22.corsOrigin = origin;
+                else if (origin !== void 0) request22.corsOrigin = [origin];
+              }
               sendRequest(refs3, request22, (error2, response2) => {
                 if (error2) return reject(new Error(error2));
                 if (onRequest) {
@@ -8287,7 +8278,7 @@ is not a problem with esbuild. You need to fix your environment instead.
               if (filter4 == null) throw new Error(`onResolve() call is missing a filter`);
               let id = nextCallbackID++;
               onResolveCallbacks[id] = { name, callback, note: registeredNote };
-              plugin2.onResolve.push({ id, filter: filter4.source, namespace: namespace || "" });
+              plugin2.onResolve.push({ id, filter: jsRegExpToGoRegExp(filter4), namespace: namespace || "" });
             },
             onLoad(options, callback) {
               let registeredText = `This error came from the "onLoad" callback registered here:`;
@@ -8299,7 +8290,7 @@ is not a problem with esbuild. You need to fix your environment instead.
               if (filter4 == null) throw new Error(`onLoad() call is missing a filter`);
               let id = nextCallbackID++;
               onLoadCallbacks[id] = { name, callback, note: registeredNote };
-              plugin2.onLoad.push({ id, filter: filter4.source, namespace: namespace || "" });
+              plugin2.onLoad.push({ id, filter: jsRegExpToGoRegExp(filter4), namespace: namespace || "" });
             },
             onDispose(callback) {
               onDisposeCallbacks.push(callback);
@@ -8359,8 +8350,8 @@ is not a problem with esbuild. You need to fix your environment instead.
               let pluginData = getFlag3(result, keys2, "pluginData", canBeAnything);
               let errors = getFlag3(result, keys2, "errors", mustBeArray);
               let warnings = getFlag3(result, keys2, "warnings", mustBeArray);
-              let watchFiles = getFlag3(result, keys2, "watchFiles", mustBeArray);
-              let watchDirs = getFlag3(result, keys2, "watchDirs", mustBeArray);
+              let watchFiles = getFlag3(result, keys2, "watchFiles", mustBeArrayOfStrings);
+              let watchDirs = getFlag3(result, keys2, "watchDirs", mustBeArrayOfStrings);
               checkForInvalidFlags(result, keys2, `from onResolve() callback in plugin ${quote(name)}`);
               response.id = id2;
               if (pluginName != null) response.pluginName = pluginName;
@@ -8405,8 +8396,8 @@ is not a problem with esbuild. You need to fix your environment instead.
               let loader = getFlag3(result, keys2, "loader", mustBeString);
               let errors = getFlag3(result, keys2, "errors", mustBeArray);
               let warnings = getFlag3(result, keys2, "warnings", mustBeArray);
-              let watchFiles = getFlag3(result, keys2, "watchFiles", mustBeArray);
-              let watchDirs = getFlag3(result, keys2, "watchDirs", mustBeArray);
+              let watchFiles = getFlag3(result, keys2, "watchFiles", mustBeArrayOfStrings);
+              let watchDirs = getFlag3(result, keys2, "watchDirs", mustBeArrayOfStrings);
               checkForInvalidFlags(result, keys2, `from onLoad() callback in plugin ${quote(name)}`);
               response.id = id2;
               if (pluginName != null) response.pluginName = pluginName;
@@ -8710,6 +8701,11 @@ ${file}:${line}:${column}: ERROR: ${pluginText}${e.text}`;
         }
       };
     }
+    function jsRegExpToGoRegExp(regexp) {
+      let result = regexp.source;
+      if (regexp.flags) result = `(?${regexp.flags})${result}`;
+      return result;
+    }
     var fs8 = __require("fs");
     var os11 = __require("os");
     var path14 = __require("path");
@@ -8746,7 +8742,8 @@ ${file}:${line}:${column}: ERROR: ${pluginText}${e.text}`;
     };
     var knownWebAssemblyFallbackPackages = {
       "android arm LE": "@esbuild/android-arm",
-      "android x64 LE": "@esbuild/android-x64"
+      "android x64 LE": "@esbuild/android-x64",
+      "openharmony arm64 LE": "@esbuild/openharmony-arm64"
     };
     function pkgAndSubpathForCurrentPlatform() {
       let pkg;
@@ -8886,7 +8883,7 @@ for your current platform.`);
             "node_modules",
             ".cache",
             "esbuild",
-            `pnpapi-${pkg.replace("/", "-")}-${"0.24.2"}-${path14.basename(subpath)}`
+            `pnpapi-${pkg.replace("/", "-")}-${"0.27.3"}-${path14.basename(subpath)}`
           );
           if (!fs8.existsSync(binTargetPath)) {
             fs8.mkdirSync(path14.dirname(binTargetPath), { recursive: true });
@@ -8919,7 +8916,7 @@ for your current platform.`);
       }
     }
     var _a7;
-    var isInternalWorkerThread = ((_a7 = worker_threads == null ? void 0 : worker_threads.workerData) == null ? void 0 : _a7.esbuildVersion) === "0.24.2";
+    var isInternalWorkerThread = ((_a7 = worker_threads == null ? void 0 : worker_threads.workerData) == null ? void 0 : _a7.esbuildVersion) === "0.27.3";
     var esbuildCommandAndArgs = () => {
       if ((!ESBUILD_BINARY_PATH || false) && (path23.basename(__filename) !== "main.js" || path23.basename(__dirname) !== "lib")) {
         throw new Error(
@@ -8986,7 +8983,7 @@ More information: The file containing the code for esbuild's JavaScript API (${_
         }
       }
     };
-    var version = "0.24.2";
+    var version = "0.27.3";
     var build = (options) => ensureServiceIsRunning().build(options);
     var context3 = (buildOptions) => ensureServiceIsRunning().context(buildOptions);
     var transform = (input3, options) => ensureServiceIsRunning().transform(input3, options);
@@ -9089,7 +9086,7 @@ More information: The file containing the code for esbuild's JavaScript API (${_
     var ensureServiceIsRunning = () => {
       if (longLivedService) return longLivedService;
       let [command3, args] = esbuildCommandAndArgs();
-      let child = child_process.spawn(command3, args.concat(`--service=${"0.24.2"}`, "--ping"), {
+      let child = child_process.spawn(command3, args.concat(`--service=${"0.27.3"}`, "--ping"), {
         windowsHide: true,
         stdio: ["pipe", "pipe", "inherit"],
         cwd: defaultWD
@@ -9193,7 +9190,7 @@ More information: The file containing the code for esbuild's JavaScript API (${_
         esbuild: node_exports
       });
       callback(service);
-      let stdout = child_process.execFileSync(command3, args.concat(`--service=${"0.24.2"}`), {
+      let stdout = child_process.execFileSync(command3, args.concat(`--service=${"0.27.3"}`), {
         cwd: defaultWD,
         windowsHide: true,
         input: stdin,
@@ -9213,7 +9210,7 @@ More information: The file containing the code for esbuild's JavaScript API (${_
     var startWorkerThreadService = (worker_threads2) => {
       let { port1: mainPort, port2: workerPort } = new worker_threads2.MessageChannel();
       let worker = new worker_threads2.Worker(__filename, {
-        workerData: { workerPort, defaultWD, esbuildVersion: "0.24.2" },
+        workerData: { workerPort, defaultWD, esbuildVersion: "0.27.3" },
         transferList: [workerPort],
         // From node's documentation: https://nodejs.org/api/worker_threads.html
         //
@@ -450501,6 +450498,70 @@ function buildEmptyRootHtml(opts) {
 </html>
 `;
 }
+function buildDesignMd(opts) {
+  const { name, style } = opts;
+  const intro = style ? `Visual identity for **${name}**, scaffolded from the **${style.name}** style (after ${style.designer}). Customise freely \u2014 this file is the single source of truth for every scene's palette, typography, and motion.` : `Visual identity for **${name}**. Fill the sections below before authoring any scene HTML or generating any backdrop. Pick a named style with \`vibe scene styles\` if you want a credible starting point.`;
+  const moodLine = style ? `**Mood:** ${style.mood} \xB7 **Best for:** ${style.bestFor}` : `**Mood:** _(one line \u2014 what should the viewer FEEL?)_`;
+  const palette = style ? `${style.palette.map((c) => `- \`${c}\``).join("\n")}
+
+${style.paletteNotes}` : `- _hex_ \u2014 primary
+- _hex_ \u2014 accent
+
+_2\u20133 colours max. Declare explicit hex values; never name colours abstractly._`;
+  const typography = style ? style.typography : `_One family, two weights. State the role of each (headline / label / body)._`;
+  const composition = style ? style.composition : `_Grid? Centered? Layered? How does negative space behave?_`;
+  const motion = style ? `${style.motion}
+
+**GSAP signature:** ${style.gsapSignature}` : `_How fast? Snappy or fluid? Overshoot or precision?_
+
+**GSAP signature:** _e.g. \`expo.out\`, \`sine.inOut\`, \`back.out(1.8)\`_`;
+  const transition = style ? style.transition : `_Which Hyperframes shader matches the energy? (Cinematic Zoom, Cross-Warp Morph, Glitch, Domain Warp, \u2026)_`;
+  const avoid = style ? style.avoid.map((a) => `- ${a}`).join("\n") : `- _anti-pattern 1_
+- _anti-pattern 2_
+- _anti-pattern 3_`;
+  return `# ${name} \u2014 Design
+
+> **Hard-gate.** This file defines the visual identity of every scene.
+> Author it before generating any HTML, backdrop image, or motion.
+> The Hyperframes \`hyperframes\` skill enforces this: scenes that
+> contradict DESIGN.md are rejected.
+
+${intro}
+
+## Style
+
+${moodLine}
+
+## Palette
+
+${palette}
+
+## Typography
+
+${typography}
+
+## Composition
+
+${composition}
+
+## Motion
+
+${motion}
+
+## Transition
+
+${transition}
+
+## What NOT to do
+
+${avoid}
+
+---
+
+_Browse other named styles: \`vibe scene styles\`_
+${style ? `_This file was seeded by \`vibe scene init --visual-style "${style.name}"\`._` : `_Seed this file from a named style: \`vibe scene init <dir> --visual-style "<name>"\`._`}
+`;
+}
 function buildProjectClaudeMd(name) {
   return `# ${name} \u2014 Scene Authoring Project
 
@@ -450508,6 +450569,16 @@ This project is **bilingual**: it works with both VibeFrame (\`vibe\`) and
 HeyGen Hyperframes (\`hyperframes\`). You can run either CLI inside this
 directory.
 
+## Visual identity hard-gate
+
+**Author \`DESIGN.md\` before any scene HTML.** It defines palette,
+typography, motion, and transition rules. Both the agent-driven path and
+the fallback emit reference it; scenes that contradict DESIGN.md are
+rejected by the Hyperframes \`hyperframes\` skill.
+
+Browse named styles: \`vibe scene styles\`. Re-seed from one with
+\`vibe scene init . --visual-style "Swiss Pulse"\` (idempotent).
+
 ## Skills \u2014 USE THESE FIRST
 
 **Always invoke the relevant skill before authoring scenes.** Skills encode
@@ -450516,14 +450587,23 @@ semantics, VibeFrame pipeline conventions) that are NOT in generic web docs.
 
 | Skill             | Command          | When to use                                                                           |
 | ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
-| **vibe-scene**    | \`/vibe-scene\`    | Authoring / editing per-scene HTML in this project \u2014 preferred                        |
-| **hyperframes**   | \`/hyperframes\`   | Fallback: direct HF authoring (install via \`npx skills add heygen-com/hyperframes\`) |
+| **hyperframes**   | \`/hyperframes\`   | Cinematic-quality composition \u2014 DESIGN.md hard-gate, named styles, motion principles  |
+| **vibe-scene**    | \`/vibe-scene\`    | VibeFrame's authoring loop, AI assets, lint feedback, pipeline integration            |
 | **gsap**          | \`/gsap\`          | GSAP tweens, timelines, easing                                                        |
 
-If the skill is not available, follow the **Key Rules** below.
+Install the Hyperframes skills once per machine:
+
+\`\`\`bash
+npx skills add heygen-com/hyperframes
+\`\`\`
+
+Restart your agent session (or reload the skill list) after installing.
+If skills aren't available, follow the **Key Rules** below \u2014 they cover
+the framework-level minimum, not the cinematic craft layer.
 
 ## Project structure
 
+- \`DESIGN.md\` \u2014 visual identity contract (palette, type, motion, transitions)
 - \`index.html\` \u2014 root composition (timeline)
 - \`compositions/scene-*.html\` \u2014 per-scene HTML authored by you or the agent
 - \`assets/\` \u2014 shared media (narration audio, images, video)
@@ -450641,6 +450721,17 @@ async function scaffoldSceneProject(opts) {
     await writeFile10(claudePath, buildProjectClaudeMd(name), "utf-8");
     created.push(claudePath);
   }
+  const designPath = resolve20(dir, "DESIGN.md");
+  if (await pathExists(designPath)) {
+    skipped.push(designPath);
+  } else {
+    await writeFile10(
+      designPath,
+      buildDesignMd({ name, style: opts.visualStyle }),
+      "utf-8"
+    );
+    created.push(designPath);
+  }
   const gitignorePath = resolve20(dir, ".gitignore");
   if (await pathExists(gitignorePath)) {
     skipped.push(gitignorePath);
@@ -450689,6 +450780,52 @@ function buildTranscriptTweens(transcript, targetSelector) {
     return `tl.fromTo('${sel}', { opacity: 0, y: 10 }, { opacity: 1, y: 0, duration: 0.18, ease: 'power2.out' }, ${start});`;
   }).join("\n      ");
 }
+function crossfadeTweens(scope, dur) {
+  return `tl.from('${scope}', { opacity: 0, duration: ${SCENE_OVERLAP_SECONDS}, ease: 'power2.out' }, 0);
+      tl.to('${scope}', { opacity: 0, duration: ${SCENE_OVERLAP_SECONDS}, ease: 'power2.in' }, ${(dur - SCENE_OVERLAP_SECONDS).toFixed(2)});`;
+}
+function fitFontSize(text, baseMaxPx, minPx, comfortableChars) {
+  const charCount = text.length;
+  if (charCount <= comfortableChars) return baseMaxPx;
+  const ratio = comfortableChars / charCount;
+  return Math.max(minPx, Math.round(baseMaxPx * ratio));
+}
+function fitKineticFontSize(words) {
+  const totalChars = words.join(" ").length;
+  if (totalChars <= 18) return 180;
+  if (totalChars <= 26) return 140;
+  if (totalChars <= 38) return 110;
+  if (totalChars <= 54) return 90;
+  return 72;
+}
+function kenBurnsTween(scope, dur, endScale = 1.08) {
+  return `tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: ${endScale}, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);`;
+}
+function idleHeroPulse(scope, selector, idleStart, dur) {
+  const cycleDur = 1.5;
+  const idleEnd = dur - SCENE_OVERLAP_SECONDS;
+  const window3 = idleEnd - idleStart;
+  if (window3 < cycleDur) return "";
+  const plays = Math.max(1, Math.floor(window3 / cycleDur));
+  const repeat = plays - 1;
+  return `tl.to('${scope} ${selector}', { scale: 1.04, y: -8, duration: ${cycleDur}, yoyo: true, repeat: ${repeat}, ease: 'sine.inOut' }, ${idleStart.toFixed(2)});`;
+}
+function kineticWordBobs(scope, wordCount, idleStart, dur) {
+  const cycleDur = 1.8;
+  const idleEnd = dur - SCENE_OVERLAP_SECONDS;
+  const window3 = idleEnd - idleStart;
+  if (window3 < cycleDur) return "";
+  const plays = Math.max(1, Math.floor(window3 / cycleDur));
+  const repeat = plays - 1;
+  const lines = [];
+  for (let i = 0; i < wordCount; i++) {
+    const start = (idleStart + i * 0.18).toFixed(2);
+    lines.push(
+      `tl.to('${scope} #w-${i}', { y: -12, duration: ${cycleDur}, yoyo: true, repeat: ${repeat}, ease: 'sine.inOut' }, ${start});`
+    );
+  }
+  return lines.join("\n      ");
+}
 function buildPreset(input3) {
   const id = input3.id;
   const scope = `[data-composition-id="${id}"]`;
@@ -450725,7 +450862,8 @@ function buildPreset(input3) {
       const captionInner = useWordSync ? renderTranscriptSpans(transcript) : esc(captionText);
       const wordCss = useWordSync ? `
       ${scope} .caption .word { display: inline-block; opacity: 0; }` : "";
-      const timeline = useWordSync ? buildTranscriptTweens(transcript, `${scope} .caption .word`) : `tl.from('${scope} .caption', { opacity: 0, y: 28, duration: 0.45, ease: 'power3.out' }, 0.05);`;
+      const captionFontPx = fitFontSize(captionText, 56, 28, 60);
+      const captionTween = useWordSync ? buildTranscriptTweens(transcript, `${scope} .caption .word`) : `tl.from('${scope} .caption', { opacity: 0, y: 28, duration: 0.45, ease: 'power3.out' }, 0.05);`;
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -450733,21 +450871,27 @@ function buildPreset(input3) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .caption {
         position: absolute;
         left: 8%; right: 8%; bottom: 12%;
         text-align: center;
-        font-size: 56px;
+        font-size: ${captionFontPx}px;
         font-weight: 700;
         line-height: 1.2;
+        overflow-wrap: break-word;
         text-shadow: 0 4px 20px rgba(0,0,0,0.65);
       }${wordCss}`,
         body: `${backdropMarkup}
     <div class="caption" id="caption">${captionInner}</div>`,
-        timeline
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      ${captionTween}
+      ${idleHeroPulse(scope, "#caption", 1, dur)}`
       };
     }
     case "announcement": {
+      const fontSize = fitFontSize(headline, 160, 72, 22);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -450755,6 +450899,7 @@ function buildPreset(input3) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .announce {
         position: absolute; inset: 0;
         display: flex; align-items: center; justify-content: center;
@@ -450763,10 +450908,11 @@ function buildPreset(input3) {
       }
       ${scope} .announce h1 {
         margin: 0;
-        font-size: 160px;
+        font-size: ${fontSize}px;
         font-weight: 900;
         letter-spacing: -4px;
-        line-height: 1;
+        line-height: 1.05;
+        overflow-wrap: break-word;
         background: linear-gradient(90deg, #8e2de2, #00c9ff);
         -webkit-background-clip: text; background-clip: text; color: transparent;
         text-shadow: 0 8px 40px rgba(142,45,226,0.35);
@@ -450776,8 +450922,12 @@ function buildPreset(input3) {
         // Faster, snappier entrance and no tail fade-out — see the
         // matching note in the `simple` case above. The headline stays
         // on screen until the producer cuts to the next clip; the next
-        // scene's own fade-in handles the visual transition.
-        timeline: `tl.from('${scope} #headline', { opacity: 0, scale: 0.92, duration: 0.55, ease: 'power3.out' }, 0.05);`
+        // scene's own fade-in handles the visual transition. Backdrop
+        // Ken-Burns fills what used to be 80% dead static frame.
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      tl.from('${scope} #headline', { opacity: 0, scale: 0.92, duration: 0.55, ease: 'power3.out' }, 0.05);
+      ${idleHeroPulse(scope, "#headline", 1, dur)}`
       };
     }
     case "explainer": {
@@ -450789,6 +450939,7 @@ function buildPreset(input3) {
       const wordCss = useWordSync ? `
       ${scope} #subtitle .word { display: inline-block; opacity: 0; }` : "";
       const subtitleTween = useWordSync ? buildTranscriptTweens(transcript, `${scope} #subtitle .word`) : sub ? `tl.from('${scope} #subtitle', { opacity: 0, y: 30, duration: 0.55, ease: 'power3.out' }, 0.55);` : "";
+      const titleFontPx = fitFontSize(headline, 110, 56, 30);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -450796,6 +450947,7 @@ function buildPreset(input3) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .stage {
         position: absolute; inset: 0;
         display: flex; flex-direction: column; justify-content: center;
@@ -450806,11 +450958,13 @@ function buildPreset(input3) {
         color: #00c9ff; font-weight: 600;
       }
       ${scope} .title {
-        font-size: 110px; font-weight: 800; letter-spacing: -2px;
+        font-size: ${titleFontPx}px; font-weight: 800; letter-spacing: -2px;
         line-height: 1.05; margin: 0;
+        overflow-wrap: break-word;
       }
       ${scope} .subtitle {
         font-size: 38px; font-weight: 300; color: #c0c0d0; max-width: 80%;
+        overflow-wrap: break-word;
       }${wordCss}`,
         body: `${backdropMarkup}
     <div class="stage">
@@ -450818,9 +450972,12 @@ function buildPreset(input3) {
       <h1 class="title" id="title">${esc(headline)}</h1>${sub ? `
       <div class="subtitle" id="subtitle">${subtitleInner}</div>` : ""}
     </div>`,
-        timeline: `tl.from('${scope} #kicker', { opacity: 0, y: 16, duration: 0.4, ease: 'power2.out' }, 0.1);
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      tl.from('${scope} #kicker', { opacity: 0, y: 16, duration: 0.4, ease: 'power2.out' }, 0.1);
       tl.from('${scope} #title', { opacity: 0, y: 60, duration: 0.7, ease: 'power3.out' }, 0.25);
-      ${subtitleTween}`
+      ${subtitleTween}
+      ${idleHeroPulse(scope, "#title", 1.2, dur)}`
       };
     }
     case "kinetic-type": {
@@ -450836,6 +450993,9 @@ function buildPreset(input3) {
         const start = (0.05 + i * stagger).toFixed(2);
         return `tl.from('${scope} #w-${i}', { opacity: 0, y: 80, scale: 0.8, duration: 0.45, ease: 'back.out(1.8)' }, ${start});`;
       }).join("\n      ");
+      const kineticFontPx = fitKineticFontSize(words);
+      const lastWordEntryEnd = useWordSync ? Math.max(...transcript.map((w) => w.end + 0.2)) : 0.05 + (words.length - 1) * stagger + 0.45 + 0.2;
+      const idleStart = Math.max(1, Number(lastWordEntryEnd.toFixed(2)));
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -450843,21 +451003,28 @@ function buildPreset(input3) {
         color: #fff; overflow: hidden; background: #000;
       }
       ${backdrop}
+      ${scope} .backdrop { transform-origin: center; }
       ${scope} .kinetic {
         position: absolute; inset: 0;
         display: flex; align-items: center; justify-content: center;
+        flex-wrap: wrap; gap: 8px 16px;
         text-align: center; padding: 0 6%;
-        font-size: 180px; font-weight: 900; letter-spacing: -6px;
+        font-size: ${kineticFontPx}px; font-weight: 900; letter-spacing: -6px;
         line-height: 1; text-shadow: 0 6px 30px rgba(0,0,0,0.6);
+        overflow-wrap: break-word;
       }
       ${scope} .kinetic .word { display: inline-block; margin: 0 12px; }`,
         body: `${backdropMarkup}
     <div class="kinetic">${wordSpans}</div>`,
-        timeline: tweens
+        timeline: `${crossfadeTweens(scope, dur)}
+      ${kenBurnsTween(scope, dur)}
+      ${tweens}
+      ${kineticWordBobs(scope, words.length, idleStart, dur)}`
       };
     }
     case "product-shot": {
       const label = kicker || humanise(id);
+      const headlineFontPx = fitFontSize(headline, 72, 40, 50);
       return {
         css: `${scope} {
         position: absolute; inset: 0; width: 100%; height: 100%;
@@ -450875,22 +451042,26 @@ function buildPreset(input3) {
       }
       ${scope} .product-headline {
         position: absolute; left: 8%; right: 8%; bottom: 14%;
-        font-size: 72px; font-weight: 800; letter-spacing: -1px;
-        line-height: 1.1; text-shadow: 0 4px 20px rgba(0,0,0,0.7);
+        font-size: ${headlineFontPx}px; font-weight: 800; letter-spacing: -1px;
+        line-height: 1.1; overflow-wrap: break-word;
+        text-shadow: 0 4px 20px rgba(0,0,0,0.7);
       }${subhead ? `
       ${scope} .product-sub {
         position: absolute; left: 8%; right: 8%; bottom: 8%;
         font-size: 28px; font-weight: 400; color: #d0d0e0;
+        overflow-wrap: break-word;
         text-shadow: 0 2px 10px rgba(0,0,0,0.7);
       }` : ""}`,
         body: `${backdropMarkup}
     <div class="label" id="label">${esc(label)}</div>
     <div class="product-headline" id="headline">${esc(headline)}</div>${subhead ? `
     <div class="product-sub" id="subhead">${esc(subhead)}</div>` : ""}`,
-        timeline: `tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: 1.08, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);
+        timeline: `${crossfadeTweens(scope, dur)}
+      tl.fromTo('${scope} .backdrop', { scale: 1.0 }, { scale: 1.12, duration: ${dur.toFixed(2)}, ease: 'none' }, 0);
       tl.from('${scope} #label', { opacity: 0, x: -30, duration: 0.5, ease: 'power3.out' }, 0.2);
       tl.from('${scope} #headline', { opacity: 0, y: 40, duration: 0.6, ease: 'power3.out' }, 0.4);${subhead ? `
-      tl.from('${scope} #subhead', { opacity: 0, y: 20, duration: 0.5, ease: 'power3.out' }, 0.65);` : ""}`
+      tl.from('${scope} #subhead', { opacity: 0, y: 20, duration: 0.5, ease: 'power3.out' }, 0.65);` : ""}
+      ${idleHeroPulse(scope, "#headline", 1.2, dur)}`
       };
     }
   }
@@ -450936,7 +451107,7 @@ ${audioBlock}
 </template>
 `;
 }
-function nextSceneStart(rootHtml) {
+function nextSceneStart(rootHtml, overlap = 0) {
   const clipRegex = /<div\s+class="clip"[^>]*?\sdata-start="([\d.]+)"[^>]*?\sdata-duration="([\d.]+)"/gi;
   let maxEnd = 0;
   let match2;
@@ -450944,14 +451115,15 @@ function nextSceneStart(rootHtml) {
     const end = parseFloat(match2[1]) + parseFloat(match2[2]);
     if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
   }
-  return maxEnd;
+  return Math.max(0, maxEnd - overlap);
 }
 function buildClipReference(opts) {
   const start = Number(opts.start.toFixed(3));
   const duration = Number(opts.duration.toFixed(3));
   const track = opts.trackIndex ?? 1;
   const src = opts.src ?? `compositions/scene-${opts.id}.html`;
-  return `<div class="clip" data-composition-id="${esc(opts.id)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}"></div>`;
+  const zIndex = Math.max(1, 1e6 - Math.floor(start * 1e3));
+  return `<div class="clip" data-composition-id="${esc(opts.id)}" data-composition-src="${esc(src)}" data-start="${start}" data-duration="${duration}" data-track-index="${track}" style="z-index: ${zIndex};"></div>`;
 }
 function insertClipIntoRoot(rootHtml, clip) {
   const clipDiv = buildClipReference(clip);
@@ -450984,7 +451156,7 @@ function readRootDims(rootHtml) {
   if (!widthMatch || !heightMatch) return null;
   return { width: parseInt(widthMatch[1], 10), height: parseInt(heightMatch[1], 10) };
 }
-var SCENE_PRESETS, GSAP_CDN;
+var SCENE_PRESETS, GSAP_CDN, SCENE_OVERLAP_SECONDS;
 var init_scene_html_emit = __esm({
   "../cli/src/commands/_shared/scene-html-emit.ts"() {
     "use strict";
@@ -450996,6 +451168,7 @@ var init_scene_html_emit = __esm({
       "product-shot"
     ];
     GSAP_CDN = "https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js";
+    SCENE_OVERLAP_SECONDS = 0.4;
   }
 });
 
@@ -451167,7 +451340,12 @@ async function executeSegmentsToScenes(opts) {
   const dims = aspectToDims(aspect);
   const preset = opts.scenePreset ?? DEFAULT_PRESET;
   const projectName = opts.projectName ?? basename8(outputDir);
-  const totalDuration = opts.segments.reduce((sum, s) => sum + (s.duration || 0), 0) || 10;
+  const totalDuration = (() => {
+    const sum = opts.segments.reduce((acc, s) => acc + (s.duration || 0), 0);
+    if (sum <= 0) return 10;
+    const joins = Math.max(0, opts.segments.length - 1);
+    return Math.max(0.1, sum - joins * SCENE_OVERLAP_SECONDS);
+  })();
   const baseError = (error) => ({
     success: false,
     outputDir,
@@ -451240,9 +451418,10 @@ async function executeSegmentsToScenes(opts) {
       id,
       start: clipStart,
       duration,
+      trackIndex: i % 2 + 1,
       src: `compositions/${id}.html`
     });
-    clipStart += duration;
+    clipStart += duration - SCENE_OVERLAP_SECONDS;
   }
   await writeFile12(rootAbs, rootHtml, "utf-8");
   let lintResult;
@@ -464231,6 +464410,176 @@ function parseTtsProviderName(value) {
 
 // ../cli/src/commands/scene.ts
 init_scene_project();
+
+// ../cli/src/commands/_shared/visual-styles.ts
+var STYLES = [
+  {
+    name: "Swiss Pulse",
+    slug: "swiss-pulse",
+    designer: "Josef M\xFCller-Brockmann",
+    mood: "Clinical, precise",
+    bestFor: "SaaS dashboards, developer tools, APIs, metrics",
+    palette: ["#1a1a1a", "#ffffff", "#0066FF"],
+    paletteNotes: "Black, white, ONE accent \u2014 electric blue (#0066FF) or amber (#FFB300). Never both accents at once.",
+    typography: "Helvetica or Inter Bold for headlines, Regular for labels. Numbers dominate at 80\u2013120px.",
+    composition: "Grid-locked. Every element snaps to an invisible 12-column grid. Hard cuts only \u2014 no decorative transitions.",
+    motion: "Animated counters count up from 0. Entries are fast and snap into place. Nothing floats.",
+    transition: "Cinematic Zoom or SDF Iris (precise, geometric)",
+    gsapSignature: "expo.out, power4.out \u2014 fast arrivals, hard stops",
+    avoid: [
+      "Decorative transitions (fades, dissolves) \u2014 use hard cuts",
+      "Two accent colours competing in one frame",
+      "Off-grid placement or floating elements"
+    ]
+  },
+  {
+    name: "Velvet Standard",
+    slug: "velvet-standard",
+    designer: "Massimo Vignelli",
+    mood: "Premium, timeless",
+    bestFor: "Luxury products, enterprise software, keynotes, investor decks",
+    palette: ["#000000", "#ffffff", "#1a237e"],
+    paletteNotes: "Black, white, ONE rich accent \u2014 deep navy (#1a237e) or gold (#c9a84c).",
+    typography: "Thin sans-serif, ALL CAPS, wide letter-spacing (0.15em+). Sequential reveals only.",
+    composition: "Generous negative space. Symmetrical, centered, architectural precision. Nothing busy.",
+    motion: "Slow, deliberate. Sequential reveals with long holds. No frantic motion.",
+    transition: "Cross-Warp Morph (elegant, organic flow between scenes)",
+    gsapSignature: "sine.inOut, power1 \u2014 nothing snaps, everything glides",
+    avoid: [
+      "Tight letter-spacing \u2014 kills the premium register",
+      "Bouncy or elastic easings \u2014 too playful",
+      "Multiple elements arriving at once \u2014 break sequence"
+    ]
+  },
+  {
+    name: "Deconstructed",
+    slug: "deconstructed",
+    designer: "Neville Brody",
+    mood: "Industrial, raw",
+    bestFor: "Tech news, developer launches, security products, punk-energy reveals",
+    palette: ["#1a1a1a", "#D4501E", "#f0f0f0"],
+    paletteNotes: "Dark grey (#1a1a1a), rust orange (#D4501E), raw white (#f0f0f0).",
+    typography: "Type at angles, overlapping edges, escaping frames. Bold industrial weight.",
+    composition: "Gritty textures \u2014 scan-line effects, glitch artifacts baked into the design.",
+    motion: "Text SLAMS and SHATTERS. Letters scramble then snap to final position.",
+    transition: "Glitch shader or Whip Pan (breaks the rules, feels aggressive)",
+    gsapSignature: "back.out(2.5), steps(8), elastic.out(1.2, 0.4) \u2014 intentional irregularity",
+    avoid: [
+      "Polished, centered compositions \u2014 must feel raw",
+      "Smooth fades \u2014 use glitch / scramble entries",
+      "Soft easings \u2014 every motion lands hard"
+    ]
+  },
+  {
+    name: "Maximalist Type",
+    slug: "maximalist-type",
+    designer: "Paula Scher",
+    mood: "Loud, kinetic",
+    bestFor: "Big product launches, milestone announcements, high-energy hype videos",
+    palette: ["#E63946", "#FFD60A", "#000000", "#ffffff"],
+    paletteNotes: "Bold saturated: red (#E63946), yellow (#FFD60A), black, white \u2014 maximum contrast.",
+    typography: "Text IS the visual. Overlapping type layers at different scales and angles, filling 50\u201380% of frame.",
+    composition: "Text layered OVER footage \u2014 never empty backgrounds. 2\u20133 second rapid-fire scenes.",
+    motion: "Everything is kinetic \u2014 slamming, sliding, scaling. No static moments.",
+    transition: "Ridged Burn (explosive, dramatic, impossible to ignore)",
+    gsapSignature: "expo.out, back.out(1.8) \u2014 fast arrivals, hard stops",
+    avoid: [
+      "Static moments \u2014 every frame must move",
+      "Empty backgrounds \u2014 text and footage must layer",
+      "Single typeface at a single size \u2014 must be layered"
+    ]
+  },
+  {
+    name: "Data Drift",
+    slug: "data-drift",
+    designer: "Refik Anadol",
+    mood: "Futuristic, immersive",
+    bestFor: "AI products, ML platforms, data companies, speculative tech",
+    palette: ["#0a0a0a", "#7c3aed", "#06b6d4"],
+    paletteNotes: "Iridescent \u2014 deep black (#0a0a0a), electric purple (#7c3aed), cyan (#06b6d4).",
+    typography: "Thin futuristic sans-serif \u2014 floating, weightless, minimal text.",
+    composition: "Fluid morphing compositions. Extreme scale shifts (micro \u2192 macro). Particles coalesce into numbers.",
+    motion: "Light traces data paths through the frame. Smooth, continuous, organic \u2014 nothing hard.",
+    transition: "Gravitational Lens or Domain Warp (otherworldly distortion)",
+    gsapSignature: "sine.inOut, power2.out \u2014 smooth, continuous, organic",
+    avoid: [
+      "Hard cuts \u2014 break the immersion",
+      "Heavy/bold typography \u2014 too grounded",
+      "Static compositions \u2014 must feel like flow"
+    ]
+  },
+  {
+    name: "Soft Signal",
+    slug: "soft-signal",
+    designer: "Stefan Sagmeister",
+    mood: "Intimate, warm",
+    bestFor: "Wellness brands, personal stories, lifestyle products, human-centered apps",
+    palette: ["#F5A623", "#FFF8EC", "#C4A3A3", "#8FAF8C"],
+    paletteNotes: "Warm amber (#F5A623), cream (#FFF8EC), dusty rose (#C4A3A3), sage green (#8FAF8C).",
+    typography: "Handwritten-style or humanist serif fonts. Personal, lowercase, delicate.",
+    composition: "Close-up framing feel \u2014 single element fills the frame. Nothing feels corporate.",
+    motion: "Slow drifts and floats, never snaps. Soft organic motion throughout.",
+    transition: "Thermal Distortion (warm, flowing, like heat shimmer)",
+    gsapSignature: "sine.inOut, power1.inOut \u2014 everything breathes",
+    avoid: [
+      "Sharp geometric layouts \u2014 break the warmth",
+      "Hard easings or snaps \u2014 too clinical",
+      "Cool tones (blue/green-blue) without warm balance"
+    ]
+  },
+  {
+    name: "Folk Frequency",
+    slug: "folk-frequency",
+    designer: "Eduardo Terrazas",
+    mood: "Cultural, vivid",
+    bestFor: "Consumer apps, food platforms, community products, festive launches",
+    palette: ["#FF1493", "#0047AB", "#FFE000", "#009B77"],
+    paletteNotes: "Vivid folk: hot pink (#FF1493), cobalt blue (#0047AB), sun yellow (#FFE000), emerald (#009B77).",
+    typography: "Bold warm rounded type. Every frame feels handcrafted.",
+    composition: "Pattern and repetition \u2014 folk art rhythm and density. Layered compositions with rich visual texture.",
+    motion: "Colorful motion \u2014 elements bounce, pop, and spin into place with joy.",
+    transition: "Swirl Vortex or Ripple Waves (hypnotic, celebratory)",
+    gsapSignature: "back.out(1.6), elastic.out(1, 0.5) \u2014 overshoots feel intentional",
+    avoid: [
+      "Muted or monochrome palettes \u2014 kill the celebration",
+      "Pure flat / minimal compositions \u2014 must feel layered",
+      "Linear easings \u2014 motion should feel joyful"
+    ]
+  },
+  {
+    name: "Shadow Cut",
+    slug: "shadow-cut",
+    designer: "Hans Hillmann",
+    mood: "Dark, cinematic",
+    bestFor: "Security products, dramatic reveals, investigative content, intense launches",
+    palette: ["#0a0a0a", "#3a3a3a", "#ffffff", "#C1121F"],
+    paletteNotes: "Near-monochrome \u2014 deep blacks (#0a0a0a), cold greys (#3a3a3a), stark white + ONE accent (blood red #C1121F or toxic green #39FF14).",
+    typography: "Sharp angular text like film noir title cards. Heavy contrast, no softness.",
+    composition: "Heavy shadow \u2014 elements emerge from darkness. The reveal IS the narrative.",
+    motion: "Slow creeping push-ins, dramatic scale reveals. Silence before the hit matters.",
+    transition: "Domain Warp (dissolves reality before revealing the next scene)",
+    gsapSignature: "power4.in for exits, power3.out for dramatic reveals \u2014 pause before the hit",
+    avoid: [
+      "Bright or saturated palettes \u2014 kill the cinematic mood",
+      "Bouncy easings \u2014 break the tension",
+      "Quick cuts \u2014 let the reveal breathe"
+    ]
+  }
+];
+function listVisualStyles() {
+  return STYLES;
+}
+function getVisualStyle(query2) {
+  const q = query2.trim().toLowerCase();
+  return STYLES.find(
+    (s) => s.name.toLowerCase() === q || s.slug === q
+  );
+}
+function visualStyleNames() {
+  return STYLES.map((s) => `"${s.name}"`).join(", ");
+}
+
+// ../cli/src/commands/scene.ts
 init_scene_html_emit();
 init_scene_lint();
 init_output();
@@ -464256,6 +464605,18 @@ function validatePreset(value) {
   }
   return value;
 }
+function validateVisualStyle(value) {
+  const found = getVisualStyle(value);
+  if (!found) {
+    exitWithError(
+      usageError(
+        `Unknown visual style: ${value}`,
+        `Valid: ${visualStyleNames()}. Browse details with \`vibe scene styles\`.`
+      )
+    );
+  }
+  return found;
+}
 var sceneCommand = new Command("scene").description("Author and render per-scene HTML compositions (Hyperframes backend)").addHelpText("after", `
 Examples:
   $ vibe scene init my-video                              # Scaffold a new project
@@ -464273,21 +464634,28 @@ Examples:
 
 A scene project is bilingual: it works with both \`vibe\` and \`npx hyperframes\`.
 Run 'vibe schema scene.<command>' for structured parameter info.`);
-sceneCommand.command("init").description("Scaffold a new scene project (or safely augment an existing Hyperframes project)").argument("<dir>", "Project directory (created if it doesn't exist)").option("-n, --name <name>", "Project name (defaults to directory basename)").option("-r, --ratio <ratio>", "Aspect ratio: 16:9, 9:16, 1:1, 4:5", "16:9").option("-d, --duration <sec>", "Default root composition duration (seconds)", "10").option("--dry-run", "Preview parameters without writing files").action(async (dir, options) => {
+sceneCommand.command("init").description("Scaffold a new scene project (or safely augment an existing Hyperframes project)").argument("<dir>", "Project directory (created if it doesn't exist)").option("-n, --name <name>", "Project name (defaults to directory basename)").option("-r, --ratio <ratio>", "Aspect ratio: 16:9, 9:16, 1:1, 4:5", "16:9").option("-d, --duration <sec>", "Default root composition duration (seconds)", "10").option("--visual-style <name>", `Seed DESIGN.md from a named style (browse via \`vibe scene styles\`). E.g. "Swiss Pulse"`).option("--dry-run", "Preview parameters without writing files").action(async (dir, options) => {
   const aspect = validateAspect(options.ratio);
   const duration = validateDuration(options.duration);
   const name = options.name ?? basename18(dir.replace(/\/+$/, ""));
+  const visualStyle = options.visualStyle ? validateVisualStyle(options.visualStyle) : void 0;
   if (options.dryRun) {
     outputResult({
       dryRun: true,
       command: "scene init",
-      params: { dir, name, aspect, duration }
+      params: {
+        dir,
+        name,
+        aspect,
+        duration,
+        visualStyle: visualStyle?.name ?? null
+      }
     });
     return;
   }
   const spinner2 = isJsonMode() ? null : ora(`Scaffolding scene project at ${dir}...`).start();
   try {
-    const result = await scaffoldSceneProject({ dir, name, aspect, duration });
+    const result = await scaffoldSceneProject({ dir, name, aspect, duration, visualStyle });
     if (isJsonMode()) {
       outputResult({
         success: true,
@@ -464296,6 +464664,7 @@ sceneCommand.command("init").description("Scaffold a new scene project (or safel
         name,
         aspect,
         duration,
+        visualStyle: visualStyle?.name ?? null,
         created: result.created,
         merged: result.merged,
         skipped: result.skipped
@@ -464312,7 +464681,13 @@ sceneCommand.command("init").description("Scaffold a new scene project (or safel
     console.log();
     console.log(source_default.bold.cyan("Next steps"));
     console.log(source_default.dim("\u2500".repeat(60)));
-    console.log(`  ${source_default.cyan("vibe scene add")} <name>    ${source_default.dim("# author a scene via AI")}`);
+    if (visualStyle) {
+      console.log(`  ${source_default.dim("DESIGN.md seeded with")} ${source_default.bold(visualStyle.name)} ${source_default.dim("\u2014 review and customise.")}`);
+    } else {
+      console.log(`  ${source_default.cyan("vibe scene styles")}        ${source_default.dim("# pick a named style for DESIGN.md")}`);
+    }
+    console.log(`  ${source_default.cyan("npx skills add heygen-com/hyperframes")}  ${source_default.dim("# load the cinematic-craft skill set")}`);
+    console.log(`  ${source_default.cyan("vibe scene add")} <name>    ${source_default.dim("# fallback path: 5-preset emit")}`);
     console.log(`  ${source_default.cyan("vibe scene lint")}          ${source_default.dim("# validate HTML")}`);
     console.log(`  ${source_default.cyan("vibe scene render")}        ${source_default.dim("# render to MP4")}`);
   } catch (error) {
@@ -464321,6 +464696,69 @@ sceneCommand.command("init").description("Scaffold a new scene project (or safel
     exitWithError(generalError(`Failed to scaffold: ${msg}`));
   }
 });
+sceneCommand.command("styles").description("List vendored visual styles (or show one) for DESIGN.md seeding").argument("[name]", "Style name to inspect (omit to list all)").action((name) => {
+  if (!name) {
+    const all = listVisualStyles();
+    if (isJsonMode()) {
+      outputResult({
+        success: true,
+        command: "scene styles",
+        count: all.length,
+        styles: all.map((s) => ({
+          name: s.name,
+          slug: s.slug,
+          designer: s.designer,
+          mood: s.mood,
+          bestFor: s.bestFor
+        }))
+      });
+      return;
+    }
+    console.log();
+    console.log(source_default.bold.cyan("Visual styles"));
+    console.log(source_default.dim("\u2500".repeat(60)));
+    for (const s of all) {
+      console.log(
+        `  ${source_default.bold(s.name.padEnd(18))} ${source_default.dim(s.mood.padEnd(24))} ${source_default.dim(s.bestFor)}`
+      );
+    }
+    console.log();
+    console.log(source_default.dim("Show details: "), source_default.cyan('vibe scene styles "<name>"'));
+    console.log(source_default.dim("Seed DESIGN.md:"), source_default.cyan('vibe scene init <dir> --visual-style "<name>"'));
+    return;
+  }
+  const style = getVisualStyle(name);
+  if (!style) {
+    exitWithError(
+      usageError(
+        `Unknown visual style: ${name}`,
+        `Valid: ${visualStyleNames()}.`
+      )
+    );
+    return;
+  }
+  if (isJsonMode()) {
+    outputResult({ success: true, command: "scene styles", style });
+    return;
+  }
+  console.log();
+  console.log(source_default.bold.cyan(style.name), source_default.dim(`\u2014 ${style.designer}`));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  console.log(`${source_default.bold("Mood:")}        ${style.mood}`);
+  console.log(`${source_default.bold("Best for:")}    ${style.bestFor}`);
+  console.log(`${source_default.bold("Palette:")}     ${style.palette.join(", ")}`);
+  console.log(source_default.dim("              ") + style.paletteNotes);
+  console.log(`${source_default.bold("Typography:")}  ${style.typography}`);
+  console.log(`${source_default.bold("Composition:")} ${style.composition}`);
+  console.log(`${source_default.bold("Motion:")}      ${style.motion}`);
+  console.log(`${source_default.bold("GSAP:")}        ${style.gsapSignature}`);
+  console.log(`${source_default.bold("Transition:")}  ${style.transition}`);
+  console.log();
+  console.log(source_default.bold("Avoid:"));
+  for (const a of style.avoid) console.log(`  ${source_default.red("\u2022")} ${a}`);
+  console.log();
+  console.log(source_default.dim("Seed DESIGN.md:"), source_default.cyan(`vibe scene init <dir> --visual-style "${style.name}"`));
+});
 sceneCommand.command("add").description("Add a new scene to a project: AI narration + image + per-scene HTML").argument("<name>", "Scene name (slugified into the composition id)").option("--style <preset>", `Style preset: ${SCENE_PRESETS.join(", ")}`, "simple").option("--narration <text>", "Narration text (or path to a .txt file). Drives TTS + scene duration.").option("--narration-file <path>", "Existing narration audio file (.wav/.mp3). Skips TTS \u2014 useful with hyperframes tts, Mac say, or other external tools.").option("-d, --duration <sec>", "Explicit scene duration in seconds (overrides narration audio)").option("--visuals <prompt>", "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider").option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option("--tts <provider>", "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)", "auto").option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option("--no-audio", "Skip TTS even when --narration is provided (useful for tests/agent dry runs)").option("--no-image", "Skip image generation even when --visuals is provided").option("--no-transcribe", "Skip Whisper word-level transcribe step (no transcript-<id>.json emitted)").option("--transcribe-language <code>", "BCP-47 language code passed to Whisper (e.g. en, ko)").option("--force", "Overwrite an existing compositions/scene-<id>.html").option("--dry-run", "Preview parameters without writing files or calling APIs").action(async (name, options) => {
   if (options.style) options.style = validatePreset(options.style);
   if (options.duration !== void 0) options.duration = validateDuration(options.duration);
@@ -464631,7 +465069,20 @@ async function executeSceneAdd(opts) {
   }
   const cfg = await loadVibeProjectConfig(projectDir);
   const fallback2 = cfg?.defaultSceneDuration ?? 5;
-  const duration = opts.duration ?? narrationDuration ?? fallback2;
+  const NARRATION_TAIL_BUFFER = 0.5;
+  const userDur = opts.duration;
+  const audioMinDur = narrationDuration !== void 0 ? narrationDuration + SCENE_OVERLAP_SECONDS + NARRATION_TAIL_BUFFER : void 0;
+  let duration;
+  if (userDur !== void 0 && audioMinDur !== void 0) {
+    duration = Math.max(userDur, audioMinDur);
+  } else if (audioMinDur !== void 0) {
+    duration = audioMinDur;
+  } else if (userDur !== void 0) {
+    duration = userDur;
+  } else {
+    duration = fallback2;
+  }
+  duration = Number(duration.toFixed(2));
   opts.onProgress?.("Emitting scene HTML...");
   const sceneHtml = emitSceneHtml({
     id,
@@ -464649,8 +465100,10 @@ async function executeSceneAdd(opts) {
   await mkdir19(dirname25(scenePath), { recursive: true });
   await writeFile25(scenePath, sceneHtml, "utf-8");
   opts.onProgress?.("Updating root composition...");
-  const start = nextSceneStart(rootHtmlBefore);
-  const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration });
+  const start = nextSceneStart(rootHtmlBefore, SCENE_OVERLAP_SECONDS);
+  const existingClipCount = (rootHtmlBefore.match(/<div\s+class="clip"/g) || []).length;
+  const trackIndex = existingClipCount % 2 + 1;
+  const updated = insertClipIntoRoot(rootHtmlBefore, { id, start, duration, trackIndex });
   await writeFile25(rootPath, updated, "utf-8");
   const transcriptAbsPath = transcriptRelPath ? resolve40(projectDir, transcriptRelPath) : void 0;
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.57.3",
+  "version": "0.58.0",
   "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -57,8 +57,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/core": "0.57.3",
-    "@vibeframe/cli": "0.57.3"
+    "@vibeframe/cli": "0.58.0",
+    "@vibeframe/core": "0.58.0"
   },
   "engines": {
     "node": ">=20"