aimeat 2.1.0 → 2.3.0

package/dist/public/cortex-bundled/aimeat-surface.yaml

@@ -0,0 +1,107 @@
+apiVersion: cortex.aimeat.org/v1
+kind: Extension
+metadata:
+  name: aimeat-surface
+  namespace: aimeat
+  description: "The panel-spec surface engine: turn a plain-language request into ONE panel spec, resolve its data source into rows, and render them through the node's UI packs (stats / table / chart / timeline / brief / options). Data sources are plugins — memory and inline ship built in, the app registers the rest, and the registered sources assemble the composer's own prompt. Renders the panel BODY only; card, frame and persistence belong to the host."
+  author: AIMEAT
+  tags: [surface, panel, spec, ai, compose, dashboard, living-surface, ui]
+  labels:
+    domain: ui
+
+spec:
+  version: "1.1.0"
+  license: MIT
+  components:
+    - type: prompt
+      name: surface-assistant
+      content: |
+        You are a living-surface assistant for an AIMEAT app. The user's node is at {{node_url}}.
+
+        aimeat-surface turns "show me X" into a rendered panel. The app never hand-builds a
+        dashboard: it composes a PANEL SPEC, resolves the spec's source into rows, and renders.
+        The same spec can be a card in one product and a frame on a canvas in another, because
+        the engine renders the BODY only.
+
+        Include the packs it renders through, then this one:
+        <script src="{{node_url}}/v1/cortex/aimeat-ui-viewers/libs/aimeat-ui-viewers.js"></script>
+        <script src="{{node_url}}/v1/cortex/aimeat-ui-motion/libs/aimeat-ui-motion.js"></script>
+        <script src="{{node_url}}/lib/chartjs@4.js"></script>
+        <script src="{{node_url}}/v1/cortex/aimeat-charts/libs/aimeat-charts.js"></script>
+        <script src="{{node_url}}/v1/cortex/aimeat-surface/libs/aimeat-surface.js"></script>
+        Every pack call has a plain-DOM fallback, so a missing pack degrades instead of blanking
+        the panel — but load them and the surface looks like one product.
+
+        const surface = AIMEAT.surface.create({ appId: APP_ID, locale: 'fi' });
+
+        THE PANEL SPEC is the whole contract:
+          { id, title, kind, intent, source, view, needsYou, updatedAt, author }
+          kind:   stats | table | chart | timeline | brief | options
+          source: { type, ... }        resolved by a registered source
+          view:   per kind —
+            table    {"columns":[{"key","label"}]}        (omit and columns are auto-picked)
+            chart    {"chartType":"bar|line|pie|doughnut","labelKey","valueKeys":[]}
+            stats    {"tiles":[{"label","key","agg":"count|sum|avg|latest","format":"usd|eur","sparkKey"}]}
+            timeline {"tsKey","textKey"}
+            brief    {"markdown":"…"}
+            options  {"items":[{"title","body"}],"chosen":{…}}
+
+        DATA SOURCES ARE PLUGINS. Built in: memory (owner-scope read by key prefix, which also
+        picks up what the owner's AGENTS wrote) and inline. Register anything else the app can
+        fetch — and note the consequence: a source you do not register is a source the composer
+        is never told about, because the registered sources assemble its prompt.
+          surface.registerSource('companies', {
+            hint: '  {"type":"companies","names":["Nokia"]}   Finnish trade-register companies',
+            fields: 'name, businessId, form, line, registered, lastChange, website, city',
+            resolve: async (src, ctx) => rowsFor(src),
+            normalize: (src) => ({ names: src.names || src.companies || [], ids: src.ids || [] }),
+            claims: (src) => !!(src.names || src.companies || src.ids),
+          })
+        `claims` matters: models rename and drop the type field, so each source gets to claim a
+        malformed source object by SHAPE before the engine falls back to inline.
+
+        THE LOOP:
+          const spec = await surface.compose(text, { prefixes });   // request → spec
+          const rows = await surface.resolve(spec, { session });    // spec → rows
+          surface.renderBody(boxEl, spec, rows, { onPick });        // rows → DOM
+          const next = await surface.reshape(spec, 'make it a chart by month');
+          const better = await surface.refine(spec, rows);          // SECOND PASS, see below
+          spec.view.markdown = await surface.writeBrief(spec, rows);
+
+        RUN refine() AFTER THE ROWS ARRIVE when the composer had to guess the data shape blind
+        (memory sources above all). It re-picks kind + view against the REAL field names, and it
+        is the difference between "my AI spend per day" arriving as a chart of the right column
+        and as a table of plumbing. Keep the source pinned — refine() does.
+
+        writeBrief() runs AFTER resolve() on purpose: the model only ever sees fetched rows, so a
+        brief cannot invent data.
+
+        Helpers you may want directly: AIMEAT.surface.flatten(obj), .autoColumns(rows),
+        .agg(rows, key, how), .num(v); on an engine, .fmtNum(n, 'usd'|'eur') and .specHint().
+
+        The engine does NOT persist anything. Store specs where they belong for your product —
+        an app memory key, a workspace record, a board — and pass them back in.
+      variables:
+        - "{{node_url}}"
+
+    - type: lib
+      name: aimeat-surface
+      filename: aimeat-surface.js
+      exports:
+        - create
+      api_surface: |
+        AIMEAT.surface.create({ appId?, locale?: 'fi'|'en', strings?, ai?, scrollClass? })
+          -> { KINDS, registerSource(type, def), resolve(spec, ctx), renderBody(box, spec, rows, opts?),
+               specHint(), normalizeSpec(out, intent), compose(text, ctx), reshape(spec, text),
+               refine(spec, rows), writeBrief(spec, rows), autoColumns(rows), fmtNum(n, format), t(key) }
+        AIMEAT.surface.{ KINDS, flatten, autoColumns, agg, num, VERSION }
+
+        Panel spec: { id, title, kind, intent, source, view, needsYou, updatedAt, author }
+        kind: stats | table | chart | timeline | brief | options
+        Built-in sources: memory ({type,prefix}, owner-scope, includes agent writes) · inline ({type,rows}).
+        registerSource def: { resolve(src, ctx), hint, fields?, normalize?(src), claims?(src) }.
+
+        Renders the panel BODY into the element you pass; chrome and persistence are the host's.
+        Rendering degrades gracefully when a UI pack is absent (statTiles → daisyUI stats,
+        ChartBuilder → warning, Timeline → list, markdown → escaped text, DataTable → table).
+        renderBody opts: { onPick(index, spec), pageSize }.

package/dist/public/cortex-bundled/aimeat-viewport.js

@@ -0,0 +1,405 @@
+/**
+ * @file aimeat-viewport.js
+ * @description The shared CAMERA primitive for AIMEAT canvas surfaces — pan, zoom-at-cursor,
+ *   pinch, drag delegation, animated fit/centerOn, and the navigate/interact capture-overlay
+ *   model that makes panning work over children which swallow pointer events (iframes). It owns
+ *   the camera and NOTHING about content: what counts as draggable content is answered by the
+ *   consumer through the `onClaimPointer` hit-test delegate. Extracted verbatim-in-behaviour from
+ *   aimeat-dag v1.0.1 (TARGET-051) so a second consumer does not mean a third pan/zoom
+ *   implementation; aimeat-dag now sits on this and embeds a byte-identical copy of this file so
+ *   it can stay a single self-contained script tag.
+ * @structure
+ *   - injectCss(prefix)            → structural CSS for one class prefix (host/world/panning/overlay)
+ *   - create(hostOrSelector, opts) → the viewport instance
+ *   - instance: world, cam(), scale(), setCamera(), fit(), centerOn(), clientToWorld(),
+ *     worldToClient(), setMode(), getMode(), refreshCaptures(), destroy()
+ * @usage
+ *   <script src="/v1/cortex/aimeat-viewport/libs/aimeat-viewport.js"></script>
+ *   const vp = AIMEAT.viewport.create('#board', {
+ *     classPrefix: 'og', minZoom: 0.05, maxZoom: 3,
+ *     captureSelector: '[data-og-frame]',            // enables the navigate/interact model
+ *     contentBBox: () => boundsOfAllFrames(),
+ *     onClaimPointer: (ev) => { const f = ev.target.closest('[data-og-frame]'); return f ? handleFor(f) : null; },
+ *   });
+ *   vp.world.appendChild(frameEl);   // children live in world space
+ * @version-history
+ *   v1.0.3 — 2026-07-25 — Report the version the manifest declares; the constant and the
+ *     manifest had crossed. pnpm check:viewport now asserts they match.
+ *   v1.0.1 — 2026-07-25 — Fix: do not force position:relative on the host (it beat a consumer's
+ *     own position:fixed at the same specificity and collapsed a full-screen board to 0px);
+ *     create() promotes the host only when its computed position is static.
+ *   v1.0.0 — 2026-07-25 — Initial (TARGET-051 Slice 1): camera extracted from aimeat-dag v1.0.1.
+ *     Behaviour-preserving for dag (same gesture semantics, same zoom clamps as defaults, same
+ *     easing and reduced-motion handling); new for other consumers are classPrefix, configurable
+ *     zoom bounds, the pointer-claim delegate, clientToWorld/worldToClient as public API (it was
+ *     dead code in dag), and the navigate/interact capture overlays.
+ */
+(function (global) {
+  'use strict';
+
+  var AIMEAT = global.AIMEAT = global.AIMEAT || {};
+
+  // Idempotent: aimeat-dag embeds a copy of this file so it can ship as one script tag. Loading
+  // both the standalone pack and dag must not redefine the namespace.
+  if (AIMEAT.viewport) return;
+
+  var REDUCED = false;
+  try { REDUCED = global.matchMedia && global.matchMedia('(prefers-reduced-motion: reduce)').matches; } catch (e) { /* noop */ }
+
+  var ANIM_MS = 320;
+  var ANIM_EASE = 'cubic-bezier(.22,1,.36,1)';
+
+  // Structural CSS only — the consumer owns cosmetics (size, background, radius). Keeping the two
+  // sets disjoint means injection order never matters and no rule fights another.
+  var injected = {};
+  function injectCss(p) {
+    if (injected[p]) return;
+    var css = [
+      /* NOTE: `position` is deliberately NOT set here. The host only has to be a positioning
+         context, and a consumer may already be one in a way that matters — a full-screen board is
+         `position: fixed; inset: 0`, and a same-specificity `position: relative` from this
+         stylesheet would silently win, collapse the host to zero height and leave every pointer
+         event landing on nothing. create() promotes the host only when it is actually static. */
+      '.' + p + '-host { overflow: hidden; touch-action: none; user-select: none; -webkit-user-select: none; cursor: grab; }',
+      '.' + p + '-host.' + p + '-panning { cursor: grabbing; }',
+      '.' + p + '-host.' + p + '-interact { cursor: default; }',
+      '.' + p + '-world { position: absolute; left: 0; top: 0; transform-origin: 0 0; will-change: transform; }',
+      '.' + p + '-world.' + p + '-animated { transition: transform ' + ANIM_MS + 'ms ' + ANIM_EASE + '; }',
+      // The capture overlay: transparent, fills its host child, sits above iframe content so the
+      // pointer stream reaches the viewport instead of being swallowed.
+      '.' + p + '-capture { position: absolute; inset: 0; z-index: 5; background: transparent; cursor: inherit; }',
+      '@media (prefers-reduced-motion: reduce) { .' + p + '-world.' + p + '-animated { transition: none; } }',
+    ].join('\n');
+    var style = document.createElement('style');
+    style.setAttribute('data-aimeat-viewport', p);
+    style.textContent = css;
+    document.head.appendChild(style);
+    injected[p] = true;
+  }
+
+  function resolveEl(elOrSelector) {
+    return typeof elOrSelector === 'string' ? document.querySelector(elOrSelector) : elOrSelector;
+  }
+
+  function dist(a, b) { return Math.hypot(a.x - b.x, a.y - b.y); }
+  function mid(a, b) { return { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }; }
+  function clamp(v, lo, hi) { return Math.min(hi, Math.max(lo, v)); }
+
+  function isTextEntry(el) {
+    if (!el) return false;
+    var tag = (el.tagName || '').toLowerCase();
+    return tag === 'input' || tag === 'textarea' || tag === 'select' || el.isContentEditable === true;
+  }
+
+  /**
+   * Create a viewport over `host`. The instance creates and owns the `world` element; put your
+   * content inside `vp.world` and position it in world coordinates.
+   *
+   * @param {Element|string} hostOrSelector clipping host (the consumer gives it a size)
+   * @param {Object} [opts]
+   * @param {string}   [opts.classPrefix='av'] prefix for host/world/panning/capture classes — a
+   *   consumer that already ships CSS selectors passes its own so nothing renames.
+   * @param {number}   [opts.minZoom=0.2] @param {number} [opts.maxZoom=2.5]
+   * @param {Object}   [opts.initial={x:40,y:40,k:1}] starting camera
+   * @param {number}   [opts.fitPadding=36] @param {number} [opts.fitMaxZoom=1.4]
+   * @param {number}   [opts.centerMinZoom=1] centerOn() zooms in to at least this
+   * @param {number}   [opts.dragThreshold=4] client px before a claimed pointer counts as moved
+   * @param {Function} [opts.contentBBox] () → {x,y,w,h} in world units; required for fit()
+   * @param {Function} [opts.onClaimPointer] (ev) → null (viewport pans) | drag handle
+   *   { onMove(worldDx, worldDy, ev, cam), onEnd(movedPastThreshold, ev) }
+   * @param {Function} [opts.onTap] (ev) fired when a pan gesture ends without moving
+   * @param {Function} [opts.onCameraChange] (cam) after any camera change
+   * @param {string}   [opts.captureSelector] children matching this get a capture overlay in
+   *   navigate mode. Supplying it OPTS IN to the two-mode model (space-hold, middle-mouse pan,
+   *   Esc). Omit it and no window listeners are attached at all.
+   * @param {string}   [opts.mode='navigate']
+   */
+  function create(hostOrSelector, opts) {
+    opts = opts || {};
+    var host = resolveEl(hostOrSelector);
+    if (!host) throw new Error('aimeat-viewport: host element not found');
+
+    var P = opts.classPrefix || 'av';
+    var minZoom = opts.minZoom != null ? opts.minZoom : 0.2;
+    var maxZoom = opts.maxZoom != null ? opts.maxZoom : 2.5;
+    var fitPadding = opts.fitPadding != null ? opts.fitPadding : 36;
+    var fitMaxZoom = opts.fitMaxZoom != null ? opts.fitMaxZoom : 1.4;
+    var centerMinZoom = opts.centerMinZoom != null ? opts.centerMinZoom : 1;
+    var dragThreshold = opts.dragThreshold != null ? opts.dragThreshold : 4;
+    var twoMode = !!opts.captureSelector;
+
+    injectCss(P);
+    host.classList.add(P + '-host');
+    /* The world is absolutely positioned, so the host must be a positioning context — but only
+       promote it when it is static. Overwriting an existing fixed/absolute/sticky host is how a
+       full-screen board ends up 0px tall. */
+    if (global.getComputedStyle(host).position === 'static') host.style.position = 'relative';
+
+    var world = document.createElement('div');
+    world.className = P + '-world';
+    host.appendChild(world);
+
+    var init = opts.initial || {};
+    var cam = { x: init.x != null ? init.x : 40, y: init.y != null ? init.y : 40, k: init.k != null ? init.k : 1 };
+    var mode = opts.mode === 'interact' ? 'interact' : 'navigate';
+    var spaceHeld = false;
+    var destroyed = false;
+
+    function emitCam() { if (opts.onCameraChange) opts.onCameraChange({ x: cam.x, y: cam.y, k: cam.k }); }
+
+    function applyCam(animated) {
+      if (animated && !REDUCED) {
+        world.classList.add(P + '-animated');
+        setTimeout(function () { world.classList.remove(P + '-animated'); }, ANIM_MS + 40);
+      }
+      world.style.transform = 'translate(' + cam.x + 'px,' + cam.y + 'px) scale(' + cam.k + ')';
+      emitCam();
+    }
+
+    // ── capture overlays ──────────────────────────────────────────────────────
+    // Children that handle their own pointer events (iframes above all) swallow the stream and
+    // panning over them silently stops working. In navigate mode each one gets a transparent
+    // overlay; in interact mode the overlays come off and the child behaves normally.
+    function refreshCaptures() {
+      if (!twoMode) return;
+      var wants = (mode === 'navigate') || spaceHeld;
+      /* Sweep first. The selector decides WHO gets an overlay, so an element that has left the set
+         must lose the one it already has. Only matching elements were visited, so a consumer that
+         excludes a frame at runtime — "let me use just this one" — kept a dead overlay sitting on
+         top of it and the frame stayed unclickable with no way to tell why. */
+      var stale = world.querySelectorAll('.' + P + '-capture');
+      for (var k = 0; k < stale.length; k++) {
+        var owner = stale[k].parentElement;
+        if (owner && owner.matches && !owner.matches(opts.captureSelector)) stale[k].remove();
+      }
+      var targets = world.querySelectorAll(opts.captureSelector);
+      for (var i = 0; i < targets.length; i++) {
+        var el = targets[i];
+        var existing = el.querySelector(':scope > .' + P + '-capture');
+        if (wants && !existing) {
+          var ov = document.createElement('div');
+          ov.className = P + '-capture';
+          ov.setAttribute('aria-hidden', 'true');
+          el.appendChild(ov);
+        } else if (!wants && existing) {
+          existing.remove();
+        }
+      }
+    }
+
+    function setMode(next) {
+      var m = next === 'interact' ? 'interact' : 'navigate';
+      if (m === mode) return;
+      mode = m;
+      host.classList.toggle(P + '-interact', mode === 'interact');
+      refreshCaptures();
+    }
+
+    // ── pointer interactions ──────────────────────────────────────────────────
+    var pointers = {};   // pointerId → {x,y}
+    var gesture = null;  // {mode:'pan'|'pinch'|'claim', ...}
+
+    function clientToWorld(cx, cy) {
+      var r = host.getBoundingClientRect();
+      return { x: (cx - r.left - cam.x) / cam.k, y: (cy - r.top - cam.y) / cam.k };
+    }
+    function worldToClient(wx, wy) {
+      var r = host.getBoundingClientRect();
+      return { x: wx * cam.k + cam.x + r.left, y: wy * cam.k + cam.y + r.top };
+    }
+
+    function beginPan(ev) {
+      gesture = { mode: 'pan', sx: ev.clientX, sy: ev.clientY, cam0: { x: cam.x, y: cam.y }, moved: false };
+      host.classList.add(P + '-panning');
+    }
+
+    function onPointerDown(ev) {
+      // Capture is best-effort: synthetic PointerEvents (tests, automation) and pointers released
+      // mid-dispatch have no active pointer and would throw NotFoundError, swallowing the whole
+      // pointerdown. (aimeat-dag v1.0.1 shipped this as a real bug fix.)
+      try { host.setPointerCapture && host.setPointerCapture(ev.pointerId); } catch (e) { /* noop */ }
+      pointers[ev.pointerId] = { x: ev.clientX, y: ev.clientY };
+
+      if (Object.keys(pointers).length === 2) {
+        var pts = Object.keys(pointers).map(function (id) { return pointers[id]; });
+        gesture = {
+          mode: 'pinch', d0: dist(pts[0], pts[1]), k0: cam.k,
+          mid0: mid(pts[0], pts[1]), cam0: { x: cam.x, y: cam.y },
+        };
+        return;
+      }
+
+      // Middle mouse always pans, and holding space is a temporary navigate — both are the
+      // conventions users bring from other canvas tools.
+      if (twoMode && (ev.button === 1 || spaceHeld)) { beginPan(ev); return; }
+
+      var handle = opts.onClaimPointer ? opts.onClaimPointer(ev) : null;
+      if (handle) {
+        gesture = { mode: 'claim', handle: handle, sx: ev.clientX, sy: ev.clientY, moved: false };
+        return;
+      }
+      beginPan(ev);
+    }
+
+    function onPointerMove(ev) {
+      if (!pointers[ev.pointerId]) return;
+      pointers[ev.pointerId] = { x: ev.clientX, y: ev.clientY };
+      if (!gesture) return;
+
+      if (gesture.mode === 'pinch') {
+        var pts = Object.keys(pointers).map(function (id) { return pointers[id]; });
+        if (pts.length < 2) return;
+        var k = clamp(gesture.k0 * dist(pts[0], pts[1]) / Math.max(1, gesture.d0), minZoom, maxZoom);
+        var m = mid(pts[0], pts[1]);
+        var r = host.getBoundingClientRect();
+        // keep the world point under the pinch midpoint stationary
+        var wx = (gesture.mid0.x - r.left - gesture.cam0.x) / gesture.k0;
+        var wy = (gesture.mid0.y - r.top - gesture.cam0.y) / gesture.k0;
+        cam.k = k;
+        cam.x = (m.x - r.left) - wx * k;
+        cam.y = (m.y - r.top) - wy * k;
+        applyCam(false);
+        return;
+      }
+
+      if (gesture.mode === 'pan') {
+        gesture.moved = gesture.moved || Math.abs(ev.clientX - gesture.sx) + Math.abs(ev.clientY - gesture.sy) > 3;
+        cam.x = gesture.cam0.x + (ev.clientX - gesture.sx);
+        cam.y = gesture.cam0.y + (ev.clientY - gesture.sy);
+        applyCam(false);
+        return;
+      }
+
+      if (gesture.mode === 'claim') {
+        var dx = (ev.clientX - gesture.sx) / cam.k;
+        var dy = (ev.clientY - gesture.sy) / cam.k;
+        if (!gesture.moved && Math.abs(dx) + Math.abs(dy) < dragThreshold / cam.k) return;
+        gesture.moved = true;
+        if (gesture.handle.onMove) gesture.handle.onMove(dx, dy, ev, { x: cam.x, y: cam.y, k: cam.k });
+      }
+    }
+
+    function onPointerUp(ev) {
+      delete pointers[ev.pointerId];
+      host.classList.remove(P + '-panning');
+      if (!gesture) return;
+      var g = gesture;
+      // A pinch that lost one finger keeps waiting for the other to lift.
+      if (Object.keys(pointers).length > 0 && g.mode === 'pinch') return;
+      gesture = null;
+      if (g.mode === 'claim') {
+        if (g.handle.onEnd) g.handle.onEnd(g.moved, ev);
+      } else if (g.mode === 'pan' && !g.moved) {
+        if (opts.onTap) opts.onTap(ev);
+      }
+    }
+
+    function onWheel(ev) {
+      ev.preventDefault();
+      var factor = Math.pow(1.0015, -ev.deltaY);
+      var k = clamp(cam.k * factor, minZoom, maxZoom);
+      var r = host.getBoundingClientRect();
+      var wx = (ev.clientX - r.left - cam.x) / cam.k;
+      var wy = (ev.clientY - r.top - cam.y) / cam.k;
+      cam.k = k;
+      cam.x = (ev.clientX - r.left) - wx * k;
+      cam.y = (ev.clientY - r.top) - wy * k;
+      applyCam(false);
+    }
+
+    function onKeyDown(ev) {
+      if (ev.code !== 'Space' || spaceHeld || isTextEntry(ev.target)) return;
+      spaceHeld = true;
+      host.classList.add(P + '-panning');
+      refreshCaptures();
+      ev.preventDefault();   // stop the page from scrolling under a held space
+    }
+    function onKeyUp(ev) {
+      if (ev.code === 'Escape') { setMode('navigate'); return; }
+      if (ev.code !== 'Space' || !spaceHeld) return;
+      spaceHeld = false;
+      if (!gesture) host.classList.remove(P + '-panning');
+      refreshCaptures();
+    }
+
+    host.addEventListener('pointerdown', onPointerDown);
+    host.addEventListener('pointermove', onPointerMove);
+    host.addEventListener('pointerup', onPointerUp);
+    host.addEventListener('pointercancel', onPointerUp);
+    host.addEventListener('wheel', onWheel, { passive: false });
+    if (twoMode) {
+      global.addEventListener('keydown', onKeyDown);
+      global.addEventListener('keyup', onKeyUp);
+      host.classList.toggle(P + '-interact', mode === 'interact');
+    }
+
+    // ── camera moves ──────────────────────────────────────────────────────────
+    function setCamera(next, animated) {
+      if (next.k != null) cam.k = clamp(next.k, minZoom, maxZoom);
+      if (next.x != null) cam.x = next.x;
+      if (next.y != null) cam.y = next.y;
+      applyCam(!!animated);
+    }
+
+    function fit(animated) {
+      var b = opts.contentBBox ? opts.contentBBox() : null;
+      if (!b || !(b.w > 0) || !(b.h > 0)) return;
+      var k = clamp(Math.min(
+        (host.clientWidth - fitPadding * 2) / b.w,
+        (host.clientHeight - fitPadding * 2) / b.h,
+        fitMaxZoom,
+      ), minZoom, maxZoom);
+      cam.k = k;
+      cam.x = (host.clientWidth - b.w * k) / 2 - b.x * k;
+      cam.y = (host.clientHeight - b.h * k) / 2 - b.y * k;
+      applyCam(animated !== false);
+    }
+
+    /** Centre the camera on a world-space rect {x,y,w,h}, zooming in to at least centerMinZoom. */
+    function centerOn(rect, animated) {
+      if (!rect) return;
+      var k = clamp(Math.max(cam.k, centerMinZoom), minZoom, maxZoom);
+      cam.k = k;
+      cam.x = host.clientWidth / 2 - (rect.x + rect.w / 2) * k;
+      cam.y = host.clientHeight / 2 - (rect.y + rect.h / 2) * k;
+      applyCam(animated !== false);
+    }
+
+    function destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      host.removeEventListener('pointerdown', onPointerDown);
+      host.removeEventListener('pointermove', onPointerMove);
+      host.removeEventListener('pointerup', onPointerUp);
+      host.removeEventListener('pointercancel', onPointerUp);
+      host.removeEventListener('wheel', onWheel);
+      if (twoMode) {
+        global.removeEventListener('keydown', onKeyDown);
+        global.removeEventListener('keyup', onKeyUp);
+      }
+      host.classList.remove(P + '-host', P + '-panning', P + '-interact');
+      world.remove();
+    }
+
+    applyCam(false);
+
+    return {
+      host: host,
+      world: world,
+      cam: function () { return { x: cam.x, y: cam.y, k: cam.k }; },
+      scale: function () { return cam.k; },
+      setCamera: setCamera,
+      fit: fit,
+      centerOn: centerOn,
+      clientToWorld: clientToWorld,
+      worldToClient: worldToClient,
+      setMode: setMode,
+      getMode: function () { return spaceHeld ? 'navigate' : mode; },
+      refreshCaptures: refreshCaptures,
+      destroy: destroy,
+    };
+  }
+
+  AIMEAT.viewport = { create: create, VERSION: '1.0.4' };
+
+})(typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : this);

package/dist/public/cortex-bundled/aimeat-viewport.yaml

@@ -0,0 +1,100 @@
+apiVersion: cortex.aimeat.org/v1
+kind: Extension
+metadata:
+  name: aimeat-viewport
+  namespace: aimeat
+  description: "The camera primitive for movable surfaces: pan, zoom-at-cursor, pinch, drag delegation, animated fit/centerOn, and the navigate/interact capture-overlay model that keeps panning working over iframes. Owns the camera and nothing about content — the consumer answers what is draggable via a hit-test delegate. Zero dependencies, theme-agnostic, reduced-motion safe."
+  author: AIMEAT
+  tags: [viewport, camera, canvas, pan, zoom, pinch, surface, ui]
+  labels:
+    domain: canvas
+
+spec:
+  version: "1.0.4"
+  license: MIT
+  components:
+    - type: prompt
+      name: viewport-assistant
+      content: |
+        You are a canvas-surface assistant for an AIMEAT app. The user's node is at {{node_url}}.
+
+        aimeat-viewport is the CAMERA ONLY. Reach for it when the app needs a movable surface of
+        its OWN content — arbitrary children, the app's own layout, pan/zoom/pinch. If the app
+        wants an auto-laid-out graph to read use aimeat-dag; a user-drawn node-and-wire diagram
+        use aimeat-flow; freehand drawing use aimeat-canvas; a static text-defined diagram use
+        mermaid. Choosing this pack for those means reimplementing what they already do.
+
+        Include ONE tag:
+        <script src="{{node_url}}/v1/cortex/aimeat-viewport/libs/aimeat-viewport.js"></script>
+
+        API:
+
+        const vp = AIMEAT.viewport.create(elOrSelector, {
+          classPrefix?: 'av',            // host/world/panning/capture class prefix
+          minZoom?: 0.2, maxZoom?: 2.5,
+          initial?: { x: 40, y: 40, k: 1 },
+          fitPadding?: 36, fitMaxZoom?: 1.4, centerMinZoom?: 1, dragThreshold?: 4,
+          contentBBox?: () => ({ x, y, w, h }),      // world units; fit() asks for this
+          onClaimPointer?: (ev) => null | {          // null => the viewport pans
+            onMove(worldDx, worldDy, ev, cam), onEnd(movedPastThreshold, ev) },
+          onTap?: (ev) => {},                        // pan gesture that never moved
+          onCameraChange?: (cam) => {},
+          captureSelector?: '[data-frame]',          // opts in to the navigate/interact model
+          mode?: 'navigate' | 'interact',
+        })
+
+        vp.world                     // append your content here; position it in WORLD coordinates
+        vp.cam() -> {x,y,k}          // copy; vp.scale() -> k
+        vp.setCamera({x,y,k}, animated) · vp.fit(animated) · vp.centerOn({x,y,w,h}, animated)
+        vp.clientToWorld(cx, cy) · vp.worldToClient(wx, wy)
+        vp.setMode('navigate'|'interact') · vp.getMode() · vp.refreshCaptures() · vp.destroy()
+
+        THE HOST ELEMENT MUST HAVE A SIZE (e.g. style="height:480px" or position:fixed;inset:0).
+        A zero-height host silently swallows every pointer event — this is the single most common
+        mistake with canvas packs.
+
+        The viewport supplies only STRUCTURAL css (positioning, transform, cursor, touch-action).
+        The app owns cosmetics — size, background, border-radius — so the two never fight.
+
+        THE POINTER-CLAIM DELEGATE is the whole content contract: on pointerdown the viewport asks
+        onClaimPointer whether you claim this event. Return a drag handle and you drive the drag
+        (deltas arrive in WORLD units, already divided by the zoom); return null and the viewport
+        pans. Keep any "did it actually move" state in the handle closure when your own rule for
+        that differs from the viewport's threshold.
+
+        NAVIGATE VS INTERACT — only needed when children swallow pointer events (iframes, or
+        anything with its own handlers). Pass captureSelector and in navigate mode each matching
+        child gets a transparent overlay so panning works over it; setMode('interact') removes the
+        overlays so the child behaves normally (forms, scroll, microphone). Holding space is a
+        temporary navigate, middle-mouse always pans, Escape returns to navigate. Call
+        refreshCaptures() after adding or removing children. Omit captureSelector entirely and no
+        window listeners are attached at all — plain DOM children you render yourself need none of
+        this.
+
+        Persist the camera from onCameraChange to an app memory key and pass it back as `initial`
+        on the next mount, the same way aimeat-dag persists node positions.
+      variables:
+        - "{{node_url}}"
+
+    - type: lib
+      name: aimeat-viewport
+      filename: aimeat-viewport.js
+      exports:
+        - create
+      api_surface: |
+        AIMEAT.viewport.create(elOrSelector, { classPrefix?, minZoom?, maxZoom?, initial?,
+          fitPadding?, fitMaxZoom?, centerMinZoom?, dragThreshold?, contentBBox?, onClaimPointer?,
+          onTap?, onCameraChange?, captureSelector?, mode? })
+          -> { host, world, cam(), scale(), setCamera(cam, animated), fit(animated),
+               centerOn(rect, animated), clientToWorld(cx,cy), worldToClient(wx,wy),
+               setMode('navigate'|'interact'), getMode(), refreshCaptures(), destroy() }
+
+        The consumer appends content to `world` in world coordinates and answers onClaimPointer
+        for anything draggable. Gestures: drag to pan, wheel to zoom at the cursor, two-finger
+        pinch to zoom about the midpoint. With captureSelector set, children that swallow pointer
+        events get a transparent overlay in navigate mode; space-hold, middle-mouse and Escape
+        behave as in other canvas tools.
+
+        Zero dependencies. Structural CSS only (the app owns cosmetics).
+        prefers-reduced-motion safe. Idempotent namespace guard: aimeat-dag embeds a
+        byte-identical copy so it can ship as a single script tag, and loading both is safe.