@kolbo/mcp 1.57.0 → 1.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.57.0",
+  "version": "1.58.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {
@@ -10,8 +10,9 @@
     "start": "node src/index.js",
     "smoke": "node scripts/smoke.js",
     "check-parity": "node scripts/check-parity.js",
-    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
+    "prepublishOnly": "node scripts/smoke.js && node scripts/check-parity.js && node scripts/check-widget-fields.js && node scripts/check-widget-render.js && node scripts/check-skill-tools.js && node scripts/check-install.js",
     "check-widget-fields": "node scripts/check-widget-fields.js",
+    "check-widget-render": "node scripts/check-widget-render.js",
     "check-skill-tools": "node scripts/check-skill-tools.js",
     "check-install": "node scripts/check-install.js"
   },

package/src/apps/theme.js

@@ -180,7 +180,7 @@ body {
   display: inline-flex; align-items: center; justify-content: center;
   cursor: pointer; opacity: 0; transition: opacity 150ms var(--smooth), background 150ms var(--smooth);
 }
-.k-media:hover .k-dl, .k-viewer:hover .k-dl { opacity: 1; }
+.k-media:hover .k-dl, .k-viewer:hover .k-dl, .k-skel:hover .k-dl { opacity: 1; }
 .k-dl:hover { background: var(--brand); border-color: var(--brand); }
 .k-viewer { position: relative; }
 

package/src/apps/widgets/generation.js

@@ -14,7 +14,8 @@ const { widgetPage } = require('../html');
  *   status_args,                       // extra args for the poll tool (optional)
 
  *   model, model_icon, prompt, count,
- *   settings: { duration, resolution, aspect_ratio, audio, voice, mode },
+ *   settings: { duration, resolution, aspect_ratio, quality, audio, voice, mode,
+ *               enhance_prompt, web_search, visual_dna, moodboard, preset, cinematic },
  *   reference_image,                   // thumbnail URL (optional)
  *   urls, thumbnail_url, title, duration, credits_used,
  *   tracks: [{ title, duration, thumbnail_url, model }], // optional audio metadata by URL index
@@ -111,11 +112,18 @@ function renderChips(sc) {
   if (s.duration) h += chip(ICONS.clock + ' ' + fmtDur(s.duration));
   if (s.resolution) h += chip(esc(s.resolution));
   if (s.aspect_ratio) h += chip(esc(s.aspect_ratio));
+  if (s.quality) h += chip(esc(s.quality) + ' quality');
+  if (s.enhance_prompt) h += chip(ICONS.sparkle + ' enhanced');
+  if (s.web_search) h += chip('web search');
+  if (s.visual_dna) h += chip(s.visual_dna + ' Visual DNA');
+  if (s.moodboard) h += chip('moodboard');
+  if (s.preset) h += chip('preset');
+  if (s.cinematic) h += chip('cinematic');
   if (s.audio) h += chip(ICONS.sound + ' audio');
   if (s.voice) h += chip(ICONS.mic + ' ' + esc(s.voice));
   if (s.mode) h += chip(esc(s.mode));
   if (sc.count > 1) h += chip('×' + sc.count);
-  if (sc.reference_image) h += '<img class="k-ref-thumb" src="' + esc(sc.reference_image) + '" alt="" title="Reference image" onerror="this.style.display=\\'none\\'">';
+  if (sc.reference_image) h += '<img class="k-ref-thumb" src="' + esc(sc.reference_image) + '" alt="" loading="lazy" title="Reference image" onerror="this.style.display=\\'none\\'">';
   el('chips').innerHTML = h;
 }
 function chip(inner) { return '<span class="k-chip">' + inner + '</span>'; }
@@ -237,13 +245,48 @@ var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
 var cancelRequested = false;   // set by the Stop button; freezes the poll loop
 
+/* ---------- offscreen gate ----------
+   The host mounts one of these iframes per generation, and re-delivers the
+   ORIGINAL "submitted" (phase:generating) result on every conversation open —
+   so a 50-generation session used to fire 50 status tools/call round trips plus
+   50+ full-resolution media downloads before the user had scrolled to any of
+   them. Hold the FIRST poll (and therefore every media request the result
+   produces) until the card is actually on screen. Once a card has been seen it
+   polls normally forever — a live generation the user scrolls away from still
+   finishes and still reports back. */
+var seen = false, whenSeenFns = [];
+function releaseSeen() {
+  if (seen) return;
+  seen = true;
+  var fns = whenSeenFns; whenSeenFns = [];
+  fns.forEach(function (f) { try { f(); } catch (e) {} });
+}
+(function () {
+  var card = document.querySelector('.k-card');
+  if (!window.IntersectionObserver || !card) return releaseSeen();
+  var fired = false;
+  var io = new IntersectionObserver(function (entries) {
+    fired = true;
+    if (!entries.some(function (e) { return e.isIntersecting; })) return;
+    io.disconnect();
+    releaseSeen();
+  // IO clips against ancestor frames, so this is true parent-viewport
+  // visibility. rootMargin starts the work just before the card scrolls in.
+  }, { rootMargin: '400px' });
+  io.observe(card);
+  // A host where IO never reports at all must not strand the card forever.
+  setTimeout(function () { if (!fired) releaseSeen(); }, 8000);
+})();
+
 function schedulePoll(sc) {
   if (cancelRequested) return;
+  if (!seen) { whenSeenFns.push(function () { schedulePoll(sc); }); return; }
+  // The call itself long-waits server-side (normally up to three minutes).
+  // This short pause only separates successive wait windows — the FIRST call
+  // goes out immediately, so a card revealed by scrolling resolves at once.
+  var delay = pollStart ? 1500 : 0;
   if (!pollStart) pollStart = Date.now();
   clearTimeout(pollTimer);
-  // The call itself long-waits server-side (normally up to three minutes).
-  // This short pause only separates successive wait windows.
-  var delay = 1500;
   pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
@@ -304,7 +347,10 @@ function poll(sc) {
 /* ---------- batch (prompts[] fan-out) ---------- */
 // Each poll round resolves when every id has completed or its wait window
 // closed (~3 min), so finished cells fill in per round while the rest keep
-// their skeleton. When all_done, the set renders through the scenes viewer.
+// their skeleton. When all_done the SAME grid is re-rendered from the resolved
+// set — a batch is one grouped card end to end. It must NOT fall through to the
+// scenes carousel: that collapses eight tiles into one big image plus a thumb
+// strip, which is where the grouping (and the per-tile prompt caption) was lost.
 function handleBatchStatus(sc, st) {
   pollErrors = 0;
   var gens = st.generations || [];
@@ -336,8 +382,9 @@ function handleBatchStatus(sc, st) {
   });
   state = done;
   el('credits').textContent = done.credits_used != null ? fmtCredits(done.credits_used) : '';
-  if (failedCount) setPhaseChip(failedCount + ' failed', false);
   renderResult(done);
+  // After renderResult — it resets the chip, so setting this first erased it.
+  if (failedCount) setPhaseChip(failedCount + ' failed', false);
   try {
     window.kolbo.updateModelContext(
       'Batch generation completed (' + (sc.tool || '') + '): ' + scenes.length + ' of ' + gens.length + ' succeeded.' +
@@ -368,6 +415,7 @@ function renderResult(sc) {
   clearTimeout(pollTimer);
 
   setPhaseChip('', false);
+  if (sc.batch && sc.scenes && sc.scenes.length) return renderBatchGrid(sc);
   if (sc.kind === 'scenes' && sc.scenes && sc.scenes.length) return renderScenes(sc);
   var urls = sc.urls || [];
   if (!urls.length) return renderError('No output received');
@@ -396,7 +444,7 @@ function renderImages(sc, urls) {
   var thumbs = '';
   if (urls.length > 1) {
     thumbs = '<div class="k-thumbs">' + urls.map(function (u, i) {
-      return '<div class="k-thumb' + (i === selected ? ' active' : '') + '" data-i="' + i + '"><img src="' + esc(u) + '" alt=""></div>';
+      return '<div class="k-thumb' + (i === selected ? ' active' : '') + '" data-i="' + i + '"><img src="' + esc(u) + '" alt="" loading="lazy"></div>';
     }).join('') + '</div>';
   }
   el('stage').innerHTML = viewer + thumbs;
@@ -415,8 +463,10 @@ function renderImages(sc, urls) {
 }
 
 function renderVideo(sc, urls) {
+  // preload="none" behind a poster: the card shows the still until the user
+  // hits play, instead of pulling the video header on mount.
   el('stage').innerHTML = '<div class="k-viewer"><video id="main-video" src="' + esc(urls[0]) + '"' +
-    (sc.thumbnail_url ? ' poster="' + esc(sc.thumbnail_url) + '"' : '') + ' controls playsinline></video>' +
+    (sc.thumbnail_url ? ' poster="' + esc(sc.thumbnail_url) + '" preload="none"' : ' preload="metadata"') + ' controls playsinline></video>' +
     dlBtnHTML(urls[0]) + '</div>';
   wireDlButtons(el('stage'));
 }
@@ -429,14 +479,14 @@ function renderAudio(sc, urls) {
     var duration = track.duration != null ? track.duration : sc.duration;
     var artwork = track.thumbnail_url || sc.thumbnail_url;
     return '<div class="k-audio-row k-generated-audio">' +
-      (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="">' :
+      (artwork ? '<img class="k-audio-art" src="' + esc(artwork) + '" alt="" loading="lazy">' :
         '<div class="k-audio-art k-audio-placeholder">' + ICONS.audio + '</div>') +
       '<div class="k-audio-meta"><div class="k-audio-title">' + esc(title) + '</div>' +
       '<div class="k-audio-sub">' + esc(track.model || sc.model || '') +
       (duration ? ' · ' + fmtDur(duration) : '') + '</div></div>' +
       '<button class="k-btn k-audio-download" data-audio-download="' + esc(u) +
       '" aria-label="Download ' + esc(title) + '">' + ICONS.download + ' Download</button>' +
-      '<audio class="k-audio-player" src="' + esc(u) + '" controls preload="metadata" aria-label="Play ' +
+      '<audio class="k-audio-player" src="' + esc(u) + '" controls preload="none" aria-label="Play ' +
       esc(title) + '"></audio></div>';
   }).join('');
   Array.prototype.forEach.call(el('stage').querySelectorAll('[data-audio-download]'), function (b) {
@@ -456,7 +506,7 @@ function renderAudio(sc, urls) {
 
 function render3d(sc, urls) {
   el('stage').innerHTML = (sc.thumbnail_url
-    ? '<div class="k-viewer"><img src="' + esc(sc.thumbnail_url) + '" alt=""></div>' : '') +
+    ? '<div class="k-viewer"><img src="' + esc(sc.thumbnail_url) + '" alt="" loading="lazy"></div>' : '') +
     urls.map(function (u) {
       var extMatch = u.split('?')[0].match(/\\.(\\w+)$/);
       var ext = extMatch ? extMatch[1].toUpperCase() : 'FILE';
@@ -508,6 +558,32 @@ function sceneItems(sc) {
   return items;
 }
 
+// Batch (prompts[] fan-out) result: the SAME tile grid the generating phase
+// showed, each tile still captioned with the prompt that produced it. Downloads
+// are per-tile (a batch has no single "current" url); click a tile to focus it.
+function renderBatchGrid(sc) {
+  var items = sceneItems(sc);
+  if (!items.length) return renderError('No completed results received');
+  var shape = items[0].type === 'video' ? 'video' : 'square';
+  el('stage').innerHTML = '<div class="k-gen-grid n' + Math.min(items.length, 4) + '">' +
+    items.map(function (it, i) {
+      return '<div class="k-skel done ' + shape + '" data-focus="' + i + '">' +
+        (it.type === 'video'
+          ? '<video class="k-cell-fill" src="' + esc(it.url) + '" controls playsinline preload="metadata"></video>'
+          : '<img class="k-cell-fill" src="' + esc(it.url) + '" alt="" loading="lazy" style="cursor:zoom-in">') +
+        (it.label ? '<span class="k-skel-cap" title="' + esc(it.label) + '">' + esc(it.label) + '</span>' : '') +
+        dlBtnHTML(it.url) + '</div>';
+    }).join('') + '</div>';
+  wireDlButtons(el('stage'));
+  Array.prototype.forEach.call(el('stage').querySelectorAll('[data-focus]'), function (cell) {
+    var it = items[+cell.getAttribute('data-focus')];
+    if (it.type !== 'image') return; // <video controls> owns its own clicks
+    cell.onclick = function () { focusMedia(it.url); };
+  });
+  renderActions(sc);
+  window.kolbo.notifySize();
+}
+
 function renderScenes(sc) {
   var items = sceneItems(sc);
   if (!items.length) return renderError('No completed scenes received');
@@ -555,7 +631,7 @@ function exitFocus() {
   window.kolbo.requestDisplayMode('inline').catch(function () {});
   isFullscreen = false;
   applyFullscreen(false);
-  renderScenes(state); // restore the grid
+  renderResult(state); // restore whichever multi-item view we came from
   window.kolbo.notifySize();
 }
 
@@ -740,7 +816,8 @@ function completedFromPlain(sc) {
     settings: {
       duration: sc.duration || originArgs.duration,
       resolution: originArgs.resolution,
-      aspect_ratio: originArgs.aspect_ratio
+      aspect_ratio: originArgs.aspect_ratio,
+      quality: originArgs.quality
     },
     urls: sc.urls || []
   });

package/src/tools/generate.js

@@ -73,6 +73,24 @@ async function pollBatch(client, batch, { interval, timeout }) {
   };
 }
 
+// ─── Widget settings block ──────────────────────────────────────────────────
+// What the CALLER actually asked for, for the generation card AND for the model
+// reading the tool result. Undefined/false keys are dropped by JSON.stringify, so
+// only values that were really supplied ever surface. This used to be
+// `{ resolution, aspect_ratio }` only — `quality` (and every knob below it) was
+// silently dropped, so three calls at low/medium/high rendered identical cards.
+const imageSettings = (a = {}) => ({
+  resolution: a.resolution,
+  aspect_ratio: a.aspect_ratio,
+  quality: a.quality,
+  enhance_prompt: a.enhance_prompt || undefined,
+  web_search: a.enable_web_search || undefined,
+  visual_dna: (a.visual_dna_ids && a.visual_dna_ids.length) || undefined,
+  moodboard: a.moodboard_id ? true : undefined,
+  preset: a.preset_id ? true : undefined,
+  cinematic: a.cinematic ? true : undefined,
+});
+
 const promptsField = (what) => z.array(z.string()).optional().describe(
   `BATCH MODE — several DIFFERENT prompts (2–${MAX_BATCH_PROMPTS}) generated concurrently in ONE call and rendered together in ONE combined widget. Whenever the user wants multiple distinct ${what} with their own prompts, ALWAYS pass them all here instead of making several separate calls — separate calls clutter the chat with stacked widgets. All prompts share the same model/settings. When set, \`prompt\` is ignored. For N variations of a SINGLE prompt use num_images (image tools); for an AI-planned coherent scene set use generate_creative_director.`
 );
@@ -121,7 +139,7 @@ function registerGenerateTools(server, client, options = {}) {
         const batch = await submitBatch(prompts, (p) => client.post('/v1/generate/image', { ...shared, prompt: p }));
         if (ui()) return uiGenerating({
           tool: 'generate_image', kind: 'image', gen: batch.ok[0].gen, client, model,
-          count: batch.ids.length, settings: { resolution, aspect_ratio },
+          count: batch.ids.length, settings: imageSettings(shared),
           generation_ids: batch.ids, prompts: batch.ok.map((o) => o.prompt),
           failed_submissions: batch.failed,
           status_args: { generation_ids: batch.ids, wait: true },
@@ -134,7 +152,7 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_image', kind: 'image', gen, client, model, prompt,
-        count: num_images, settings: { resolution, aspect_ratio },
+        count: num_images, settings: imageSettings(shared),
         reference_image: reference_images?.[0]
       });
 
@@ -167,7 +185,7 @@ function registerGenerateTools(server, client, options = {}) {
     'THE tool for ANY prompt-driven / content edit of an existing image — changing the scene ("make it night", "change the sky to sunset"), adding/removing/replacing objects, restyling, recoloring, compositing, or any "edit this image to…" request. This is the image-editing equivalent of generate_image and runs on strong dedicated editing models (nano-banana-2, gpt-image-2). Provide the source image URL(s) in `source_images` and the instruction in `prompt`. Supports Visual DNA profiles and moodboards for style-consistent edits. Do NOT use `edit_image` for these — that tool is only for mechanical enhancements (upscale/reframe/remove-background/skin). For a brand-new image from scratch, use generate_image. Returns the edited image URL(s) when complete.',
     {
       prompt: z.string().describe('Description of the edit to apply (e.g., "remove the background", "change the sky to sunset")'),
-      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific IMAGE-EDITING model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Strong current defaults: "nano-banana-pro/edit" (best general prompt editor), "gpt-image/1.5-image-to-image" (photoreal), or "flux-2/edit". NOTE: text-to-image ids like "nano-banana-2"/"gpt-image-2" are NOT editors — don\'t use them here. Call list_models type="image_editing" to see all options and pick per the user\'s intent.'),
+      model: z.string().optional().describe('Model identifier — REQUIRED in practice: pick a specific model, do NOT omit (omitting = Smart Select auto-pick, which we avoid). Many text-to-image ids double as editors: the server auto-routes a base id to its editing variant when source_images is present (e.g. "gpt-image-2" → gpt-image-2/edit, "nano-banana-2" → nano-banana-2/edit) — passing the bare id is fine, no need to hunt for the "/edit" suffix yourself. BUT this only works for models that actually have a registered edit variant (most flagship models do: gpt-image, nano-banana, flux-2, seedream, qwen, wan, grok-imagine, kling-image families). Models with none (Midjourney, Flux Pro/Ultra, Imagen4, Ideogram, Recraft, Higgsfield Soul, Krea, Dreamina, and others) silently ignore source_images if passed here instead of erroring — if unsure, confirm the model appears in `list_models type="image_editing"` before trusting a bare id, or just use a known-safe default: "nano-banana-pro/edit" (best general prompt editor), "gpt-image-2" (photoreal, strong text), or "flux-2/edit".'),
       source_images: z.array(z.string()).describe('PIXEL-ACCURATE compositing. Array of source image URLs whose pixel content is composited into the output. **Cap: pass at most `max_reference_images` URLs from list_models for the chosen model — exceeding it is a deterministic 400.** Three modes the model auto-detects from input shape: (1) Single image → edit/transform that image. (2) Multiple images, one base + others → composite the others into the base. (3) Multiple images with no clear base → generate a new scene that pixel-accurately embeds the supplied images at positions described in the prompt. Mode 3 is the canonical pattern for thumbnails / branded compositions where exact-pixel logo + face fidelity matter. Refer to source images in the prompt by ordinal position ("FIRST source image", "SECOND source image") or use @image1/@image2 tags. Add "composite AS-IS, do not redraw or restyle" to lock pixels.'),
       aspect_ratio: z.string().optional().describe('Output aspect ratio (e.g., "1:1", "16:9", "9:16"). Must be in the chosen model\'s `supported_aspect_ratios` from list_models. Default: "1:1"'),
       enhance_prompt: z.boolean().optional().describe('Enhance the prompt for better results. Default: false — only pass true if the user explicitly asks to enhance/improve the prompt.'),
@@ -189,7 +207,8 @@ function registerGenerateTools(server, client, options = {}) {
 
       if (ui()) return uiGenerating({
         tool: 'generate_image_edit', kind: 'image', gen, client, model, prompt,
-        count: num_images, settings: { resolution, aspect_ratio },
+        count: num_images,
+        settings: imageSettings({ resolution, aspect_ratio, enhance_prompt, enable_web_search, visual_dna_ids, moodboard_id, cinematic }),
         reference_image: source_images?.[0]
       });
 
@@ -1434,13 +1453,13 @@ function registerGenerateTools(server, client, options = {}) {
         .describe('Output quality preset (e.g. "high", "standard"). Applies where the underlying model supports quality tiers.'),
 
       ai_optimize: z.boolean().optional()
-        .describe('Whether to let Kolbo AI enhance your prompt before sending to the model. Default: true. Set false to use your prompt exactly as written.'),
+        .describe('Whether to let Kolbo AI enhance your prompt before sending to the model. Default: false — your prompt reaches the model exactly as written. Only pass true if the user explicitly asks to enhance/improve the prompt.'),
 
       project_id: projectIdField
     },
     async ({
       image_url, operation, model, scale, aspect_ratio, skin_strength, prompt,
-      mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize,
+      mask_image_url, additional_images, generate_all_angles, resolution, quality, ai_optimize = false,
       zoom_out_percentage, expand_left, expand_right, expand_top, expand_bottom,
       project_id
     }) => {