akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/store/action.ts

@@ -136,7 +136,7 @@ type BaseAction<
   ) => Promise<void>;
 } & { [K in `set${_CapitalizedRefName}`]: (...models: (Full | Light)[]) => void } & {
   [K in `reset${_CapitalizedRefName}`]: (model?: Full) => void;
-};
+} & { [K in `invalidate${_CapitalizedRefName}`]: () => void };
 
 export type SliceAction<
   RefName extends string,
@@ -310,9 +310,19 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
 
   const names = {
     modelForm: `${fieldName}Form`,
+    modelFormUploading: databaseStateNames(refName).modelFormUploading,
     writeOnModel: `writeOn${className}`,
     addModelFiles: `add${className}Files`,
   };
+  type UploadState = { [key: string]: { [field: string]: string[] } };
+  let uploadSeq = 0;
+  const releaseUpload = (state: UploadState, field: string, ticket?: string) => {
+    const pending = state[names.modelFormUploading][field];
+    if (!pending || (ticket && !pending.includes(ticket))) return;
+    const { [field]: tickets = [], ...rest } = state[names.modelFormUploading];
+    const left = ticket ? tickets.filter((pending) => pending !== ticket) : [];
+    state[names.modelFormUploading] = left.length ? { ...rest, [field]: left } : rest;
+  };
   const baseSetAction = {
     [names.writeOnModel]: function (this: SetGet, path: string | (string | number)[], value: any) {
       this.set((state: { [key: string]: any }) => {
@@ -322,9 +332,13 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
   };
   const fieldSetAction = Object.entries(modelRef[FIELD_META]).reduce((acc, [key, field]) => {
     const namesOfField = formSetterNames(className, key);
+    const isFileField =
+      field.isClass && !!fileUploadRefName && ConstantRegistry.getRefName(field.modelRef) === fileUploadRefName;
     const singleFieldSetAction = {
       [namesOfField.setFieldOnModel]: function (this: SetGet, value: any | null) {
         this.set((state: { [key: string]: any }) => {
+          
+          if (isFileField && !field.isArray) releaseUpload(state as UploadState, namesOfField.field);
           const setValue =
             value === null
               ? null
@@ -384,56 +398,88 @@ export const makeFormSetter = (refName: string, fetch: FetchProxy<any>) => {
             },
           }
         : {}),
-      ...(field.isClass && fileUploadRefName && ConstantRegistry.getRefName(field.modelRef) === fileUploadRefName
+      ...(isFileField && fileUploadRefName
         ? {
             [namesOfField.uploadFieldOnModel]: async function (
               this: SetGet,
               fileList: FileList | File[],
               index?: number,
             ) {
-              const form = (this.get() as { [key: string]: any })[names.modelForm] as { [key: string]: any };
+              const formId = ((this.get() as { [key: string]: any })[names.modelForm] as { id?: string }).id;
               if (!fileList.length) return;
-              const files = await (fetch[names.addModelFiles] as (...args: any) => Promise<ProtoFile[]>)(
-                fileList,
-                form.id,
-              );
-              if (field.isArray) {
-                const idx = index ?? (form[namesOfField.field] as ProtoLightFile[]).length;
-                this.set((state: { [key: string]: { [key: string]: ProtoLightFile[] } }) => {
-                  state[names.modelForm][namesOfField.field] = [
-                    ...(form[namesOfField.field] as ProtoLightFile[]).slice(0, idx),
-                    ...files,
-                    ...(form[namesOfField.field] as ProtoLightFile[]).slice(idx),
-                  ];
-                });
-              } else {
-                this.set((state: { [key: string]: { [key: string]: ProtoLightFile | null } }) => {
-                  state[names.modelForm][namesOfField.field] = files[0];
-                });
+              
+              const ticket = `${++uploadSeq}`;
+              this.set((state: UploadState) => {
+                const tickets = state[names.modelFormUploading][namesOfField.field] ?? [];
+                state[names.modelFormUploading] = {
+                  ...state[names.modelFormUploading],
+                  [namesOfField.field]: field.isArray ? [...tickets, ticket] : [ticket],
+                };
+              });
+              const held = (state: { [key: string]: any }) =>
+                !!(state as UploadState)[names.modelFormUploading][namesOfField.field]?.includes(ticket) &&
+                (state[names.modelForm] as { id?: string }).id === formId;
+              let files: ProtoFile[];
+              try {
+                files = await (fetch[names.addModelFiles] as (...args: any) => Promise<ProtoFile[]>)(fileList, formId);
+              } catch (error) {
+                this.set((state: UploadState) => releaseUpload(state, namesOfField.field, ticket));
+                throw error;
               }
+              let isWritten = false;
+              
+              this.set((state: { [key: string]: any }) => {
+                isWritten = held(state);
+                releaseUpload(state as UploadState, namesOfField.field, ticket);
+                if (!isWritten) return;
+                const form = state[names.modelForm] as { [key: string]: ProtoLightFile[] | ProtoLightFile | null };
+                if (field.isArray) {
+                  const current = (form[namesOfField.field] as ProtoLightFile[] | null) ?? [];
+                  const idx = Math.min(index ?? current.length, current.length);
+                  form[namesOfField.field] = [...current.slice(0, idx), ...files, ...current.slice(idx)];
+                } else form[namesOfField.field] = files[0] ?? null;
+              });
+              if (!isWritten) return;
+              const postSet = (this as unknown as { [key: string]: ((value: unknown) => unknown) | undefined })[
+                namesOfField.postSetField
+              ];
+              if (postSet)
+                void postSet.call(this, (this.get() as { [key: string]: any })[names.modelForm][namesOfField.field]);
               
               const fileReadName = ConstantRegistry.isLight(field.modelRef)
                 ? `light${capitalize(fileUploadRefName)}`
                 : fileUploadRefName;
+              const holdsFile = (id: string) => {
+                const value = (this.get() as { [key: string]: { [key: string]: unknown } })[names.modelForm][
+                  namesOfField.field
+                ] as ProtoLightFile | ProtoLightFile[] | null;
+                return Array.isArray(value) ? value.some((heldFile) => heldFile.id === id) : value?.id === id;
+              };
               files.forEach((file) => {
                 let attemptsLeft = UPLOAD_POLL_ATTEMPTS;
                 const intervalKey = setInterval(() => {
                   void (async () => {
+                    if (!holdsFile(file.id)) {
+                      clearInterval(intervalKey);
+                      return;
+                    }
                     attemptsLeft -= 1;
                     try {
                       const currentFile = await (
                         (fetch as { [key: string]: any })[fileReadName] as (id: string) => Promise<ProtoLightFile>
                       )(file.id);
-                      if (field.isArray)
-                        this.set((state: { [key: string]: { [key: string]: ProtoLightFile[] } }) => {
-                          state[names.modelForm][namesOfField.field] = state[names.modelForm][namesOfField.field].map(
-                            (file) => (file.id === currentFile.id ? currentFile : file),
-                          );
-                        });
-                      else
-                        this.set((state: { [key: string]: { [key: string]: ProtoLightFile | null } }) => {
-                          state[names.modelForm][namesOfField.field] = currentFile;
-                        });
+                      if (!holdsFile(currentFile.id)) {
+                        clearInterval(intervalKey);
+                        return;
+                      }
+                      this.set(
+                        (state: { [key: string]: { [key: string]: ProtoLightFile[] | ProtoLightFile | null } }) => {
+                          const value = state[names.modelForm][namesOfField.field];
+                          state[names.modelForm][namesOfField.field] = Array.isArray(value)
+                            ? value.map((heldFile) => (heldFile.id === currentFile.id ? currentFile : heldFile))
+                            : currentFile;
+                        },
+                      );
                       if (currentFile.status !== "uploading" || attemptsLeft <= 0) clearInterval(intervalKey);
                     } catch (error) {
                       clearInterval(intervalKey);
@@ -497,10 +543,14 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     viewModel: `view${className}`,
     setModel: `set${className}`,
     resetModel: `reset${className}`,
+    invalidateModel: `invalidate${className}`,
     loadModelDraft: `load${className}FormDraft`,
     restoreModelDraft: `restore${className}FormDraft`,
     discardModelDraft: `discard${className}FormDraft`,
   };
+  
+  const isUploadingIn = (state: { [key: string]: any }) =>
+    Object.keys(state[names.modelFormUploading] as object).length > 0;
   const defaultKeyOf = (sliceName: string) => capitalize(sliceName).replace(names.Model, names.defaultModel);
   
   const staleAtOfSlices = () => {
@@ -602,7 +652,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       const defaultModel = currentState[defaultKeyOf(sliceName)] as Full;
       const modelInput = (cnst.input.purify as (form: any) => DefaultOf<Input> | null)(modelForm);
 
-      if (!modelInput) return;
+      if (!modelInput || isUploadingIn(currentState)) return;
       this.set({ [names.modelLoading]: true });
       const model = await servedFetch<Full>(names.createModel)(modelInput, { onError });
       this.set({
@@ -627,7 +677,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       const modelForm = currentState[names.modelForm] as Input & { id: string };
       const defaultModel = currentState[defaultKeyOf(sliceName)] as Full;
       const modelInput = (cnst.input.purify as (form: any) => DefaultOf<Input> | null)(modelForm);
-      if (!modelInput) return;
+      if (!modelInput || isUploadingIn(currentState)) return;
       if (model?.id === modelForm.id) this.set({ [names.modelLoading]: modelForm.id });
       const updatedModel = await servedFetch<Full>(names.updateModel)(modelForm.id, modelInput, { onError });
       this.set({
@@ -730,7 +780,8 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       const modelForm = currentState[names.modelForm] as Input;
       const modelSubmit = currentState[names.modelSubmit] as { disabled: boolean };
       const modelInput = (cnst.input.purify as (obj: any) => DefaultOf<Input> | null)(modelForm);
-      this.set({ [names.modelSubmit]: { ...modelSubmit, disabled: !modelInput || disabled } });
+      const isDisabled = !modelInput || isUploadingIn(currentState) || disabled;
+      this.set({ [names.modelSubmit]: { ...modelSubmit, disabled: isDisabled } });
     },
     [names.submitModel]: async function (this: SetGet, option?: CreateOption<Full>) {
       const currentState = this.get() as { [key: string]: any };
@@ -855,6 +906,9 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       });
       return model ?? null;
     },
+    [names.invalidateModel]: function (this: SetGet) {
+      this.set(staleAtOfSlices());
+    },
     
     [names.loadModelDraft]: async function (this: SetGet, draftScope?: string) {
       const currentState = this.get() as { [key: string]: any };
@@ -897,6 +951,10 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
     const hasMoreFrom = (batch: unknown[], askedFor: number) => ({
       [namesOfSlice.hasMoreOfModel]: batch.length >= askedFor && askedFor > 0,
     });
+    
+    const lastPageFrom = (count: number, limit: number) => ({
+      [namesOfSlice.lastPageOfModel]: limit > 0 ? Math.max(Math.floor((count - 1) / limit) + 1, 1) : 1,
+    });
     const fetchList = (queryArgs: unknown[], skip: number, limit: number, sort: Sort, options?: object) =>
       (fetch[namesOfSlice.modelList] as (...args: any[]) => Promise<Light[]>)(
         ...expandQueryArgs(queryArgs, slice.args),
@@ -979,6 +1037,8 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
           isQueryEqual(sort as unknown as object, sortOfModel as unknown as object)
         )
           return;
+        
+        const requestedAt = new Date();
         await loadList(
           this,
           () =>
@@ -995,8 +1055,8 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
               [namesOfSlice.modelList]: modelList,
               [namesOfSlice.modelInsight]: modelInsight,
               [namesOfSlice.modelInitList]: modelList,
-              [namesOfSlice.modelInitAt]: new Date(),
-              [namesOfSlice.lastPageOfModel]: Math.max(Math.floor((modelInsight.count - 1) / (limit || 20)) + 1, 1),
+              [namesOfSlice.modelInitAt]: requestedAt,
+              ...lastPageFrom(modelInsight.count, limit),
               ...hasMoreFrom(modelDataList, fetchLimit),
               [namesOfSlice.limitOfModel]: limit,
               [namesOfSlice.queryArgsOfModel]: queryArgs,
@@ -1085,7 +1145,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
           () => fetchList(queryArgsOfModel, (page - 1) * limit, limit, sortOfModel, options),
           (modelDataList) => ({
             [namesOfSlice.modelList]: new DataList(modelDataList),
-            [namesOfSlice.lastPageOfModel]: Math.max(Math.floor((modelInsight.count - 1) / limit) + 1, 1),
+            ...lastPageFrom(modelInsight.count, limit),
             [namesOfSlice.limitOfModel]: limit,
             [namesOfSlice.pageOfModel]: page,
             [namesOfSlice.isCumulativeOfModel]: false,
@@ -1126,7 +1186,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
             [namesOfSlice.queryArgsOfModel]: queryArgs,
             [namesOfSlice.modelList]: new DataList(modelDataList),
             [namesOfSlice.modelInsight]: modelInsight,
-            [namesOfSlice.lastPageOfModel]: Math.max(Math.floor((modelInsight.count - 1) / limitOfModel) + 1, 1),
+            ...lastPageFrom(modelInsight.count, limitOfModel),
             [namesOfSlice.pageOfModel]: 1,
             [namesOfSlice.isCumulativeOfModel]: false,
             ...hasMoreFrom(modelDataList, limitOfModel),
@@ -1155,19 +1215,19 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
       
       [namesOfSlice.applyLiveModel]: function (this: SetGet, event: LiveEventPayload) {
         const currentState = this.get() as { [key: string]: any };
-        if (currentState[namesOfSlice.modelListLoading] as boolean) return;
         const modelList = currentState[namesOfSlice.modelList] as DataList<Light>;
         const staleAt = { [namesOfSlice.modelStaleAt]: new Date() };
-        if (event.op === "invalidate") {
+        
+        if (event.op === "invalidate" || (currentState[namesOfSlice.modelListLoading] as boolean)) {
           this.set(staleAt);
           return;
         }
         const modelInsight = currentState[namesOfSlice.modelInsight] as Insight & BaseInsight;
-        const limit = (currentState[namesOfSlice.limitOfModel] as number) || 20;
+        const limit = currentState[namesOfSlice.limitOfModel] as number;
         const isCumulative = currentState[namesOfSlice.isCumulativeOfModel] as boolean;
         const countedTo = (count: number) => ({
           [namesOfSlice.modelInsight]: new cnst.insight().set({ ...modelInsight, count }),
-          [namesOfSlice.lastPageOfModel]: Math.max(Math.floor((count - 1) / limit) + 1, 1),
+          ...lastPageFrom(count, limit),
         });
         if (event.op === "leave") {
           if (!modelList.has(event.id)) return;
@@ -1206,7 +1266,7 @@ export const makeActions = (refName: string, slice: { [key: string]: SerializedS
         }
         
         const inserted = [...modelList.slice(0, placement), light, ...modelList.slice(placement)];
-        const placed = isCumulative ? inserted : inserted.slice(0, limit);
+        const placed = isCumulative || !limit ? inserted : inserted.slice(0, limit);
         this.set({
           [namesOfSlice.modelList]: new DataList(placed as Light[]),
           ...countedTo(modelInsight.count + 1),

package/store/agent/ScreenImage.ts

@@ -0,0 +1,166 @@
+import { Binary } from "akanjs/base";
+import { type MessageAttachment, ToolOutput } from "../../vendor/use-agentic";
+import { ScreenTarget } from "./ScreenTarget";
+
+export interface ScreenImageView {
+  attachment: MessageAttachment;
+  /** The picture's size and how it was sent, for a model asked about its proportions or resolution. */
+  size: string;
+}
+
+/**
+ * A picture on the screen, handed to the model as the browser drew it: redrawn into a JPEG no longer than
+ * `maxEdge`, inlined as bytes. Redrawing turns HEIC, AVIF and SVG into a type every provider reads, bounds what one
+ * picture costs, and leaves the provider nothing to download — a storage path or a `blob:` address it cannot reach,
+ * or a signed URL that expires while the conversation still carries it.
+ */
+export class ScreenImage {
+  /** The long edge Anthropic downscales past; a bigger picture spends upload and latency on pixels nobody reads. */
+  static readonly maxEdge = 1568;
+  static readonly quality = 0.85;
+  static readonly loadMs = 10_000;
+
+  static readonly #typeByExtension = new Map([
+    ["jpg", "image/jpeg"],
+    ["jpeg", "image/jpeg"],
+    ["png", "image/png"],
+    ["gif", "image/gif"],
+    ["webp", "image/webp"],
+  ]);
+
+  /** The `<img>` showing `src` in `root`, matched on what readScreen prints, its absolute form, or the attribute. */
+  static find(src: string, root?: HTMLElement): HTMLImageElement | null {
+    const scope = root ?? (typeof document === "undefined" ? null : document.body);
+    if (!scope) return null;
+    for (const image of scope.querySelectorAll("img"))
+      if (
+        (image.currentSrc === src || image.src === src || image.getAttribute("src") === src) &&
+        ScreenTarget.visible(image)
+      )
+        return image;
+    return null;
+  }
+
+  static async view(image: HTMLImageElement): Promise<ScreenImageView> {
+    const src = image.currentSrc || image.src;
+    const name = ScreenImage.#nameOf(image, src);
+    
+    const loaded = image.complete && image.naturalWidth > 0 ? image : await ScreenImage.#load(src, false);
+    const drawn =
+      (loaded ? await ScreenImage.#draw(loaded, name) : null) ??
+      (await ScreenImage.#drawFrom(await ScreenImage.#load(src, true), name));
+    if (drawn) return drawn;
+    const mimeType = ScreenImage.#typeOf(src);
+    if (mimeType && ScreenImage.publiclyFetchable(src))
+      return {
+        attachment: { name, mimeType, url: src },
+        size: `${ScreenImage.#sizeOf(image)}, sent by address because this page may not read its pixels`,
+      };
+    throw new Error(
+      `${name} cannot be viewed: its host does not let this page read the picture, and the model's provider cannot download it from ${src}. Tell the user you cannot see it.`,
+    );
+  }
+
+  /**
+   * Whether a provider could download `url` itself — an http(s) address off loopback, private, link-local and CGNAT
+   * ranges. It decides between an address and no picture at all; it is not an SSRF guard and must not become one.
+   */
+  static publiclyFetchable(url: string): boolean {
+    if (!/^https?:\/\//i.test(url)) return false;
+    let hostname: string;
+    try {
+      hostname = new URL(url).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname.endsWith(".local")) return false;
+    if (hostname === "internal" || hostname.endsWith(".internal")) return false;
+    if (hostname.startsWith("[")) return !ScreenImage.#privateV6(hostname.slice(1, -1));
+    return !/^(?:0\.|10\.|127\.|169\.254\.|192\.168\.|172\.(?:1[6-9]|2\d|3[01])\.|100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(
+      hostname,
+    );
+  }
+
+  static #privateV6(address: string): boolean {
+    if (address === "::" || address === "::1" || address.startsWith("::ffff:")) return true;
+    const first = Number.parseInt(address.split(":")[0] || "0", 16);
+    return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80;
+  }
+
+  static async #drawFrom(image: HTMLImageElement | null, name: string): Promise<ScreenImageView | null> {
+    return image ? await ScreenImage.#draw(image, name) : null;
+  }
+
+  static async #draw(image: HTMLImageElement, name: string): Promise<ScreenImageView | null> {
+    const width = image.naturalWidth || image.width;
+    const height = image.naturalHeight || image.height;
+    if (!width || !height) return null;
+    const scale = Math.min(1, ScreenImage.maxEdge / Math.max(width, height));
+    const canvas = document.createElement("canvas");
+    canvas.width = Math.max(1, Math.round(width * scale));
+    canvas.height = Math.max(1, Math.round(height * scale));
+    const context = canvas.getContext("2d");
+    if (!context) return null;
+    
+    context.fillStyle = "#ffffff";
+    context.fillRect(0, 0, canvas.width, canvas.height);
+    context.drawImage(image, 0, 0, canvas.width, canvas.height);
+    let blob: Blob | null;
+    try {
+      blob = await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/jpeg", ScreenImage.quality));
+    } catch {
+      
+      return null;
+    }
+    if (!blob) return null;
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    if (bytes.length > ToolOutput.attachmentBytes)
+      throw new Error(`${name} is ${bytes.length} bytes even as a JPEG, past what one tool result may carry.`);
+    return {
+      attachment: { name, mimeType: "image/jpeg", data: Binary.toBase64(bytes) },
+      size: `${width}×${height}, sent as ${canvas.width}×${canvas.height} JPEG`,
+    };
+  }
+
+  static #load(src: string, cors: boolean): Promise<HTMLImageElement | null> {
+    return new Promise((resolve) => {
+      const image = new Image();
+      if (cors) image.crossOrigin = "anonymous";
+      const timer = setTimeout(() => resolve(null), ScreenImage.loadMs);
+      image.onload = () => {
+        clearTimeout(timer);
+        resolve(image);
+      };
+      image.onerror = () => {
+        clearTimeout(timer);
+        resolve(null);
+      };
+      image.src = src;
+    });
+  }
+
+  static #nameOf(image: HTMLImageElement, src: string): string {
+    const alt = image.getAttribute("alt")?.trim();
+    if (alt) return alt;
+    if (!/^https?:/i.test(src)) return "image";
+    try {
+      return decodeURIComponent(new URL(src).pathname.split("/").pop() ?? "") || "image";
+    } catch {
+      return "image";
+    }
+  }
+
+  static #typeOf(src: string): string | null {
+    let pathname: string;
+    try {
+      pathname = new URL(src).pathname;
+    } catch {
+      return null;
+    }
+    return ScreenImage.#typeByExtension.get(pathname.split(".").pop()?.toLowerCase() ?? "") ?? null;
+  }
+
+  static #sizeOf(image: HTMLImageElement): string {
+    return image.naturalWidth ? `${image.naturalWidth}×${image.naturalHeight}` : "size unknown";
+  }
+}

package/store/agent/ScreenReader.ts

@@ -13,6 +13,7 @@ const skipTags = new Set([
 ]);
 const headingLevels = { H1: 1, H2: 2, H3: 3, H4: 4, H5: 5, H6: 6 } as const;
 const headingSelector = "h1, h2, h3, h4, h5, h6";
+const unprintedHrefScheme = /^(?:javascript|data|vbscript):/i;
 const blockTags = new Set([
   "ADDRESS",
   "ARTICLE",
@@ -255,7 +256,7 @@ export class ScreenReader {
     const before = this.#buffer;
     this.#walkChildren(el);
     const text = this.#buffer.slice(before.length).replace(/\s+/g, " ").trim();
-    if (href && href !== "#" && !href.startsWith("javascript:") && text !== href) this.#buffer += ` (${href})`;
+    if (href && href !== "#" && !unprintedHrefScheme.test(href) && text !== href) this.#buffer += ` (${href})`;
   }
 
   static #off(el: HTMLElement) {

package/store/agent/StoreSurfaceSource.ts

@@ -1,7 +1,8 @@
 import { router } from "akanjs/client";
-import { AgenticSurface, type SurfaceSource, type ToolEntry } from "../../vendor/use-agentic";
+import { AgenticSurface, type SurfaceSource, type ToolEntry, ToolReturn } from "../../vendor/use-agentic";
 import { AgentBridge } from "./AgentBridge";
 import { ScreenFlash } from "./ScreenFlash";
+import { ScreenImage } from "./ScreenImage";
 import { ScreenReader } from "./ScreenReader";
 import { ScreenSettle } from "./ScreenSettle";
 import { ScreenTarget } from "./ScreenTarget";
@@ -9,7 +10,7 @@ import { ScreenTarget } from "./ScreenTarget";
 /** Every screen's built-in tools. A same-named hook tool shadows one at root scope only; a zone uses `builtins`. */
 export class StoreSurfaceSource implements SurfaceSource {
   /** What a session's `builtins` option selects from, in build order. */
-  static readonly builtins = ["navigate", "goBack", "readScreen", "readState", "highlight"] as const;
+  static readonly builtins = ["navigate", "goBack", "readScreen", "readState", "highlight", "viewImage"] as const;
 
   #bridge: AgentBridge | null;
   readonly #builtins = new Map<string, ToolEntry[]>();
@@ -29,6 +30,7 @@ export class StoreSurfaceSource implements SurfaceSource {
         StoreSurfaceSource.#readScreen(viewKey),
         this.#readState(viewKey),
         StoreSurfaceSource.#highlight(viewKey),
+        StoreSurfaceSource.#viewImage(viewKey),
       ];
       this.#builtins.set(viewKey, builtins);
     }
@@ -158,6 +160,43 @@ export class StoreSurfaceSource implements SurfaceSource {
     };
   }
 
+  static #viewImage(viewKey: string): ToolEntry {
+    const absent = (src: string) =>
+      `No picture at ${src} is on screen now. Call readScreen with images: true and pass the <address> of an [image: <alt>](<address>) it prints; a picture that has left the screen cannot be viewed.`;
+    return {
+      name: "viewImage",
+      description:
+        "Look at one picture on screen, to answer from what it shows rather than from its caption. readScreen with `images: true` prints each picture as `[image: <alt>](<address>)`, or `[image](<address>)` when it has no alt; pass that address. Each picture costs this turn over a thousand tokens, so view only the ones the answer needs.",
+      parameters: {
+        type: "object",
+        properties: {
+          src: {
+            type: "string",
+            description: "The <address> of an [image: <alt>](<address>) readScreen printed, without the parentheses.",
+          },
+        },
+        required: ["src"],
+        additionalProperties: false,
+      },
+      settle: false,
+      
+      guard: (args) => {
+        const src = typeof args.src === "string" ? args.src.trim() : "";
+        if (!src) return "viewImage needs a src.";
+        if (src.startsWith("data:"))
+          return "A data: address is the picture's bytes, not an address readScreen prints. Pass one readScreen printed.";
+        return ScreenImage.find(src, StoreSurfaceSource.#zoneRoot(viewKey)) ? true : absent(src);
+      },
+      run: async (args) => {
+        const src = String(args.src).trim();
+        const image = ScreenImage.find(src, StoreSurfaceSource.#zoneRoot(viewKey));
+        if (!image) throw new Error(absent(src));
+        const { attachment, size } = await ScreenImage.view(image);
+        return ToolReturn.attach(`Attached ${attachment.name}: ${size}.`, [attachment]);
+      },
+    };
+  }
+
   #readState(viewKey: string): ToolEntry {
     return {
       name: "readState",

package/store/agent/index.ts

@@ -1,11 +1,12 @@
 
-export { AgentAbort, AgentProgress, type AgentProgressStep } from "../../vendor/use-agentic";
+export { AgentAbort, AgentProgress, type AgentProgressStep, ToolReturn } from "../../vendor/use-agentic";
 export * from "./AgentBridge";
 export * from "./AgentContext";
 export * from "./AgentCursor";
 export * from "./AgentPrompts";
 export * from "./AgentVisual";
 export * from "./ScreenFlash";
+export * from "./ScreenImage";
 export * from "./ScreenReader";
 export * from "./ScreenSettle";
 export * from "./ScreenTarget";

package/store/databaseStateNames.ts

@@ -7,6 +7,7 @@ export const databaseStateNames = (refName: string) => {
     modelLoading: `${refName}Loading`,
     modelForm: `${refName}Form`,
     modelFormLoading: `${refName}FormLoading`,
+    modelFormUploading: `${refName}FormUploading`,
     modelSubmit: `${refName}Submit`,
     modelViewAt: `${refName}ViewAt`,
     modelModal: `${refName}Modal`,

package/store/formUploadOf.ts

@@ -0,0 +1,41 @@
+import { capitalize } from "akanjs/common";
+import { actionTagOf } from "./actionTag";
+import { StoreRegistry } from "./storeRegistry";
+
+interface HeldFile {
+  id: string;
+}
+
+export interface FormUpload {
+  upload: (fileList: FileList | File[]) => Promise<void>;
+  refresh: (files: HeldFile[]) => void;
+}
+
+export const formUploadOf = (setter: unknown): FormUpload | null => {
+  const tag = actionTagOf(setter);
+  const [formKey, field, ...rest] = tag?.state?.split(".") ?? [];
+  if (!formKey?.endsWith("Form") || !field || rest.length) return null;
+  const [Model, Field] = [capitalize(formKey.slice(0, -"Form".length)), capitalize(field)];
+  if (tag?.action !== `set${Field}On${Model}`) return null;
+  const actions = StoreRegistry.instance.do as unknown as { [key: string]: unknown };
+  const upload = actions[`upload${Field}On${Model}`];
+  const writeOn = actions[`writeOn${Model}`] as ((path: string, value: unknown) => unknown) | undefined;
+  if (typeof upload !== "function" || typeof writeOn !== "function") return null;
+  
+  const refresh = (files: HeldFile[]) => {
+    const form = StoreRegistry.instance.get()[formKey] as { [key: string]: unknown } | undefined;
+    const held = form?.[field] as HeldFile | HeldFile[] | null | undefined;
+    const fresh = (file: HeldFile) => files.find((updated) => updated.id === file.id);
+    if (Array.isArray(held)) {
+      if (held.some((file) => fresh(file)))
+        void writeOn(
+          field,
+          held.map((file) => fresh(file) ?? file),
+        );
+    } else if (held) {
+      const updated = fresh(held);
+      if (updated) void writeOn(field, updated);
+    }
+  };
+  return { upload: upload as FormUpload["upload"], refresh };
+};

package/store/index.ts

@@ -6,6 +6,7 @@ export * from "./baseSt";
 export * from "./databaseStateNames";
 export * from "./draftStore";
 export * from "./formSetterNames";
+export * from "./formUploadOf";
 export * from "./liveInsert";
 export * from "./rootStore";
 export * from "./sliceRole";

package/store/liveInsert.ts

@@ -39,9 +39,9 @@ export const livePlacementIndex = ({
   });
   if (!orderable) return null;
   if (index !== -1) return index;
-  
+
   if (cumulative) return hasMore ? null : list.length;
-  return list.length < limit ? list.length : null;
+  return !limit || list.length < limit ? list.length : null;
 };
 
 const compareRows = (left: LiveSortableRow, right: LiveSortableRow, paths: [string, 1 | -1][]): number | null => {