@kolbo/mcp 1.88.3 → 1.89.0

package/README.md

@@ -8,6 +8,10 @@ Use `list_fonts` / `get_font` to discover My Fonts. Local stdio clients upload o
 
 Only models reporting `supports_custom_fonts: true` accept these selections. Fonts and backend-generated specimens never go through media upload. See [Personal Fonts](https://docs.kolbo.ai/developer-api/personal-fonts). Availability requires a published client and deployed backend containing these tools; source changes alone do not update installed clients.
 
+## No-background images
+
+`generate_image` and `generate_image_edit` accept `background: "transparent"` for models whose `list_models` record reports `supports_transparent_background: true`. Kolbo also appends the exact phrase `no background` once to the effective prompt, while the structured setting requests the native alpha channel through the configured provider route. Use `output_format: "png"` or `"webp"` (PNG is selected automatically when omitted). Prompt wording alone is not sufficient, and unsupported models reject the request instead of silently returning an opaque image.
+
 Use [Kolbo AI](https://kolbo.ai) as native tools in Claude Code and Claude Desktop via MCP (Model Context Protocol).
 
 Generate images, videos, music, speech, sound effects, multi-scene campaigns, and conversational chat — all from natural language in your coding environment. 100+ AI models behind Smart Select routing, with reusable Visual DNA profiles for character/style consistency.
@@ -278,7 +282,9 @@ Every generation tool also accepts an optional `project_id` arg that routes the
 | `generate_character_sheet` | Generate a multi-angle character sheet from reference images (credits) → pass URL to create_visual_dna or update_visual_dna |
 | `list_visual_dna_folders` / `create_visual_dna_folder` / `update_visual_dna_folder` / `delete_visual_dna_folder` / `move_visual_dna_to_folder` | Organize Visual DNA characters into user folders (create/rename/recolor/delete + move DNAs in/out) |
 | `create_project` / `update_project` / `archive_project` / `unarchive_project` | Project lifecycle (create/rename/describe/archive; deletion stays in-app) |
-| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Custom chat agents (reusable named personas; `description` is the system instruction) |
+| `list_skills` / `create_skill` / `update_skill` / `delete_skill` | Skills — reusable named personas for the chat tool; `description` is the system instruction |
+| `list_agents` / `create_agent` / `update_agent` / `delete_agent` | Same four tools under their original names. Still supported and unchanged; new integrations should use the `*_skill` names |
+| `create_video_editor_session` / `export_video_editor_session` | Build an editable timeline from Kolbo-hosted clips, audio and text, then export it to MP4. No new media is generated; identical snapshots reuse the same export job |
 | `get_creative_director_status` | Re-check a Creative Director batch by generation_id until all parallel scenes finish (use after a `_timed_out` Director run) |
 | `list_sessions` | Enumerate sessions across all types, filterable by project, `type`, and `types[]` |
 | `rename_session` / `delete_session` / `restore_session` | Rename a session; soft-delete leftovers after a move; restore from trash |
@@ -307,4 +313,4 @@ Both are optional — the local install logs in via the browser on first use.
 
 ### Chat thinking level
 
-`chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability.
+`chat_send_message` accepts optional `thinking_level`, using an ID from `list_models` with `type: "text"`. The server validates it against the resolved model; omitted or invalid values use `thinkingDefault`. Existing safeguards and legacy `deep_think` take precedence. Discover allowed levels through `thinkingLevels`; no package update is required when the server changes a model capability. For the Auto model, optional `routing_mode` accepts `fast`, `balanced`, or `smart`; omitted uses the server default of `balanced`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolbo/mcp",
-  "version": "1.88.3",
+  "version": "1.89.0",
   "description": "Kolbo AI MCP Server - Generate images, videos, music, speech, and sound effects from Claude Code",
   "main": "src/index.js",
   "bin": {

package/skill/GENERATED.md

@@ -1,6 +1,6 @@
 # AUTO-GENERATED — do not edit
 
-This tree is mirrored from kolbo-code@0ac4fba, the single source of truth.
+This tree is mirrored from kolbo-code@1dc58c1, the single source of truth.
 Canonical source: packages/opencode/skills/kolbo/
 Distribution: .github/workflows/sync-skill-to-plugin.yml
 

package/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-version: 0.9.15
+version: 0.9.16
 name: kolbo
 description: |
   Generate, edit, analyze, and direct creative media through Kolbo AI: images,
@@ -72,7 +72,8 @@ For multi-scene / batch work this pairs with `generate_creative_director` (see b
 | Build, inspect, animate, light, render, or edit a **Blender scene through Kolbo Blender MCP** | `references/workflows/blender-mcp.md` |
 | Generate a **Seedance 2.5** video | `skill` `elements-prompting` + `references/models/seedance25.md` + Locked Intro in `references/models/seedance.md`. For narrative/continuity also load `references/workflows/filmmaking.md` — but compile the prompt as Locked Intro, NOT the SCENE CONTEXT / OPTICS / ACTION pack |
 | Generate a **Seedance 2 / WAN / MiniMax H3 / Gemini / Elements** video (`generate_elements` or Visual DNA) | `skill` `elements-prompting` + `references/models/seedance.md` — same Locked Intro. Elements is NOT a different prompt language |
-| Generate a **GPT Image 2** image | `references/models/gpt-image.md` |
+| Generate a **GPT Image 2 / 2.5** image | `references/models/gpt-image.md` |
+| **No background / transparent PNG / cutout** on any image | `references/models/gpt-image.md` |
 | Generate a **Nano Banana / Gemini** image | `references/models/nano-banana.md` |
 | Generate a **Veo 3 / 3.1** video | `references/models/veo.md` |
 | Build a **multi-scene set** (Creative Director, storyboard, campaign batch, 4+ angles) | `references/models/creative-director.md` |
@@ -113,8 +114,8 @@ Font tools (when exposed by the installed MCP): `list_fonts`, `get_font`, `uploa
 ### Generation
 | Tool | Description |
 |------|-------------|
-| `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets (custom instructions live here), reference images, web-search grounding. Named sheets/styles: `list_presets({ type: "image", search: "headless" })` then `preset_id`. |
-| `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`. |
+| `generate_image` | Single image from a text prompt. Supports Visual DNA, moodboards, image presets (custom instructions live here), reference images, web-search grounding. Named sheets/styles: `list_presets({ type: "image", search: "headless" })` then `preset_id`.  NO BACKGROUND: require `supports_transparent_background: true` from `list_models`, then pass `background: "transparent"` with PNG/WebP — Kolbo appends the phrase `no background` once; prompt wording alone does not replace the setting. |
+| `generate_image_edit` | Edit/transform an existing image. Pass `source_images` + edit prompt. Image-editing presets are supported through `preset_id` from `list_presets({ type: "image_edit" })`.  Native no-background output uses the same capability gate and `background: "transparent"` contract as `generate_image`. |
 | `generate_creative_director` | **2–8 related images or videos as one coherent set.** Use INSTEAD of multiple `generate_image` calls for any related multi-output. |
 | `generate_video` | Text-to-video. Accepts `visual_dna_ids` and `sound_enabled`; `generate_elements` is still the primary reference-driven route for a DNA-anchored film. |
 | `generate_video_from_image` | Animate a still. Prompt describes motion, not subject. |
@@ -274,6 +275,7 @@ A user-named tool — in any language — overrides every other rule. Recognized
 | "Modify THIS one image" — change bg, remove object, recolor | `generate_image_edit` | ❌ Not for multi-output |
 | "4 angles / poses / views of this character" / "variations of this character" | `generate_creative_director` with `visual_dna_ids` | ❌ Don't loop `generate_image_edit` |
 | "4 variations of THIS exact image" (same prompt, different seeds) | `generate_image` with `num_images=4` | ❌ Not `generate_image_edit` |
+| "No background" / transparent PNG / cutout, **בלי רקע** / **רקע שקוף** — new image or existing one | `generate_image` / `generate_image_edit` with `background: "transparent"` on a GPT Image 2 / 2.5 model (gate on `supports_transparent_background: true`) | ❌ Prompt wording alone — it returns an opaque image. ❌ `edit_image` `removebg` unless they want a purely mechanical cutout of an existing photo |
 
 ## Core Workflow
 

package/skill/VERSION

@@ -1 +1 @@
-0.9.15
+0.9.16

package/skill/references/models/gpt-image.md

@@ -2,16 +2,17 @@
      kolbo-api/src/config/systemPrompt.js (lines ~858–965).
      When that function changes, update this file in the same session. -->
 
-# GPT Image 2 — Prompt Rules
+# GPT Image 2 / 2.5 — Prompt Rules
 
-Load this file when the user wants a **GPT Image 2 / gpt-image-2** image (OpenAI). For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
+Load this file when the user wants a **GPT Image 2 or GPT Image 2.5** image (OpenAI). The live family is `gpt-image-2`, `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` — all three are the ONLY Kolbo image models that can output a native transparent background. (`gpt-image/1.5-text-to-image` is the older row and cannot.) For other image models see `models/nano-banana.md`, `models/creative-director.md`, or `models/prompt-copilot.md`.
 
-**Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass `model: "gpt-image-2"` when the user named it; otherwise consult `list_models({ type: "text_to_img" })`.
+**Kolbo MCP routing:** call `generate_image` (text-to-image) or `generate_image_edit` (edits with `source_images`). Pass the exact identifier the user named (`gpt-image-2`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-flare`); otherwise consult `list_models({ type: "text_to_img" })`. On `generate_image_edit` the same families appear as their `/edit` rows under `list_models({ type: "image_editing" })`.
 
 ## CRITICAL Kolbo Platform Rules
 
 - **Resolution and aspect ratio are MCP-tool params** (`aspect_ratio`, `resolution`) — NEVER include `size=`, `1024x1536`, aspect-ratio tags, or any resolution syntax inside the `prompt` field.
 - Pass aspect / resolution as separate tool parameters. Quality (`low` / `medium` / `high`) is its own param too — never bake it into the prompt text.
+- **No background uses both a tool parameter and a prompt cue.** If the user asks for no background / a transparent cutout, call `list_models` for the chosen image type and require `supports_transparent_background: true`. Then pass `background: "transparent"` and `output_format: "png"` (or `"webp"`). Kolbo appends the exact phrase `no background` once to the effective prompt automatically. The phrase alone is not sufficient; if the model does not advertise the capability, choose a supported model with the user.
 - Do not write Python, `client.images.generate`, OpenAI SDK code, or `size=` keyword arguments. The user is generating through Kolbo's MCP tools.
 
 ## Universal Prompting Rules (apply to EVERY prompt)

package/skill/references/workflows/cost-and-validation.md

@@ -119,3 +119,7 @@ Normal cost formula: `final_cost = credit × output_seconds × resolution_multip
 ## Log Approved Resolution / Duration / Sound Choices
 
 After the user approves the actual result, log its `credits_used`, resolution, duration, and sound state. Pending and rejected outputs stay out; use the format in `production-log.md`.
+
+## Reference evidence in generation status
+
+For a reference audit, inspect the persisted status result's `visual_dna` and reference image fields. The widget's `visual_dnas` is display metadata, not the original submitted request. Missing widget metadata means unknown, not that no reference was used. Server-side @mention resolution can attach references beyond the caller’s explicit fields. Keep submitted inputs, persisted references, and observed visual fidelity distinct; attaching a DNA does not prove identity fidelity.

package/skill/references/workflows/media-library.md

@@ -4,6 +4,10 @@ Load this file when the user wants to browse, list, organize, delete, restore, m
 
 The library covers both **uploaded files** and **AI-generated outputs the user has saved**. Tools fall into five groups: ingest, browse, lifecycle (delete/restore/move), folders, and favorites.
 
+`list_media` returns the complete requested page in both text and widget results. Follow `pagination.has_next` using the returned page size; use smaller pages (for example 20) when reviewing detailed assets to keep context manageable. `project_id` restricts SDK results to that project's recorded membership, not the project-looking segment in a CDN URL (files can be moved). A folder filter takes precedence over the project filter.
+
+For production research, `get_visual_dna` provides the full stored description and references; list descriptions are compact previews. Internal extraction system prompts are intentionally private. `get_project_profile` reads the stored synthesized brief; it is not a substitute for the original project documents or session history.
+
 ## ⚠️ Already-hosted URLs — never re-upload
 
 `generate_*` / `list_media` / `get_media` / a prior `upload_media` already return a Kolbo CDN URL (`media.kolbo.ai`, `*.kolbo.ai`, Spaces). Pass that exact URL into the next generation tool. Calling `upload_media` on it duplicates the file.

package/src/apps/bridge.js

@@ -36,6 +36,22 @@ const BRIDGE_JS = `
   var queue = [];        // deferred host-bound sends until initialized
   var hostContext = null;
   var readyFns = [], toolResultFns = [], themeFns = [], toolInputFns = [];
+  var latestResult, latestInput;
+  function deliver(f, args) {
+    try { f.apply(null, args); }
+    catch (e) {
+      console.error('Kolbo widget render failed', e);
+      var card = document.querySelector('.k-card');
+      var notice = document.getElementById('kolbo-render-error');
+      if (card && !notice) {
+        notice = document.createElement('div');
+        notice.id = 'kolbo-render-error';
+        notice.setAttribute('role', 'alert');
+        notice.textContent = 'This preview could not update. Your generation may still be running. Reopen this card or check your Kolbo library.';
+        card.appendChild(notice);
+      }
+    }
+  }
 
   function post(msg) { window.parent.postMessage(msg, '*'); }
 
@@ -67,11 +83,13 @@ const BRIDGE_JS = `
       return;
     }
     if (m.method === 'ui/notifications/tool-result') {
-      toolResultFns.forEach(function (f) { try { f(m.params || {}); } catch (e) {} });
+      latestResult = m.params || {};
+      toolResultFns.forEach(function (f) { deliver(f, [latestResult]); });
     } else if (m.method === 'ui/notifications/tool-input' || m.method === 'ui/notifications/tool-input-partial') {
       // Fires while the tool is still RUNNING — lets widgets show a real
       // "preparing" state instead of a blank card until the result lands.
-      toolInputFns.forEach(function (f) { try { f((m.params && m.params.arguments) || {}, m.params || {}); } catch (e) {} });
+      latestInput = [(m.params && m.params.arguments) || {}, m.params || {}];
+      toolInputFns.forEach(function (f) { deliver(f, latestInput); });
     } else if (m.method === 'ui/notifications/host-context-changed') {
       hostContext = (m.params && m.params.hostContext) || m.params || hostContext;
       themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
@@ -88,12 +106,13 @@ const BRIDGE_JS = `
     appInfo: { name: 'kolbo-widget', version: '1.0.0' },
     appCapabilities: {}
   }).then(function (res) {
+    if (oa) return; // A late JSON-RPC ack must not replace OpenAI host context.
     hostContext = (res && res.hostContext) || null;
     notify('ui/notifications/initialized');
     initialized = true;
     queue.forEach(post);
     queue = [];
-    readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+    readyFns.forEach(function (f) { deliver(f, [hostContext]); });
   }).catch(function () { /* host without apps support — widget stays static */ });
 
   var fsMode = false; // fullscreen: the HOST owns layout — size reports there
@@ -176,9 +195,9 @@ const BRIDGE_JS = `
   document.addEventListener('loadedmetadata', function () { queueSize(60); }, true);
 
   window.kolbo = {
-    ready: function (f) { if (initialized) f(hostContext); else readyFns.push(f); },
-    onToolResult: function (f) { toolResultFns.push(f); },
-    onToolInput: function (f) { toolInputFns.push(f); },
+    ready: function (f) { if (initialized) deliver(f, [hostContext]); else readyFns.push(f); },
+    onToolResult: function (f) { toolResultFns.push(f); if (latestResult) deliver(f, [latestResult]); },
+    onToolInput: function (f) { toolInputFns.push(f); if (latestInput) deliver(f, latestInput); },
     onThemeChange: function (f) { themeFns.push(f); },
     callTool: function (name, args) { return request('tools/call', { name: name, arguments: args || {} }); },
     sendMessage: function (text) {
@@ -218,9 +237,13 @@ const BRIDGE_JS = `
   // came, and sat on "Preparing" with no prompt, no settings and no result —
   // even after the tool had returned. Everything here maps onto the same
   // callbacks the JSON-RPC path drives, so widgets need no host-specific code.
-  var oa = window.openai && typeof window.openai === 'object' ? window.openai : null;
-  if (oa) {
-    var oaInputSeen = false, oaOutputSeen = false;
+  var oa = null;
+  var oaInputSeen, oaOutputSeen;
+  function attachOpenAI(event) {
+    var current = window.openai;
+    if (!current || typeof current !== 'object') return;
+    oa = current;
+    var globals = event && event.detail && event.detail.globals;
     var oaName = function () {
       var meta = oa.toolResponseMetadata || {};
       return oa.toolName || meta['kolbo/tool'] || (oa.toolOutput && oa.toolOutput.tool) || undefined;
@@ -232,18 +255,28 @@ const BRIDGE_JS = `
       if (!initialized) {
         initialized = true;
         queue = [];
-        readyFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
+        readyFns.forEach(function (f) { deliver(f, [hostContext]); });
       } else {
         themeFns.forEach(function (f) { try { f(hostContext); } catch (e) {} });
       }
-      if (oa.toolInput && !oaInputSeen) {
-        oaInputSeen = true;
-        toolInputFns.forEach(function (f) { try { f(oa.toolInput, { name: oaName(), arguments: oa.toolInput }); } catch (e) {} });
+      var input = globals && Object.prototype.hasOwnProperty.call(globals, 'toolInput') ? globals.toolInput : oa.toolInput;
+      var output = globals && Object.prototype.hasOwnProperty.call(globals, 'toolOutput') ? globals.toolOutput : oa.toolOutput;
+      var inputKey = JSON.stringify(input);
+      var metadata = globals && globals.toolResponseMetadata || oa.toolResponseMetadata || {};
+      var envelope = metadata.call_tool_result || metadata.mcp_tool_result;
+      var result = envelope && typeof envelope === 'object' ? Object.assign({}, envelope) : {};
+      if (output != null) result.structuredContent = output;
+      result._meta = Object.assign({}, result._meta || {}, metadata);
+      var outputKey = JSON.stringify(result);
+      if (input && inputKey !== oaInputSeen) {
+        oaInputSeen = inputKey;
+        latestInput = [input, { name: oaName(), arguments: input }];
+        toolInputFns.forEach(function (f) { deliver(f, latestInput); });
       }
-      if (oa.toolOutput && !oaOutputSeen) {
-        oaOutputSeen = true;
-        var res = { structuredContent: oa.toolOutput, _meta: oa.toolResponseMetadata || {} };
-        toolResultFns.forEach(function (f) { try { f(res); } catch (e) {} });
+      if ((output || envelope) && outputKey !== oaOutputSeen) {
+        oaOutputSeen = outputKey;
+        latestResult = result;
+        toolResultFns.forEach(function (f) { deliver(f, [latestResult]); });
       }
     };
     var oaCall = function (method) { return typeof oa[method] === 'function'; };
@@ -272,13 +305,14 @@ const BRIDGE_JS = `
       if (!oaCall('requestDisplayMode')) return Promise.resolve({ mode: 'inline' });
       return Promise.resolve(oa.requestDisplayMode({ mode: mode })).then(function (r) { return { mode: (r && r.mode) || mode }; });
     };
-    window.addEventListener('openai:set_globals', oaSync);
     // Deferred: the widget's own script (which registers ready/onToolInput/
     // onToolResult) runs AFTER this bridge block in the same document, and a
     // synchronous sync here fired into empty listener lists and marked the
     // input/output as seen.
-    setTimeout(oaSync, 0);
+    oaSync();
   }
+  window.addEventListener('openai:set_globals', attachOpenAI);
+  setTimeout(attachOpenAI, 0);
 })();
 `;
 

package/src/apps/html.js

@@ -60,6 +60,8 @@ var ICONS = {
   file: _svg('<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/>'),
   copy: _svg('<rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>'),
   chevronDown: _svg('<path d="M6 9l6 6 6-6"/>'),
+  chevronLeft: _svg('<path d="M15 18l-6-6 6-6"/>'),
+  chevronRight: _svg('<path d="M9 18l6-6-6-6"/>'),
   chevronUp: _svg('<path d="M18 15l-6-6-6 6"/>')
 };
 // Media-kind → icon (accepts model kind / media_type strings).

package/src/apps/index.js

@@ -20,8 +20,8 @@ const { generationWidgetHtml } = require('./widgets/generation');
 const { mediaGridWidgetHtml } = require('./widgets/mediaGrid');
 const { catalogWidgetHtml } = require('./widgets/catalog');
 const { transcriptWidgetHtml } = require('./widgets/transcript');
-const { uploadWidgetHtml } = require('./widgets/upload');
-const { fontUploadWidgetHtml } = require('./widgets/fontUpload');
+const { uploadWidgetHtml } = require('./widgets/upload');
+const { fontUploadWidgetHtml } = require('./widgets/fontUpload');
 const { listWidgetHtml } = require('./widgets/list');
 const { HOST_MAP } = require('../cdn');
 const { plansWidgetHtml } = require('./widgets/plans');
@@ -31,8 +31,8 @@ const UI = {
   mediaGrid: 'ui://kolbo/media-grid.html',
   catalog: 'ui://kolbo/catalog.html',
   transcript: 'ui://kolbo/transcript.html',
-  upload: 'ui://kolbo/upload.html',
-  fontUpload: 'ui://kolbo/font-upload.html',
+  upload: 'ui://kolbo/upload.html',
+  fontUpload: 'ui://kolbo/font-upload.html',
   list: 'ui://kolbo/list.html',
   plans: 'ui://kolbo/plans.html',
 };
@@ -42,8 +42,8 @@ const WIDGET_BUILDERS = {
   [UI.mediaGrid]: mediaGridWidgetHtml,
   [UI.catalog]: catalogWidgetHtml,
   [UI.transcript]: transcriptWidgetHtml,
-  [UI.upload]: uploadWidgetHtml,
-  [UI.fontUpload]: fontUploadWidgetHtml,
+  [UI.upload]: uploadWidgetHtml,
+  [UI.fontUpload]: fontUploadWidgetHtml,
   [UI.list]: listWidgetHtml,
   [UI.plans]: plansWidgetHtml,
 };
@@ -734,8 +734,8 @@ const TOOL_WIDGETS = {
   // never saw it as widget-carrying. Result-level _meta alone isn't enough.
   list_color_palettes: UI.mediaGrid,
   // upload widget
-  media_upload_widget: UI.upload,
-  font_upload_widget: UI.fontUpload,
+  media_upload_widget: UI.upload,
+  font_upload_widget: UI.fontUpload,
   // generic list widget — flat record lists with no natural thumbnail
   list_projects: UI.list,
   // Must stay list.html — mapping this to generation.html mounts "Kolbo Generation /

package/src/apps/theme.js

@@ -354,18 +354,64 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
 .k-input:focus { border-color: var(--brand); box-shadow: 0 0 0 3px var(--brand-soft); }
 .k-input::placeholder { color: var(--text-faint); }
 
-/* ---- Grid widget (media / stock / presets) ---- */
-.k-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 8px; }
-.k-cell { position: relative; border-radius: 10px; overflow: hidden; border: 1px solid var(--border);
-  background: var(--surface); cursor: pointer; transition: transform 250ms var(--spring); }
-.k-cell:hover { transform: translateY(-2px) scale(1.01); }
-.k-cell .k-cell-media { position: relative; aspect-ratio: 1; background: #000; }
-.k-cell .k-cell-media img { width: 100%; height: 100%; object-fit: contain; display: block; }
-.k-cell-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); }
-.k-cell .k-cell-label { padding: 6px 8px; font-size: 11px; color: var(--text-muted);
+/* ---- Paged media grid (library / stock / presets / DNAs / moodboards) ----
+   Media-first tiles: the artwork IS the row. A title rides a gradient scrim
+   INSIDE the tile instead of a text block under it, so a page of results reads
+   as a contact sheet rather than a list of captions. No backdrop-filter on the
+   scrim for the same reason .k-gen-badge has none — a dozen blurred strips over
+   a dozen images forces a per-frame backdrop re-sample on phones. */
+.k-grid { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 8px; }
+/* Narrow hosts (Kolbo Code sidebar, phone): step down instead of shrinking
+   tiles below a thumbnail worth looking at. The 520px block further down wins
+   under 520 and takes it to 2. */
+@media (max-width: 620px) { .k-grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } }
+.k-tile { position: relative; aspect-ratio: 1; border-radius: 12px; overflow: hidden;
+  border: 1px solid var(--border); background: var(--surface); cursor: pointer;
+  transition: transform 250ms var(--spring), box-shadow 250ms var(--smooth), border-color 150ms var(--smooth); }
+.k-tile:hover { transform: translateY(-2px); border-color: var(--border-strong);
+  box-shadow: 0 10px 26px rgba(0, 0, 0, 0.42); }
+.k-tile img, .k-tile video { display: block; width: 100%; height: 100%; object-fit: cover; }
+.k-tile-fb { position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+  color: var(--text-faint); font-size: 24px; }
+.k-tile-cap { position: absolute; left: 0; right: 0; bottom: 0; z-index: 2; pointer-events: none;
+  padding: 20px 8px 7px; background: linear-gradient(transparent, rgba(0, 0, 0, 0.78)); }
+.k-tile-t { font-size: 11px; font-weight: 600; color: #fff;
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.k-cell .k-cell-sub { padding: 0 8px 7px; font-size: 10px; color: var(--text-faint);
+.k-tile-s { font-size: 10px; color: rgba(255, 255, 255, 0.66);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+/* Hover actions, revealed on pointer devices and always-on where there is no
+   hover — a touch host must never hide the only Use affordance. */
+.k-tile-acts { position: absolute; top: 6px; right: 6px; z-index: 3; display: flex; gap: 4px;
+  opacity: 0; transition: opacity 150ms var(--smooth); }
+.k-tile:hover .k-tile-acts, .k-tile:focus-within .k-tile-acts { opacity: 1; }
+@media (hover: none) { .k-tile-acts { opacity: 1; } }
+.k-tile-act { width: 26px; height: 26px; padding: 0; border-radius: 7px;
+  border: 1px solid rgba(255, 255, 255, 0.18); background: rgba(0, 0, 0, 0.62); color: #fff;
+  display: inline-flex; align-items: center; justify-content: center; cursor: pointer;
+  transition: background 150ms var(--smooth); }
+.k-tile-act:hover { background: var(--brand); border-color: var(--brand); }
+.k-tile-play { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); z-index: 2; }
+
+/* ---- Pager (media grid + list) ----
+   A page of results at a fixed card height, instead of a card that grows a row
+   every time you ask for more. Forward past the last loaded page still goes
+   through the server's page_tool + next_args contract. */
+.k-pager { display: flex; align-items: center; justify-content: center; gap: 12px; margin-top: 12px; }
+.k-pager-btn { width: 28px; height: 28px; padding: 0; border-radius: 8px;
+  border: 1px solid var(--border); background: var(--surface-2); color: var(--text);
+  box-shadow: var(--specular); display: inline-flex; align-items: center; justify-content: center;
+  cursor: pointer; transition: background 150ms var(--smooth); }
+.k-pager-btn:hover:not(:disabled) { background: var(--border-strong); }
+.k-pager-btn:disabled { opacity: 0.3; cursor: default; }
+.k-dots { display: flex; align-items: center; gap: 6px; }
+.k-dot { width: 7px; height: 7px; padding: 0; border: 0; border-radius: 999px; cursor: pointer;
+  background: var(--text); opacity: 0.28;
+  transition: width 220ms var(--spring), opacity 150ms var(--smooth); }
+.k-dot:hover { opacity: 0.6; }
+.k-dot.on { width: 22px; opacity: 0.95; cursor: default; }
+.k-dot.ghost { cursor: default; opacity: 0.14; }
+.k-pager-label { font-size: 11px; color: var(--text-faint);
+  font-family: 'JetBrains Mono', ui-monospace, monospace; min-width: 58px; text-align: center; }
 
 /* ---- Audio rows ---- */
 .k-audio-row { display: flex; align-items: center; gap: 10px; padding: 9px 10px;
@@ -405,6 +451,8 @@ html.k-fullscreen .k-actions { flex: none; padding-top: 8px; }
   .k-body { padding: 10px 12px 12px; }
   .k-footer { padding: 8px 12px 12px; }
   .k-grid { grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; }
+  .k-tile-act { width: 30px; height: 30px; }
+  .k-pager-btn { width: 34px; height: 34px; }
   .k-actions { flex-direction: column; align-items: stretch; }
   .k-actions .k-btn { width: 100%; min-height: 44px; justify-content: center; }
   .k-btn { min-height: 40px; padding: 10px 14px; }

package/src/apps/widgets/generation.js

@@ -659,6 +659,7 @@ function renderCancelled(creditsRefunded) {
 var MAX_POLL_MS = 35 * 60 * 1000;
 var MAX_POLL_ERRORS = 30;
 var pollStart = 0, pollErrors = 0;
+var pollInFlight = false;
 var cancelRequested = false;   // set by the Stop button; freezes the poll loop
 
 /* ---------- offscreen gate ----------
@@ -696,6 +697,7 @@ function releaseSeen() {
 
 function schedulePoll(sc) {
   if (cancelRequested) return;
+  if (!sc.generation_id && !(sc.generation_ids && sc.generation_ids.length) && !sc.status_args) return;
   if (!seen) { whenSeenFns.push(function () { schedulePoll(sc); }); return; }
   // The call itself long-waits server-side, for one transport-safe window
   // (~45s over the remote connector — see WAIT_WINDOW_MS in tools/generate.js).
@@ -707,12 +709,15 @@ function schedulePoll(sc) {
   pollTimer = setTimeout(function () { poll(sc); }, delay);
 }
 function poll(sc) {
-  if (cancelRequested) return;
+  if (cancelRequested || pollInFlight) return;
   if (pollStart && (Date.now() - pollStart) > MAX_POLL_MS) {
     return renderTrackingIssue('This is still running longer than the tracking window. Do not retry it — any completed result will appear in your Kolbo library.');
   }
   var args = sc.status_args || { generation_id: sc.generation_id, wait: true };
+  pollInFlight = true;
   window.kolbo.callTool(sc.poll_tool || 'get_generation_status', args).then(function (res) {
+    pollInFlight = false;
+    if (cancelRequested || (state && (state.phase === 'completed' || state.phase === 'failed'))) return;
     var st = structured(res) || {};
     var stateName = st.state || st.phase || st.status;
     // A failed status CALL (tool error / not-found / {success:false}) is not a
@@ -766,6 +771,8 @@ function poll(sc) {
       schedulePoll(sc);
     }
   }).catch(function () {
+    pollInFlight = false;
+    if (cancelRequested || (state && (state.phase === 'completed' || state.phase === 'failed'))) return;
     if (++pollErrors >= MAX_POLL_ERRORS) return renderTrackingIssue('Tracking paused after repeated connection errors. The generation may still be running.');
     schedulePoll(sc);
   });
@@ -1340,20 +1347,20 @@ var PRE_VIDEO_KEYS = ['source_video', 'reference_videos'];
 var PRE_AUDIO_KEYS = ['audio', 'audio_url', 'reference_audio_urls', 'seed_reference_audio_urls'];
 
 // The card mounts the moment the tool is CALLED, so the only thing it knows is
-// the raw tool input - and for an edit/elements call the submit that follows is
+// the raw tool input — and for an edit/elements call the submit that follows is
 // the LONGEST wait on the card (local files are re-hosted first). Map the input
 // onto the same shape renderChips already reads for a server payload so the
 // references, DNA count and settings are on screen immediately instead of after
 // a minute of blank skeleton.
 // Deliberately NOT shown here: model, voice, DNA and moodboard NAMES. Those are
 // resolved server-side and arrive with the result (which overwrites all of
-// this) - rendering the raw identifier the caller passed would put an id on the
+// this) — rendering the raw identifier the caller passed would put an id on the
 // card, which is never allowed.
 function preRefSc(toolName, a) {
   var img = [], vid = [], aud = [];
   var take = function (v, bucket) {
     if (typeof v === 'string') {
-      // http(s) only - an absolute local path is not loadable from the iframe.
+      // http(s) only — an absolute local path is not loadable from the iframe.
       if (/^https?:/i.test(v) && bucket.indexOf(v) < 0) bucket.push(v);
       return;
     }
@@ -1484,6 +1491,8 @@ function completedFromPlain(sc) {
 }
 
 /* ---------- wire host events ---------- */
+// Paint before the host handshake: tool input may arrive late or be withheld.
+bootPre(null, null);
 window.kolbo.onToolResult(function (result) {
   var sc = result.structuredContent || structured(result);
   var list = listPayload(sc);