@innovastudio/contentbuilder 1.5.217 → 1.5.219

package/public/contentbuilder/contentbuilder.esm.js

@@ -17428,8 +17428,16 @@ class CodeElement {
     if (doc.getElementById('css-cb-code-element')) return;
     const style = doc.createElement('style');
     style.id = 'css-cb-code-element';
+    /*
+        No 'position' here. The editor must lay a block out exactly as the
+        published page does, and a block whose content is absolutely
+        positioned (a full-bleed scene in an overlay, say) resolves against
+        its nearest positioned ancestor: making the block itself one put
+        that content inside a 30px-tall box in the editor while the same
+        markup filled the section on the page.
+    */
     style.textContent = `
-            [${ATTR}] { min-height: 30px; position: relative; -webkit-user-select: none; user-select: none; }
+            [${ATTR}] { min-height: 30px; -webkit-user-select: none; user-select: none; }
         `;
     doc.head.appendChild(style);
   }
@@ -20970,7 +20978,7 @@ function getOffset(element) {
     top: box.top + (window.pageYOffset - document.documentElement.clientTop)
   };
 }
-var location = WINDOW.location;
+var location$1 = WINDOW.location;
 var REGEXP_ORIGINS = /^(\w+:)\/\/([^:/?#]*):?(\d*)/i;
 /**
  * Check if the given URL is a cross origin URL.
@@ -20980,7 +20988,7 @@ var REGEXP_ORIGINS = /^(\w+:)\/\/([^:/?#]*):?(\d*)/i;
 
 function isCrossOriginURL(url) {
   var parts = url.match(REGEXP_ORIGINS);
-  return parts !== null && (parts[1] !== location.protocol || parts[2] !== location.hostname || parts[3] !== location.port);
+  return parts !== null && (parts[1] !== location$1.protocol || parts[2] !== location$1.hostname || parts[3] !== location$1.port);
 }
 /**
  * Add timestamp to the given URL.
@@ -29555,7 +29563,7 @@ class Image$1 {
                         <label class="label-checkbox">
                             <input class="input-newwindow" id="__input_newwindow2" type="checkbox" /> ${util.out('Open new window')}
                         </label>
-                        <label class="label-checkbox" id="lblImageLinkOpenLightbox" style="${this.builder.useLightbox ? '' : 'display:none'}">
+                        <label class="label-checkbox mt-1" id="lblImageLinkOpenLightbox" style="${this.builder.useLightbox ? '' : 'display:none'}">
                             <input class="input-openlightbox" id="__input_openlightbox2" type="checkbox" /> ${util.out('Open in a lightbox (for image, video or Youtube)')}
                         </label>
                         </div>
@@ -46265,7 +46273,16 @@ class ColorPickerKelir {
     }
 
     // Close the picker on scroll — it's positioned once, so scrolling detaches it.
-    const hideOnScroll = () => {
+    //
+    // The page moving under the picker is the only scroll that counts. A text
+    // input scrolls its own content whenever the caret passes the edge — on
+    // paste, on Delete, on Cmd+Left/Right — and that is a scroll event too,
+    // which a capture listener on window receives even though it does not
+    // bubble. Without this guard the picker closed while its own hex field
+    // was being edited.
+    const hideOnScroll = e => {
+      const target = e && e.target;
+      if (target && target.nodeType === 1 && popPicker.contains(target)) return;
       this.builder.util.hidePop(popPicker);
       window.removeEventListener('scroll', hideOnScroll, true);
       if (this.builder.win && this.builder.win !== window) this.builder.win.removeEventListener('scroll', hideOnScroll, true);
@@ -82978,6 +82995,23 @@ ${this.buildHistoryContext()}`;
    * IMAGE PREVIEW HELPER
    * ============================================================================
    */
+  /* Attachments shown under a user message, matching what the composer
+   * renders when a file is attached for real. Demo playback only. */
+  addUserAttachmentPreview(images) {
+    const previewDiv = document.createElement('div');
+    previewDiv.className = 'message user';
+    let html = '<div class="message-content" style="display:flex;flex-wrap:wrap;gap:8px;padding:10px;">';
+    images.forEach(img => {
+      const url = this.escapeHtml(img.url || '');
+      if (!url) return;
+      const alt = this.escapeHtml(img.context || url.split('/').pop() || 'Attachment');
+      html += `<img src="${url}" alt="${alt}" style="width:64px;height:64px;object-fit:cover;border-radius:6px;" />`;
+    });
+    html += '</div>';
+    previewDiv.innerHTML = html;
+    this.messagesContainer.appendChild(previewDiv);
+    this.messagesContainer.scrollTop = this.messagesContainer.scrollHeight;
+  }
   addImagePreview(images) {
     const out = s => this.out(s);
     const previewDiv = document.createElement('div');
@@ -84528,9 +84562,12 @@ Return ONLY the edited section as a single <div class="is-section ...>. Do not o
     announcement.setAttribute('aria-live', 'polite');
     announcement.className = 'sr-only';
     announcement.textContent = message;
-    document.body.appendChild(announcement);
+
+    // Must live inside the builder container: the .sr-only rule is scoped
+    // to [data-cb-ui], so elsewhere the text would be visible on screen.
+    this.builderStuff.appendChild(announcement);
     setTimeout(() => {
-      document.body.removeChild(announcement);
+      announcement.remove();
     }, 1000);
   }
 
@@ -84545,6 +84582,11 @@ Return ONLY the edited section as a single <div class="is-section ...>. Do not o
       this.demoConversations.forEach(msg => {
         if (msg.role === 'user') {
           this.addMessage('user', msg.content);
+
+          // Attachments the user sent with the message
+          if (msg.imagePreview && msg.imagePreview.length > 0) {
+            this.addUserAttachmentPreview(msg.imagePreview);
+          }
         } else if (msg.role === 'assistant') {
           this.addMessage('assistant', msg.content, true);
 
@@ -84885,6 +84927,45 @@ Return ONLY the edited section as a single <div class="is-section ...>. Do not o
   }
 }
 
+/**
+ * repair-markup.js
+ * ----------------------------------------------------------------------------
+ * Fixes applied to AI-written HTML on its way to the page, in the targets'
+ * normalize() step.
+ *
+ * Only for defects that are unambiguous — a rule the framework states, where
+ * the result is visibly broken and there is exactly one correct repair. Taste
+ * belongs in the context documentation, not here: this must never turn one
+ * valid design into another.
+ * ----------------------------------------------------------------------------
+ */
+
+/*
+An outline button needs 'hover:border-transparent'.
+
+'border-current' makes the 2px border follow the text colour, hover colour
+included, so on hover the border becomes a visible ring and the hover fill
+stops inside it — the button appears to shrink. The class lets the border take
+the hover background instead.
+
+Left alone: a button that sets its own hover border (any 'hover:border-*'
+class, or 'border' listed in data-cb-hover), which is a deliberate choice the
+class would override.
+*/
+function repairButtons(root) {
+  if (!root || !root.querySelectorAll) return 0;
+  let fixed = 0;
+  root.querySelectorAll('a[role="button"], button').forEach(el => {
+    if (!el.classList.contains('border-current')) return;
+    if ([...el.classList].some(c => c.startsWith('hover:border-'))) return;
+    const hover = (el.getAttribute('data-cb-hover') || '').split(/\s+/);
+    if (hover.includes('border')) return;
+    el.classList.add('hover:border-transparent');
+    fixed++;
+  });
+  return fixed;
+}
+
 /**
  * target-section.js
  * ----------------------------------------------------------------------------
@@ -84899,7 +84980,6 @@ Return ONLY the edited section as a single <div class="is-section ...>. Do not o
  * products run the same engine instead of a copy of it.
  * ----------------------------------------------------------------------------
  */
-
 function createSectionTarget(engine) {
   const b = () => engine.builder;
   const nodes = () => b().getSectionNodes();
@@ -84930,7 +85010,7 @@ function createSectionTarget(engine) {
 
   /* Reference the host actually supplied, in the order it is offered. */
   const docTopics = () => {
-    const t = ['box', 'animation'].filter(k => engine.contextParts[k]);
+    const t = ['box', 'animation', '3d', 'games', 'code'].filter(k => engine.contextParts[k]);
     if (motionPathMode()) t.push('motionPath');
     return t;
   };
@@ -84948,6 +85028,7 @@ function createSectionTarget(engine) {
     const found = holder.querySelectorAll('.is-section');
     if (found.length !== 1) return null;
     const section = found[0];
+    repairButtons(section);
     section.querySelectorAll('div.is-container').forEach(c => {
       if (![...c.classList].some(x => /^size-\d/.test(x))) c.classList.add('size-17');
       if (![...c.classList].some(x => /^leading-\d/.test(x))) c.classList.add('leading-17');
@@ -85074,7 +85155,7 @@ Sections are <div class="is-section ...">. Use ONLY documented classes — this
 ${onDemand.length ? `
 REFERENCE YOU MUST LOAD WHEN RELEVANT
 The documentation below covers grid, typography, spacing and colour. Further reference is available through get_framework_docs and is NOT included here:
-${onDemand.includes('box') ? '- "box": section and box structure — load before ADDING, REMOVING or RESTRUCTURING a section, or changing its layout, width or background.\n' : ''}${onDemand.includes('animation') ? '- "animation": the motion system — load before adding, changing or removing any animation.\n' : ''}${onDemand.includes('motionPath') ? `- "motionPath": moving an OBJECT along a route — a plane, rocket, car, dot or arrow flying, following or tracing a path, curve or journey across a scene. ${motionPathMode() === 'preserve' ? 'This effect is DISABLED for this site: load it only to preserve or adjust a path already in the markup, never to add one.' : 'Load it only for that; it is not needed for ordinary motion — entrances, fades, parallax, scroll reveals or hover effects.'} ALSO load it whenever markup you are about to edit contains a "data-fx-path" attribute, whatever the request was — those attributes are undocumented anywhere else and you will corrupt them otherwise.\n` : ''}Load what a task needs BEFORE writing markup for it. Never guess at classes from those areas.` : ''}`;
+${onDemand.includes('box') ? '- "box": section and box structure — load before ADDING, REMOVING or RESTRUCTURING a section, or changing its layout, width or background.\n' : ''}${onDemand.includes('animation') ? '- "animation": the motion system — load before adding, changing or removing any animation.\n' : ''}${onDemand.includes('3d') ? '- "3d": real-time 3D (three.js) — load before creating or editing a 3D scene, 3D object or WebGL content; for a 3D game load it TOGETHER with "games".\n' : ''}${onDemand.includes('games') ? '- "games": building any game, 2D or 3D — load before game work. A 2D/doodle/casual game uses Canvas 2D from this doc alone (no three.js); a 3D game also loads "3d".\n' : ''}${onDemand.includes('code') ? '- "code": the code block (data-cb-code) for elements that need JavaScript — load before writing or editing one. Not needed for 3D (the "3d" reference covers its own block).\n' : ''}${onDemand.includes('motionPath') ? `- "motionPath": moving an OBJECT along a route — a plane, rocket, car, dot or arrow flying, following or tracing a path, curve or journey across a scene. ${motionPathMode() === 'preserve' ? 'This effect is DISABLED for this site: load it only to preserve or adjust a path already in the markup, never to add one.' : 'Load it only for that; it is not needed for ordinary motion — entrances, fades, parallax, scroll reveals or hover effects.'} ALSO load it whenever markup you are about to edit contains a "data-fx-path" attribute, whatever the request was — those attributes are undocumented anywhere else and you will corrupt them otherwise.\n` : ''}Load what a task needs BEFORE writing markup for it. Never guess at classes from those areas.` : ''}`;
     },
     /* Structural tools. The engine adds the attachment and image tools. */
     tools() {
@@ -85146,7 +85227,7 @@ ${onDemand.includes('box') ? '- "box": section and box structure — load before
         }
       }, ...(topics.length ? [{
         name: 'get_framework_docs',
-        description: `Load reference not included in your instructions. "box" covers section and box structure — layout, width, background. "animation" covers the motion system.${topics.includes('motionPath') ? ' "motionPath" covers moving an object along a route (a plane/rocket/dot tracing a path across a scene) — load it for that, and whenever markup you are editing contains a "data-fx-path" attribute.' : ''} Load what you need before writing the markup that uses it.`,
+        description: `Load reference not included in your instructions. "box" covers section and box structure — layout, width, background. "animation" covers the motion system.${topics.includes('3d') ? ' "3d" covers real-time 3D (three.js).' : ''}${topics.includes('games') ? ' "games" covers building games, 2D and 3D.' : ''}${topics.includes('code') ? ' "code" covers the JavaScript code block (data-cb-code).' : ''}${topics.includes('motionPath') ? ' "motionPath" covers moving an object along a route (a plane/rocket/dot tracing a path across a scene) — load it for that, and whenever markup you are editing contains a "data-fx-path" attribute.' : ''} Load what you need before writing the markup that uses it.`,
         parameters: {
           type: 'object',
           properties: {
@@ -85346,7 +85427,7 @@ function createRowTarget(engine) {
   const limit = () => engine.limits.toolResult;
 
   /* Reference the host actually supplied, in the order it is offered. */
-  const docTopics = () => ['buttons', 'animation'].filter(k => engine.contextParts[k]);
+  const docTopics = () => ['buttons', 'animation', '3d', 'games', 'code'].filter(k => engine.contextParts[k]);
 
   /*
   Exactly one .row, or null. Markup arrives fenced as often as not, and a
@@ -85360,6 +85441,7 @@ function createRowTarget(engine) {
     holder.innerHTML = html.replace(/```html\n?/g, '').replace(/```\n?/g, '').trim();
     const found = Array.from(holder.children).filter(el => el.classList.contains('row'));
     if (found.length !== 1) return null;
+    repairButtons(found[0]);
     return found[0].outerHTML;
   }
   return {
@@ -86018,6 +86100,78 @@ ${docs}`;
         }
       });
     }
+
+    /*
+    3D asset generation (image-to-3D). Offered only when the host lists
+    models3D — the same opt-in convention as the image tools. One image in,
+    one .glb URL out; the model then loads it with GLTFLoader per the "3d"
+    reference doc.
+    */
+    if (this.threeDConfig()) {
+      const threeDParams = {
+        image_url: {
+          type: 'string',
+          description: 'URL of the source image: a photo on the page, or a generate_image result.'
+        }
+      };
+      if ((this.currentAttachments || []).some(a => a && a.kind === 'image')) {
+        threeDParams.attachment = {
+          type: 'integer',
+          description: 'Use an attached image as the source instead of image_url, numbered from 1.'
+        };
+      }
+      t.push({
+        name: 'generate_3d_model',
+        description: 'Generate a 3D model (.glb file) from an image and return its URL, for use inside a 3D scene (load the "3d" reference doc first if you have not). The image must show ONE object, clearly and mostly front-facing — a product shot, an illustration, a generated image. For an object with no source image, call generate_image first and feed its result in. Generation is billed and takes 30-90 seconds, so one call per object the user asked for. Then load the returned URL with GLTFLoader and the normalize pattern from the "3d" reference — the URL goes inside the scene code, never in an <img>.',
+        parameters: {
+          type: 'object',
+          properties: threeDParams,
+          required: []
+        }
+      });
+    }
+
+    /*
+    The critic loop: the model can SEE what a code block's canvas actually
+    renders and fix visual problems before answering — the difference
+    between shipping a black scene and noticing it. Offered only while the
+    page holds a canvas inside a code block, so ordinary requests never
+    see it.
+    */
+    /* Gated on the block, not its canvas — right after an insert the
+       scene is still importing modules and the canvas does not exist yet,
+       which is exactly when the model needs the tool in its list.
+       captureRender does the waiting. */
+    /*
+    Only a model that reads images can act on the screenshot — for a
+    text-only model the injected image is a provider error, so the tool is
+    simply not offered and the docs' "when a view_render tool is offered"
+    phrasing degrades the whole flow gracefully. Same capability registry
+    the attach button uses.
+    */
+    /*
+    Off unless the host turns it on: the self-check costs an extra
+    vision round-trip per scene, so it is opt-in per site.
+    */
+    const selfCheckOn = !!(this.builder && this.builder.renderSelfCheck);
+    const seesImages = resolveFileCapability(this.model, this.v1 && this.v1.codeModels || this.builder && this.builder.codeModels || []).accepts.includes('image');
+    if (selfCheckOn && seesImages && this.builder && this.builder.doc && this.builder.doc.querySelector('[data-cb-code]')) {
+      t.push({
+        name: 'view_render',
+        description: 'Screenshot the live render of a code block\'s canvas (3D scene, game, visualization). ALWAYS call this after creating a scene or making a significant visual change, then LOOK at the image and fix what is wrong (all black = missing environment/lights; empty = camera not framing the content; clipped or tiny = wrong scale or camera position) before giving your final answer. The screenshot arrives as an image in the next message. HTML overlays are not included — only the canvas.',
+        parameters: {
+          type: 'object',
+          properties: {
+            block: {
+              type: 'integer',
+              description: '1-based index among the page\'s canvas-bearing code blocks; omit for the first',
+              default: 1
+            }
+          },
+          required: []
+        }
+      });
+    }
     return t;
   }
 
@@ -86068,6 +86222,14 @@ ${docs}`;
           {
             return await this.editImage(args);
           }
+        case 'generate_3d_model':
+          {
+            return await this.generate3DModel(args);
+          }
+        case 'view_render':
+          {
+            return await this.captureRender(args);
+          }
         default:
           return {
             error: `unknown tool ${name}`
@@ -86087,6 +86249,12 @@ ${docs}`;
 
   async send(text, attachments = []) {
     this.abort = new AbortController();
+    // Per-request ceilings on the expensive/loopable tools. MAX_STEPS
+    // bounds the loop as a whole; these stop a model from burning paid
+    // generations or endless self-checks chasing a critique it cannot
+    // satisfy — past the cap the tool refuses and tells it to finish.
+    this.spent3D = 0;
+    this.spentShots = 0;
     this.beginBatch(); // one undo entry for the whole request
     this.currentAttachments = attachments || [];
     this.attachmentUrls = {};
@@ -86147,6 +86315,30 @@ ${docs}`;
             content: JSON.stringify(result)
           });
         }
+
+        /*
+        view_render screenshots cannot ride in the tool message —
+        tool results are text on every provider — so they follow as a
+        user message. dropAttachmentPayloads compacts them on the next
+        request like any other image, so they never accumulate.
+        */
+        if (this.pendingShots && this.pendingShots.length) {
+          const parts = [{
+            type: 'text',
+            text: 'Screenshot of the current render:'
+          }];
+          this.pendingShots.forEach(u => parts.push({
+            type: 'image_url',
+            image_url: {
+              url: u
+            }
+          }));
+          messages.push({
+            role: 'user',
+            content: parts
+          });
+          this.pendingShots = [];
+        }
       }
 
       // Ran out of steps. Not an error the user should see as a crash.
@@ -86582,6 +86774,267 @@ ${docs}`;
   freshOutline() {
     return this.target.outline();
   }
+
+  /*
+  Screenshot a code block's canvas for the critic loop. Waits for the canvas
+  to exist and paint (module imports take a moment after an insert), then
+  downscales to keep the image cheap. Requires the scene's renderer to have
+  preserveDrawingBuffer: true (the 3d reference's shell sets it) — without
+  it a WebGL canvas reads back blank between frames.
+  */
+  async captureRender(args = {}) {
+    const doc = this.builder && this.builder.doc;
+    if (!doc) return {
+      error: 'no page'
+    };
+    this.spentShots = (this.spentShots || 0) + 1;
+    if (this.spentShots > 6) {
+      return {
+        error: 'limit reached: no more render checks in this request. Answer with the scene as it is, and be honest about anything still not right.'
+      };
+    }
+    const n = Math.max(1, parseInt(args.block, 10) || 1);
+    let canvas = null;
+    for (let i = 0; i < 24; i++) {
+      const canvases = doc.querySelectorAll('[data-cb-code] canvas');
+      canvas = canvases[n - 1] || null;
+      if (canvas && canvas.width > 2 && canvas.height > 2) break;
+      await new Promise(r => setTimeout(r, 500));
+      if (this.abort && this.abort.signal.aborted) throw Object.assign(new Error('aborted'), {
+        name: 'AbortError'
+      });
+    }
+    if (!canvas) return {
+      error: 'no rendering canvas found in a code block (is the scene failing before it creates one?)'
+    };
+    await new Promise(r => setTimeout(r, 1500)); // let the first real frames draw
+
+    try {
+      const scale = Math.min(1, 768 / canvas.width);
+      const w = Math.max(1, Math.round(canvas.width * scale));
+      const h = Math.max(1, Math.round(canvas.height * scale));
+      const off = document.createElement('canvas');
+      off.width = w;
+      off.height = h;
+      const ctx = off.getContext('2d');
+      ctx.drawImage(canvas, 0, 0, w, h);
+
+      // A uniform image means nothing drew (or the renderer lacks
+      // preserveDrawingBuffer) — say so instead of sending a blank.
+      const d = ctx.getImageData(0, 0, w, h).data;
+      let uniform = true;
+      for (let i = 4; i < d.length; i += 997 * 4) {
+        if (d[i] !== d[0] || d[i + 1] !== d[1] || d[i + 2] !== d[2]) {
+          uniform = false;
+          break;
+        }
+      }
+      const dataUrl = off.toDataURL('image/jpeg', 0.8);
+      this.pendingShots = this.pendingShots || [];
+      this.pendingShots.push(dataUrl);
+      if (uniform) {
+        return {
+          ok: true,
+          warning: 'the canvas is a single flat color — either nothing rendered (check for errors: missing environment, objects outside the camera view) or the renderer lacks preserveDrawingBuffer: true, which this check requires. The (blank) screenshot follows as an image.'
+        };
+      }
+      return {
+        ok: true,
+        note: 'screenshot captured — it follows as an image in the next message. Look at it before answering.'
+      };
+    } catch (e) {
+      return {
+        error: 'could not capture the canvas: ' + String(e && e.message || e)
+      };
+    }
+  }
+
+  /*
+  3D generation configuration, resolved per call so a host can switch
+  provider at runtime the same way image generation can. Mirrors v1's
+  provider resolution: endpoint options are looked up as
+  `<base>_<Provider>` in any casing, falling back to the _Fal names.
+  Today every supported provider is queue-shaped (request/status/result);
+  a future single-call 3D provider gets its own branch in generate3DModel,
+  the way SINGLE_CALL_IMAGE_PROVIDERS did for images.
+  */
+  threeDConfig() {
+    const b = this.builder;
+    if (!b) return null;
+    const models = Array.isArray(b.models3D) ? b.models3D.filter(m => m && m.id) : [];
+    if (!models.length) return null;
+    const provider = b.default3DGenerationProvider || 'fal';
+    const val = base => {
+      const wanted = `${base}_${provider}`.toLowerCase();
+      const key = Object.keys(b).find(k => k.toLowerCase() === wanted && b[k]);
+      return key ? b[key] : undefined;
+    };
+    const generateUrl = val('generateMediaUrl') || b.generateMediaUrl_Fal;
+    const statusUrl = val('checkRequestStatusUrl') || b.checkRequestStatusUrl_Fal;
+    const resultUrl = val('getResultUrl') || b.getResultUrl_Fal;
+    if (!generateUrl || !statusUrl || !resultUrl) return null;
+
+    // The saved selection, snapping to the first entry when it is not listed
+    const saved = this.v1 && this.v1.settings && this.v1.settings.model3D;
+    const model = (models.find(m => m.id === saved) || models[0]).id;
+    return {
+      provider,
+      models,
+      model,
+      generateUrl,
+      statusUrl,
+      resultUrl
+    };
+  }
+
+  /*
+  Image-to-3D. The image reaches the provider the same way reference images
+  do for image editing: data URLs go through as-is, same-origin files are
+  read into a data URL (the provider cannot fetch a private host), and
+  public URLs are passed for the provider to fetch itself.
+  */
+  async generate3DModel(args = {}) {
+    const cfg = this.threeDConfig();
+    if (!cfg) return {
+      error: '3D generation is not configured'
+    };
+    this.spent3D = (this.spent3D || 0) + 1;
+    if (this.spent3D > 4) {
+      return {
+        error: 'limit reached: no more 3D model generations in this request. Use the models you already have (or build the object from code), finish the scene, and tell the user a model did not come out right if that is the case.'
+      };
+    }
+    const signal = this.abort ? this.abort.signal : null;
+
+    // Resolve the source image
+    let src = null;
+    if (args.attachment !== undefined && args.attachment !== null) {
+      const list = (this.currentAttachments || []).filter(a => a && a.kind === 'image');
+      const att = list[(parseInt(args.attachment, 10) || 1) - 1];
+      if (!att) return {
+        error: `there ${list.length === 1 ? 'is 1 attached image' : `are ${list.length} attached images`}`
+      };
+      src = att.dataUrl;
+    } else if (args.image_url) {
+      src = this.expandAttachmentUrls(String(args.image_url));
+      if (!/^data:/i.test(src)) {
+        let abs;
+        try {
+          abs = new URL(src, location.href);
+        } catch (e) {
+          return {
+            error: 'image_url is not a valid URL'
+          };
+        }
+        if (abs.origin === location.origin) {
+          try {
+            const blob = await (await fetch(abs.href, {
+              signal
+            })).blob();
+            src = await new Promise((resolve, reject) => {
+              const r = new FileReader();
+              r.onload = () => resolve(r.result);
+              r.onerror = reject;
+              r.readAsDataURL(blob);
+            });
+          } catch (e) {
+            return {
+              error: 'could not read the image at image_url'
+            };
+          }
+        } else {
+          src = abs.href; // public URL — the provider fetches it
+        }
+      }
+    } else {
+      return {
+        error: 'give image_url or attachment'
+      };
+    }
+    const b = this.builder;
+    const headers = {
+      ...b.headers,
+      ...b.defaultHeaders
+    };
+    const customData = b.editor && b.editor.customData || {};
+    const post = async (url, body) => {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        signal,
+        body: JSON.stringify(body)
+      });
+      return await response.json();
+    };
+
+    // Each model family names its input field differently
+    const payload = /hunyuan/i.test(cfg.model) ? {
+      input_image_url: src
+    } : {
+      image_urls: [src],
+      geometry_file_format: 'glb'
+    }; // Rodin-shaped default
+
+    const firstTwoParts = cfg.model.split('/').slice(0, 2).join('/');
+    const req = await post(cfg.generateUrl, {
+      model: cfg.model,
+      customData,
+      endpoint: `https://queue.fal.run/${cfg.model}`,
+      payload
+    });
+    if (req.error || !req.request_id) {
+      return {
+        error: typeof req.error === 'string' ? req.error : '3D generation request failed'
+      };
+    }
+    const request_id = req.request_id;
+    const statusBody = {
+      model: cfg.model,
+      endpoint: `https://queue.fal.run/${firstTwoParts}/requests/${request_id}/status`,
+      request_id,
+      customData
+    };
+    let status = '';
+    for (let i = 0; i < 150 && status !== 'COMPLETED'; i++) {
+      const st = await post(cfg.statusUrl, statusBody);
+      if (st.ok === false) return {
+        error: st.error || '3D generation failed'
+      };
+      if (st.ok && st.status) {
+        status = st.status;
+        if (status === 'FAILED') return {
+          error: '3D generation failed'
+        };
+      } else if (st.data) {
+        // API-style status (mirrors the image flow's fallback)
+        if (st.data.model_mesh || st.data.model_glb || st.data.model_urls) status = 'COMPLETED';else if (st.data.status && !st.data.error) status = st.data.status;
+      }
+      if (status !== 'COMPLETED') await new Promise(r => setTimeout(r, 2000));
+      if (signal && signal.aborted) throw Object.assign(new Error('aborted'), {
+        name: 'AbortError'
+      });
+    }
+    if (status !== 'COMPLETED') return {
+      error: '3D generation timed out'
+    };
+    const res = await post(cfg.resultUrl, {
+      model: cfg.model,
+      request_id,
+      customData,
+      endpoint: `https://queue.fal.run/${firstTwoParts}/requests/${request_id}`
+    });
+    if (res.error) return {
+      error: typeof res.error === 'string' ? res.error : '3D result failed'
+    };
+    const entry = res.data && res.data.entries && res.data.entries[0];
+    if (!entry || !entry.url) return {
+      error: 'the generation returned no model file'
+    };
+    return {
+      url: entry.url,
+      format: 'glb'
+    };
+  }
   async generateImages(prompt, count = 1, size) {
     if (!this.v1) throw new Error('image generation is not configured');
     const signal = this.abort ? this.abort.signal : null;
@@ -86748,6 +87201,10 @@ function describeStep(tool, args, out, target) {
       return out('Reading the attachment') + '…';
     case 'generate_image':
       return out('Generating image') + '…';
+    case 'generate_3d_model':
+      return out('Generating 3D model') + '…';
+    case 'view_render':
+      return out('Checking the render') + '…';
     case 'edit_image':
       return out('Editing image') + '…';
     case '__waiting':
@@ -87009,6 +87466,55 @@ function attachCodeChatV2(codechat, builder, opts = {}) {
     v2.stop();
     if (origAbort) origAbort();
   };
+
+  /*
+  Settings dialog: the 3D model picker. Injected here rather than written
+  into the panel because the panel belongs to v1 and 3D generation is a v2
+  feature — the same borrowing pattern as sendMessage above. The group
+  exists only when the host configured models3D; with one entry it simply
+  shows what is active.
+  */
+  const t3d = v2.threeDConfig && v2.threeDConfig();
+  if (t3d && codechat.builderStuff && !codechat.builderStuff.querySelector('#model3DSelect')) {
+    const anchor = codechat.builderStuff.querySelector('.div-image-generation-options');
+    if (anchor) {
+      const group = document.createElement('div');
+      group.className = 'setting-group';
+      group.innerHTML = `
+                <label for="model3DSelect" class="setting-label">${out('3D Model')}</label>
+                <p class="setting-description">${out('Select the AI model used for 3D model generation')}</p>
+                <div class="cb-sel"><select id="model3DSelect"></select></div>`;
+      const sel = group.querySelector('#model3DSelect');
+      t3d.models.forEach(m => {
+        const opt = document.createElement('option');
+        opt.value = m.id;
+        opt.textContent = m.label || m.id;
+        sel.appendChild(opt);
+      });
+      anchor.parentNode.insertBefore(group, anchor.nextSibling);
+
+      // Current value on every open; snap to the first when stale
+      const origOpen = codechat.openSettings ? codechat.openSettings.bind(codechat) : null;
+      if (origOpen) {
+        codechat.openSettings = function () {
+          origOpen();
+          const cfg = v2.threeDConfig();
+          sel.value = cfg && cfg.model || '';
+          if (sel.selectedIndex < 0 && sel.options.length) sel.selectedIndex = 0;
+        };
+      }
+
+      // Persist with the rest of the settings: set before the panel's
+      // own save stringifies this.settings.
+      const origSave = codechat.saveSettings ? codechat.saveSettings.bind(codechat) : null;
+      if (origSave) {
+        codechat.saveSettings = function () {
+          codechat.settings.model3D = sel.value;
+          origSave();
+        };
+      }
+    }
+  }
   return v2;
 }
 
@@ -87038,7 +87544,7 @@ All content lives in rows and columns — NEVER place content directly under a c
 
 - Size: 'size-<n>' (px). Available: 12,13,14,15,16,17,18,19,20,21,24,28,32,35,38,42,46,48,50,54,60,64,68,72,76,80,84,88,92,96,100 … up to 400. Anchors: labels 12-14, body 16-18, subheads 20-32, headings 42-60, hero/display 60-96.
 - Weight: font-light font-normal font-medium font-semibold font-bold
-- Tracking: tracking-tight tracking-normal tracking-wide tracking-wider tracking-150 (ideal for uppercase labels)
+- Tracking: named steps tracking-tighter tracking-tight tracking-normal tracking-wide tracking-wider tracking-widest, then a numeric scale 'tracking-<n>' where n is a multiple of 25 from 0 to 500 (n/1000 em, so 'tracking-150' = 0.15em). Uppercase labels read best at 150-250; display headings often want tracking-tight.
 - Leading: leading-none leading-12 leading-13 leading-14 leading-15 leading-16 leading-17 leading-18 — body: leading-17/18, headings: leading-12/13
 - Text utils: uppercase lowercase capitalize text-center text-left text-right — put alignment classes ON the text elements (h/p), NOT on a wrapper div. Keep column content flat.
 
@@ -87176,184 +87682,591 @@ Icons: use Bootstrap Icons (NOT emojis), wrapped in a div: <div class="text-cent
 - Minimalist: generous whitespace; palette of black/white/grays; light heading weights; hierarchy through size and spacing, not color.
 `;
 
-const contextCodeBlock = `
-# Custom Code Block
-
-Use Code Block for creating interactive elements that need JavaScript.
+/*
+ * context-code.js — the code element reference for Code Chat.
+ *
+ * Documents the RELEASED code element ([data-cb-code], see
+ * contentbuilder/docs/code-element-guide.md and codeelement.js). The previous
+ * version of this file described an old experimental contract
+ * (data-cb-type="code" + container.mount) that never shipped.
+ *
+ * Sent on every v1 request and served as the on-demand 'code' topic in v2,
+ * so it is kept short. No backticks or ${ } — template literal.
+ *
+ * Takes the host's options because where a block may sit differs by product:
+ * ContentBox also has overlay layers, ContentBuilder does not. One file, one
+ * wording, and neither product is told about markup it has no use for.
+ */
 
-Code Block can only be placed:
+function getContextCodeBlock(opts = {}) {
+  // Where a block may sit. ContentBox also has overlay layers; ContentBuilder
+  // has columns only, and must not be told about markup it does not have.
+  const placement = opts.overlay ? `It sits inside a column,
+beside other content, or inside '.is-overlay > .is-overlay-content'. To fill
+that layer, give the block 'position:absolute;inset:0' — the overlay is
+full-screen, the block is not.` : `It sits
+inside a column, beside other content.`;
+  return `
+# Code Block
 
-- in content (inside div.column)
-- in overlay (must be in div.is-overlay-content)
+For elements that need JavaScript, use a code block: <div data-cb-code>
+(that attribute alone marks it — no class, no other bookkeeping). ${placement} The code runs live while editing and
+runs again on the saved page.
 
-**In Content**
+A simple block is complete as written — no wrapper, no ceremony:
 
-<div class="row">
-    <div class="column">
-  		<div data-cb-type="code">
-        <!-- Your Code -->
-      </div>
-  	</div>
+<div data-cb-code>
+    <h1 id="greet7x">Lorem ipsum</h1>
+    <p>This is a code block.</p>
+    <script>
+        document.querySelector('#greet7x').innerHTML = '<b>Hello World..!</b>';
+    </script>
 </div>
 
-**In Overlay**
+Ids are safe: when a block is duplicated, the editor gives the copy fresh ids
+and updates the references inside its script to match.
 
-<div class="is-section is-box is-section-100 type-system-ui">
-    <div class="is-overlay">
-        <div class="is-overlay-content">
-            <div data-cb-type="code" style="position: absolute; top:0, left:0; width: 100%; height: 100%">
-        			<!-- Your Code -->
-            </div>
-        </div>
-    </div>
-  
-    <!-- ... -->
-</div>
+For blocks that do more, these rules keep them working through editing:
 
-### 1. Basic Example
+- The editor re-renders the block on edit, undo and duplicate, and each
+  render runs the code again on FRESH elements. Anything that keeps running
+  — a timer, an interval, a window/document listener, an animation loop —
+  must stop by itself when its elements leave the page. Check isConnected:
 
-**Important**: Always Use 'data-cb-type="code"' and create 'mount' function.
+    const display = document.querySelector('#clock9k');
+    const iv = setInterval(() => {
+        if (!display.isConnected) { clearInterval(iv); return; }
+        display.textContent = new Date().toLocaleTimeString();
+    }, 1000);
+
+- Plain classic <script> tags only — never type="module". To load a library,
+  use dynamic import() inside ONE async IIFE wrapping the whole script,
+  closed with exactly one })(); at the end — never nest a second wrapper:
 
-<div data-cb-type="code">
-    <h3 class="code-block__title font-normal size-24">Code Block</h3>
-    <p>This is a custom code block. Open HTML code editor to edit this block.</p>
     <script>
-        (function() {
-            // Get reference to this specific script element
-            const currentScript = document.currentScript;
-            // Navigate to the parent container
-            const container = currentScript.parentElement;
-
-          	const initialize = async () => {
-              // Find the title within THIS container only
-              const title = container.querySelector('.code-block__title');
-              if (title) {
-                  title.textContent = 'Code Block';
-              }
-            };
-          
-            // Create mount function and store it on the container
-            // for the Runtime to render the plugin
-            container.mount = function() {
-                initialize(); // Start initialization
-            };
-            // If no runtime, just start initialization
-            if (!window.builderRuntime) {
-                initialize();
-            }
+        (async () => {
+            const confetti = (await import('https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.3/+esm')).default;
+            // ... the rest of the block's code ...
         })();
     </script>
-</div>
-
-### 2. Inline '<style>' and Dynamic External Script Loading
-` + `
-<div data-cb-type="code">
-    <style>
 
-    </style>
+  A classic library that defines a global loads with a created <script>
+  element (check for an existing one first); CSS files the same way with a
+  <link rel="stylesheet">. If you read document.currentScript, do it on the
+  first line — it is null after the first await.
 
-    <div class="swiper swiper-initialized swiper-horizontal">
-        
-    </div>
+- Self-contained only: styles inline or in a <style> tag inside the block;
+  never touch document-level styles or elements outside the block.
+`;
+}
 
-    <script>
-        (function() {
-            const currentScript = document.currentScript;
-            const container = currentScript.parentElement;
-
-            // Dynamic loader for Swiper CSS
-            const loadSwiperCSS = () => {
-                return new Promise((resolve, reject) => {
-                    // Check if CSS already loaded
-                    const existingLink = document.querySelector('link[href*="swiper-bundle.min.css"]');
-                    if (existingLink) {
-                        resolve();
-                        return;
-                    }
+/*
+ * context-3d.js — the "3d" on-demand doc topic for Code Chat v2.
+ *
+ * Loaded via get_framework_docs ONLY when a request involves real-time 3D:
+ * a three.js scene, WebGL content, a 3D product view, or a browser game.
+ * It is never part of the resident system prompt — 3D requests are rare and
+ * this reference is long, so it rides the same on-demand rail as "animation".
+ *
+ * The recipes here were verified in the ContentBuilder public/test-3d
+ * experiments (Sept 2026): the quality shell, sky-as-light, instanced grass,
+ * and the glb normalize pattern are lifted from working pages, not invented.
+ * Keep code samples free of backticks and ${ } — this is a template literal.
+ */
 
-                    const link = document.createElement('link');
-                    link.rel = 'stylesheet';
-                    link.href = 'https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.css';
-                    link.onload = () => resolve();
-                    link.onerror = reject;
-                    document.head.appendChild(link);
-                });
-            };
+const context3D = `
+# Real-Time 3D & Games (three.js)
 
-            // Dynamic loader for Swiper JS
-            const loadSwiper = () => {
-                return new Promise((resolve, reject) => {
-                    if (window.Swiper) {
-                        resolve(window.Swiper);
-                        return;
-                    }
-                    const script = document.createElement('script');
-                    script.src = 'https://cdn.jsdelivr.net/npm/swiper@11/swiper-bundle.min.js';
-                    script.onload = () => resolve(window.Swiper);
-                    script.onerror = reject;
-                    document.head.appendChild(script);
-                });
-            };
+Use this whenever the user asks for a 3D scene, 3D object, WebGL, a 3D
+product/hero visual, or a playable browser game. Everything lives in a code
+element (data-cb-code), which runs live in the editor and as plain HTML on
+the published page.
 
-            // Initialize plugin
-            const initializeSlider = async () => {
-                try {
-                    // Load dependencies
-                    await loadSwiperCSS();
-                    const Swiper = await loadSwiper();
+A finished-looking scene is mostly LIGHTING, not geometry. Never ship the
+naive setup (ambient + directional light, no environment, no tone mapping) —
+it makes every material look like flat plastic. Always use the Scene Shell
+below.
 
-										// ...
+## 1. The block
 
-                } catch (error) {
-                    console.error('Failed to initialize slider:', error);
-                }
-            };
+3D lives in a code element: <div data-cb-code> (that attribute alone marks
+it; no class, no other bookkeeping). It sits inside a normal column, beside
+other content. The code runs LIVE while editing and runs again on the saved
+page, so what the user sees in the editor is the real scene.
 
-            // Create mount function and store it on the container
-            // for the Runtime to render the plugin
-            container.mount = function() {
-                initializeSlider(); // Start initialization
-            };
-            // If no runtime, just start initialization
-            if (!window.builderRuntime) {
-                initializeSlider();
-            }
+<div data-cb-code>
+    <div class="scene3d-stage" style="width:100%; aspect-ratio:16/9; position:relative; overflow:hidden; border-radius:8px; background:#101014;"></div>
+    <script>
+        (async () => {
+            const container = document.currentScript.parentElement;   // BEFORE any await
+            const stage = container.querySelector('.scene3d-stage');
+            // ... imports, then build the scene (see Scene Shell) ...
         })();
     </script>
 </div>
 
-Remember: The goal is to create code blocks that are **self-contained**, **conflict-free**, and **easy to integrate** into any HTML environment. Follow these patterns for consistent, reliable code block development.
-
-### Important:
-
-**Code Block can only be placed**:
-
-- in content (inside div.column)
-- in overlay (must be in div.is-overlay-content)
+ONE async IIFE wraps the whole script — do not nest a second wrapper
+function, and close it with exactly one })(); at the end. Read
+document.currentScript on the first line: it is only set before the first
+await.
+
+Rules that keep it healthy in the editor:
+- Plain classic <script> tags only — never type="module" (dynamic import()
+  inside the classic script is the way to load modules).
+- Query elements from the container (document.currentScript.parentElement),
+  not by id — the block can be duplicated, and container-scoped queries stay
+  correct in every copy.
+- The editor re-renders the block on edit, undo and duplicate, and each
+  render runs the code again on FRESH elements. Anything that keeps running
+  — the render loop, timers, window/document listeners — must stop by itself
+  when its elements leave the page. The shell's loop below does this with an
+  isConnected check; apply the same rule to any setInterval or listener you
+  add outside the loop.
+- The stage div is styled inline (width 100% + aspect-ratio); make it taller
+  or full-bleed by changing that style, not by touching anything outside the
+  block.
+
+## 2. Loading three.js
+
+Load as ES modules with dynamic import inside the script. Use jsdelivr's
++esm build and PIN the version — addons then resolve their internal 'three'
+import to the same module instance, so no import map is needed:
+
+const THREE = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/+esm');
+const { OrbitControls } = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/controls/OrbitControls.js/+esm');
+const { GLTFLoader } = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/loaders/GLTFLoader.js/+esm');
+const { MeshoptDecoder } = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/libs/meshopt_decoder.module.js/+esm');
+const { RoomEnvironment } = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/environments/RoomEnvironment.js/+esm');
+const { Sky } = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/objects/Sky.js/+esm');
+
+Import only what the scene uses. Every addon lives under examples/jsm/ with
+the same /+esm suffix.
+
+## 3. The Scene Shell — always
+
+const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });   // preserveDrawingBuffer: required by the view_render self-check
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+renderer.toneMapping = THREE.ACESFilmicToneMapping;
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+stage.appendChild(renderer.domElement);
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(40, 1, 0.1, 200);
+
+// ENVIRONMENT LIGHT — the single biggest quality lever. Pick one:
+// (a) Indoor / product / abstract: the built-in room, no files needed.
+const pmrem = new THREE.PMREMGenerator(renderer);
+scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+// (b) Outdoor: a physical sky that also LIGHTS the scene — see Environments.
+// (c) A specific mood: an equirect .hdr URL via RGBELoader, same mapping.
+
+// KEY LIGHT with soft shadows grounds the objects.
+const sun = new THREE.DirectionalLight(0xfff2e0, 2.2);
+sun.position.set(4, 6, 3);
+sun.castShadow = true;
+sun.shadow.mapSize.set(2048, 2048);
+sun.shadow.radius = 5;
+sun.shadow.bias = -0.0005;
+scene.add(sun);
+
+// SIZE to the stage, not the window. Handles editor column resizes too.
+function resize() {
+    const w = stage.clientWidth, h = stage.clientHeight;
+    if (!w || !h) return;
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+    renderer.setSize(w, h);
+}
+new ResizeObserver(resize).observe(stage);
+resize();
+
+// LOOP — stops itself when this render is replaced (edit/undo/duplicate),
+// and pauses while the block is off-screen or the tab is hidden.
+let visible = true;
+new IntersectionObserver(function(e) { visible = e[0].isIntersecting; }).observe(stage);
+const clock = new THREE.Clock();
+renderer.setAnimationLoop(function() {
+    if (!stage.isConnected) {              // this render was discarded
+        renderer.setAnimationLoop(null);
+        renderer.dispose();
+        return;
+    }
+    if (!visible || document.hidden) return;
+    const dt = Math.min(clock.getDelta(), 0.05);
+    // ... update(dt) ...
+    renderer.render(scene, camera);
+});
 
-**In Content**
+Materials: MeshStandardMaterial (metalness/roughness) or MeshPhysicalMaterial
+(clearcoat, transmission). With the environment set they pick up real
+reflections; without it, metals render black — that is the "flat plastic"
+failure. Shadows: castShadow/receiveShadow on meshes, receiveShadow on the
+ground. A ShadowMaterial plane (opacity ~0.35) gives a shadow-only floor for
+product shots.
+
+## 4. Objects: write code or load a .glb
+
+- WRITE CODE for man-made, regular shapes: buildings, furniture, product
+  mockups, abstract hero geometry. Compose primitives (Box, Cylinder,
+  Extrude, Lathe, RoundedBoxGeometry addon), and add a subtle CanvasTexture
+  for surface interest (wood planks, panel lines). Free, tiny, editable.
+- LOAD A .glb for organic or specific things: characters, animals, plants, a
+  real product, anything that must match a reference image. Getting one:
+  - When a generate_3d_model tool is offered, use it: give it ONE clear image
+    of the object (a photo on the page, a generate_image result, or the
+    user's attachment) and load the .glb URL it returns. For an object with
+    no image yet, generate_image first, then feed that in — image quality
+    decides model quality.
+  - When no such tool is offered, build the object from primitives with
+    real material craft instead — never fabricate a model URL.
+
+Always set the meshopt decoder (generated models are usually
+meshopt-compressed; it is harmless for plain files), and normalize — glbs
+come in arbitrary scale:
+
+const loader = new GLTFLoader();
+loader.setMeshoptDecoder(MeshoptDecoder);
+const gltf = await loader.loadAsync(url);
+const obj = gltf.scene;
+const box = new THREE.Box3().setFromObject(obj);
+const size = box.getSize(new THREE.Vector3());
+obj.scale.setScalar(TARGET_HEIGHT / Math.max(size.x, size.y, size.z));
+box.setFromObject(obj);
+const center = box.getCenter(new THREE.Vector3());
+obj.position.set(-center.x, -box.min.y, -center.z);   // centered, on the floor
+obj.traverse(function(n) { if (n.isMesh) { n.castShadow = true; n.receiveShadow = true; } });
+scene.add(obj);
+
+## 5. Environments (outdoor scenes)
+
+SKY THAT LIGHTS THE SCENE — golden hour in a few lines, no texture files:
+
+const sky = new Sky();
+sky.scale.setScalar(4000);
+scene.add(sky);
+const sunDir = new THREE.Vector3().setFromSphericalCoords(1,
+    THREE.MathUtils.degToRad(90 - 6),      // elevation: 2-8 = sunset, 30+ = day
+    THREE.MathUtils.degToRad(245));        // azimuth
+sky.material.uniforms.sunPosition.value.copy(sunDir);
+sky.material.uniforms.turbidity.value = 6;
+sky.material.uniforms.rayleigh.value = 2.2;
+scene.environment = pmrem.fromScene(sky, 0.02).texture;   // the sky IS the light
+sun.position.copy(sunDir).multiplyScalar(120);            // key light matches it
+renderer.toneMappingExposure = 0.55;                      // Sky is bright; tune 0.4-0.7
+scene.fog = new THREE.FogExp2(0xe8c8a0, 0.0035);          // depth haze sells distance
+
+TERRAIN — a displaced plane. Define ONE height function and reuse it for
+placing everything (grass, props) so nothing floats:
+
+function ground(x, z) {
+    return 1.1 * Math.sin(x * 0.045 + 1) * Math.cos(z * 0.05)
+         + 0.5 * Math.sin(x * 0.11 + 2.3) * Math.sin(z * 0.13 + 1.1);
+}
+Build a PlaneGeometry(240, 240, 180, 180), rotateX(-PI/2), set each vertex y
+from ground(x, z), give vertices green colors varied by height, then
+computeVertexNormals() and a MeshStandardMaterial({ vertexColors: true,
+roughness: 1 }).
+
+WATER — a large plane with a dark blue-grey MeshStandardMaterial and
+roughness around 0.15. With the sky environment set it reflects the sunset
+by itself. Place it below the terrain edge.
+
+GRASS / vegetation — NEVER individual meshes, always ONE InstancedBufferGeometry
+draw call. One tapered blade (a 4-row triangle strip about 0.018 wide, 1 tall),
+instanced 50k-150k times with per-instance attributes: offset vec3 (position,
+y from ground()), data vec4 (rotation angle, height 0.35-0.9, wind phase,
+tint 0.8-1.2). A small ShaderMaterial does the rest:
+- vertex: scale by height, bend tip (p.z += t*t*0.1), rotate by angle, sway by
+  sin(time * 1.5 + phase + offset.x * 0.15) * 0.14 * t * t, add offset.
+- fragment: mix a dark base green (0.07, 0.13, 0.03) to a light tip green
+  (0.38, 0.46, 0.13) by the blade's v coordinate, times tint; optionally add a
+  small warm term at the very tip for sunset scenes.
+Scatter on a disc around the focal point (radius * sqrt(random) keeps it
+even), skip blades under objects, set instanceCount, frustumCulled = false,
+side: THREE.DoubleSide. Update the time uniform in the loop. The same
+technique makes flowers, reeds and starfields — change the geometry and count.
+
+## 6. Interaction
+
+HOVER + CLICK on 3D objects — a raycaster against the renderer bounds (never
+window coordinates; the canvas is inside a column):
+
+const ray = new THREE.Raycaster();
+const pointer = new THREE.Vector2();
+function pick(e) {
+    const r = renderer.domElement.getBoundingClientRect();
+    pointer.set(((e.clientX - r.left) / r.width) * 2 - 1,
+                -((e.clientY - r.top) / r.height) * 2 + 1);
+    ray.setFromCamera(pointer, camera);
+    const hit = ray.intersectObjects(pickables, true)[0];
+    return hit ? hit.object : null;
+}
+renderer.domElement.addEventListener('pointermove', function(e) {
+    const o = pick(e);
+    renderer.domElement.style.cursor = o ? 'pointer' : '';
+    // hover response: scale/emissive lerp in the loop, not a snap
+});
+renderer.domElement.addEventListener('click', function(e) {
+    const o = pick(e); if (o) { /* select, open, score ... */ }
+});
 
-<div class="row">
-    <div class="column">
-  		<div data-cb-type="code">
-        <!-- Your Code -->
-      </div>
-  	</div>
-</div>
+Animate responses smoothly in the loop (lerp toward a target scale/rotation/
+color) instead of setting values on the event — that is what makes it feel
+polished. Camera orbit: OrbitControls with enableDamping = true; constrain
+(maxPolarAngle, min/maxDistance) so users cannot go under the floor.
+
+REVEAL PATTERNS — a click should MEAN something, not just wobble. Four
+recurring shapes, all built from the same pieces (pick + lerp + HTML):
+
+CAMERA FOCUS (product tour): click an object, fly the camera to frame it,
+and offer the way back.
+
+let camTo = null, lookTo = null;
+function focus(obj) {
+    const p = new THREE.Vector3();
+    obj.getWorldPosition(p);
+    camTo = p.clone().add(new THREE.Vector3(1.4, 0.8, 2.0));  // offset that frames it
+    lookTo = p.clone();
+    backBtn.style.display = 'block';
+}
+function overview() {
+    camTo = HOME_POS.clone(); lookTo = HOME_TARGET.clone();
+    backBtn.style.display = 'none'; card.style.display = 'none';
+}
+// in the loop:
+if (camTo) {
+    const k = 1 - Math.exp(-dt * 4);
+    camera.position.lerp(camTo, k);
+    controls.target.lerp(lookTo, k);
+    if (camera.position.distanceTo(camTo) < 0.01) { camTo = null; lookTo = null; }
+}
+controls.addEventListener('start', function() { camTo = null; lookTo = null; });  // user drag wins
+
+INFO CARD: the revealed details are real HTML overlaid on the stage — never
+3D text. A fixed-position card (absolute inside the stage, e.g. right side)
+reads better than one tracking the 3D point, and never clips. Fill it per
+object from a plain data object keyed by mesh name; give it a real <button>
+to close, and close on Escape too. Selectable, accessible, translatable.
+
+STATE REVEAL: the click changes the scene itself — a lid opens, parts fan
+out into an exploded view, the chosen item stays lit while the rest dim.
+Record each part's home transform at build time, keep one 0..1 reveal value
+per group, and lerp every part between home and revealed each frame from
+that value. Dimming: lerp material color or opacity, never a CSS filter.
+
+SCENE-TO-PAGE REVEAL: when the revealed content belongs in the page (specs,
+paragraphs, a price table), toggle a normal HTML element NEXT TO the stage
+instead of an overlay. The content stays selectable and readable without
+WebGL; the scene is the index, the page is the content.
+
+Shared rules: one selection at a time; clicking empty space = Back; Back and
+close are real, keyboard-reachable buttons; everything moves through the
+loop's lerp, nothing snaps.
+
+Touch: pointer events above already cover it; OrbitControls handles touch
+orbit. Do not call preventDefault on wheel/touch you do not use — the page
+must keep scrolling normally past the block.
+
+SCROLL-DRIVEN scenes: read progress from the block's own position — works
+everywhere:
+
+function scrollProgress() {   // 0 when entering, 1 when leaving
+    const r = stage.getBoundingClientRect();
+    return THREE.MathUtils.clamp((innerHeight - r.top) / (innerHeight + r.height), 0, 1);
+}
+Call it in the loop and drive camera/objects from it (again through lerp for
+smoothness). On a ContentBox page whose section has data-fx-emit, prefer the
+host's event: container.closest('.is-section').addEventListener('fx:progress',
+function(e) { p = e.detail.progress; }).
+
+## 7. Games (3D)
+
+Game craft — loop, input, state machine, HUD, sound, recycling, cleanup —
+lives in the "games" reference: load it for any game. This section is only
+what makes a THREE.JS game look and feel right:
+
+- The Scene Shell applies to games in full. Environment lighting, real
+  materials, fog and shadows are what separate a game from a tech demo —
+  never fall back to flat MeshBasicMaterial arcade defaults. Emissive
+  materials + bloom give the cheap "neon glow" so many game styles want.
+- HERO ASSETS: the 2-3 entities that carry the whole look — the player
+  craft, the collectible, one signature obstacle — deserve generated models
+  (generate_3d_model when offered). Load each .glb ONCE, then obj.clone()
+  per spawn; cloning is as cheap as cloning boxes, so recycling pools work
+  unchanged. This single choice is the difference between "colored cubes"
+  and a game with an identity.
+- FILLER stays coded, but crafted: RoundedBoxGeometry over BoxGeometry,
+  slight bevels, emissive rims, vertex-colored gradients — never bare
+  saturated boxes.
+- Movement feel: lerp positions and tilt/bank the player toward its motion;
+  camera follows with damping, never rigidly.
+- Update per frame from the update(dt) function; collisions at this scale
+  are distance checks (player.position.distanceTo(e.position) < r1 + r2).
+
+## 8. Self-check — see your work
+
+When a view_render tool is offered, ALWAYS call it after creating a scene or
+making a significant visual change, and LOOK at the screenshot before
+answering:
+- All black or flat: the environment/lighting is missing, or every object is
+  outside the camera view.
+- Empty or nearly empty: camera position/target does not frame the content —
+  check object positions and scale.
+- Clipped, tiny or washed out: adjust framing, scale or exposure.
+Fix what is wrong, re-check once, and only then answer. Do not describe a
+scene you have not seen. (The screenshot shows the canvas only — HTML
+overlays are not in it.)
+
+Judge the render like an art director: the bar is FINISHED, not merely
+correct. A right-shaped scene rendered badly — glaring or flat light, dead
+materials, awkward framing, harsh exposure — is not done. Weigh the impact
+yourself, and reach for the cheap lever first:
+- Anything fixable in code — lighting, environment, exposure, camera,
+  materials, scale — is FREE. If a change would noticeably improve the
+  scene, make it.
+- Regenerating a model costs the user money. Do it only when the asset
+  itself is the problem (mangled geometry, clearly the wrong object) and
+  code cannot compensate — better light, exposure and framing rescue a
+  mediocre asset more often than a re-roll does.
+When the scene genuinely reads well, it is done — stop; do not iterate on
+differences a viewer would not notice.
+
+## 9. Performance & hygiene
+
+- One scene per block; reuse geometries/materials; instancing for anything
+  repeated more than ~20 times.
+- Keep pixelRatio capped at 2 and shadow maps at 2048 or below.
+- The visibility pause in the shell is mandatory — a page can hold several
+  blocks and background tabs must not burn CPU.
+- Respect prefers-reduced-motion: if it matches, skip autonomous camera
+  motion and wind sway; render still frames on interaction only.
+- Do not touch document-level styles, and never assume the block is the only
+  3D on the page.
+`;
 
-**In Overlay**
+/*
+ * context-games.js — the "games" on-demand doc topic for Code Chat v2.
+ *
+ * Loaded via get_framework_docs for ANY game request, 2D or 3D. It owns the
+ * craft every game shares (loop, input, state, HUD, sound, cleanup) plus the
+ * 2D Canvas branch; a 3D game additionally loads the "3d" topic, whose games
+ * section holds only the 3D-specific rendering rules.
+ *
+ * Asset reality check (user-verified, Sept 2026): most image models FAIL at
+ * transparent PNGs — sprites are requested on solid backgrounds and handled
+ * in code. Never instruct the model to ask for transparency.
+ * Keep code samples free of backticks and ${ } — template literal.
+ */
 
-<div class="is-section is-box is-section-100 type-system-ui">
-    <div class="is-overlay">
-        <div class="is-overlay-content">
-            <div data-cb-type="code" style="position: absolute; top:0, left:0; width: 100%; height: 100%">
-        			<!-- Your Code -->
-            </div>
-        </div>
+const contextGames = `
+# Building Games
+
+Use this for any playable game. First decide the dimension — it changes the
+whole toolchain:
+
+- 2D (doodle, flat, sprite, puzzle, casual, "simple game"): the Canvas 2D
+  API in a code block. Do NOT use three.js for these — it is heavier, slower
+  to write, and fights the flat aesthetic.
+- 3D (depth, camera, "3D"): three.js — ALSO load the "3d" reference and
+  follow its games section for rendering and assets.
+
+Target scale either way: an arcade mini-game — one scene, one core mechanic,
+polished. Refine with the user over turns.
+
+## The skeleton every game shares
+
+Everything lives in one code block (see the "code" reference for the block
+contract). Inside it:
+
+- LOOP: requestAnimationFrame with a clamped delta; stop yourself when the
+  block is re-rendered:
+
+    let last = performance.now();
+    function frame(now) {
+        if (!stage.isConnected) return;           // this render was replaced
+        const dt = Math.min((now - last) / 1000, 0.05);
+        last = now;
+        update(dt); draw();
+        requestAnimationFrame(frame);
+    }
+    requestAnimationFrame(frame);
+
+- INPUT: one flags object; keyboard listeners attach on game start (the
+  start click also gives focus), ignore keys while the user types elsewhere,
+  and detach themselves via the isConnected check. Map pointerdown /
+  pointermove on the stage to the same flags so touch works. Do not
+  preventDefault on events you do not use — the page must keep scrolling.
+- STATE: a small machine — ready / playing / over — with restart resetting
+  state, never reloading. Show "click or tap to start".
+- HUD: HTML positioned over the stage (score, lives, messages) — real text,
+  updated via textContent, never drawn glyph-by-glyph into the canvas.
+- SOUND: only if asked; short WebAudio oscillator beeps, no external files.
+- ENTITIES: recycle, never allocate per frame — spawn from a pool, move
+  off-screen items back in.
+- SELF-CHECK: when a view_render tool is offered, screenshot after building
+  and after big visual changes, judge it, fix, re-check once.
+
+## 2D games (Canvas 2D)
+
+Setup — crisp on every screen:
+
+<div data-cb-code>
+    <div class="game-stage" style="position:relative; width:100%; aspect-ratio:16/10; overflow:hidden; border-radius:8px; background:#fdfdf8;">
+        <canvas style="position:absolute; inset:0; width:100%; height:100%;"></canvas>
+        <!-- HUD elements here -->
     </div>
-  
-    <!-- ... -->
+    <script>
+        (async () => {
+            const container = document.currentScript.parentElement;
+            const stage = container.querySelector('.game-stage');
+            const canvas = stage.querySelector('canvas');
+            const ctx = canvas.getContext('2d');
+            function fit() {
+                const dpr = Math.min(devicePixelRatio, 2);
+                canvas.width = stage.clientWidth * dpr;
+                canvas.height = stage.clientHeight * dpr;
+                ctx.setTransform(dpr, 0, 0, dpr, 0, 0);   // draw in CSS pixels
+            }
+            new ResizeObserver(fit).observe(stage);
+            fit();
+            // ... game ...
+        })();
+    </script>
 </div>
+
+Collision at this scale is rectangles and circle distances — no physics
+library unless the game truly is physics.
+
+ART DIRECTION — a 2D game must look intentional, not like debug rectangles:
+pick a style (hand-drawn doodle, flat pastel, neon minimal) and carry it
+through background, entities, HUD typography and even the game-over screen.
+
+- DOODLE STYLE, pure code: draw with strokes, not fills — rounded lineJoin,
+  slightly thick lines, and a small random jitter added to each vertex,
+  re-rolled only a few times per second (a wobble timer, not every frame) so
+  shapes shiver like a flipbook. Paper background (#fdfdf8, faint grid),
+  handwritten-feel HUD (a casual system font, slight rotation).
+- SPRITES from generate_image, when the style needs real drawings: request
+  each sprite "on a plain solid white background, no shadow" in one
+  consistent style. Do NOT request transparent backgrounds — image models
+  usually fail at true transparency, delivering fake checkerboards or dirty
+  edges. Then either:
+  - design the game on the SAME background color, so the sprite's white
+    simply disappears (the doodle-on-paper trick — zero code); or
+  - key it out at load: draw to an offscreen canvas, getImageData, and set
+    alpha 0 on pixels close to the corner color (tolerance ~28); cache the
+    result and draw that.
+- Parallax sells motion cheaply: two or three background layers scrolling at
+  different speeds.
+
+## 3D games
+
+Load the "3d" reference and follow its games section. The short version:
+the scene shell (environment light, real materials, fog) applies to games
+exactly as to scenes — no flat-material arcade fallback — and the 2-3 hero
+entities that carry the look (player, collectible, signature obstacle)
+deserve generated models, loaded once and cloned per spawn.
 `;
 
 const contextDesignGuide = `
@@ -88961,7 +89874,7 @@ class ContentBuilder {
     this.ShortcutInfo = new ShortcutInfo(this);
     if (!this.opts.isContentBox) {
       this.codechat = new CodeChat({
-        context: contextContentFramework + contextCodeBlock + contextDesignGuide
+        context: contextContentFramework + getContextCodeBlock() + contextDesignGuide
       }, this);
 
       /*
@@ -88976,10 +89889,16 @@ class ContentBuilder {
         attachCodeChatV2(this.codechat, this, {
           contextParts: {
             content: contextContentFramework,
-            designCore: contextDesignGuide
+            designCore: contextDesignGuide,
+            code: getContextCodeBlock(),
+            // on-demand 'code' doc topic
+            '3d': context3D,
+            // on-demand '3d' doc topic
+            games: contextGames // on-demand 'games' doc topic
           }
         });
       }
+
       if (this.startAIAssistant) {
         this.openAIAssistant();
       }
@@ -91937,6 +92856,90 @@ class ContentBuilder {
   openFilePicker(type, callback) {
     this.openAssetSelect(type, callback);
   }
+
+  /**
+   * Is an asset manager reachable for this type of file? Mirrors the branches
+   * openAsset() takes: either a picker page (filePicker / imageSelect / ...)
+   * or the host's own onXSelectClick handler.
+   */
+  hasFilePicker(type) {
+    if (type === 'media') return !!(this.onMediaSelectClick || this.onImageSelectClick || this.mediaSelect || this.imageSelect);
+    if (type === 'video') return !!(this.onVideoSelectClick || this.videoSelect);
+    if (type === 'audio') return !!(this.onAudioSelectClick || this.audioSelect);
+    if (type === 'all') return !!(this.onFileSelectClick || this.fileSelect);
+    return !!(this.onImageSelectClick || this.imageSelect);
+  }
+
+  /**
+   * Upload a file from the user's computer and hand its URL to `callback`.
+   *
+   * The per-type upload handler always exists — a builder configured without
+   * one gets the data-URL fallback — so this is available whatever the host
+   * set up. The URL comes back through returnUrl(), the same path the image
+   * tool's upload button uses.
+   */
+  openFileUpload(type, callback) {
+    const accept = type === 'video' ? 'video/*' : type === 'audio' ? 'audio/*' : type === 'media' ? 'image/*,video/*' : type === 'all' ? '*' : 'image/*';
+    const handler = type === 'video' ? this.onVideoUpload : type === 'audio' ? this.onAudioUpload : type === 'media' ? this.onMediaUpload : type === 'all' ? this.onFileUpload : this.onImageUpload;
+    if (!handler) return;
+    const inpFile = document.createElement('input');
+    inpFile.type = 'file';
+    inpFile.accept = accept;
+    inpFile.style.display = 'none';
+    document.body.appendChild(inpFile);
+    inpFile.addEventListener('change', async e => {
+      if (!e.target.files || !e.target.files.length) {
+        inpFile.remove();
+        return;
+      }
+      this.onAssetUpload = url => {
+        if (callback) callback(url);
+      };
+      await handler(e);
+      inpFile.remove();
+    });
+    inpFile.click();
+  }
+
+  /**
+   * The file controls for a URL field in a plugin's settings: select from the
+   * asset manager, and upload from the computer.
+   *
+   * Returns the buttons to append next to the input, in the order and with the
+   * icons the editor's own image dialog uses — select first, upload last, and
+   * select only where an asset manager is configured. A plugin appends what it
+   * gets rather than deciding, so a builder without an asset manager never
+   * shows a button that cannot open one.
+   *
+   *   const [ ...buttons ] = builder.createFileButtons('media', (url) => {...});
+   *   row.append(input, ...buttons);
+   *
+   * `type` may be a function for a field whose kind follows another control
+   * (a Media Type select, say) — it is then read on each click.
+   */
+  createFileButtons(type, callback) {
+    const out = s => this.util.out(s);
+    const fileType = () => typeof type === 'function' ? type() : type;
+    const button = (label, icon, onClick) => {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'cbx-iconbtn';
+      btn.title = label;
+      btn.setAttribute('aria-label', label);
+      btn.innerHTML = `<svg aria-hidden="true"><use xlink:href="#${icon}"></use></svg>`;
+      btn.addEventListener('click', e => {
+        e.preventDefault();
+        onClick(btn);
+      });
+      return btn;
+    };
+    const buttons = [];
+    if (this.hasFilePicker(fileType())) {
+      buttons.push(button(out('Select'), 'icon-folder', btn => this.openFilePicker(fileType(), callback, btn)));
+    }
+    buttons.push(button(out('Upload'), 'icon-upload', () => this.openFileUpload(fileType(), callback)));
+    return buttons;
+  }
   openAssetSelect(targetAssetType, callback, defaultValue) {
     const inpUrl = document.createElement('input');