@robosystems/core 0.11.5 → 0.13.0

package/components/console/ConsoleContent.js

@@ -6,6 +6,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { HiTerminal } from 'react-icons/hi';
 import { useGraphContext } from '../../contexts';
 import { useStreamingQuery } from '../../hooks';
+import { emitGraphWrites, readGraphWrites, } from '../../lib/graph-writes';
 import { ConsoleMarkdown } from './ConsoleMarkdown';
 import { ProgressiveText } from './ProgressiveText';
 function generateMessageId() {
@@ -53,6 +54,23 @@ function downloadText(filename, text, mime) {
     anchor.click();
     URL.revokeObjectURL(url);
 }
+const WRITE_LABELS = {
+    'create-taxonomy-block': 'Created taxonomy block',
+    'create-information-block': 'Created block',
+    'update-information-block': 'Updated block',
+    'assert-metrics': 'Asserted metrics',
+    'compute-metrics': 'Computed metrics',
+    'compute-forecast': 'Computed forecast',
+    'create-agent': 'Created counterparty',
+    'update-agent': 'Updated counterparty',
+    remember: 'Saved memory',
+};
+function describeWrite(write) {
+    var _a, _b;
+    const label = (_a = WRITE_LABELS[write.operation]) !== null && _a !== void 0 ? _a : write.operation;
+    const subject = (_b = write.name) !== null && _b !== void 0 ? _b : write.id;
+    return subject ? `${label}: ${subject}` : label;
+}
 function copyRowsJson(rows) {
     var _a;
     (_a = navigator.clipboard) === null || _a === void 0 ? void 0 : _a.writeText(JSON.stringify(rows, null, 2));
@@ -102,6 +120,9 @@ export function ConsoleContent({ config }) {
             (config.enableRecall
                 ? `  /recall     - Recall semantic memories\n`
                 : '') +
+            (config.enableAuthor
+                ? `  /do         - Make a change (a block, a counterparty, a memory)\n`
+                : '') +
             `  /mcp        - Connect an MCP client (sign in — no key)\n` +
             `  /mcp key    - Mint a graph-scoped API key for header-only clients\n` +
             `  /help       - Show this help message\n` +
@@ -145,6 +166,7 @@ export function ConsoleContent({ config }) {
         setTerminalMessages((prev) => [...prev, message]);
     }, []);
     const addResultMessage = useCallback((content, data, cypher, opts) => {
+        var _a;
         const message = {
             id: generateMessageId(),
             type: 'system',
@@ -154,6 +176,7 @@ export function ConsoleContent({ config }) {
             cypher,
             markdown: opts === null || opts === void 0 ? void 0 : opts.markdown,
             footer: opts === null || opts === void 0 ? void 0 : opts.footer,
+            writes: ((_a = opts === null || opts === void 0 ? void 0 : opts.writes) === null || _a === void 0 ? void 0 : _a.length) ? opts.writes : undefined,
         };
         setTerminalMessages((prev) => [...prev, message]);
     }, []);
@@ -328,7 +351,9 @@ export function ConsoleContent({ config }) {
             setCurrentQueryStartTime(null);
         }
     };
-    const executeOperatorQuery = async (userQuery) => {
+    // `operatorType` names an operator (`author` for /do); unset, the API
+    // chooses one for a question.
+    const executeOperatorQuery = async (userQuery, operatorType) => {
         var _a;
         if (!graphId) {
             addErrorMessage(config.noSelectionError);
@@ -342,10 +367,11 @@ export function ConsoleContent({ config }) {
         try {
             const { clients } = await import('@robosystems/client/clients');
             const history = conversationRef.current;
-            const result = await clients.operator.executeQuery(graphId, Object.assign({ message: userQuery, 
+            const request = Object.assign({ message: userQuery, 
                 // `standard` gives the operator loop six tool turns; `quick` (three)
                 // was exhausted by schema + examples before the first query ran.
-                mode: 'standard' }, (history.length > 0 ? { history } : {})), {
+                mode: 'standard' }, (history.length > 0 ? { history } : {}));
+            const options = {
                 mode: 'auto',
                 onProgress: (message, percentage) => {
                     if (isStale())
@@ -356,7 +382,10 @@ export function ConsoleContent({ config }) {
                         percentage,
                     });
                 },
-            });
+            };
+            const result = operatorType
+                ? await clients.operator.executeOperator(graphId, operatorType, request, options)
+                : await clients.operator.executeQuery(graphId, request, options);
             // The user switched graphs while the operator ran: the reset already
             // cleared the console, so drop the answer rather than print it (and
             // record it as history) under the new graph.
@@ -378,6 +407,9 @@ export function ConsoleContent({ config }) {
             }
             const duration = Date.now() - startTime;
             const metadata = (result.metadata || {});
+            const writes = readGraphWrites(metadata);
+            // Pages showing this graph reload what the console just changed.
+            emitGraphWrites(requestGraphId, writes);
             const creditsUsed = metadata.credits_consumed;
             const resultCount = metadata.result_count;
             // Prefer the structured outputs the operator loop now returns
@@ -429,7 +461,11 @@ export function ConsoleContent({ config }) {
             // otherwise collapse under markdown). With no narrative, fall back to the
             // plain footer, matching the direct-query result style.
             if (narrative) {
-                addResultMessage(narrative, rows, cypher, { markdown: true, footer });
+                addResultMessage(narrative, rows, cypher, {
+                    markdown: true,
+                    footer,
+                    writes,
+                });
                 // Record the exchange for follow-ups. Only a narrative answer is
                 // worth carrying; the answer is clipped so history stays cheap.
                 conversationRef.current = [
@@ -439,7 +475,7 @@ export function ConsoleContent({ config }) {
                 ].slice(-6);
             }
             else {
-                addResultMessage(footer, rows, cypher);
+                addResultMessage(footer, rows, cypher, { writes });
             }
         }
         catch (error) {
@@ -596,6 +632,17 @@ export function ConsoleContent({ config }) {
             }
             return;
         }
+        // Handle /do — the author operator, which may change the graph. Writes
+        // are never inferred from a question; they need this command.
+        if (config.enableAuthor && /^\/do(\s|$)/i.test(command)) {
+            const request = command.slice(3).trim();
+            if (!request) {
+                addErrorMessage('Usage: /do <change>\n\nExamples:\n  /do add Notion Labs as a vendor\n  /do remember that we report ARPC on subscription revenue only');
+                return;
+            }
+            await executeOperatorQuery(request, 'author');
+            return;
+        }
         // Handle /recall command — built-in only when the target supports
         // semantic memory (user graphs; shared repositories reject it). When
         // disabled it falls through to the unknown-command branch below.
@@ -702,7 +749,10 @@ export function ConsoleContent({ config }) {
                                                     ? 'text-green-400'
                                                     : message.type === 'error'
                                                         ? 'text-red-400'
-                                                        : 'text-gray-300'}`, children: [message.type === 'user' && (_jsx("span", { className: "mr-2 text-green-500", children: "$" })), message.isAnimating ? (_jsx(ProgressiveText, { text: message.content, onComplete: () => handleAnimationComplete(message.id), onUpdate: scrollToBottom })) : message.markdown ? (_jsx(ConsoleMarkdown, { content: message.content })) : (message.content)] }), message.footer && (_jsx("div", { className: "mt-3 text-xs whitespace-pre-wrap text-gray-500", children: message.footer })), message.cypher && (_jsxs("div", { className: "mt-3 overflow-hidden rounded border border-gray-800 bg-gray-900/40", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-gray-800 px-3 py-1.5", children: [_jsx("span", { className: "text-xs tracking-wider text-gray-500 uppercase", children: "Generated Cypher" }), _jsx("button", { onClick: () => { var _a; return handleCommand(`/query ${(_a = message.cypher) !== null && _a !== void 0 ? _a : ''}`); }, className: "rounded bg-cyan-600/90 px-2 py-0.5 text-xs font-medium text-white transition-colors hover:bg-cyan-600", children: "Run" })] }), _jsx("pre", { className: "overflow-x-auto px-3 py-2 font-mono text-xs whitespace-pre-wrap text-cyan-300", children: message.cypher })] })), message.data && message.data.length > 0 && (_jsxs("div", { className: "mt-3 overflow-hidden rounded border border-gray-800", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-gray-800 bg-gray-900 px-4 py-2", children: [_jsxs("span", { className: "text-xs text-gray-500", children: [message.data.length, " row", message.data.length === 1 ? '' : 's'] }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { onClick: () => copyRowsJson(message.data), className: "rounded border border-gray-700 px-2 py-0.5 text-xs text-gray-300 transition-colors hover:bg-gray-800", children: "Copy JSON" }), _jsx("button", { onClick: () => downloadText('results.csv', rowsToCsv(message.data), 'text/csv'), className: "rounded border border-gray-700 px-2 py-0.5 text-xs text-gray-300 transition-colors hover:bg-gray-800", children: "Download CSV" })] })] }), _jsx("div", { className: "max-h-96 overflow-auto", children: _jsxs("table", { className: "w-full border-collapse text-xs", children: [_jsx("thead", { className: "sticky top-0", children: _jsx("tr", { className: "border-b border-gray-800 bg-gray-900", children: Object.keys(message.data[0]).map((key) => (_jsx("th", { className: "px-4 py-2 text-left font-semibold whitespace-nowrap text-cyan-400", children: key }, key))) }) }), _jsx("tbody", { children: message.data
+                                                        : 'text-gray-300'}`, children: [message.type === 'user' && (_jsx("span", { className: "mr-2 text-green-500", children: "$" })), message.isAnimating ? (_jsx(ProgressiveText, { text: message.content, onComplete: () => handleAnimationComplete(message.id), onUpdate: scrollToBottom })) : message.markdown ? (_jsx(ConsoleMarkdown, { content: message.content })) : (message.content)] }), message.writes && (_jsxs("div", { className: "mt-3 rounded border border-emerald-900/60 bg-emerald-950/30 px-3 py-2", children: [_jsx("div", { className: "text-xs tracking-wider text-emerald-400 uppercase", children: "Changes made" }), _jsx("ul", { className: "mt-1 space-y-0.5 text-sm text-emerald-200", children: message.writes.map((write, idx) => {
+                                                        var _a;
+                                                        return (_jsxs("li", { children: ["\u2713 ", describeWrite(write)] }, `${write.operation}-${(_a = write.id) !== null && _a !== void 0 ? _a : idx}`));
+                                                    }) })] })), message.footer && (_jsx("div", { className: "mt-3 text-xs whitespace-pre-wrap text-gray-500", children: message.footer })), message.cypher && (_jsxs("div", { className: "mt-3 overflow-hidden rounded border border-gray-800 bg-gray-900/40", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-gray-800 px-3 py-1.5", children: [_jsx("span", { className: "text-xs tracking-wider text-gray-500 uppercase", children: "Generated Cypher" }), _jsx("button", { onClick: () => { var _a; return handleCommand(`/query ${(_a = message.cypher) !== null && _a !== void 0 ? _a : ''}`); }, className: "rounded bg-cyan-600/90 px-2 py-0.5 text-xs font-medium text-white transition-colors hover:bg-cyan-600", children: "Run" })] }), _jsx("pre", { className: "overflow-x-auto px-3 py-2 font-mono text-xs whitespace-pre-wrap text-cyan-300", children: message.cypher })] })), message.data && message.data.length > 0 && (_jsxs("div", { className: "mt-3 overflow-hidden rounded border border-gray-800", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-gray-800 bg-gray-900 px-4 py-2", children: [_jsxs("span", { className: "text-xs text-gray-500", children: [message.data.length, " row", message.data.length === 1 ? '' : 's'] }), _jsxs("div", { className: "flex gap-2", children: [_jsx("button", { onClick: () => copyRowsJson(message.data), className: "rounded border border-gray-700 px-2 py-0.5 text-xs text-gray-300 transition-colors hover:bg-gray-800", children: "Copy JSON" }), _jsx("button", { onClick: () => downloadText('results.csv', rowsToCsv(message.data), 'text/csv'), className: "rounded border border-gray-700 px-2 py-0.5 text-xs text-gray-300 transition-colors hover:bg-gray-800", children: "Download CSV" })] })] }), _jsx("div", { className: "max-h-96 overflow-auto", children: _jsxs("table", { className: "w-full border-collapse text-xs", children: [_jsx("thead", { className: "sticky top-0", children: _jsx("tr", { className: "border-b border-gray-800 bg-gray-900", children: Object.keys(message.data[0]).map((key) => (_jsx("th", { className: "px-4 py-2 text-left font-semibold whitespace-nowrap text-cyan-400", children: key }, key))) }) }), _jsx("tbody", { children: message.data
                                                                     .slice(0, MAX_TABLE_ROWS)
                                                                     .map((row, idx) => (_jsx("tr", { className: "border-b border-gray-900 hover:bg-gray-900/50", children: Object.keys(message.data[0]).map((key) => {
                                                                         const value = row[key];

package/components/console/graphAwareConfig.js

@@ -404,6 +404,8 @@ export function buildGraphAwareConsoleConfig(graph, branding) {
         noSelectionError: (_c = branding.noSelectionError) !== null && _c !== void 0 ? _c : 'No graph selected. Please select a graph first.',
         // Semantic memory is per-user-graph; shared repositories reject it.
         enableRecall: !isRepository,
+        // Writes need a user graph; the API also checks the write role.
+        enableAuthor: !isRepository,
     };
 }
 /**

package/components/console/types.d.ts

@@ -1,3 +1,4 @@
+import type { GraphWrite } from '../../lib/graph-writes';
 export interface SampleQuery {
     name: string;
     query: string;
@@ -65,6 +66,9 @@ export interface ConsoleConfig {
      *  shared repositories don't support memory, so the graph-aware builder
      *  enables it only for user graphs. */
     enableRecall?: boolean;
+    /** Enable `/do`, which runs the write-capable author operator. The API
+     *  gates it on the graph write role; off for shared repositories. */
+    enableAuthor?: boolean;
     /** Extra slash commands beyond the built-in set */
     extraCommands?: ConsoleExtraCommand[];
 }
@@ -90,4 +94,6 @@ export interface TerminalMessage {
      * breaks survive markdown rendering.
      */
     footer?: string;
+    /** Changes the author operator made, shown as a receipt below the answer. */
+    writes?: GraphWrite[];
 }

package/demos/runtime.d.ts

@@ -0,0 +1,66 @@
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface DemoTheme {
+    /** Selector for the sidebar that holds `.pill` and the `.nv[data-k]` items. */
+    side: string;
+    /** Resting item colour, as RGB. */
+    rest: [number, number, number];
+    /** Resting colour of an indented `.nv.sub` item; defaults to `rest`. */
+    restSub?: [number, number, number];
+    /** Colour of the item under the pill. */
+    active: [number, number, number];
+}
+export interface DemoContext {
+    $: (id: string) => HTMLElement;
+    root: ShadowRoot;
+    stage: HTMLElement;
+    rel: (el: Element) => Rect;
+    ring: (hl: HTMLElement, target: Element, p: number, pad?: number) => void;
+    nav: (k: string, from?: string, m?: number, scope?: ParentNode) => void;
+}
+export interface DemoLayout {
+    width: number;
+    height: number;
+    css?: string;
+}
+export interface DemoDefinition extends DemoLayout {
+    total: number;
+    poster?: number;
+    html: string;
+    setup: (ctx: DemoContext) => (t: number) => void;
+    mobile?: DemoLayout;
+}
+export interface MountOptions {
+    autoplay?: boolean;
+    phone?: boolean;
+    /** The app's base CSS: its tokens, window chrome and shared components. */
+    css?: string;
+    theme?: DemoTheme;
+}
+export interface DemoHandle {
+    seek: (t: number) => void;
+    destroy: () => void;
+}
+export declare const clamp01: (x: number) => number;
+export declare const seg: (t: number, a: number, b: number) => number;
+export declare const eo: (x: number) => number;
+export declare const eio: (x: number) => number;
+export declare const typed: (s: string, t: number, t0: number, cps?: number) => string;
+export declare const spin: (t: number) => string;
+export declare const money: (v: number, dp?: number) => string;
+export declare function rise(el: HTMLElement, p: number, dy?: number): void;
+export declare const dip: (t: number, at: number, d?: number) => number;
+export declare function swap(el: HTMLElement, t: number, at: number, a?: string | null, b?: string | null, cls?: [string, string]): boolean;
+export declare function steps(el: HTMLElement, t: number, times: number[], texts?: string[] | null, classes?: string[] | null): number;
+export declare function blurIn(el: HTMLElement, p: number, dy?: number): void;
+export declare function push(el: HTMLElement, t: number, total: number, ox: number, oy: number, amount?: number): void;
+export declare function pointer(ctx: DemoContext, cur: HTMLElement, el: Element, t: number, t0: number, t1: number, { from, out, }?: {
+    from?: [number, number];
+    out?: number;
+}): boolean;
+export declare function variant(def: DemoDefinition, phone: boolean): DemoDefinition;
+export declare function mount(host: HTMLElement, def: DemoDefinition, { autoplay, phone, css, theme }?: MountOptions): DemoHandle;

package/demos/runtime.js

@@ -0,0 +1,278 @@
+/*
+ * The runtime behind the landing-page demos in each app's /public/demos.
+ *
+ * A demo module default-exports { width, height, total, poster, css, html,
+ * setup(ctx), mobile? } where setup returns seek(t), a pure function of time.
+ * The same module runs live on the landing page (mount, in a shadow root,
+ * looping while visible) and frame by frame under the content machine's
+ * renderer (render.html), so the page and the social cut share one source.
+ *
+ * This file compiles to dependency-free ESM that a browser loads as-is: each
+ * app commits a copy at public/demos/runtime.js (npm run sync:demos) and a
+ * test there fails when the copy drifts from the installed package. The app's
+ * own kit.js wraps mount() with its window chrome, base CSS and sidebar theme.
+ */
+export const clamp01 = (x) => Math.max(0, Math.min(1, x));
+export const seg = (t, a, b) => clamp01((t - a) / (b - a));
+export const eo = (x) => 1 - Math.pow(1 - clamp01(x), 3);
+export const eio = (x) => {
+    x = clamp01(x);
+    return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
+};
+export const typed = (s, t, t0, cps = 34) => s.slice(0, Math.max(0, Math.floor((t - t0) * cps)));
+export const spin = (t) => '◐◓◑◒'[Math.floor(t * 8) % 4];
+export const money = (v, dp = 2) => '$' +
+    v.toLocaleString('en-US', {
+        minimumFractionDigits: dp,
+        maximumFractionDigits: dp,
+    });
+export function rise(el, p, dy = 40) {
+    el.style.opacity = String(p);
+    el.style.transform = `translateY(${(1 - p) * dy}px)`;
+}
+/* Opacity for an element whose content changes at `at`: dips through 0.15 over `d` seconds. */
+export const dip = (t, at, d = 0.3) => Math.min(1, 0.15 + 0.85 * (Math.abs(t - at) / (d / 2)));
+/*
+ * Change a label or badge without a one-frame pop: before `at` it shows `a`,
+ * after it `b` (text, and optional class names), with an opacity dip across
+ * the change. With `a` null only the dip applies, for text set elsewhere.
+ */
+export function swap(el, t, at, a, b, cls) {
+    const after = t >= at;
+    if (a != null)
+        el.textContent = after ? (b !== null && b !== void 0 ? b : '') : a;
+    if (cls)
+        el.className = after ? cls[1] : cls[0];
+    el.style.opacity = String(dip(t, at));
+    return after;
+}
+/* A badge that moves through states at `times`: texts[k] and classes[k], dipping at each change. */
+export function steps(el, t, times, texts, classes) {
+    let k = 0;
+    times.forEach((x) => (k += t >= x ? 1 : 0));
+    if (texts)
+        el.textContent = texts[k];
+    if (classes)
+        el.className = classes[k];
+    el.style.opacity = String(Math.min(1, ...times.map((x) => dip(t, x))));
+    return k;
+}
+/* Headline entrance: blur to sharp, rising, as p goes 0 to 1. */
+export function blurIn(el, p, dy = 24) {
+    const e = eo(p);
+    el.style.opacity = String(clamp01(p * 1.4));
+    el.style.filter = e < 1 ? `blur(${(1 - e) * 14}px)` : '';
+    el.style.transform = `translateY(${(1 - e) * dy}px)`;
+}
+/*
+ * A slow camera push over the loop toward (ox, oy), in stage px, easing back
+ * before the loop wraps, so no screen sits still like a slide.
+ */
+export function push(el, t, total, ox, oy, amount = 0.04) {
+    const k = amount *
+        eio(seg(t, 0.4, total - 1.2)) *
+        (1 - eio(seg(t, total - 1.2, total)));
+    el.style.transformOrigin = `${ox}px ${oy}px`;
+    el.style.transform = `scale(${1 + k})`;
+}
+/* A drawn pointer that travels from `from` to the centre of `el`, presses, and fades out. */
+export function pointer(ctx, cur, el, t, t0, t1, { from = [260, 160], out = 0.6, } = {}) {
+    if (t < t0 - 0.15 || t > t1 + out) {
+        cur.style.opacity = '0';
+        return t > t1;
+    }
+    const r = ctx.rel(el);
+    const tx = r.x + r.w * 0.55;
+    const ty = r.y + r.h * 0.55;
+    const m = eio(seg(t, t0, t1));
+    cur.style.left = tx + (1 - m) * from[0] + 'px';
+    cur.style.top = ty + (1 - m) * from[1] + 'px';
+    cur.style.opacity = String(seg(t, t0 - 0.15, t0) * (1 - seg(t, t1 + out - 0.2, t1 + out)));
+    const pressed = t > t1 && t < t1 + 0.18;
+    cur.style.transform = `scale(${pressed ? 0.85 : 1})`;
+    return t > t1;
+}
+/* The stage's own reset; everything else, including the tokens, comes from the app. */
+const STAGE_CSS = `
+:host { display: block; }
+.stage { position: absolute; left: 0; top: 0; transform-origin: 0 0; overflow: hidden; }
+:where(.stage *) { box-sizing: border-box; margin: 0; padding: 0; }
+`;
+function makeCtx(root, stage, getScale, theme) {
+    const $ = (id) => root.getElementById(id);
+    const rel = (el) => {
+        const s = stage.getBoundingClientRect();
+        const r = el.getBoundingClientRect();
+        const k = getScale();
+        return {
+            x: (r.left - s.left) / k,
+            y: (r.top - s.top) / k,
+            w: r.width / k,
+            h: r.height / k,
+        };
+    };
+    /* ring `hl` (absolutely positioned in its offsetParent) around `target` */
+    const ring = (hl, target, p, pad = 6) => {
+        const parent = hl.offsetParent;
+        // a hidden scene has no layout to measure; skip rather than throw
+        if (!parent) {
+            hl.style.opacity = '0';
+            return;
+        }
+        const a = rel(target);
+        const b = rel(parent);
+        // a camera push scales the parent; undo it so the ring sits in its local px
+        const k = b.w / parent.offsetWidth || 1;
+        hl.style.left = (a.x - b.x) / k - pad + 'px';
+        hl.style.top = (a.y - b.y) / k - pad * 0.7 + 'px';
+        hl.style.width = a.w / k + pad * 2 + 'px';
+        hl.style.height = a.h / k + pad * 1.4 + 'px';
+        hl.style.opacity = String(p);
+    };
+    /* slide the pill of the sidebar inside `scope` to `k`, blending from `from` by m */
+    const nav = (k, from = k, m = 1, scope = root) => {
+        if (!theme)
+            return;
+        const side = scope.querySelector(theme.side);
+        if (!side)
+            return;
+        const item = (key) => side.querySelector(`[data-k="${key}"]`);
+        const y = (key) => { var _a, _b; return (_b = (_a = item(key)) === null || _a === void 0 ? void 0 : _a.offsetTop) !== null && _b !== void 0 ? _b : 0; };
+        const pill = side.querySelector('.pill');
+        if (pill)
+            pill.style.top = y(from) + (y(k) - y(from)) * eio(m) + 'px';
+        // the active item's colour blends across the move instead of switching
+        const w = eio(m);
+        side.querySelectorAll('.nv').forEach((d) => {
+            var _a;
+            const key = d.dataset.k;
+            const on = (key === k ? w : 0) + (key === from && from !== k ? 1 - w : 0);
+            const rest = d.classList.contains('sub')
+                ? ((_a = theme.restSub) !== null && _a !== void 0 ? _a : theme.rest)
+                : theme.rest;
+            const c = rest.map((v, i) => Math.round(v + (theme.active[i] - v) * on));
+            d.classList.remove('on');
+            d.style.color = `rgb(${c.join(',')})`;
+        });
+    };
+    return { $, root, stage, rel, ring, nav };
+}
+/* The phone layout of a demo: its `mobile` block overrides the stage size and adds CSS. */
+export function variant(def, phone) {
+    if (!phone || !def.mobile)
+        return def;
+    return Object.assign(Object.assign(Object.assign({}, def), def.mobile), { css: (def.css || '') + (def.mobile.css || '') });
+}
+/* Phones: screens narrower than Tailwind's sm breakpoint get a demo's phone layout. */
+const PHONE = '(max-width: 639px)';
+/*
+ * Mount a demo into `host` (a shadow root keeps its CSS off the page). With
+ * autoplay it scales to the host's width, uses the phone layout on narrow
+ * screens, loops while on screen, and holds the poster frame for reduced
+ * motion; without, it sits at native size for the renderer (`phone` picks the
+ * phone layout there).
+ */
+export function mount(host, def, { autoplay = true, phone = false, css = '', theme } = {}) {
+    var _a;
+    const root = host.shadowRoot || host.attachShadow({ mode: 'open' });
+    let scale = 1;
+    let v = def;
+    let stage;
+    let seek = () => { };
+    const build = (isPhone) => {
+        v = variant(def, isPhone);
+        root.innerHTML = `<style>${STAGE_CSS}${css}${v.css || ''}</style>
+    <div class="stage" style="width:${v.width}px;height:${v.height}px">${v.html}</div>`;
+        stage = root.querySelector('.stage');
+        const ctx = makeCtx(root, stage, () => scale, theme);
+        // each window's pill starts under the item its chrome marked active, so a
+        // demo that never calls nav() does not show it on the first item
+        if (theme)
+            root.querySelectorAll(theme.side).forEach((side) => {
+                const on = side.querySelector('.nv.on');
+                if ((on === null || on === void 0 ? void 0 : on.dataset.k) && side.parentNode)
+                    ctx.nav(on.dataset.k, on.dataset.k, 1, side.parentNode);
+            });
+        const pose = v.setup(ctx);
+        // [data-loop] content fades in at the start of the loop and out at its end,
+        // so the wrap back to the first frame is a dissolve, not a jump.
+        const looped = [...root.querySelectorAll('[data-loop]')];
+        const total = v.total;
+        seek = (t) => {
+            pose(t);
+            const f = Math.min(seg(t, 0, 0.35), 1 - seg(t, total - 0.35, total));
+            looped.forEach((el) => (el.style.opacity = String(f)));
+        };
+    };
+    const poster = (_a = def.poster) !== null && _a !== void 0 ? _a : 0;
+    if (!autoplay) {
+        build(phone);
+        seek(poster);
+        return { seek: (t) => seek(t), destroy() { } };
+    }
+    const phoneQuery = matchMedia(PHONE);
+    const fit = () => {
+        scale = host.clientWidth / v.width || 1;
+        stage.style.transform = `scale(${scale})`;
+    };
+    build(phoneQuery.matches);
+    fit();
+    const ro = new ResizeObserver(fit);
+    ro.observe(host);
+    const reduce = matchMedia('(prefers-reduced-motion: reduce)');
+    let t = poster;
+    let started = false;
+    let last = null;
+    let raf = 0;
+    let visible = false;
+    seek(t);
+    const loop = (now) => {
+        if (last != null)
+            t = (t + Math.min(0.1, (now - last) / 1000)) % def.total;
+        last = now;
+        seek(t);
+        raf = requestAnimationFrame(loop);
+    };
+    const update = () => {
+        cancelAnimationFrame(raf);
+        last = null;
+        if (reduce.matches) {
+            t = poster;
+            seek(t);
+            return;
+        }
+        if (visible && !document.hidden) {
+            if (!started) {
+                started = true;
+                t = 0;
+            }
+            raf = requestAnimationFrame(loop);
+        }
+        else
+            seek(t);
+    };
+    const relayout = () => {
+        build(phoneQuery.matches);
+        fit();
+        update();
+    };
+    const io = new IntersectionObserver(([e]) => {
+        visible = e.isIntersecting;
+        update();
+    }, { threshold: 0.2 });
+    io.observe(host);
+    document.addEventListener('visibilitychange', update);
+    reduce.addEventListener('change', update);
+    phoneQuery.addEventListener('change', relayout);
+    return {
+        seek: (x) => seek(x),
+        destroy() {
+            cancelAnimationFrame(raf);
+            io.disconnect();
+            ro.disconnect();
+            document.removeEventListener('visibilitychange', update);
+            reduce.removeEventListener('change', update);
+            phoneQuery.removeEventListener('change', relayout);
+        },
+    };
+}

package/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export { useApiError } from './use-api-error';
 export { useCrossAppLink, type CrossAppTarget, type OpenCrossAppOptions, type UseCrossAppLinkResult, } from './use-cross-app-link';
+export { useGraphWrites } from './use-graph-writes';
 export { useMediaQuery } from './use-media-query';
 export { useStreamingQuery } from './use-streaming-query';
 export { useToast, type ToastMessage } from './use-toast';

package/hooks/index.js

@@ -1,5 +1,6 @@
 export { useApiError } from './use-api-error';
 export { useCrossAppLink, } from './use-cross-app-link';
+export { useGraphWrites } from './use-graph-writes';
 export { useMediaQuery } from './use-media-query';
 export { useStreamingQuery } from './use-streaming-query';
 export { useToast } from './use-toast';

package/hooks/use-graph-writes.d.ts

@@ -0,0 +1,6 @@
+import { type GraphWrite } from '../lib/graph-writes';
+/**
+ * Calls `onWrites` when the console changes the graph a page is showing, so
+ * the page can reload what it displays. Writes to other graphs are ignored.
+ */
+export declare function useGraphWrites(graphId: string | null | undefined, onWrites: (writes: GraphWrite[]) => void): void;

package/hooks/use-graph-writes.js

@@ -0,0 +1,22 @@
+'use client';
+import { useEffect, useRef } from 'react';
+import { GRAPH_WRITES_EVENT, } from '../lib/graph-writes';
+/**
+ * Calls `onWrites` when the console changes the graph a page is showing, so
+ * the page can reload what it displays. Writes to other graphs are ignored.
+ */
+export function useGraphWrites(graphId, onWrites) {
+    const onWritesRef = useRef(onWrites);
+    onWritesRef.current = onWrites;
+    useEffect(() => {
+        if (!graphId)
+            return;
+        const handler = (event) => {
+            const detail = event.detail;
+            if ((detail === null || detail === void 0 ? void 0 : detail.graphId) === graphId)
+                onWritesRef.current(detail.writes);
+        };
+        window.addEventListener(GRAPH_WRITES_EVENT, handler);
+        return () => window.removeEventListener(GRAPH_WRITES_EVENT, handler);
+    }, [graphId]);
+}

package/index.d.ts

@@ -2,9 +2,9 @@ export * as AuthCore from './auth-core';
 export { clearToken, getAuthHeader, getRefreshToken, getToken, getValidToken, handleAuthResponse, hasValidToken, storeToken, } from './auth-core/token-storage';
 export { clearUserCookies, clearUserLocalStorage, clearUserSessionStorage, listUserData, performLogoutCleanup, resetUIState, } from './auth-core/cleanup';
 export { AppSwitcher, AuthGuard, AuthProvider, LoginRedirector, SignInForm, SignUpForm, useAuth, } from './auth-components';
-export { useApiError, useMediaQuery, useToast, useUser, useUserLimits, type ToastMessage, } from './hooks';
+export { useApiError, useGraphWrites, useMediaQuery, useToast, useUser, useUserLimits, type ToastMessage, } from './hooks';
 export { createGraphContext, createGraphProvider, createUseGraphContext, EntityProvider, GraphContext, GraphProvider, OrgProvider, ServiceOfferingsProvider, SidebarProvider, useEntity, useGraphContext, useOrg, useServiceOfferings, useSidebarContext, type EntityContextValue, type EntityProviderProps, type GraphContextValue, type GraphProviderProps, type GraphState, type OrgContextState, type OrgContextValue, type OrgProviderProps, type ServiceOfferings, } from './contexts';
-export { clientGraphCookie, clientSidebarCookie, createMcpConnectorUrl, entityCookie, graphCookie, sidebarCookie, type EntityCookie, type GraphCookie, type McpConnectorUrl, type SidebarCookie, } from './lib';
+export { clientGraphCookie, clientSidebarCookie, createMcpConnectorUrl, emitGraphWrites, entityCookie, GRAPH_WRITES_EVENT, graphCookie, readGraphWrites, sidebarCookie, type EntityCookie, type GraphCookie, type GraphWrite, type GraphWritesDetail, type McpConnectorUrl, type SidebarCookie, } from './lib';
 export { ApiError, errorStatus, extractErrorDetail, isApiError, isSessionRejection, isTransientError, toApiError, unwrapSdk, type SdkResult, } from './lib/sdk-errors';
 export { generateEntityUri, isUUID, UUID_REGEX } from './utils';
 export { clearGraphSelection, getGraphSelection, persistGraphSelection, } from './actions/graph-actions';

package/index.js

@@ -8,7 +8,7 @@ export { clearUserCookies, clearUserLocalStorage, clearUserSessionStorage, listU
 // Export auth-components
 export { AppSwitcher, AuthGuard, AuthProvider, LoginRedirector, SignInForm, SignUpForm, useAuth, } from './auth-components';
 // Export hooks
-export { useApiError, useMediaQuery, useToast, useUser, useUserLimits, } from './hooks';
+export { useApiError, useGraphWrites, useMediaQuery, useToast, useUser, useUserLimits, } from './hooks';
 // Export contexts
 export { 
 // Graph context exports
@@ -20,7 +20,7 @@ OrgProvider,
 // Service offerings context
 ServiceOfferingsProvider, SidebarProvider, useEntity, useGraphContext, useOrg, useServiceOfferings, useSidebarContext, } from './contexts';
 // Export lib utilities
-export { clientGraphCookie, clientSidebarCookie, createMcpConnectorUrl, entityCookie, graphCookie, sidebarCookie, } from './lib';
+export { clientGraphCookie, clientSidebarCookie, createMcpConnectorUrl, emitGraphWrites, entityCookie, GRAPH_WRITES_EVENT, graphCookie, readGraphWrites, sidebarCookie, } from './lib';
 // Export the SDK error seam (unwrap an SDK result or throw ApiError)
 export { ApiError, errorStatus, extractErrorDetail, isApiError, isSessionRejection, isTransientError, toApiError, unwrapSdk, } from './lib/sdk-errors';
 // Export utils

package/lib/graph-writes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A write an operator made, as the API reports it in `metadata.writes`.
+ * `id` is null when the tool returned no object id (for example a memory).
+ */
+export interface GraphWrite {
+    operation: string;
+    id: string | null;
+    name: string | null;
+    block_type?: string;
+}
+export interface GraphWritesDetail {
+    graphId: string;
+    writes: GraphWrite[];
+}
+/** Window event fired after the console changes a graph. */
+export declare const GRAPH_WRITES_EVENT = "robosystems:graph-writes";
+/** Tell any page showing `graphId` that it changed. No-op when nothing was written. */
+export declare function emitGraphWrites(graphId: string, writes: GraphWrite[]): void;
+/** Read `metadata.writes` defensively: anything malformed yields no writes. */
+export declare function readGraphWrites(metadata: unknown): GraphWrite[];

package/lib/graph-writes.js

@@ -0,0 +1,19 @@
+/** Window event fired after the console changes a graph. */
+export const GRAPH_WRITES_EVENT = 'robosystems:graph-writes';
+/** Tell any page showing `graphId` that it changed. No-op when nothing was written. */
+export function emitGraphWrites(graphId, writes) {
+    if (typeof window === 'undefined' || writes.length === 0)
+        return;
+    window.dispatchEvent(new CustomEvent(GRAPH_WRITES_EVENT, {
+        detail: { graphId, writes },
+    }));
+}
+/** Read `metadata.writes` defensively: anything malformed yields no writes. */
+export function readGraphWrites(metadata) {
+    const writes = metadata === null || metadata === void 0 ? void 0 : metadata.writes;
+    if (!Array.isArray(writes))
+        return [];
+    return writes.filter((w) => typeof w === 'object' &&
+        w !== null &&
+        typeof w.operation === 'string');
+}

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 export { clientSidebarCookie, sidebarCookie, type SidebarCookie, } from './sidebar-cookie';
 export { clientGraphCookie, graphCookie, type GraphCookie, } from './graph-cookie';
 export { entityCookie, type EntityCookie } from './entity-cookie';
+export { GRAPH_WRITES_EVENT, emitGraphWrites, readGraphWrites, type GraphWrite, type GraphWritesDetail, } from './graph-writes';
 export { createMcpConnectorUrl, type McpConnectorUrl } from './mcp-connector';
 export { ApiError, errorStatus, extractErrorDetail, isApiError, isSessionRejection, isTransientError, toApiError, unwrapSdk, type SdkResult, } from './sdk-errors';

package/lib/index.js

@@ -1,5 +1,6 @@
 export { clientSidebarCookie, sidebarCookie, } from './sidebar-cookie';
 export { clientGraphCookie, graphCookie, } from './graph-cookie';
 export { entityCookie } from './entity-cookie';
+export { GRAPH_WRITES_EVENT, emitGraphWrites, readGraphWrites, } from './graph-writes';
 export { createMcpConnectorUrl } from './mcp-connector';
 export { ApiError, errorStatus, extractErrorDetail, isApiError, isSessionRejection, isTransientError, toApiError, unwrapSdk, } from './sdk-errors';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosystems/core",
-  "version": "0.11.5",
+  "version": "0.13.0",
   "description": "Shared RoboSystems frontend core library (auth, contexts, task monitoring, UI components) for the RoboSystems Next.js apps",
   "license": "MIT",
   "private": false,

package/ui-components/layout/LiveDemo.d.ts

@@ -0,0 +1,22 @@
+export interface LiveDemoProps {
+    /** Demo module name under /public/demos (e.g. "hero", "inbox"). */
+    name: string;
+    /** Stage aspect ratio as width / height, reserved before the demo loads. */
+    aspect: number;
+    /**
+     * The phone layout's aspect ratio (the demo module's `mobile` width / height),
+     * used below the sm breakpoint, where kit.js mounts that layout.
+     */
+    phoneAspect?: number;
+    /** What the animation shows, for screen readers. */
+    label: string;
+    className?: string;
+}
+/**
+ * An animated product demo from the app's /public/demos, mounted in a shadow root so its
+ * styles stay off the page. The demos are plain ES modules shared with the
+ * content machine's renderer, which shoots the same files for the social cuts;
+ * see demos/runtime.ts in this package. They loop only while on screen and hold one frame
+ * for reduced motion.
+ */
+export declare function LiveDemo({ name, aspect, label, phoneAspect, className, }: LiveDemoProps): import("react").JSX.Element;

package/ui-components/layout/LiveDemo.js

@@ -0,0 +1,44 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+/**
+ * An animated product demo from the app's /public/demos, mounted in a shadow root so its
+ * styles stay off the page. The demos are plain ES modules shared with the
+ * content machine's renderer, which shoots the same files for the social cuts;
+ * see demos/runtime.ts in this package. They loop only while on screen and hold one frame
+ * for reduced motion.
+ */
+export function LiveDemo({ name, aspect, label, phoneAspect, className = '', }) {
+    const host = useRef(null);
+    useEffect(() => {
+        let handle;
+        let cancelled = false;
+        const load = async () => {
+            // Served from /public at runtime, never bundled.
+            const base = '/demos/';
+            const [kit, demo] = await Promise.all([
+                import(
+                /* webpackIgnore: true */ /* turbopackIgnore: true */ base + 'kit.js'),
+                import(
+                /* webpackIgnore: true */ /* turbopackIgnore: true */ base +
+                    name +
+                    '.js'),
+            ]);
+            if (cancelled || !host.current)
+                return;
+            handle = kit.mount(host.current, demo.default);
+        };
+        load().catch((err) => {
+            // The page stands without the demo, but a broken module should still show up.
+            console.error(`LiveDemo "${name}" failed to load`, err);
+        });
+        return () => {
+            cancelled = true;
+            handle === null || handle === void 0 ? void 0 : handle.destroy();
+        };
+    }, [name]);
+    return (_jsx("div", { ref: host, role: "img", "aria-label": label, className: `relative aspect-(--aspect) w-full overflow-hidden max-sm:aspect-(--phone-aspect) ${className}`, style: {
+            '--aspect': aspect,
+            '--phone-aspect': phoneAspect !== null && phoneAspect !== void 0 ? phoneAspect : aspect,
+        } }));
+}

package/ui-components/layout/index.d.ts

@@ -2,6 +2,7 @@ export { ACCOUNT_SETTINGS_PATH, useAccountSettingsLink, type AccountSettingsLink
 export { CoreNavbar } from './CoreNavbar';
 export { CoreSidebar, type SidebarItemData } from './CoreSidebar';
 export { LandingFooter, type FooterLink, type LandingFooterProps, } from './LandingFooter';
+export { LiveDemo, type LiveDemoProps } from './LiveDemo';
 export { PageContainer } from './PageContainer';
 export { PageHeader, type PageHeaderProps } from './PageHeader';
 export { SettingsContainer } from './SettingsContainer';

package/ui-components/layout/index.js

@@ -2,6 +2,7 @@ export { ACCOUNT_SETTINGS_PATH, useAccountSettingsLink, } from './account-settin
 export { CoreNavbar } from './CoreNavbar';
 export { CoreSidebar } from './CoreSidebar';
 export { LandingFooter, } from './LandingFooter';
+export { LiveDemo } from './LiveDemo';
 export { PageContainer } from './PageContainer';
 export { PageHeader } from './PageHeader';
 export { SettingsContainer } from './SettingsContainer';