mulmoclaude 1.2.0 → 1.4.0

package/server/api/routes/collections.ts

@@ -12,34 +12,35 @@ import { Router, Request, Response, NextFunction } from "express";
 import { API_ROUTES } from "../../../src/config/apiRoutes.js";
 import { actionVisible } from "@mulmoclaude/core/collection";
 import {
+  collectionWritable,
   computeCollectionIcon,
   discoverCollections,
   generateItemId,
   deleteCollection,
   deleteCollectionRefusalMessage,
   deleteCustomView,
-  deleteItem,
-  listItems,
   loadCollection,
-  readItem,
   readSkillTemplate,
   readCustomViewHtml,
   readCustomViewI18n,
+  readOnlyRefusal,
   buildActionSeedPrompt,
   buildCollectionActionSeedPrompt,
+  buildWorkspaceOntology,
   promptPathsFor,
   resolveCreateItemId,
+  storeFor,
   toDetail,
   toSummary,
   applyMutateAction,
   validateCollectionRecords,
-  writeItem,
 } from "../../workspace/collections/index.js";
 import type {
   CollectionMutateAction,
   CollectionSeededAction,
   CollectionDetail,
   CollectionItem,
+  CollectionOntologyEntry,
   CollectionSummary,
   DeleteViewResult,
   LoadedCollection,
@@ -56,8 +57,9 @@ import {
   type RemoteViewBuildResult,
   type RemoteViewItemsResult,
 } from "../../workspace/collections/remoteView.js";
-import { clampLimit, clampOffset, normalizeFields, normalizeMutate } from "@mulmoclaude/core/remote-view";
-import { badRequest, notFound, conflict, forbidden, serverError, serviceUnavailable } from "../../utils/httpError.js";
+import { clampImageMaxEdge, clampLimit, clampOffset, normalizeFields, normalizeMutate } from "@mulmoclaude/core/remote-view";
+import { resolveThumbnail } from "../../utils/files/thumbnail-store.js";
+import { badRequest, notFound, conflict, forbidden, methodNotAllowed, serverError, serviceUnavailable } from "../../utils/httpError.js";
 import { ONE_MINUTE_MS } from "../../utils/time.js";
 import { errorMessage } from "../../utils/errors.js";
 import { log } from "../../system/logger/index.js";
@@ -69,10 +71,42 @@ import { clampCapabilities, mintViewToken, requireViewToken, type ViewCapability
 
 const router = Router();
 
+// Load a collection by slug or send a 404 and return null. Callers do
+// `const collection = await loadCollectionOr404(slug, res); if (!collection) return;`.
+// The load-or-404 preamble was repeated across ~16 route handlers.
+async function loadCollectionOr404(slug: string, res: Response): Promise<LoadedCollection | null> {
+  const collection = await loadCollection(slug);
+  if (!collection) {
+    notFound(res, `collection '${slug}' not found`);
+    return null;
+  }
+  return collection;
+}
+
+type CustomView = NonNullable<LoadedCollection["schema"]["views"]>[number];
+
+// Resolve a collection + one of its custom views by id, or send a 404
+// (missing collection or missing view) and return null. Shared by the
+// view-file / view-i18n / view-token routes.
+async function resolveCustomViewOr404(slug: string, viewId: string, res: Response): Promise<{ collection: LoadedCollection; view: CustomView } | null> {
+  const collection = await loadCollectionOr404(slug, res);
+  if (!collection) return null;
+  const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
+  if (!view) {
+    notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
+    return null;
+  }
+  return { collection, view };
+}
+
 interface CollectionsListResponse {
   collections: CollectionSummary[];
 }
 
+interface CollectionOntologyResponse {
+  entries: CollectionOntologyEntry[];
+}
+
 interface CollectionDetailResponse {
   collection: CollectionDetail;
   items: CollectionItem[];
@@ -155,14 +189,24 @@ router.get(API_ROUTES.collections.list, async (_req: Request, res: Response<Coll
   }
 });
 
-router.get(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>, res: Response<CollectionDetailResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
+// Raw workspace-ontology entries (buildWorkspaceOntology — derived on
+// demand, never stored); the /collections Map tab builds its graph from
+// these with the shared `buildOntologyGraph`. Registered before the
+// `:slug` routes so "ontology" is never swallowed as a slug.
+router.get(API_ROUTES.collections.ontology, async (_req: Request, res: Response<CollectionOntologyResponse>) => {
+  try {
+    res.json({ entries: await buildWorkspaceOntology() });
+  } catch (err) {
+    log.warn("collections", "ontology failed", { error: errorMessage(err) });
+    serverError(res, errorMessage(err));
   }
+});
+
+router.get(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>, res: Response<CollectionDetailResponse>) => {
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   try {
-    const items = await listItems(collection.dataDir);
+    const items = await storeFor(collection).list();
     // Best-effort validation: a malformed record is silently skipped at
     // read time, so surface the problems here too (the same pass
     // presentCollection runs) and let the view offer a Repair button.
@@ -193,11 +237,8 @@ router.get(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>,
 // non-preset collections are deletable; see deleteCollection for the
 // scope rules and the archive layout.
 router.delete(API_ROUTES.collections.detail, async (req: Request<{ slug: string }>, res: Response<DeleteCollectionResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   try {
     const result = await deleteCollection(collection);
     if (result.kind !== "ok") {
@@ -218,9 +259,11 @@ function extractRecord(body: unknown): CollectionItem | null {
 }
 
 router.post(API_ROUTES.collections.items, async (req: Request<{ slug: string }>, res: Response<ItemMutationResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  const createStore = storeFor(collection).write;
+  if (!createStore) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   const record = extractRecord(req.body);
@@ -238,7 +281,7 @@ router.post(API_ROUTES.collections.items, async (req: Request<{ slug: string }>,
   const itemId = resolveCreateItemId(collection.schema, record) ?? generateItemId();
   const recordWithId: CollectionItem = { ...record, [collection.schema.primaryKey]: itemId };
   try {
-    const result = await writeItem(collection.dataDir, itemId, recordWithId, { refuseOverwrite: true, slug: collection.slug });
+    const result = await createStore(itemId, recordWithId, { refuseOverwrite: true });
     if (result.kind === "invalid-id") {
       badRequest(res, `invalid item id: ${result.itemId}`);
       return;
@@ -260,9 +303,11 @@ router.post(API_ROUTES.collections.items, async (req: Request<{ slug: string }>,
 });
 
 router.put(API_ROUTES.collections.item, async (req: Request<{ slug: string; itemId: string }>, res: Response<ItemMutationResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  const updateStore = storeFor(collection).write;
+  if (!updateStore) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   const record = extractRecord(req.body);
@@ -282,7 +327,7 @@ router.put(API_ROUTES.collections.item, async (req: Request<{ slug: string; item
   // record id never drift.
   const recordWithId: CollectionItem = { ...record, [primaryKey]: req.params.itemId };
   try {
-    const result = await writeItem(collection.dataDir, req.params.itemId, recordWithId, { slug: collection.slug });
+    const result = await updateStore(req.params.itemId, recordWithId);
     if (result.kind === "invalid-id") {
       badRequest(res, `invalid item id: ${result.itemId}`);
       return;
@@ -306,13 +351,15 @@ router.put(API_ROUTES.collections.item, async (req: Request<{ slug: string; item
 });
 
 router.delete(API_ROUTES.collections.item, async (req: Request<{ slug: string; itemId: string }>, res: Response<DeleteResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
+  const deleteStore = storeFor(collection).delete;
+  if (!deleteStore) {
+    methodNotAllowed(res, readOnlyRefusal(collection.slug));
     return;
   }
   try {
-    const result = await deleteItem(collection.dataDir, req.params.itemId, { slug: collection.slug });
+    const result = await deleteStore(req.params.itemId);
     if (result.kind === "invalid-id") {
       badRequest(res, `invalid item id: ${result.itemId}`);
       return;
@@ -351,11 +398,8 @@ interface RefreshResponse {
 // carries no `ingest` block (it's an ordinary skill collection, not a
 // feed). Backs the CollectionView "Refresh feed" button.
 router.post(API_ROUTES.collections.refresh, async (req: Request<{ slug: string }>, res: Response<RefreshResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   if (!collection.schema.ingest) {
     badRequest(res, `collection '${collection.slug}' is not a feed (no ingest config)`);
     return;
@@ -441,18 +485,15 @@ async function respondForMutateAction(
 // the hidden worker itself; for `kind: "mutate"`, it applies the
 // declarative write). No domain (invoice / PDF / role) literals.
 router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: string; itemId: string; actionId: string }>, res: Response<ActionRunResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   const action = collection.schema.actions?.find((entry) => entry.id === req.params.actionId);
   if (!action) {
     notFound(res, `action '${req.params.actionId}' not found on collection '${collection.slug}'`);
     return;
   }
   try {
-    const record = await readItem(collection.dataDir, req.params.itemId);
+    const record = await storeFor(collection).read(req.params.itemId);
     if (!record) {
       notFound(res, `item '${req.params.itemId}' not found`);
       return;
@@ -469,6 +510,12 @@ router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: strin
     // the declarative write itself (require was just enforced above,
     // same visibility-is-authorization rule as the seeded kinds).
     if (action.kind === "mutate") {
+      // Schema validation already rejects mutate actions on a dataSource
+      // collection; this is the defensive server-side twin.
+      if (!collectionWritable(collection)) {
+        methodNotAllowed(res, readOnlyRefusal(collection.slug));
+        return;
+      }
       await respondForMutateAction(res, collection, action, req.params.itemId, req.body as { params?: unknown } | undefined);
       return;
     }
@@ -498,7 +545,7 @@ router.post(API_ROUTES.collections.itemAction, async (req: Request<{ slug: strin
 async function buildCollectionActionSeed(collection: LoadedCollection, action: CollectionSeededAction): Promise<ActionSeedResponse | null> {
   const template = await readSkillTemplate(collection.skillDir, action.template);
   if (template === null) return null;
-  const items = await listItems(collection.dataDir);
+  const items = await storeFor(collection).list();
   log.info("collections", "collection action seed built", { slug: collection.slug, actionId: action.id, items: items.length });
   return { prompt: buildCollectionActionSeedPrompt(items, collection.schema, template, promptPathsFor(collection, workspacePath)), role: action.role };
 }
@@ -506,11 +553,8 @@ async function buildCollectionActionSeed(collection: LoadedCollection, action: C
 // Like the per-record route but with no `itemId`: there is no record to read or
 // gate on, so the seed injects a progress summary instead. No domain literals.
 router.post(API_ROUTES.collections.collectionAction, async (req: Request<{ slug: string; actionId: string }>, res: Response<ActionRunResponse>) => {
-  const collection = await loadCollection(req.params.slug);
-  if (!collection) {
-    notFound(res, `collection '${req.params.slug}' not found`);
-    return;
-  }
+  const collection = await loadCollectionOr404(req.params.slug, res);
+  if (!collection) return;
   const action = collection.schema.collectionActions?.find((entry) => entry.id === req.params.actionId);
   if (!action) {
     notFound(res, `collection action '${req.params.actionId}' not found on collection '${collection.slug}'`);
@@ -566,6 +610,20 @@ function sendToolResult(res: Response, raw: string): void {
   }
 }
 
+// ── View-data routes: a FROZEN public contract ──────────────────────────────
+// Everything under `viewData*` below is called by LLM-authored custom-view
+// HTML files persisted in users' workspaces (`data/skills/*/views/*.html`,
+// `feeds/*/views/*.html`), written against the contract in
+// `packages/core/assets/helps/custom-view.md`. Those files cannot be
+// re-generated or migrated centrally, so this surface must stay
+// backward-compatible indefinitely: keep `?fields=` / `?ids=` semantics, the
+// `{ collection, count, items }` / `{ written, rejected }` / `{ rows }`
+// response shapes, and the status-code semantics (400 with `{ error }`,
+// 403 mutate-kind, 409 require-gate) stable. Evolve by ADDITION only —
+// new optional params, new routes — never by renaming or reshaping.
+// Storage virtualization (new `CollectionStore` backends — see
+// `@mulmoclaude/core` collection/server/store.ts) must be invisible here.
+//
 // The view-data fetch comes from a sandboxed (opaque-origin) iframe, so it is
 // a cross-origin request that the browser gates with CORS. `*` is safe here:
 // auth is the unguessable scoped token in the Authorization header (not a
@@ -614,6 +672,12 @@ export function makeViewActionRateLimiter(max: number, windowMs: number, now: ()
 
 const VIEW_ACTION_RATE_LIMIT_PER_MINUTE = 60;
 const viewActionRateLimit = makeViewActionRateLimiter(VIEW_ACTION_RATE_LIMIT_PER_MINUTE, ONE_MINUTE_MS);
+// Image thumbnails get their own, roomier bucket: a gallery legitimately
+// fetches dozens of images on first paint, so the action budget (60/min)
+// would starve it — while the endpoint still needs a ceiling (each request
+// is a record scan + a thumbnail decode).
+const VIEW_IMAGE_RATE_LIMIT_PER_MINUTE = 300;
+const viewImageRateLimit = makeViewActionRateLimiter(VIEW_IMAGE_RATE_LIMIT_PER_MINUTE, ONE_MINUTE_MS);
 
 router.options(API_ROUTES.collections.viewData, viewDataCors, (_req: Request, res: Response) => {
   res.status(204).end();
@@ -628,16 +692,9 @@ router.get(API_ROUTES.collections.viewFile, async (req: Request<{ slug: string }
   try {
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { collection, view } = resolved;
     // Path-safe, source-aware read through the collections domain layer (no raw
     // fs / hardcoded subpaths in the route).
     const html = await readCustomViewHtml(collection, view.file);
@@ -670,11 +727,8 @@ router.get(API_ROUTES.collections.remoteView, async (req: Request<{ slug: string
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
     const locale = typeof req.query.locale === "string" ? req.query.locale : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await buildRemoteView(collection, viewId, locale);
     if (result.kind !== "ok") {
       sendRemoteViewFailure(res, result, slug);
@@ -692,6 +746,7 @@ router.get(API_ROUTES.collections.remoteView, async (req: Request<{ slug: string
 function sendMutateRemoteViewFailure(res: Response, result: Exclude<MutateRemoteViewResult, { kind: "ok" }>, slug: string): void {
   const message = mutateRemoteViewFailureMessage(result, slug);
   if (result.kind === "view-not-found" || result.kind === "item-not-found") notFound(res, message);
+  else if (result.kind === "read-only-collection") methodNotAllowed(res, message);
   else if (result.kind === "not-writable" || result.kind === "delete-not-allowed" || result.kind === "field-not-editable" || result.kind === "path-escape")
     forbidden(res, message);
   else badRequest(res, message);
@@ -710,11 +765,8 @@ router.post(API_ROUTES.collections.remoteViewMutate, async (req: Request<{ slug:
       badRequest(res, "invalid mutate request — expected { op: 'update'|'delete', id, patch? }");
       return;
     }
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await mutateRemoteView(collection, viewId, request);
     if (result.kind !== "ok") {
       sendMutateRemoteViewFailure(res, result, slug);
@@ -753,11 +805,8 @@ router.get(API_ROUTES.collections.remoteViewItems, async (req: Request<{ slug: s
   try {
     const { slug, viewId } = req.params;
     const request = { offset: clampOffset(req.query.offset), limit: clampLimit(req.query.limit), fields: normalizeFields(csvParam(req.query.fields)) };
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(slug, res);
+    if (!collection) return;
     const result = await remoteViewItems(collection, viewId, request);
     if (result.kind !== "ok") {
       sendRemoteViewItemsFailure(res, result, slug);
@@ -788,16 +837,9 @@ router.get(API_ROUTES.collections.viewI18n, async (req: Request<{ slug: string }
     const { slug } = req.params;
     const viewId = typeof req.query.id === "string" ? req.query.id : "";
     const locale = typeof req.query.locale === "string" ? req.query.locale : "";
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { collection, view } = resolved;
     if (!view.i18n) {
       // The view declared no translation file — return the empty contract so
       // the client doesn't have to special-case "no i18n" with a different
@@ -829,16 +871,9 @@ router.post(API_ROUTES.collections.viewToken, async (req: Request<{ slug: string
       badRequest(res, "`viewId` is required");
       return;
     }
-    const collection = await loadCollection(slug);
-    if (!collection) {
-      notFound(res, `collection '${slug}' not found`);
-      return;
-    }
-    const view = (collection.schema.views ?? []).find((entry) => entry.id === viewId);
-    if (!view) {
-      notFound(res, `custom view '${viewId}' not found on collection '${slug}'`);
-      return;
-    }
+    const resolved = await resolveCustomViewOr404(slug, viewId, res);
+    if (!resolved) return;
+    const { view } = resolved;
     const granted = clampCapabilities(view.capabilities, parseCapabilities(body.capabilities));
     const minted = mintViewToken(slug, granted);
     if (!minted) {
@@ -871,6 +906,149 @@ router.get(API_ROUTES.collections.viewData, viewDataCors, requireViewToken("read
   }
 });
 
+// Preflight for the token-scoped query endpoint (POST + JSON from a
+// sandboxed opaque-origin iframe — same CORS story as view-data itself).
+router.options(API_ROUTES.collections.viewDataQuery, viewDataCors, (_req: Request, res: Response) => {
+  res.sendStatus(204);
+});
+
+/** Per-slug in-flight cap for view-issued aggregation queries. The
+ *  per-minute limiter alone still lets a burst arrive CONCURRENTLY —
+ *  each query is a full-file DuckDB scan, so a runaway dashboard loop
+ *  could otherwise stack dozens of scans at once. Exported factory so
+ *  the unit test can drive the counter without HTTP. */
+export function makeViewQueryConcurrencyGuard(max: number) {
+  const inflight = new Map<string, number>();
+  return (req: Request<{ slug?: string }>, res: Response, next: NextFunction): void => {
+    const slug = req.params.slug ?? "";
+    const current = inflight.get(slug) ?? 0;
+    if (current >= max) {
+      res.status(429).json({ error: "too many concurrent queries for this collection — retry shortly" });
+      return;
+    }
+    inflight.set(slug, current + 1);
+    let released = false;
+    // `close` fires after the response finishes OR the client disconnects
+    // mid-request — either way the scan slot must come back exactly once.
+    res.once("close", () => {
+      if (released) return;
+      released = true;
+      const now = inflight.get(slug) ?? 1;
+      if (now <= 1) inflight.delete(slug);
+      else inflight.set(slug, now - 1);
+    });
+    next();
+  };
+}
+
+const VIEW_QUERY_MAX_CONCURRENT = 4;
+const viewQueryConcurrency = makeViewQueryConcurrencyGuard(VIEW_QUERY_MAX_CONCURRENT);
+
+// Scoped aggregation: run a structured query (the DSL — never raw SQL)
+// over a dataSource collection's whole data file. Read capability only:
+// the DSL is read-only by construction. Reuses the manageCollection
+// handler so a view can never do more than the agent's own queryItems
+// (same validation, same file-backed refusal). Guarded twice: the
+// per-minute limiter (request volume) + the in-flight cap (concurrent
+// full-file scans).
+router.post(
+  API_ROUTES.collections.viewDataQuery,
+  viewDataCors,
+  viewActionRateLimit,
+  viewQueryConcurrency,
+  requireViewToken("read"),
+  async (req: Request<{ slug: string }>, res: Response) => {
+    try {
+      const body = (req.body ?? {}) as { query?: unknown };
+      const raw = await manageCollection.handler({ action: "queryItems", slug: req.params.slug, query: body.query });
+      sendToolResult(res, raw);
+    } catch (err) {
+      // Log the detail server-side; the token holder gets a FIXED message —
+      // a raw DuckDB error can carry absolute paths / host internals, and a
+      // scoped view is not a trusted audience for those.
+      log.warn("collections", "view-data query failed", { slug: req.params.slug.replace(/[\r\n]/g, " "), error: errorMessage(err) });
+      serverError(res, "collection query failed");
+    }
+  },
+);
+
+/** True when `relPath` is a CURRENT value of one of the schema's
+ *  `image`-type fields (top-level fields only, matching the remote view's
+ *  `inlineFields` rule) across `items`. This is the authorization rule for
+ *  the view-data image route: a scoped view token may resolve exactly these
+ *  paths and nothing else — never an arbitrary workspace file. Early-exit
+ *  scan (no per-request Set allocation). Exported for the unit test. */
+export function isAuthorizedImagePath(schema: LoadedCollection["schema"], items: CollectionItem[], relPath: string): boolean {
+  const imageFields = Object.entries(schema.fields)
+    .filter(([, spec]) => spec.type === "image")
+    .map(([name]) => name);
+  if (imageFields.length === 0 || relPath.length === 0) return false;
+  return items.some((item) => imageFields.some((field) => item[field] === relPath));
+}
+
+export interface ViewDataImageDeps {
+  loadCollection: (slug: string) => Promise<LoadedCollection | null>;
+  listRecords: (collection: LoadedCollection) => Promise<CollectionItem[]>;
+  resolveThumbnail: typeof resolveThumbnail;
+}
+
+/** The image-route handler behind a deps seam so its contract (400 missing
+ *  path / 404 unknown collection / 404 unauthorized path / 404 unresolvable
+ *  / clamped `maxEdge` plumbing / 500 on a thrown resolver) is
+ *  unit-testable without mounting the express app — same factory pattern as
+ *  the remote-view handlers. */
+export const createViewDataImageHandler =
+  (deps: ViewDataImageDeps) =>
+  async (req: Request<{ slug: string }>, res: Response): Promise<void> => {
+    const collection = await deps.loadCollection(req.params.slug);
+    if (!collection) {
+      notFound(res, `collection '${req.params.slug}' not found`);
+      return;
+    }
+    const relPath = typeof req.query.path === "string" ? req.query.path : "";
+    if (relPath.length === 0) {
+      badRequest(res, "pass `path` — an image field's workspace-relative value");
+      return;
+    }
+    try {
+      const items = await deps.listRecords(collection);
+      if (!isAuthorizedImagePath(collection.schema, items, relPath)) {
+        notFound(res, "path is not a current value of this collection's image fields");
+        return;
+      }
+      const dataUrl = await deps.resolveThumbnail(relPath, clampImageMaxEdge(req.query.maxEdge));
+      if (dataUrl === null) {
+        notFound(res, "image could not be resolved");
+        return;
+      }
+      res.json({ path: relPath, dataUrl });
+    } catch (err) {
+      log.warn("collections", "view-data image failed", { slug: collection.slug, error: errorMessage(err) });
+      serverError(res, "image resolve failed");
+    }
+  };
+
+router.options(API_ROUTES.collections.viewDataImage, viewDataCors, (_req: Request, res: Response) => {
+  res.status(204).end();
+});
+
+// Scoped image read: resolve one record-referenced image path into a
+// downscaled `data:` thumbnail (same resolver + clamps as the remote view's
+// `imageFields` inlining). The record scan doubles as the authorization
+// check — the requested path must be a CURRENT image-field value — and runs
+// under the same in-flight cap as /query (both are per-request full scans).
+// Sandboxed views can't attach the bearer to an <img>, so the JSON
+// { dataUrl } shape (fetch → img.src) is the contract; see
+// packages/core/assets/helps/custom-view.md "Displaying images".
+router.get(
+  API_ROUTES.collections.viewDataImage,
+  viewDataCors,
+  viewImageRateLimit,
+  viewQueryConcurrency,
+  requireViewToken("read"),
+  createViewDataImageHandler({ loadCollection, listRecords: (collection) => storeFor(collection).list(), resolveThumbnail }),
+);
+
 // Scoped write: validated putItems. Requires the `write` capability.
 router.put(API_ROUTES.collections.viewData, viewDataCors, requireViewToken("write"), async (req: Request<{ slug: string }>, res: Response) => {
   try {
@@ -903,11 +1081,8 @@ router.post(
   requireViewToken("write"),
   async (req: Request<{ slug: string; actionId: string }>, res: Response<ActionRunResponse>) => {
     try {
-      const collection = await loadCollection(req.params.slug);
-      if (!collection) {
-        notFound(res, `collection '${req.params.slug}' not found`);
-        return;
-      }
+      const collection = await loadCollectionOr404(req.params.slug, res);
+      if (!collection) return;
       const action = collection.schema.actions?.find((entry) => entry.id === req.params.actionId);
       if (!action) {
         notFound(res, `action '${req.params.actionId}' not found on collection '${collection.slug}'`);
@@ -923,7 +1098,7 @@ router.post(
         badRequest(res, "`itemId` is required (the record's primary-key value)");
         return;
       }
-      const record = await readItem(collection.dataDir, itemId);
+      const record = await storeFor(collection).read(itemId);
       if (!record) {
         notFound(res, `item '${itemId}' not found`);
         return;
@@ -971,11 +1146,8 @@ function sendDeleteViewRefusal(res: Response, result: Exclude<DeleteViewResult,
 // refuses user-scope + preset collections, consistent with collection delete.
 router.delete(API_ROUTES.collections.viewDelete, async (req: Request<{ slug: string; viewId: string }>, res: Response<DeleteViewResponse>) => {
   try {
-    const collection = await loadCollection(req.params.slug);
-    if (!collection) {
-      notFound(res, `collection '${req.params.slug}' not found`);
-      return;
-    }
+    const collection = await loadCollectionOr404(req.params.slug, res);
+    if (!collection) return;
     const result = await deleteCustomView(collection, req.params.viewId);
     if (result.kind !== "ok") {
       sendDeleteViewRefusal(res, result);