@elizaos/ui 2.0.3-beta.2 → 2.0.3-beta.3

package/styles/styles.css

@@ -44,6 +44,7 @@ body {
   max-width: 100%;
   height: 100%;
   margin: 0;
+  background: var(--launch-bg, #ef5a1f);
   overflow: hidden;
   overscroll-behavior: none;
   -webkit-text-size-adjust: 100%;
@@ -58,7 +59,7 @@ body {
   overflow: hidden;
   font-family: var(--font-body);
   color: var(--text);
-  background: var(--bg);
+  background: var(--launch-bg, #ef5a1f);
 }
 
 html.eliza-chat-overlay-shell,
@@ -338,9 +339,13 @@ kbd {
   *::before,
   /* biome-ignore lint/style/noDescendingSpecificity: a11y override must apply to every pseudo-element. */
   *::after {
-    animation-duration: 0.01ms;
-    animation-iteration-count: 1;
-    transition-duration: 0.01ms;
-    scroll-behavior: auto;
+    /* biome-ignore lint/complexity/noImportantStyles: reduced-motion accessibility override must win the cascade. */
+    animation-duration: 0.01ms !important;
+    /* biome-ignore lint/complexity/noImportantStyles: reduced-motion accessibility override must win the cascade. */
+    animation-iteration-count: 1 !important;
+    /* biome-ignore lint/complexity/noImportantStyles: reduced-motion accessibility override must win the cascade. */
+    transition-duration: 0.01ms !important;
+    /* biome-ignore lint/complexity/noImportantStyles: reduced-motion accessibility override must win the cascade. */
+    scroll-behavior: auto !important;
   }
 }

package/testing/layout-stability.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Layout-stability / flicker detection (pure, real, fails-when-broken).
+ *
+ * Two real, browser-measurable symptoms of "not smooth":
+ *  1. Layout shift — content jumps/reflows after paint (the ranked widget list
+ *     reordering, a card popping in and pushing others down). Quantified the
+ *     same way Chrome computes CLS: the sum of `layout-shift` PerformanceEntry
+ *     values that were NOT caused by recent user input.
+ *  2. Opacity flash — an element fades out and back (or in then out), e.g. an
+ *     animation that re-triggers on re-render. Detected from a time series of
+ *     sampled opacity.
+ *
+ * This module is the PURE math (mirrors frame-budget.ts): a Playwright/runtime
+ * caller feeds it the observed entries/samples and it returns a verdict. Pure ⇒
+ * unit-testable deterministically, so the detector itself is proven (not larp)
+ * before it's pointed at the live app.
+ */
+/** One `layout-shift` PerformanceEntry, narrowed to what CLS needs. */
+export interface LayoutShiftSample {
+    /** The entry's shift `value`. */
+    value: number;
+    /** True if a user interaction happened just before — excluded from CLS. */
+    hadRecentInput: boolean;
+}
+/**
+ * Cumulative Layout Shift: the sum of shift values not attributable to recent
+ * user input (matching the Web Vitals CLS definition). 0 = perfectly stable.
+ */
+export declare function cumulativeLayoutShift(samples: readonly LayoutShiftSample[]): number;
+/** A timestamped opacity reading of one element. */
+export interface OpacitySample {
+    /** Monotonic time (ms). */
+    t: number;
+    /** Computed opacity in [0,1]. */
+    opacity: number;
+}
+/**
+ * A "flash" is a non-monotonic opacity excursion: the value moves away from its
+ * settled level and comes back by at least `minDelta` (a fade-out-then-in, or a
+ * fade-in-then-out). A clean one-way fade-in on mount is NOT a flash. Returns
+ * true if any such excursion exceeding `minDelta` is found.
+ */
+export declare function detectOpacityFlash(samples: readonly OpacitySample[], minDelta?: number): boolean;
+export interface StabilityBudget {
+    /** Max acceptable CLS for the window (Web Vitals "good" is < 0.1). */
+    maxCls: number;
+    /** Min opacity excursion to count as a flash. Default 0.2. */
+    flashMinDelta?: number;
+}
+export interface StabilitySummary {
+    cls: number;
+    shiftCount: number;
+    flashed: boolean;
+    /** True when CLS exceeds budget OR a flash was detected. */
+    flagged: boolean;
+}
+/** Combine shift + opacity samples into a single pass/flag verdict. */
+export declare function summarizeStability(shifts: readonly LayoutShiftSample[], opacity: readonly OpacitySample[], budget: StabilityBudget): StabilitySummary;
+/**
+ * Browser-side script body (as a string-returning fn for `page.evaluate` /
+ * addInitScript) that installs a `layout-shift` PerformanceObserver and stashes
+ * samples on `window.__ELIZA_LAYOUT_SHIFTS__`. The Playwright caller reads that
+ * array and feeds {@link summarizeStability}. Kept here so the contract lives
+ * next to the math it feeds.
+ */
+export declare const LAYOUT_SHIFT_OBSERVER_INIT = "\n(() => {\n  const w = window;\n  if (w.__ELIZA_LAYOUT_SHIFTS__) return;\n  w.__ELIZA_LAYOUT_SHIFTS__ = [];\n  try {\n    const obs = new PerformanceObserver((list) => {\n      for (const entry of list.getEntries()) {\n        w.__ELIZA_LAYOUT_SHIFTS__.push({\n          value: entry.value,\n          hadRecentInput: entry.hadRecentInput === true,\n        });\n      }\n    });\n    obs.observe({ type: 'layout-shift', buffered: true });\n  } catch {\n    /* layout-shift unsupported \u2014 caller treats absence as 0 CLS */\n  }\n})();\n";
+//# sourceMappingURL=layout-stability.d.ts.map

package/testing/layout-stability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-stability.d.ts","sourceRoot":"","sources":["../../../../../src/testing/layout-stability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,MAAM,CAQR;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,QAAQ,SAAM,GACb,OAAO,CA2BT;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,MAAM,EAAE,eAAe,GACtB,gBAAgB,CAYlB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,kiBAmBtC,CAAC"}

package/testing/layout-stability.js

@@ -0,0 +1,106 @@
+/**
+ * Layout-stability / flicker detection (pure, real, fails-when-broken).
+ *
+ * Two real, browser-measurable symptoms of "not smooth":
+ *  1. Layout shift — content jumps/reflows after paint (the ranked widget list
+ *     reordering, a card popping in and pushing others down). Quantified the
+ *     same way Chrome computes CLS: the sum of `layout-shift` PerformanceEntry
+ *     values that were NOT caused by recent user input.
+ *  2. Opacity flash — an element fades out and back (or in then out), e.g. an
+ *     animation that re-triggers on re-render. Detected from a time series of
+ *     sampled opacity.
+ *
+ * This module is the PURE math (mirrors frame-budget.ts): a Playwright/runtime
+ * caller feeds it the observed entries/samples and it returns a verdict. Pure ⇒
+ * unit-testable deterministically, so the detector itself is proven (not larp)
+ * before it's pointed at the live app.
+ */
+/**
+ * Cumulative Layout Shift: the sum of shift values not attributable to recent
+ * user input (matching the Web Vitals CLS definition). 0 = perfectly stable.
+ */
+export function cumulativeLayoutShift(samples) {
+    let cls = 0;
+    for (const s of samples) {
+        if (!s.hadRecentInput && Number.isFinite(s.value) && s.value > 0) {
+            cls += s.value;
+        }
+    }
+    return cls;
+}
+/**
+ * A "flash" is a non-monotonic opacity excursion: the value moves away from its
+ * settled level and comes back by at least `minDelta` (a fade-out-then-in, or a
+ * fade-in-then-out). A clean one-way fade-in on mount is NOT a flash. Returns
+ * true if any such excursion exceeding `minDelta` is found.
+ */
+export function detectOpacityFlash(samples, minDelta = 0.2) {
+    if (samples.length < 3)
+        return false;
+    // Walk the series tracking local extrema; a reversal of >= minDelta in each
+    // direction (down then up, or up then down) is a flash.
+    let prev = samples[0].opacity;
+    let direction = "flat";
+    let pendingSwing = 0;
+    for (let i = 1; i < samples.length; i++) {
+        const cur = samples[i].opacity;
+        const d = cur - prev;
+        if (Math.abs(d) < 1e-3) {
+            prev = cur;
+            continue;
+        }
+        const nextDir = d > 0 ? "up" : "down";
+        if (direction !== "flat" && nextDir !== direction) {
+            // A reversal: if the prior swing AND this swing both clear minDelta,
+            // it's a visible flash.
+            if (pendingSwing >= minDelta && Math.abs(d) >= minDelta)
+                return true;
+            pendingSwing = Math.abs(d);
+        }
+        else {
+            pendingSwing += Math.abs(d);
+        }
+        direction = nextDir;
+        prev = cur;
+    }
+    return false;
+}
+/** Combine shift + opacity samples into a single pass/flag verdict. */
+export function summarizeStability(shifts, opacity, budget) {
+    const cls = cumulativeLayoutShift(shifts);
+    const shiftCount = shifts.filter((s) => !s.hadRecentInput && s.value > 0).length;
+    const flashed = detectOpacityFlash(opacity, budget.flashMinDelta ?? 0.2);
+    return {
+        cls,
+        shiftCount,
+        flashed,
+        flagged: cls > budget.maxCls || flashed,
+    };
+}
+/**
+ * Browser-side script body (as a string-returning fn for `page.evaluate` /
+ * addInitScript) that installs a `layout-shift` PerformanceObserver and stashes
+ * samples on `window.__ELIZA_LAYOUT_SHIFTS__`. The Playwright caller reads that
+ * array and feeds {@link summarizeStability}. Kept here so the contract lives
+ * next to the math it feeds.
+ */
+export const LAYOUT_SHIFT_OBSERVER_INIT = `
+(() => {
+  const w = window;
+  if (w.__ELIZA_LAYOUT_SHIFTS__) return;
+  w.__ELIZA_LAYOUT_SHIFTS__ = [];
+  try {
+    const obs = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        w.__ELIZA_LAYOUT_SHIFTS__.push({
+          value: entry.value,
+          hadRecentInput: entry.hadRecentInput === true,
+        });
+      }
+    });
+    obs.observe({ type: 'layout-shift', buffered: true });
+  } catch {
+    /* layout-shift unsupported — caller treats absence as 0 CLS */
+  }
+})();
+`;

package/testing/render-counter.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Render-count test tooling (real, fails-when-broken).
+ *
+ * A re-render is a React *commit* to a subtree. To catch unnecessary re-renders
+ * (and lock them against regression), wrap the subtree under test in
+ * {@link RenderProbe} and assert on the counter after an interaction — the
+ * counter increments once per commit (mount + each update), exactly mirroring
+ * React's own profiler. A regression that adds an extra commit makes the count
+ * go up, so the assertion FAILS. This is not a heuristic: it counts the real
+ * commits React performs.
+ *
+ * Two granularities:
+ *  - {@link RenderProbe} (React.Profiler): counts commits of a whole subtree —
+ *    use it to lock "this view does not re-render its children when X ticks".
+ *  - {@link useRenderSpy}: increments a counter on every render of the component
+ *    it's called in — use it to lock a single component's render count.
+ *
+ * Both are pure test instrumentation (no behavior change); they belong in
+ * *.test.tsx files, not shipped UI.
+ */
+import { type ReactNode } from "react";
+export interface RenderCounter {
+    /** Total commits (mounts + updates). */
+    count: number;
+    /** Commits in the "mount" phase. */
+    mounts: number;
+    /** Commits in "update" / "nested-update" phases. */
+    updates: number;
+    /** Sum of React's actualDuration across commits (ms) — cost, not just count. */
+    totalActualMs: number;
+    /** Reset all tallies (e.g. to count only post-interaction commits). */
+    reset(): void;
+}
+/** Create a fresh render counter for a test. */
+export declare function makeRenderCounter(): RenderCounter;
+export interface RenderProbeProps {
+    /** Stable id for the profiled region (shown in failure messages). */
+    id: string;
+    /** The counter this probe writes commits into. */
+    counter: RenderCounter;
+    children: ReactNode;
+}
+/**
+ * Wrap a subtree to count its React commits into `counter`. Every time React
+ * commits this region (mount or update), the counter advances — so a test can
+ * assert the exact number of renders an interaction triggers.
+ */
+export declare function RenderProbe({ id, counter, children, }: RenderProbeProps): React.JSX.Element;
+/**
+ * Increment `counter` on every render of the component that calls this hook.
+ * Unlike {@link RenderProbe} (subtree commits), this counts a single
+ * component's render function invocations — the tightest lock for "component X
+ * must not re-render on an unrelated state change".
+ */
+export declare function useRenderSpy(counter: RenderCounter): void;
+//# sourceMappingURL=render-counter.d.ts.map

package/testing/render-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-counter.d.ts","sourceRoot":"","sources":["../../../../../src/testing/render-counter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA2C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,KAAK,IAAI,IAAI,CAAC;CACf;AAED,gDAAgD;AAChD,wBAAgB,iBAAiB,IAAI,aAAa,CAajD;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,OAAO,EACP,QAAQ,GACT,EAAE,gBAAgB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAYtC;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAEzD"}

package/testing/render-counter.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Render-count test tooling (real, fails-when-broken).
+ *
+ * A re-render is a React *commit* to a subtree. To catch unnecessary re-renders
+ * (and lock them against regression), wrap the subtree under test in
+ * {@link RenderProbe} and assert on the counter after an interaction — the
+ * counter increments once per commit (mount + each update), exactly mirroring
+ * React's own profiler. A regression that adds an extra commit makes the count
+ * go up, so the assertion FAILS. This is not a heuristic: it counts the real
+ * commits React performs.
+ *
+ * Two granularities:
+ *  - {@link RenderProbe} (React.Profiler): counts commits of a whole subtree —
+ *    use it to lock "this view does not re-render its children when X ticks".
+ *  - {@link useRenderSpy}: increments a counter on every render of the component
+ *    it's called in — use it to lock a single component's render count.
+ *
+ * Both are pure test instrumentation (no behavior change); they belong in
+ * *.test.tsx files, not shipped UI.
+ */
+import { Profiler } from "react";
+/** Create a fresh render counter for a test. */
+export function makeRenderCounter() {
+    return {
+        count: 0,
+        mounts: 0,
+        updates: 0,
+        totalActualMs: 0,
+        reset() {
+            this.count = 0;
+            this.mounts = 0;
+            this.updates = 0;
+            this.totalActualMs = 0;
+        },
+    };
+}
+/**
+ * Wrap a subtree to count its React commits into `counter`. Every time React
+ * commits this region (mount or update), the counter advances — so a test can
+ * assert the exact number of renders an interaction triggers.
+ */
+export function RenderProbe({ id, counter, children, }) {
+    const onRender = (_id, phase, actualDuration) => {
+        counter.count += 1;
+        if (phase === "mount")
+            counter.mounts += 1;
+        else
+            counter.updates += 1;
+        counter.totalActualMs += actualDuration;
+    };
+    return (_jsx(Profiler, { id: id, onRender: onRender, children: children }));
+}
+/**
+ * Increment `counter` on every render of the component that calls this hook.
+ * Unlike {@link RenderProbe} (subtree commits), this counts a single
+ * component's render function invocations — the tightest lock for "component X
+ * must not re-render on an unrelated state change".
+ */
+export function useRenderSpy(counter) {
+    counter.count += 1;
+}

package/themes/presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../../../src/themes/presets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,eAAO,MAAM,mBAAmB,EAAE,eA0JjC,CAAC"}
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../../../src/themes/presets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,eAAO,MAAM,mBAAmB,EAAE,eA4JjC,CAAC"}

package/themes/presets.js

@@ -9,21 +9,21 @@ export const ELIZA_DEFAULT_THEME = {
     // Brand rule (#8796): no blue anywhere. Orange accent → neutral, no blue stop.
     preview: "linear-gradient(135deg, #ffb066 0%, #ff8a24 55%, #0b0e11 100%)",
     light: {
-        bg: "#eef8ff",
-        bgAccent: "#dff2ff",
+        bg: "#f5f5f4",
+        bgAccent: "#ececeb",
         bgElevated: "rgba(255, 255, 255, 0.86)",
         bgHover: "rgba(255, 255, 255, 0.94)",
-        bgMuted: "#d8efff",
+        bgMuted: "#e7e7e5",
         card: "rgba(255, 255, 255, 0.88)",
-        cardForeground: "#1e2329",
+        cardForeground: "#23231f",
         surface: "rgba(255, 255, 255, 0.82)",
-        text: "#1e2329",
-        textStrong: "#0b0e11",
-        chatText: "#1e2329",
-        muted: "rgba(6, 19, 31, 0.58)",
-        mutedStrong: "rgba(6, 19, 31, 0.74)",
-        border: "rgba(6, 19, 31, 0.12)",
-        borderStrong: "rgba(6, 19, 31, 0.2)",
+        text: "#23231f",
+        textStrong: "#111110",
+        chatText: "#23231f",
+        muted: "rgba(20, 20, 18, 0.58)",
+        mutedStrong: "rgba(20, 20, 18, 0.74)",
+        border: "rgba(20, 20, 18, 0.12)",
+        borderStrong: "rgba(20, 20, 18, 0.2)",
         borderHover: "#ff8a24",
         input: "rgba(255, 255, 255, 0.9)",
         ring: "#ff8a24",
@@ -51,7 +51,7 @@ export const ELIZA_DEFAULT_THEME = {
         statusInfoBg: "rgba(111, 111, 115, 0.12)",
         focus: "rgba(255, 138, 36, 0.18)",
         focusRing: "0 0 0 2px rgba(255, 138, 36, 0.42)",
-        scrollbarTrack: "#edf1f4",
+        scrollbarTrack: "#ededec",
         scrollbarThumbStart: "rgba(240, 185, 11, 0.42)",
         scrollbarThumbMid: "rgba(240, 185, 11, 0.58)",
         scrollbarThumbEnd: "rgba(216, 160, 0, 0.66)",
@@ -60,10 +60,12 @@ export const ELIZA_DEFAULT_THEME = {
         scrollbarThumbHoverEnd: "rgba(216, 160, 0, 0.78)",
         scrollbarThumbEdge: "rgba(240, 185, 11, 0.12)",
         headerBarBg: "rgba(255, 255, 255, 0.64)",
-        headerBarFg: "#06131f",
+        headerBarFg: "#1a1a18",
         sectionBarBg: "rgba(255, 255, 255, 0.68)",
-        sectionBarFg: "#1e2329",
-        linkColor: "#0c5f9e",
+        sectionBarFg: "#23231f",
+        // No blue (#8796): links rest at body-text color and warm to orange on
+        // hover, mirroring the dark theme — never a blue link.
+        linkColor: "var(--text)",
         linkHoverColor: "#d95f16",
         shadowXs: "0 1px 2px rgb(15 23 42 / 0.04)",
         shadowSm: "0 1px 3px rgb(15 23 42 / 0.05)",

package/utils/attachment-url.d.ts

@@ -0,0 +1,42 @@
+/**
+ * URL scheme allowlist for attachment rendering.
+ *
+ * Agent- and connector-provided attachment URLs are rendered directly into the
+ * DOM as `href` / `src` attributes (links, images, audio, video, downloads).
+ * An untrusted URL with a dangerous scheme - `javascript:`, `vbscript:`,
+ * `file:`, `data:text/html`, `data:image/svg+xml`, etc. - can lead to script
+ * execution or local-file disclosure when clicked or loaded. To prevent that,
+ * every attachment URL MUST be passed through {@link isSafeAttachmentUrl}
+ * before it is used as an `href` / `src`, and the media/link must NOT be
+ * rendered when it returns `false`.
+ *
+ * A URL is considered safe ONLY when it is one of:
+ *  - an `http://` or `https://` URL;
+ *  - a root-relative / app URL (begins with `/`, e.g. `/api/media/<hash>`);
+ *  - a `blob:` URL;
+ *  - a `data:` URL whose media type is in the allowlist
+ *    (`image/*`, `audio/*`, `video/*`, `application/pdf`, `text/plain`).
+ *
+ * Everything else returns `false`: other/unknown schemes (`javascript:`,
+ * `vbscript:`, `file:`, `mailto:`, custom `foo://`, ...), `data:` URLs with a
+ * non-allowlisted media type (notably `data:text/html` and
+ * `data:image/svg+xml`, both script-capable), empty / whitespace-only input,
+ * and malformed input.
+ *
+ * The check is deliberately strict and conservative: it tolerates surrounding
+ * whitespace, embedded control characters (which browsers strip when parsing
+ * the scheme, so `java\0script:` must be treated as `javascript:`), and a
+ * mixed-case scheme, all of which are common XSS-payload obfuscations.
+ */
+/**
+ * Returns `true` only for attachment URLs that are safe to render as an
+ * `href` / `src`. See the module doc comment for the exact allowlist.
+ */
+export declare function isSafeAttachmentUrl(url: string): boolean;
+/**
+ * Returns `url` when it is safe to render (per {@link isSafeAttachmentUrl}),
+ * otherwise returns `fallback` (default: empty string). Useful for inlining a
+ * guarded value directly into an `href` / `src`.
+ */
+export declare function safeAttachmentUrl(url: string, fallback?: string): string;
+//# sourceMappingURL=attachment-url.d.ts.map

package/utils/attachment-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-url.d.ts","sourceRoot":"","sources":["../../../../../src/utils/attachment-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA2CH;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAmDxD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAEpE"}

package/utils/attachment-url.js

@@ -0,0 +1,130 @@
+/**
+ * URL scheme allowlist for attachment rendering.
+ *
+ * Agent- and connector-provided attachment URLs are rendered directly into the
+ * DOM as `href` / `src` attributes (links, images, audio, video, downloads).
+ * An untrusted URL with a dangerous scheme - `javascript:`, `vbscript:`,
+ * `file:`, `data:text/html`, `data:image/svg+xml`, etc. - can lead to script
+ * execution or local-file disclosure when clicked or loaded. To prevent that,
+ * every attachment URL MUST be passed through {@link isSafeAttachmentUrl}
+ * before it is used as an `href` / `src`, and the media/link must NOT be
+ * rendered when it returns `false`.
+ *
+ * A URL is considered safe ONLY when it is one of:
+ *  - an `http://` or `https://` URL;
+ *  - a root-relative / app URL (begins with `/`, e.g. `/api/media/<hash>`);
+ *  - a `blob:` URL;
+ *  - a `data:` URL whose media type is in the allowlist
+ *    (`image/*`, `audio/*`, `video/*`, `application/pdf`, `text/plain`).
+ *
+ * Everything else returns `false`: other/unknown schemes (`javascript:`,
+ * `vbscript:`, `file:`, `mailto:`, custom `foo://`, ...), `data:` URLs with a
+ * non-allowlisted media type (notably `data:text/html` and
+ * `data:image/svg+xml`, both script-capable), empty / whitespace-only input,
+ * and malformed input.
+ *
+ * The check is deliberately strict and conservative: it tolerates surrounding
+ * whitespace, embedded control characters (which browsers strip when parsing
+ * the scheme, so `java\0script:` must be treated as `javascript:`), and a
+ * mixed-case scheme, all of which are common XSS-payload obfuscations.
+ */
+/**
+ * `data:` media type prefixes permitted for inline rendering. `*` allows any
+ * subtype (e.g. `image/png`, `audio/mpeg`), except the explicit exclusions in
+ * {@link UNSAFE_DATA_MEDIA_TYPES}.
+ */
+const SAFE_DATA_MEDIA_TYPE_PREFIXES = ["image/", "audio/", "video/"];
+const SAFE_DATA_MEDIA_TYPES_EXACT = new Set([
+    "application/pdf",
+    "text/plain",
+]);
+// Disallowed even though they would match a prefix above: both can run script.
+const UNSAFE_DATA_MEDIA_TYPES = new Set(["image/svg+xml", "text/html"]);
+/**
+ * Strip ASCII whitespace and C0/DEL control characters the way a browser does
+ * before resolving a URL's scheme. This neutralises obfuscation like
+ * `java\tscript:` / `java\nscript:` so the scheme test sees `javascript:`.
+ * Done by code point to avoid embedding literal control chars in source.
+ */
+function sanitizeForSchemeCheck(url) {
+    let out = "";
+    for (const ch of url) {
+        const code = ch.codePointAt(0) ?? 0;
+        // Skip C0 controls (0x00-0x1F), space (0x20), and DEL (0x7F).
+        if (code <= 0x20 || code === 0x7f)
+            continue;
+        out += ch;
+    }
+    return out;
+}
+function isAllowedDataMediaType(mediaType) {
+    const type = mediaType.toLowerCase();
+    if (UNSAFE_DATA_MEDIA_TYPES.has(type))
+        return false;
+    if (SAFE_DATA_MEDIA_TYPES_EXACT.has(type))
+        return true;
+    return SAFE_DATA_MEDIA_TYPE_PREFIXES.some((prefix) => type.startsWith(prefix));
+}
+/**
+ * Returns `true` only for attachment URLs that are safe to render as an
+ * `href` / `src`. See the module doc comment for the exact allowlist.
+ */
+export function isSafeAttachmentUrl(url) {
+    if (typeof url !== "string")
+        return false;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return false;
+    // Root-relative / app URL (e.g. `/api/media/<hash>`). A scheme-relative URL
+    // (`//host/...`) is rejected: it is not an app path and its scheme is
+    // ambiguous.
+    if (trimmed.startsWith("/")) {
+        return !trimmed.startsWith("//");
+    }
+    // Resolve the scheme the way a browser would: ignore whitespace/control
+    // chars, then read up to the first colon.
+    const sanitized = sanitizeForSchemeCheck(trimmed);
+    const colonIndex = sanitized.indexOf(":");
+    // No colon, or a leading colon: not an absolute URL and not root-relative,
+    // so reject. (Relative paths like `foo/bar` are never produced for
+    // attachments and are not safe to assume an origin for.)
+    if (colonIndex <= 0)
+        return false;
+    const scheme = sanitized.slice(0, colonIndex).toLowerCase();
+    // A scheme must be a valid URL scheme token; anything else is malformed.
+    if (!/^[a-z][a-z0-9+.-]*$/.test(scheme))
+        return false;
+    switch (scheme) {
+        case "http":
+        case "https":
+        case "blob":
+            return true;
+        case "data": {
+            // Parse the media type out of `data:[<media type>][;base64],<data>`.
+            // Use the sanitized string so control-char obfuscation inside the
+            // header cannot smuggle a disallowed media type past the check.
+            const header = sanitized.slice(sanitized.indexOf(":") + 1);
+            const comma = header.indexOf(",");
+            // A data: URL with no comma is malformed.
+            if (comma < 0)
+                return false;
+            const meta = header.slice(0, comma);
+            // media type is everything before the first `;` (params like `;base64`).
+            const mediaType = meta.split(";")[0]?.trim() ?? "";
+            // An empty media type defaults to `text/plain` per the data: URL spec.
+            if (!mediaType)
+                return true;
+            return isAllowedDataMediaType(mediaType);
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * Returns `url` when it is safe to render (per {@link isSafeAttachmentUrl}),
+ * otherwise returns `fallback` (default: empty string). Useful for inlining a
+ * guarded value directly into an `href` / `src`.
+ */
+export function safeAttachmentUrl(url, fallback = "") {
+    return isSafeAttachmentUrl(url) ? url : fallback;
+}

package/utils/cloud-agent-base.d.ts

@@ -3,7 +3,6 @@
  * `/api/v1/eliza/agents/:id` and JSON-RPC at the sibling `/bridge`.
  */
 export declare function normalizeDirectCloudSharedAgentApiBase(value: string): string;
-export declare function isDirectCloudSharedAgentApiBase(value: string): boolean;
 /**
  * Eliza Cloud control-plane hostnames. The bare origin (and the
  * `/api/v1/eliza/agents` collection) on any of these is NOT a per-agent base —

package/utils/cloud-agent-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloud-agent-base.d.ts","sourceRoot":"","sources":["../../../../../src/utils/cloud-agent-base.ts"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,wBAAgB,sCAAsC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW5E;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMtE;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,aAK1C,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAOf"}
+{"version":3,"file":"cloud-agent-base.d.ts","sourceRoot":"","sources":["../../../../../src/utils/cloud-agent-base.ts"],"names":[],"mappings":"AA6BA;;;GAGG;AACH,wBAAgB,sCAAsC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAW5E;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,aAK1C,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAMT;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CAOf"}

package/utils/cloud-agent-base.js

@@ -43,14 +43,6 @@ export function normalizeDirectCloudSharedAgentApiBase(value) {
     url.hash = "";
     return stripTrailingSlash(url.toString());
 }
-export function isDirectCloudSharedAgentApiBase(value) {
-    const normalized = normalizeDirectCloudSharedAgentApiBase(value);
-    const url = normalizeHttpUrl(normalized);
-    if (!url)
-        return false;
-    const sharedPath = directSharedAgentPath(url.pathname);
-    return Boolean(sharedPath && !sharedPath.hasBridgeSuffix);
-}
 /**
  * Eliza Cloud control-plane hostnames. The bare origin (and the
  * `/api/v1/eliza/agents` collection) on any of these is NOT a per-agent base —