akanjs 3.0.0-beta.3 → 3.0.0-beta.5

package/common/types.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
   onError?: (error: string) => void;
   token?: string;
   partial?: string[];
-  timeout?: number;
+  /**
+   * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+   * endpoint's declared `timeout`, which overrides the client's own default.
+   */
+  timeout?: number | false;
   /**
    * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
    *

package/fetch/client/fetchClient.ts

@@ -173,6 +173,13 @@ export class FetchClient {
         }
       : signal;
   }
+  /**
+   * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+   * as long as the runtime will, which is the browser's own limit — minutes.
+   */
+  setTimeout(timeout?: number | false) {
+    this.http.setTimeout(timeout);
+  }
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
@@ -316,8 +323,9 @@ export class FetchClient {
           const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
           const headers = this.#makeAuthHeaders(option);
           const baseUrl = option?.origin;
+          const timeout = option?.timeout ?? endpoint.timeout;
 
-          const requestQuery = () => this.http.get(url, { headers, baseUrl });
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -339,6 +347,7 @@ export class FetchClient {
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeAuthHeaders(option),
             baseUrl: option?.origin,
+            timeout: option?.timeout ?? endpoint.timeout,
           });
           const parsedReturn = parseReturn(response, { crystalize: option?.crystalize ?? true });
           return parsedReturn;
@@ -827,7 +836,15 @@ export class FetchClient {
       connect = false,
       base,
       Err,
-    }: { origin?: string; connect?: boolean; base?: FetchProxy; Err?: ErrorConstructor } = {},
+      timeout,
+    }: {
+      origin?: string;
+      connect?: boolean;
+      base?: FetchProxy;
+      Err?: ErrorConstructor;
+      /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+      timeout?: number | false;
+    } = {},
   ): {
     sig: ClientSignalMap<SigType>;
     fetch: SigType["fetch"];
@@ -838,6 +855,7 @@ export class FetchClient {
     const proxy =
       shared ??
       FetchClient.#makeProxy<unknown, Record<string, SliceMeta>>(new FetchClient(origin, {}, serializedSignal, Err));
+    if (timeout !== undefined) proxy.instance.setTimeout(timeout);
     if (connect) proxy.instance.connect();
     const sig = {} as any;
     Object.entries(serializedSignal).forEach(([refName, serializedSignal]) => {

package/fetch/client/httpClient.ts

@@ -49,6 +49,10 @@ export class HttpClient {
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
   }
+  /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+  setTimeout(timeout?: number | false) {
+    this.#timeout = timeout;
+  }
   #resolveBaseUrl(baseUrl?: string) {
     return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -17,7 +17,7 @@ import { agentTurnConstant, agentTurnDocument } from "../../signal/agentTurn";
 import { Base, BaseEndpoint, BaseInternal } from "../../signal/base.signal";
 import type { Endpoint } from "../../signal/endpoint";
 import type { Internal } from "../../signal/internal";
-import { Logging, type MiddlewareCls } from "../../signal/middleware";
+import { Cache, Logging, type MiddlewareCls, Timeout } from "../../signal/middleware";
 import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
 import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
@@ -126,6 +126,10 @@ export class DiLifecycle {
       : null;
     if (frameworkAgent) this.#service.set("agent", frameworkAgent);
     this.#middleware.set(Logging.refName, Logging);
+
+    this.#middleware.set(Timeout.refName, Timeout);
+
+    this.#middleware.set(Cache.refName, Cache);
     const defaultOption = createDefaultAkanOption();
     defaultOption.getMiddlewares().forEach((middleware) => {
       this.#middleware.set(middleware.refName, middleware);

package/service/agent.service.ts

@@ -98,14 +98,18 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;
+
+    if (typeof attachment.mimeType !== "string") return false;
     return attachment.mimeType.startsWith("image/") ? !!accepts.image : !!accepts.document;
   }
 
   private static note(attachment: AgentWireAttachment): string {
     const why =
-      attachment.data || attachment.url
-        ? "this model cannot read that type"
-        : "its content is no longer available, as a reloaded conversation keeps the name and not the bytes";
+      !attachment.data && !attachment.url
+        ? "its content is no longer available, as a reloaded conversation keeps the name and not the bytes"
+        : typeof attachment.mimeType === "string"
+          ? "this model cannot read that type"
+          : "it names no type it could be read as";
     return `[Attachment not read: ${attachment.name} (${attachment.mimeType}) — ${why}. Tell the user it was not read instead of guessing what it holds, and ask for the text if the answer needs it.]`;
   }
 }

package/signal/middleware.ts

@@ -2,6 +2,7 @@ import type { BackendEnv, Cls, PromiseOrObject } from "akanjs/base";
 import { Logger } from "akanjs/common";
 import { type CacheAdaptor, CacheAdaptorRole } from "akanjs/service";
 import dayjs from "dayjs";
+import { Exception } from "./exception";
 import type { SignalContext } from "./signalContext";
 import { traceCache } from "./trace";
 
@@ -46,71 +47,105 @@ export class Logging extends middleware("logging") {
   }
 }
 
+/**
+ * Serves an endpoint's own answer back for as long as its declared `cache` allows, and stands aside for every
+ * endpoint that declared none — this is registered by default, so a TTL of its own would put a stale window on
+ * every call in the app.
+ *
+ * A cached answer is **shared**, which is why only a `query` taking no internal argument can carry one: internal
+ * arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers per caller
+ * and one entry would be one caller's answer handed to the next. Guards are re-run on every hit regardless —
+ * shared is not public, and `next()`, which is what runs them, is exactly what a hit skips.
+ */
 export class Cache extends middleware("cache") {
+  static #topic = "cache";
+  static #refused = new Set<string>();
+
   override async use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
+      const ttl = context.endpointInfo.signalOption.cache;
+      if (!ttl || !Number.isFinite(ttl) || ttl <= 0) return await next();
+      if (!Cache.#cacheable(context)) return await next();
       const cache = context.getAdaptor(CacheAdaptorRole) as unknown as CacheAdaptor;
-      const topic = "cache";
       const key = `${context.key}:${JSON.stringify(context.args)}`;
-
-      const cached = await cache.get<string>(topic, key);
-      if (cached) {
-        context.adaptor.logger.debug(`Cache hit ${context.key}`);
-        try {
-          const parsed = JSON.parse(cached);
-          traceCache(true);
-          return parsed;
-        } catch (parseError) {
-          context.adaptor.logger.warn(`Cache parse error ${context.key}: ${String(parseError)}`);
-          await cache.delete(topic, key);
-        }
+      const cached = await Cache.#read(context, cache, key);
+      if (cached !== undefined) {
+        await context.checkGuards();
+        traceCache(true);
+        return cached;
       }
       traceCache(false);
-
       const result = await next();
-
-      context.adaptor.logger.debug(`Caching result type ${context.key}: ${typeof result} / ${Array.isArray(result)}`);
-
-      const serialized = JSON.stringify(result);
-      await cache.set(topic, key, serialized, { expireAt: dayjs().add(60, "second") });
-
+      await Cache.#write(context, cache, key, result, ttl);
       return result;
     };
   }
-}
-
-export class Timeout extends middleware("timeout") {
-  override async use() {
-    return async (context: SignalContext, next: () => Promise<unknown>) => {
-      const timeout = context.endpointInfo.signalOption.timeout ?? 5000;
-      return Promise.race([
-        next(),
-        new Promise((_, reject) => setTimeout(() => reject(new Error(`Request timeout after ${timeout}ms`)), timeout)),
-      ]);
-    };
+  /**
+   * The handler's inputs are its declared arguments and its internal arguments, so an endpoint with none of the
+   * latter answers the same thing to everyone who may read it — which is the only answer a shared entry can hold.
+   * A `cache` declared anywhere else is named once rather than silently ignored.
+   */
+  static #cacheable(context: SignalContext) {
+    if (context.endpointInfo.type === "query" && context.endpointInfo.internalArgs.length === 0) return true;
+    if (Cache.#refused.has(context.key)) return false;
+    Cache.#refused.add(context.key);
+    const reason =
+      context.endpointInfo.type === "query"
+        ? "it takes an internal argument, so its answer is the caller's and not a shared one"
+        : `a ${context.endpointInfo.type} is never cached`;
+    context.adaptor.logger.warn(`"${context.key}" declares \`cache\` and cannot take one: ${reason}.`);
+    return false;
+  }
+  /** A cache backend that is down must not take the endpoint down with it: the call runs uncached instead. */
+  static async #read(context: SignalContext, cache: CacheAdaptor, key: string) {
+    try {
+      const cached = await cache.get<string>(Cache.#topic, key);
+      if (cached == null) return undefined;
+      return JSON.parse(cached) as unknown;
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache read failed for ${context.key}: ${String(error)}`);
+      
+      await cache.delete(Cache.#topic, key).catch(() => undefined);
+      return undefined;
+    }
+  }
+  static async #write(context: SignalContext, cache: CacheAdaptor, key: string, result: unknown, ttl: number) {
+    const serialized = JSON.stringify(result);
+    
+    if (serialized === undefined) return;
+    try {
+      await cache.set(Cache.#topic, key, serialized, { expireAt: dayjs().add(ttl, "millisecond") });
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache write failed for ${context.key}: ${String(error)}`);
+    }
   }
 }
 
-export class Retry extends middleware("retry") {
+/**
+ * Bounds an endpoint that declared a `timeout`, and nothing else — this is registered by default, so a default
+ * of its own would put a deadline on every endpoint in the app that nobody asked for.
+ *
+ * XXX losing the race does not cancel the work: `next()` keeps running with nobody holding its result, so a
+ * handler that writes is still going to write. The deadline answers the caller; it does not undo the call.
+ */
+export class Timeout extends middleware("timeout") {
   override async use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
-      const maxRetries = 3;
-      let lastError: Error | null = null;
-
-      for (let attempt = 0; attempt < maxRetries; attempt++) {
-        try {
-          return await next();
-        } catch (error) {
-          lastError = error instanceof Error ? error : new Error(String(error));
-          console.warn(`[${context.key}] Retry ${attempt + 1}/${maxRetries}:`, lastError.message);
+      const timeout = context.endpointInfo.signalOption.timeout;
+      if (!timeout || !Number.isFinite(timeout) || timeout <= 0) return await next();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        return await Promise.race([
+          next(),
 
-          if (attempt < maxRetries - 1) {
-            
-            await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 100));
-          }
-        }
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Exception(504, "base.error.gatewayTimeout")), timeout);
+          }),
+        ]);
+      } finally {
+        
+        clearTimeout(timer);
       }
-      throw lastError;
     };
   }
 }

package/signal/serializer/fetch.serializer.ts

@@ -70,6 +70,7 @@ export class FetchSerializer {
       ...(endpointInfo.signalOption.path ? { path: endpointInfo.signalOption.path } : {}),
       ...(endpointInfo.signalOption.method ? { method: endpointInfo.signalOption.method } : {}),
       ...(endpointInfo.signalOption.fileUpload ? { fileUpload: true } : {}),
+      ...(endpointInfo.signalOption.timeout ? { timeout: endpointInfo.signalOption.timeout } : {}),
       ...(guards?.length ? { guards } : {}),
       ...(endpointInfo.signalOption.mcp === false ? { mcp: false as const } : {}),
       ...(refusesAgents(endpointInfo.signalOption.guards) ? { agents: false as const } : {}),

package/signal/signalContext.ts

@@ -154,10 +154,17 @@ export class SignalContext<
         throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
     }
   }
+  /**
+   * The endpoint's guards, for a middleware that answers a call without executing it — a cache hit skips
+   * `next()`, and `next()` is what would otherwise run them. Side-effect free, like the guards themselves.
+   */
+  async checkGuards() {
+    await this.#checkGuards();
+  }
   /**
    * Re-checks this context's guards outside of a request, for a websocket room that is already
    * subscribed. Only global middlewares run: they carry the account resolution this depends on,
-   * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+   * while endpoint middlewares (cache/retry) would observe a call that never executes.
    */
   async authorize(): Promise<boolean> {
     try {

package/signal/types.ts

@@ -81,8 +81,26 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   default?: boolean;
   path?: string;
   serverMode?: "federation" | "batch" | "all";
+  /**
+   * How long this endpoint may take, in milliseconds. It bounds both ends: the `Timeout` middleware — registered
+   * by default — rejects the call with `base.error.gatewayTimeout` once it is spent, and the value is serialized
+   * to the client, where it becomes that call's request budget in place of the client default. Declared nowhere,
+   * neither side imposes one beyond the client's own default.
+   *
+   * Losing the race does not stop the work: the handler runs to completion with nobody holding its result.
+   */
   timeout?: number;
   partial?: _Key[] | readonly _Key[];
+  /**
+   * How long this endpoint's answer may be reused, in milliseconds. The `Cache` middleware — registered by
+   * default — keeps the handler's result under the endpoint's key and its arguments and serves it until it
+   * expires; declared nowhere, nothing is cached.
+   *
+   * **Only a `query` that takes no internal argument may carry one.** Internal arguments are how a call learns
+   * who is asking (`.with(Self)`), so an endpoint that has them answers per caller, and one shared entry would be
+   * one caller's answer handed to the next; such an endpoint is named in the log and left uncached. Guards still
+   * run on every hit — a shared answer is not a public one.
+   */
   cache?: number;
   guards?: GuardCls[];
   middlewares?: MiddlewareCls[];
@@ -180,6 +198,12 @@ export interface SerializedArg {
 export interface SerializedEndpoint extends SerializedSignalOption {
   type: "query" | "mutation" | "pubsub" | "message";
   returns: SerializedReturns;
+  /**
+   * The deadline the endpoint declared, in milliseconds. It travels because the client has to size its own
+   * request budget from it: a call the server is allowed to spend five minutes on is one the browser must not
+   * abandon after the client default.
+   */
+  timeout?: number;
 }
 export interface SerializedFilter {
   /** Every filter query the model declares, by key, with the args each one takes. */

package/types/common/types.d.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
     onError?: (error: string) => void;
     token?: string;
     partial?: string[];
-    timeout?: number;
+    /**
+     * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+     * endpoint's declared `timeout`, which overrides the client's own default.
+     */
+    timeout?: number | false;
     /**
      * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
      *

package/types/fetch/client/fetchClient.d.ts

@@ -55,6 +55,11 @@ export declare class FetchClient {
     };
     static resetSharedRegistry(): void;
     static resetSharedClient(): void;
+    /**
+     * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+     * as long as the runtime will, which is the browser's own limit — minutes.
+     */
+    setTimeout(timeout?: number | false): void;
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
     applySignal(serializedSignal: {
         [key: string]: SerializedSignal;
@@ -88,11 +93,13 @@ export declare class FetchClient {
         fetch: any;
     }>(constant: object, serializedSignal: {
         [key: string]: SerializedSignal;
-    }, { origin, connect, base, Err, }?: {
+    }, { origin, connect, base, Err, timeout, }?: {
         origin?: string;
         connect?: boolean;
         base?: FetchProxy;
         Err?: ErrorConstructor;
+        /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+        timeout?: number | false;
     }): {
         sig: ClientSignalMap<SigType>;
         fetch: SigType["fetch"];

package/types/fetch/client/httpClient.d.ts

@@ -15,6 +15,8 @@ export declare class HttpClient {
     private ErrorCls?;
     constructor(baseUrl: string, options?: HttpClientOptions);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
+    /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+    setTimeout(timeout?: number | false): void;
     get<Returns = unknown>(url: string, options?: FetchOptions): Promise<Returns>;
     send<Returns = unknown>(method: HttpMutationMethod, url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;
     put<Returns = unknown>(url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;

package/types/signal/middleware.d.ts

@@ -27,8 +27,19 @@ declare const Cache_base: {
     };
     refName: string;
 };
+/**
+ * Serves an endpoint's own answer back for as long as its declared `cache` allows, and stands aside for every
+ * endpoint that declared none — this is registered by default, so a TTL of its own would put a stale window on
+ * every call in the app.
+ *
+ * A cached answer is **shared**, which is why only a `query` taking no internal argument can carry one: internal
+ * arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers per caller
+ * and one entry would be one caller's answer handed to the next. Guards are re-run on every hit regardless —
+ * shared is not public, and `next()`, which is what runs them, is exactly what a hit skips.
+ */
 export declare class Cache extends Cache_base {
-    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<any>>;
+    #private;
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }
 declare const Timeout_base: {
     new (): {
@@ -36,16 +47,14 @@ declare const Timeout_base: {
     };
     refName: string;
 };
+/**
+ * Bounds an endpoint that declared a `timeout`, and nothing else — this is registered by default, so a default
+ * of its own would put a deadline on every endpoint in the app that nobody asked for.
+ *
+ * XXX losing the race does not cancel the work: `next()` keeps running with nobody holding its result, so a
+ * handler that writes is still going to write. The deadline answers the caller; it does not undo the call.
+ */
 export declare class Timeout extends Timeout_base {
     use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }
-declare const Retry_base: {
-    new (): {
-        use(env: BackendEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-    };
-    refName: string;
-};
-export declare class Retry extends Retry_base {
-    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-}
 export {};

package/types/signal/signalContext.d.ts

@@ -56,10 +56,15 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
     init(): Promise<this>;
+    /**
+     * The endpoint's guards, for a middleware that answers a call without executing it — a cache hit skips
+     * `next()`, and `next()` is what would otherwise run them. Side-effect free, like the guards themselves.
+     */
+    checkGuards(): Promise<void>;
     /**
      * Re-checks this context's guards outside of a request, for a websocket room that is already
      * subscribed. Only global middlewares run: they carry the account resolution this depends on,
-     * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+     * while endpoint middlewares (cache/retry) would observe a call that never executes.
      */
     authorize(): Promise<boolean>;
     /**

package/types/signal/types.d.ts

@@ -69,8 +69,26 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     default?: boolean;
     path?: string;
     serverMode?: "federation" | "batch" | "all";
+    /**
+     * How long this endpoint may take, in milliseconds. It bounds both ends: the `Timeout` middleware — registered
+     * by default — rejects the call with `base.error.gatewayTimeout` once it is spent, and the value is serialized
+     * to the client, where it becomes that call's request budget in place of the client default. Declared nowhere,
+     * neither side imposes one beyond the client's own default.
+     *
+     * Losing the race does not stop the work: the handler runs to completion with nobody holding its result.
+     */
     timeout?: number;
     partial?: _Key[] | readonly _Key[];
+    /**
+     * How long this endpoint's answer may be reused, in milliseconds. The `Cache` middleware — registered by
+     * default — keeps the handler's result under the endpoint's key and its arguments and serves it until it
+     * expires; declared nowhere, nothing is cached.
+     *
+     * **Only a `query` that takes no internal argument may carry one.** Internal arguments are how a call learns
+     * who is asking (`.with(Self)`), so an endpoint that has them answers per caller, and one shared entry would be
+     * one caller's answer handed to the next; such an endpoint is named in the log and left uncached. Guards still
+     * run on every hit — a shared answer is not a public one.
+     */
     cache?: number;
     guards?: GuardCls[];
     middlewares?: MiddlewareCls[];
@@ -168,6 +186,12 @@ export interface SerializedArg {
 export interface SerializedEndpoint extends SerializedSignalOption {
     type: "query" | "mutation" | "pubsub" | "message";
     returns: SerializedReturns;
+    /**
+     * The deadline the endpoint declared, in milliseconds. It travels because the client has to size its own
+     * request budget from it: a call the server is allowed to spend five minutes on is one the browser must not
+     * abandon after the client default.
+     */
+    timeout?: number;
 }
 export interface SerializedFilter {
     /** Every filter query the model declares, by key, with the args each one takes. */

package/types/ui/Loading/Spin.d.ts

@@ -1,8 +1,24 @@
 import type { ReactNode } from "react";
 export interface SpinProps {
+    className?: string;
+    /**
+     * Replaces the built-in icon. It carries its own color; the rotation is the wrapper's
+     * (`[&>svg]:animate-spin`), so the node needs no `animate-spin` of its own.
+     */
     indicator?: ReactNode;
     isCenter?: boolean;
-    className?: string;
-    size?: "sm" | "md" | "lg";
+    /** A named step, or the pixel size the icon is drawn at. */
+    size?: "sm" | "md" | "lg" | number;
+    /**
+     * What the built-in icon is colored with. `"current"` inherits the surface's own foreground, which is what a
+     * filled surface needs — `text-primary/70` is legible on the app background and vanishes on a `bg-info` badge
+     * or a primary button. Every tone loses to a `text-*` in `className`.
+     */
+    tone?: "primary" | "current" | "muted";
 }
-export declare const Spin: ({ indicator, isCenter, className, size }: SpinProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The color and the size sit on the wrapper, not on the icon: the icon is drawn at `1em` in `currentColor`, so
+ * both cascade to it — and `className`, which is also the wrapper's, is merged last and therefore wins. On the
+ * icon they would have been unreachable, which is what made every `text-*` and `size-*` a caller passed a no-op.
+ */
+export declare const Spin: ({ className, indicator, isCenter, size, tone }: SpinProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/index.d.ts

@@ -1,4 +1,4 @@
-export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type PublishedTool, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
+export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type MessageAttachment, type PublishedTool, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
 export { Agent } from "./Agent.d.ts";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval.d.ts";
 export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf.d.ts";

package/types/vendor/use-agentic/Transcript.d.ts

@@ -10,9 +10,10 @@ import type { ChatMessage } from "./types.d.ts";
  * transcript is assembled rather than where each hole is made.
  */
 export declare class Transcript {
-    #private;
     static readonly unanswered = "The turn was stopped before this call ran.";
     /** What one turn posts: no host-only message, no unanswered call, no result answering a call nobody sees. */
     static wire(messages: readonly ChatMessage[]): ChatMessage[];
     static sanitize(messages: readonly ChatMessage[]): ChatMessage[];
+    /** An empty assistant message is a draft a reload or an abort caught before it said anything. */
+    static carries(message: ChatMessage): boolean;
 }

package/ui/Agent/Attach.tsx

@@ -40,6 +40,7 @@ export const Attach = ({ className, label, onPick }: AttachProps) => {
 
 interface ChipsProps {
   className?: string;
+
   attachments: readonly MessageAttachment[];
   /** Omitted for a sent message: what is already on the wire cannot be taken back. */
   onRemove?: (index: number) => void;
@@ -56,7 +57,7 @@ export const Chips = ({ className, attachments, onRemove, removeLabel, pending =
         className="flex items-center gap-1 rounded-field bg-muted px-2 py-0.5 text-xs"
         key={`${attachment.name}-${idx}`}
       >
-        {attachment.data && attachment.mimeType.startsWith("image/") ? (
+        {attachment.data && attachment.mimeType?.startsWith("image/") ? (
           <img
             alt={attachment.name}
             className="size-6 rounded-field object-cover"

package/ui/Loading/Spin.tsx

@@ -3,26 +3,46 @@ import type { ReactNode } from "react";
 import { AiOutlineLoading3Quarters } from "react-icons/ai";
 
 export interface SpinProps {
+  className?: string;
+  /**
+   * Replaces the built-in icon. It carries its own color; the rotation is the wrapper's
+   * (`[&>svg]:animate-spin`), so the node needs no `animate-spin` of its own.
+   */
   indicator?: ReactNode;
   isCenter?: boolean;
-  className?: string;
-  size?: "sm" | "md" | "lg";
+  /** A named step, or the pixel size the icon is drawn at. */
+  size?: "sm" | "md" | "lg" | number;
+  /**
+   * What the built-in icon is colored with. `"current"` inherits the surface's own foreground, which is what a
+   * filled surface needs — `text-primary/70` is legible on the app background and vanishes on a `bg-info` badge
+   * or a primary button. Every tone loses to a `text-*` in `className`.
+   */
+  tone?: "primary" | "current" | "muted";
 }
 
 const sizeClass = { sm: "text-sm", md: "text-xl", lg: "text-3xl" } as const;
+const toneClass = { primary: "text-primary/70", current: "", muted: "text-muted-foreground" } as const;
 
-export const Spin = ({ indicator, isCenter, className, size = "md" }: SpinProps) => (
+/**
+ * The color and the size sit on the wrapper, not on the icon: the icon is drawn at `1em` in `currentColor`, so
+ * both cascade to it — and `className`, which is also the wrapper's, is merged last and therefore wins. On the
+ * icon they would have been unreachable, which is what made every `text-*` and `size-*` a caller passed a no-op.
+ */
+export const Spin = ({ className, indicator, isCenter, size = "md", tone = "primary" }: SpinProps) => (
   <div
     className={cn(
       "inline-block py-1",
+      !indicator && toneClass[tone],
+      typeof size === "string" && sizeClass[size],
       isCenter && "absolute inset-0 flex size-full items-center justify-center py-0",
       className,
     )}
+    style={typeof size === "number" ? { fontSize: size } : undefined}
   >
     {indicator ? (
       <span className="[&>svg]:animate-spin">{indicator}</span>
     ) : (
-      <AiOutlineLoading3Quarters className={cn("animate-spin text-primary/70", sizeClass[size])} />
+      <AiOutlineLoading3Quarters className="animate-spin" />
     )}
   </div>
 );

package/ui/index.ts

@@ -10,6 +10,7 @@ export {
   type CompactOptions,
   type ContextBlock,
   httpRunner,
+  type MessageAttachment,
   type PublishedTool,
   type RunnerEvent,
   type RunnerRequest,

package/vendor/use-agentic/AgentSession.ts

@@ -293,6 +293,9 @@ export class AgentSession {
       this.#pending = null;
       this.#question = null;
       this.#progress = null;
+
+      const draft = this.#messages[this.#messages.length - 1];
+      if (draft?.role === "assistant" && !Transcript.carries(draft)) this.#messages = this.#messages.slice(0, -1);
       this.#notify();
     }
   }

package/vendor/use-agentic/Transcript.ts

@@ -28,7 +28,7 @@ export class Transcript {
         if (results.length) kept.push({ ...message, toolResults: results });
         continue;
       }
-      if (message.role === "assistant" && !Transcript.#carries(message)) continue;
+      if (message.role === "assistant" && !Transcript.carries(message)) continue;
       kept.push(message);
       const calls = message.toolCalls ?? [];
       for (const call of calls) called.add(call.id);
@@ -44,7 +44,7 @@ export class Transcript {
   }
 
   /** An empty assistant message is a draft a reload or an abort caught before it said anything. */
-  static #carries(message: ChatMessage) {
+  static carries(message: ChatMessage) {
     return !!message.text || !!message.error || !!message.toolCalls?.length || !!message.attachments?.length;
   }
 }