@luckydraw/cumulus 1.0.0 → 1.0.2

package/dist/gateway/static/blex-render.js

@@ -0,0 +1,399 @@
+/**
+ * Cumulus shared blex renderer (task 131, item 3).
+ *
+ * ONE renderer, many surfaces. The standalone chat widget and any embedding app
+ * (the web-app-agent kit, kalendeer, …) drive this same file through an injected
+ * adapter, rather than each re-deriving a port of it. Copying the port is what
+ * guarantees drift in every consumer at once.
+ *
+ * Served by the gateway at /blex-render.js. It is plain ES5-compatible script —
+ * no modules, no build step — so a browser can load it directly, cross-origin.
+ *
+ * ── Adapter contract ────────────────────────────────────────────────────────
+ * Required:
+ *   allowType(type)            -> boolean. Which block types this surface renders.
+ *   getInput()                 -> the text input element, or null.
+ *   getSendButton()            -> the send button element, or null.
+ * Optional (default to no-ops, which is what makes a surface render-only):
+ *   addChip(interaction, handle, sourceId)
+ *   readPersisted(storeKey)    -> previously stored interaction value
+ *   persist(storeKey, value)
+ *   onRendered(container, storeKey)
+ *
+ * A surface that supplies only the three required members gets render-only
+ * behaviour for free: interactions that complete locally still work, and
+ * deferred ones land in a no-op instead of a dead button.
+ */
+(function (global) {
+  'use strict';
+
+  // ── Fenced-code spans ──────────────────────────────────────────────────────
+  //
+  // Held as a source string, not a shared RegExp object — a /g regex carries
+  // lastIndex state, and these call sites must not be able to affect each other.
+  var CODE_FENCE_SRC = '```([^\\n`]*)\\n([\\s\\S]*?)```';
+  var BLEX_FENCE_SRC = '~~~blex:(\\w[\\w-]*)\\n([\\s\\S]*?)\\n~~~';
+
+  function codeFenceRe() {
+    return new RegExp(CODE_FENCE_SRC, 'g');
+  }
+
+  function findCodeFenceSpans(text) {
+    var spans = [];
+    var re = codeFenceRe();
+    var m;
+    while ((m = re.exec(text)) !== null) {
+      spans.push([m.index, m.index + m[0].length]);
+    }
+    return spans;
+  }
+
+  /**
+   * Replace ~~~blex fences with \x00BLEX_n\x00 tokens.
+   *
+   * A fence INSIDE a code block is an example being displayed, not a block to
+   * render — extracting it would delete it from the code block that exists to
+   * show it. String.replace reports offsets into the original string, so one
+   * pass over precomputed spans is enough.
+   */
+  function extractBlocks(text) {
+    var blocks = [];
+    var protectedSpans = findCodeFenceSpans(text);
+    var replaced = text.replace(
+      new RegExp(BLEX_FENCE_SRC, 'g'),
+      function (match, type, json, offset) {
+        for (var i = 0; i < protectedSpans.length; i++) {
+          if (offset >= protectedSpans[i][0] && offset < protectedSpans[i][1]) return match;
+        }
+        var idx = blocks.length;
+        blocks.push({ type: type, json: json.trim(), idx: idx });
+        return '\x00BLEX_' + idx + '\x00';
+      }
+    );
+    return { text: replaced, blocks: blocks };
+  }
+
+  function escapeHtml(text) {
+    var div = document.createElement('div');
+    div.textContent = text;
+    return div.innerHTML;
+  }
+
+  /** The original fence text, reconstructed for display. */
+  function fenceSource(block) {
+    return '~~~blex:' + block.type + '\n' + block.json + '\n~~~';
+  }
+
+  /**
+   * HTML for one placeholder container.
+   *
+   * The container carries the raw fence as its body. `render()` clears it before
+   * rendering, so a CLAIMED container is unchanged — but an unclaimed one shows
+   * what the author actually wrote instead of a blank rectangle. Containers go
+   * unclaimed on several real paths: user messages and changelog entries (which
+   * render markdown but never call render()), any page where blex.min.js failed
+   * to fetch, and — deliberately — any block type the adapter denies.
+   *
+   * opts.streaming suppresses the fallback: a completed-but-not-yet-rendered
+   * fence would otherwise flash its JSON before flipping to the rendered block.
+   */
+  function placeholderHtml(idx, block, opts) {
+    var streaming = !!(opts && opts.streaming);
+    var body =
+      streaming || !block
+        ? ''
+        : '<pre class="blex-fallback">' + escapeHtml(fenceSource(block)) + '</pre>';
+    return '<div class="blex-block-container" data-blex-idx="' + idx + '">' + body + '</div>';
+  }
+
+  /** Replace every \x00BLEX_n\x00 token in rendered HTML with its placeholder. */
+  function insertPlaceholders(html, blocks, opts) {
+    // The NUL is a deliberate in-band sentinel: it cannot occur in model output,
+    // so a token can never be forged by message content.
+    // eslint-disable-next-line no-control-regex
+    return html.replace(/\x00BLEX_(\d+)\x00/g, function (_, idx) {
+      return placeholderHtml(idx, blocks[parseInt(idx, 10)], opts);
+    });
+  }
+
+  // ── The render-only allow set ──────────────────────────────────────────────
+  //
+  // Derived, not argued. A type may render on a non-interactive surface iff every
+  // affordance it draws either completes locally or is purely visual:
+  //
+  //   table / code / file-tree / timeline / image — selection is a highlight.
+  //     Nothing is labelled with a verb; an emit landing in a no-op is invisible.
+  //   terminal / svg — labelled buttons, but clipboard write and the object-URL
+  //     download both run BEFORE the emit. The emit is a receipt, not the mechanism.
+  //   chart / status / metric / progress / gallery / kanban / calendar /
+  //     branch / layout — no clickable affordances at all.
+  //
+  // Excluded, and the reason each is excluded rather than merely unwired:
+  //   confirm / poll / form — interaction is the entire point.
+  //   diff — Apply/Reject have no local half. The emit IS the mechanism, so on a
+  //     render-only surface they are guaranteed dead buttons that read as
+  //     "click to apply" — worse than not rendering, because a dead button looks
+  //     alive in a way raw JSON does not.
+  //   mermaid — passes the affordance test (Show source / Export SVG / Export PNG
+  //     all complete locally, like terminal and svg). It used to be excluded on a
+  //     DIFFERENT axis — it could not LOAD — which is now fixed by vendoring the
+  //     library and declaring an import map (task 132). Loadability is therefore
+  //     no longer an allow-set question: it is a property of the DOCUMENT, and it
+  //     is enforced for every adapter by BARE_SPECIFIER_TYPES below.
+  var RENDER_ONLY_TYPES = [
+    'table',
+    'status',
+    'metric',
+    'progress',
+    'code',
+    'timeline',
+    'svg',
+    'image',
+    'gallery',
+    'file-tree',
+    'terminal',
+    'chart',
+    'kanban',
+    'calendar',
+    'branch',
+    'layout',
+    'mermaid',
+  ];
+
+  var INTERACTIVE_TYPES = ['confirm', 'poll', 'form', 'diff'];
+
+  // ── Load capability: a document property, checked for EVERY adapter ─────────
+  //
+  // Some renderers can only run if the PAGE resolves a bare module specifier for
+  // them. blex's mermaid renderer is the only one today: it does
+  // `await import("mermaid")`, whose sole resolution mechanism in a browser is an
+  // import map. Upstream catches the failure and paints the literal string
+  // "Mermaid render error", so a page without the mapping would show an error box
+  // where the fence used to be — worse than the fence.
+  //
+  // This is deliberately NOT expressed in the allow set. The allow set describes a
+  // surface's affordances, and the widget's adapter is `allowType: () => true`, so
+  // an allow-set entry would not govern /chat at all. One rule, both surfaces: a
+  // type whose renderer needs a bare specifier is never claimed unless the
+  // document declares an import mapping for it. A page that opts in gets real
+  // diagrams; a page that does not keeps a readable raw fence.
+  var BARE_SPECIFIER_TYPES = { mermaid: 'mermaid' };
+
+  var importMapCache = null;
+
+  /** Does this document declare an import mapping for `specifier`? */
+  function pageResolvesSpecifier(specifier) {
+    if (importMapCache === null) {
+      importMapCache = {};
+      try {
+        var maps = global.document
+          ? global.document.querySelectorAll('script[type="importmap"]')
+          : [];
+        for (var i = 0; i < maps.length; i++) {
+          var parsed = JSON.parse(maps[i].textContent || '{}');
+          var imports = parsed && parsed.imports;
+          if (!imports) continue;
+          for (var key in imports) {
+            if (Object.prototype.hasOwnProperty.call(imports, key)) importMapCache[key] = true;
+          }
+        }
+      } catch {
+        /* a malformed import map must not break every other block type */
+      }
+    }
+    return importMapCache[specifier] === true;
+  }
+
+  /** False only for a type that needs a bare specifier this page cannot resolve. */
+  function pageCanLoadType(type) {
+    var specifier = BARE_SPECIFIER_TYPES[type];
+    return !specifier || pageResolvesSpecifier(specifier);
+  }
+
+  /**
+   * An adapter for a surface that has an input but no chip tray.
+   *
+   * Denied types are NOT routed to a library fallback renderer: the global blex
+   * bundle exports BaseRenderer, getPluginInfo, getRegisteredTypes, hasBlockType,
+   * registerBlockType, registerLazyBlockType, registerPlugin, renderBlock,
+   * renderPlaceholder, unregisterBlockType, unregisterPlugin — and no fallback
+   * renderer among them. Leaving the container unclaimed reuses the raw-fence
+   * body above, which is honest and costs nothing.
+   *
+   * Deny is a per-render gate on purpose. Do NOT implement it with
+   * unregisterBlockType: the registry is module-global, so unregistering
+   * `confirm` removes it for every surface sharing that module instance.
+   */
+  function renderOnlyAdapter(overrides) {
+    var base = {
+      allowType: function (type) {
+        return RENDER_ONLY_TYPES.indexOf(type) !== -1;
+      },
+      getInput: function () {
+        return null;
+      },
+      getSendButton: function () {
+        return null;
+      },
+    };
+    if (overrides) {
+      for (var k in overrides) {
+        if (Object.prototype.hasOwnProperty.call(overrides, k)) base[k] = overrides[k];
+      }
+    }
+    return base;
+  }
+
+  // ── Handle lifecycle ───────────────────────────────────────────────────────
+
+  var handleMap = typeof WeakMap !== 'undefined' ? new WeakMap() : null;
+
+  function trackHandle(el, handle) {
+    if (!handleMap) return;
+    var existing = handleMap.get(el) || [];
+    existing.push(handle);
+    handleMap.set(el, existing);
+  }
+
+  function destroy(el) {
+    if (!handleMap) return;
+    var handles = handleMap.get(el);
+    if (!handles) return;
+    handles.forEach(function (h) {
+      try {
+        h.destroy();
+      } catch {
+        /* a renderer that cannot tear down must not block the rest */
+      }
+    });
+    handleMap.delete(el);
+  }
+
+  function errorBox(message) {
+    return (
+      '<pre style="color:#f66;font-size:0.85em;padding:0.5em;">' + escapeHtml(message) + '</pre>'
+    );
+  }
+
+  function callOptional(adapter, name, args) {
+    if (adapter && typeof adapter[name] === 'function') {
+      return adapter[name].apply(adapter, args);
+    }
+    return undefined;
+  }
+
+  /**
+   * Render extracted blocks into the placeholder containers inside `el`.
+   *
+   * opts: { msgKey, streaming, keyPrefix }
+   */
+  function render(el, blocks, adapter, opts) {
+    if (!blocks || blocks.length === 0) return;
+    // Contract violation, checked before the library guard: an adapter without
+    // allowType is a programming error and must surface whether or not blex
+    // happened to load, otherwise it hides until the first page that has blex.
+    if (!adapter || typeof adapter.allowType !== 'function') {
+      throw new Error('[blex] render() requires an adapter with allowType()');
+    }
+    if (typeof global.Blex === 'undefined') {
+      // The raw-fence fallback is already in the DOM, so the reader sees the
+      // payload rather than a blank box. warn, not error: some embedders fail
+      // their build gate on any console error.
+      console.warn('[blex] library not loaded — leaving raw fences in place');
+      return;
+    }
+    var options = opts || {};
+    var streaming = !!options.streaming;
+    var msgKey = options.msgKey;
+
+    var containers = el.querySelectorAll('.blex-block-container');
+    Array.prototype.forEach.call(containers, function (container) {
+      var idx = parseInt(container.getAttribute('data-blex-idx'), 10);
+      if (isNaN(idx) || idx >= blocks.length) return;
+      var block = blocks[idx];
+      // Checked before allowType: this one is about the DOCUMENT, not the
+      // surface, so it applies even to an allow-everything adapter.
+      if (!pageCanLoadType(block.type)) {
+        // Deliberately unclaimed — the raw fence stays visible, which beats the
+        // error box upstream would paint.
+        console.warn(
+          '[blex] ' +
+            block.type +
+            ' needs an import map this page does not declare — leaving the fence in place'
+        );
+        return;
+      }
+      if (!adapter.allowType(block.type)) {
+        // Deliberately unclaimed — the raw fence stays visible.
+        console.warn('[blex] type not rendered on this surface: ' + block.type);
+        return;
+      }
+      var storeKey = msgKey ? msgKey + ':' + idx : null;
+
+      try {
+        var data = JSON.parse(block.json);
+        var blockObj = { type: block.type, id: block.type + '-' + idx, data: data };
+
+        // Claim the container: drop the raw-fence fallback. Bad JSON throws
+        // before this line and is reported by the catch below, which names the
+        // problem — better than either the fallback or a blank box.
+        container.innerHTML = '';
+
+        if (streaming) {
+          global.Blex.renderPlaceholder(block.type, container);
+          return;
+        }
+
+        var renderOpts = {};
+        var previous = callOptional(adapter, 'readPersisted', [storeKey]);
+        if (previous !== undefined) renderOpts.previousValue = previous;
+
+        global.Blex.renderBlock(blockObj, container, renderOpts)
+          .then(function (handle) {
+            trackHandle(el, handle);
+            callOptional(adapter, 'onRendered', [container, storeKey]);
+            if (!handle || !handle.onInteraction) return;
+            handle.onInteraction(function (interaction) {
+              if (storeKey && interaction.value !== undefined) {
+                callOptional(adapter, 'persist', [storeKey, interaction.value]);
+              }
+              if (!interaction.serialized) return;
+              var inputEl = adapter.getInput();
+              if (!inputEl) return;
+              if (interaction.immediate) {
+                var existingText = (inputEl.value || '').trim();
+                inputEl.value = existingText
+                  ? existingText + '\n\n' + interaction.serialized
+                  : interaction.serialized;
+                inputEl.dispatchEvent(new Event('input', { bubbles: true }));
+                var sendBtn = adapter.getSendButton();
+                if (sendBtn) sendBtn.click();
+              } else {
+                callOptional(adapter, 'addChip', [interaction, handle, block.type + '-' + idx]);
+              }
+            });
+          })
+          .catch(function (err) {
+            container.innerHTML = errorBox('Blex error: ' + (err.message || err));
+          });
+      } catch (e) {
+        container.innerHTML = errorBox('Invalid blex JSON: ' + e.message);
+      }
+    });
+  }
+
+  global.CumulusBlexRender = {
+    extractBlocks: extractBlocks,
+    placeholderHtml: placeholderHtml,
+    insertPlaceholders: insertPlaceholders,
+    fenceSource: fenceSource,
+    render: render,
+    destroy: destroy,
+    renderOnlyAdapter: renderOnlyAdapter,
+    RENDER_ONLY_TYPES: RENDER_ONLY_TYPES,
+    INTERACTIVE_TYPES: INTERACTIVE_TYPES,
+    BARE_SPECIFIER_TYPES: BARE_SPECIFIER_TYPES,
+    pageCanLoadType: pageCanLoadType,
+    CODE_FENCE_SRC: CODE_FENCE_SRC,
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/gateway/static/chat.html

@@ -9,6 +9,12 @@
   <link rel="manifest" href="/manifest.json">
   <link rel="apple-touch-icon" href="/icon-192.png">
   <title>Cumulus Chat</title>
+  <!-- blex's mermaid renderer resolves the bare specifier "mermaid" (task 132).
+       An import map is the only mechanism that can satisfy it; without this tag
+       blex-render.js leaves mermaid fences unclaimed rather than letting upstream
+       paint "Mermaid render error". The URL is stamped with a content hash at
+       serve time by stampAssetUrls(). -->
+  <script type="importmap">{"imports":{"mermaid":"/mermaid-esm.js"}}</script>
   <style>
     *, *::before, *::after { box-sizing: border-box; }
     html, body {
@@ -24,6 +30,7 @@
 </head>
 <body>
   <script src="/blex.min.js" onload="console.log('[blex] blex.min.js loaded, Blex:', typeof Blex)" onerror="console.error('[blex] FAILED to load blex.min.js')"></script>
+  <script src="/blex-render.js"></script>
   <script src="/widget.js" data-standalone="true" data-api-key=""></script>
 </body>
 </html>