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

package/server/rscClient.tsx

@@ -2,8 +2,6 @@ import { createElement, type ReactNode, startTransition, type Usable, use, useLa
 import { hydrateRoot } from "react-dom/client";
 import { createFromReadableStream } from "react-server-dom-webpack/client.browser";
 import type {} from "../client/rscNavigation";
-import { transitionTypes, viewTransitionClassOf } from "../client/transitionTypes";
-import { addTransitionType } from "../client/viewTransition";
 import {
   type AkanHeadSnapshotV1,
   type AkanRouterStateV1,
@@ -34,6 +32,7 @@ import {
   rememberRscCacheNode,
   resolveCachedRscPatchNavigation,
 } from "./rscNavigationState";
+import { RscScrollRestoration } from "./rscScrollRestoration";
 import { commitAkanSegmentOutletPatch, resetAkanSegmentOutletPatches } from "./rscSegmentOutlet";
 
 type InlineRscChunk = [1, string] | [3, string];
@@ -156,14 +155,12 @@ function commitRscPatchNavigation({
   target,
   patch,
   replace,
-  scrollToTop,
-  bumpScrollToTop,
+  requestScroll,
 }: {
   target: string;
   patch: Extract<RscFetchResult, { type: "patched" }>;
   replace?: boolean;
-  scrollToTop?: boolean;
-  bumpScrollToTop?: () => void;
+  requestScroll?: () => void;
 }): boolean {
   const patchThenable = patch.patchedNode.thenable;
   if (!patchThenable) throw new Error("[rscClient] validated RSC patch is missing a thenable");
@@ -182,7 +179,7 @@ function commitRscPatchNavigation({
         return;
       }
       commitHistory(target, replace);
-      if (scrollToTop) bumpScrollToTop?.();
+      requestScroll?.();
     } catch {
       if (headApplied) rollbackPreparedAkanHeadSnapshotPatch(preparedHeadPatch);
       if (outletCommitted) resetAkanSegmentOutletPatches();
@@ -197,10 +194,12 @@ function akanHistoryState(replace: boolean, shallow = false) {
   const idx = (window.history.state as { __akanRouter?: { idx?: unknown } } | null)?.__akanRouter?.idx;
   const current = Number.isInteger(idx) ? (idx as number) : 0;
   const shallowState = shallow ? { shallow: true, rendered: renderedHref } : {};
-  return { __akanRouter: { idx: replace ? current : current + 1, ...shallowState } };
+  const scrollState = replace ? scrollRestoration.replaceEntry() : scrollRestoration.pushEntry();
+  return { __akanRouter: { idx: replace ? current : current + 1, ...scrollState, ...shallowState } };
 }
 
 let renderedHref = normalizeHref(window.location.href);
+const scrollRestoration = new RscScrollRestoration();
 const pathnameOf = (href: string) => new URL(href).pathname;
 
 function commitHistory(target: string, replace: boolean | undefined) {
@@ -209,13 +208,6 @@ function commitHistory(target: string, replace: boolean | undefined) {
   renderedHref = target;
 }
 
-function viewTransitionTypeOf(transition: string | undefined, push: boolean): string | null {
-  const type = transitionTypes.find((candidate) => candidate === transition);
-  if (!type || type === "none") return null;
-  if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return null;
-  return viewTransitionClassOf(type, push ? "push" : "pop");
-}
-
 /** Writes the entry without asking the server for the page; only a change that keeps the rendered path qualifies. */
 function navigateShallow(target: string, replace: boolean | undefined): boolean {
   if (pathnameOf(target) !== pathnameOf(renderedHref)) return false;
@@ -336,12 +328,11 @@ function rememberPatchedRouteState(tree: RscSegmentCacheNode, patchedNode: RscSe
 
 function Root(): ReactNode {
   const [thenable, setThenable] = useState<RscThenable>(initialThenable);
-  const [scrollToTopTick, setScrollToTopTick] = useState(0);
+  const [scrollRequest, setScrollRequest] = useState<{ scrollY: number } | null>(null);
 
   useLayoutEffect(() => {
-    if (!scrollToTopTick) return;
-    window.scrollTo(0, 0);
-  }, [scrollToTopTick]);
+    if (scrollRequest) scrollRestoration.scrollTo(scrollRequest.scrollY);
+  }, [scrollRequest]);
 
   globalThis.__AKAN_RSC_CLEAR_CACHE__ = () => {
     rscCache.clear();
@@ -419,7 +410,8 @@ function Root(): ReactNode {
     if (options.shallow && navigateShallow(normalizeHref(href), options.replace)) return;
     const navId = ++navigationSeq;
     const target = normalizeHref(href);
-    const scrollToTop = options.scrollToTop ?? true;
+    const scrollY = options.scrollY ?? ((options.scrollToTop ?? true) ? 0 : undefined);
+    const requestScroll = scrollY === undefined ? undefined : () => setScrollRequest({ scrollY });
     try {
       let nextNode = rscCache.get(target);
       const servedFromCache = !!nextNode;
@@ -447,8 +439,7 @@ function Root(): ReactNode {
                 target,
                 patch: replayedPatch,
                 replace: options.replace,
-                scrollToTop,
-                bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
+                requestScroll,
               })
             ) {
               currentCommitFromCache = true;
@@ -473,8 +464,7 @@ function Root(): ReactNode {
               target,
               patch: fetched,
               replace: options.replace,
-              scrollToTop,
-              bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
+              requestScroll,
             })
           ) {
             currentCommitFromCache = false;
@@ -516,11 +506,6 @@ function Root(): ReactNode {
       });
       
       await nextNode.thenable;
-      
-      const viewTransitionType = viewTransitionTypeOf(
-        options.pop ? currentRouterState?.transition : nextNode.routerState?.transition,
-        !options.pop,
-      );
       const committed = commitLatestRscNavigation({
         cache: rscCache,
         href: target,
@@ -528,10 +513,6 @@ function Root(): ReactNode {
         maxEntries: MAX_RSC_CACHE_ENTRIES,
         startTransition,
         commitThenable: (node) => {
-          if (viewTransitionType && addTransitionType) {
-            addTransitionType("akan-nav");
-            addTransitionType(viewTransitionType);
-          }
           currentCommitFromCache = servedFromCache;
           resetAkanSegmentOutletPatches();
           setThenable(node.thenable);
@@ -539,8 +520,7 @@ function Root(): ReactNode {
         updateHistory: () => {
           commitHistory(target, options.replace);
         },
-        scrollToTop,
-        bumpScrollToTop: () => setScrollToTopTick((tick) => tick + 1),
+        requestScroll,
         navId,
         getCurrentNavId: () => navigationSeq,
       });
@@ -559,13 +539,15 @@ function Root(): ReactNode {
 window.addEventListener("popstate", (event) => {
   const here = normalizeHref(window.location.href);
   const entry = (event.state as { __akanRouter?: { shallow?: boolean; rendered?: string } } | null)?.__akanRouter;
+  const scrollY = scrollRestoration.traverseTo(event.state);
   
   const keepsPage = (entry?.shallow ? entry.rendered : here) === renderedHref;
   
   if (!keepsPage)
     void globalThis
-      .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false, pop: true })
+      .__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false, scrollY })
       ?.catch((error: unknown) => hardNavigateAfterRscFailure(window.location.href, true, error));
+  else if (scrollY !== undefined) scrollRestoration.scrollTo(scrollY);
   window.setTimeout(() => {
     if (globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
     const href = globalThis.__AKAN_GET_SYNC_ROUTE_HREF__?.(window.location.href) ?? window.location.href;
@@ -573,5 +555,8 @@ window.addEventListener("popstate", (event) => {
   }, 0);
 });
 
-const hydrate = () => hydrateRoot(document, createElement(Root));
+const hydrate = () => {
+  hydrateRoot(document, createElement(Root));
+  scrollRestoration.restoreDocumentLoad();
+};
 void Promise.resolve(initialThenable).then(hydrate, hydrate);

package/server/rscNavigationState.ts

@@ -312,8 +312,7 @@ interface CommitRscNavigationInput<T> {
   startTransition: (callback: () => void) => void;
   commitThenable: (thenable: T) => void;
   updateHistory?: () => void;
-  scrollToTop?: boolean;
-  bumpScrollToTop?: () => void;
+  requestScroll?: () => void;
 }
 
 export function commitRscNavigation<T>({
@@ -324,14 +323,13 @@ export function commitRscNavigation<T>({
   startTransition,
   commitThenable,
   updateHistory,
-  scrollToTop,
-  bumpScrollToTop,
+  requestScroll,
 }: CommitRscNavigationInput<T>): void {
   rememberRscCacheEntry(cache, href, thenable, maxEntries);
   startTransition(() => {
     commitThenable(thenable);
     updateHistory?.();
-    if (scrollToTop) bumpScrollToTop?.();
+    requestScroll?.();
   });
 }
 

package/server/rscScrollRestoration.ts

@@ -0,0 +1,116 @@
+const RESTORE_WINDOW_MS = 2000;
+const PERSIST_DELAY_MS = 200;
+const userScrollEvents = ["wheel", "touchstart", "keydown", "pointerdown"] as const;
+
+interface AkanEntryState {
+  key?: unknown;
+  scrollY?: unknown;
+}
+
+export class RscScrollRestoration {
+  #positions = new Map<string, number>();
+  #key: string;
+  #manual: boolean = false;
+  #persistTimer: ReturnType<typeof setTimeout> | null = null;
+  #cancelPending: (() => void) | null = null;
+
+  constructor() {
+    this.#key = RscScrollRestoration.#entryOf(window.history.state).key ?? RscScrollRestoration.#mintKey();
+    
+    window.addEventListener("scroll", () => this.#schedulePersist(), { passive: true });
+    window.addEventListener("pagehide", () => {
+      if (this.#persistTimer) this.#persist();
+    });
+  }
+
+  pushEntry(): { key: string } {
+    this.#settle();
+    this.#manual = true;
+    window.history.scrollRestoration = "manual";
+    this.#positions.set(this.#key, window.scrollY);
+    this.#persist();
+    this.#key = RscScrollRestoration.#mintKey();
+    return { key: this.#key };
+  }
+
+  replaceEntry(): { key: string; scrollY?: number } {
+    const { scrollY } = RscScrollRestoration.#entryOf(window.history.state);
+    return { key: this.#key, ...(scrollY === undefined ? {} : { scrollY }) };
+  }
+
+  traverseTo(state: unknown): number | undefined {
+    this.#settle();
+    this.#positions.set(this.#key, window.scrollY);
+    const entry = RscScrollRestoration.#entryOf(state);
+    if (entry.key) {
+      this.#key = entry.key;
+      return this.#positions.get(entry.key) ?? entry.scrollY;
+    }
+    
+    this.#key = RscScrollRestoration.#mintKey();
+    RscScrollRestoration.#writeEntry({ key: this.#key });
+    return undefined;
+  }
+
+  scrollTo(scrollY: number) {
+    this.#cancelPending?.();
+    window.scrollTo(0, scrollY);
+    if (scrollY === 0 || typeof ResizeObserver === "undefined") return;
+    
+    const observer = new ResizeObserver(() => {
+      if (Math.abs(window.scrollY - scrollY) > 1) window.scrollTo(0, scrollY);
+    });
+    const timer = setTimeout(() => cancel(), RESTORE_WINDOW_MS);
+    const cancel = () => {
+      observer.disconnect();
+      clearTimeout(timer);
+      for (const type of userScrollEvents) window.removeEventListener(type, cancel, true);
+      if (this.#cancelPending === cancel) this.#cancelPending = null;
+    };
+    for (const type of userScrollEvents) window.addEventListener(type, cancel, { capture: true, passive: true });
+    observer.observe(document.body);
+    this.#cancelPending = cancel;
+  }
+
+  restoreDocumentLoad() {
+    if (window.history.scrollRestoration !== "manual") return;
+    this.#manual = true;
+    const { scrollY } = RscScrollRestoration.#entryOf(window.history.state);
+    if (scrollY !== undefined) this.scrollTo(scrollY);
+  }
+
+  #schedulePersist() {
+    if (!this.#manual) return;
+    if (this.#persistTimer) clearTimeout(this.#persistTimer);
+    this.#persistTimer = setTimeout(() => this.#persist(), PERSIST_DELAY_MS);
+  }
+
+  #persist() {
+    if (this.#persistTimer) clearTimeout(this.#persistTimer);
+    this.#persistTimer = null;
+    RscScrollRestoration.#writeEntry({ key: this.#key, scrollY: window.scrollY });
+  }
+
+  #settle() {
+    this.#cancelPending?.();
+    if (this.#persistTimer) clearTimeout(this.#persistTimer);
+    this.#persistTimer = null;
+  }
+
+  static #entryOf(state: unknown): { key?: string; scrollY?: number } {
+    const entry = (state as { __akanRouter?: AkanEntryState } | null)?.__akanRouter;
+    return {
+      key: typeof entry?.key === "string" ? entry.key : undefined,
+      scrollY: typeof entry?.scrollY === "number" && Number.isFinite(entry.scrollY) ? entry.scrollY : undefined,
+    };
+  }
+
+  static #writeEntry(fields: AkanEntryState) {
+    const state = (window.history.state ?? {}) as { __akanRouter?: object };
+    window.history.replaceState({ ...state, __akanRouter: { ...state.__akanRouter, ...fields } }, "");
+  }
+
+  static #mintKey() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+  }
+}

package/server/rscWorker.tsx

@@ -491,18 +491,11 @@ export class RscRenderer {
         const beforeLoadedKeys = RouteTreeBuilder.getCacheStats().loadedModuleKeys;
         const cacheDecision = match ? this.#getResultCacheEntry(request, urlObj) : { entry: null };
         const cacheEntry = cacheDecision.entry;
-        const targetFrame = match
-          ? await RouteElementComposer.resolveSsrFramePathRoute({
-              pathRoute: match.pathRoute,
-              basePath: this.#getBasePath(urlObj),
-            })
-          : null;
         const targetRouterState = match
           ? createAkanRouterState({
               pathRoute: match.pathRoute,
               href: urlObj.href,
               buildId: this.#pagesBundleBuildId,
-              transition: targetFrame?.pageState.transition,
             })
           : null;
         const searchParams = parseSearchParams(urlObj.search);
@@ -886,8 +879,11 @@ export class RscRenderer {
     } = {},
   ): Promise<FlightRenderResult> {
     const controlRef: { current: RenderControl | null } = { current: null };
+    
+    let isCancelling = false;
     const stream = await renderToReadableStream(element, clientManifest, {
       onError: (error) => {
+        if (isCancelling || (options.requestId && this.#cancelledRenderRequests.has(options.requestId))) return;
         if (isAkanRedirectError(error)) {
           const { location, method, status } = error;
           controlRef.current = { type: "redirect", location, method, status };
@@ -934,6 +930,11 @@ export class RscRenderer {
       reportedTheme = theme;
       this.#send({ type: "theme", requestId: options.requestId, theme });
     };
+    const cancelWith = async (control: RenderControl | null, cancelled: boolean): Promise<FlightRenderResult> => {
+      isCancelling = true;
+      await reader.cancel();
+      return { chunks, bytes, chunksCount, control, lateControlSent, cancelled };
+    };
     const readProbe = () => {
       if (!controlRef.current && options.notFoundProbe?.hit) controlRef.current = { type: "not-found" };
     };
@@ -960,26 +961,18 @@ export class RscRenderer {
     };
     try {
       for (;;) {
-        if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
-          await reader.cancel();
-          return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
-        }
+        if (options.requestId && this.#cancelledRenderRequests.has(options.requestId))
+          return await cancelWith(null, true);
         const { value, done } = await reader.read();
         readProbe();
-        if (controlRef.current && !sentChunk) {
-          await reader.cancel();
-          return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
-        }
+        if (controlRef.current && !sentChunk) return await cancelWith(controlRef.current, false);
         if (controlRef.current && sentChunk) sendLateControl();
         if (done) break;
 
         if (!sentChunk && options.requestId) {
           await new Promise((resolve) => setTimeout(resolve, 0));
           readProbe();
-          if (controlRef.current) {
-            await reader.cancel();
-            return { chunks, bytes, chunksCount, control: controlRef.current, lateControlSent, cancelled: false };
-          }
+          if (controlRef.current) return await cancelWith(controlRef.current, false);
         }
         const chunk = value instanceof Uint8Array ? value : new Uint8Array(value as ArrayBufferLike);
         bytes += chunk.byteLength;

package/server/sitemap.ts

@@ -1,4 +1,4 @@
-import type { AkanI18nConfig } from "akanjs/common";
+import { type AkanI18nConfig, trimSlashes, trimTrailingSlashes } from "akanjs/common";
 import type { RouteSeedEntry } from "./artifact";
 
 export interface DefaultSitemapOptions {
@@ -24,7 +24,7 @@ export function createDefaultSitemapXml({ origin, basePath, entries, i18n }: Def
 }
 
 export function createDefaultSitemapUrls({ origin, basePath, entries, i18n }: DefaultSitemapOptions): string[] {
-  const normalizedOrigin = origin.replace(/\/+$/, "");
+  const normalizedOrigin = trimTrailingSlashes(origin);
   const normalizedBasePath = normalizeSegment(basePath ?? "");
   const paths = entries.flatMap((entry) => expandStaticRoute(entry.pattern, normalizedBasePath, i18n.locales));
   return paths.map((pathname) => `${normalizedOrigin}${pathname}`);
@@ -66,12 +66,12 @@ function expandStaticRoute(pattern: string, basePath: string, locales: readonly
 }
 
 function normalizePathname(pathname: string): string {
-  const trimmed = pathname.trim().replace(/\/+$/, "");
+  const trimmed = trimTrailingSlashes(pathname.trim());
   return trimmed ? `/${trimmed.replace(/^\/+/, "")}` : "/";
 }
 
 function normalizeSegment(value: string): string {
-  return value.trim().replace(/^\/+|\/+$/g, "");
+  return trimSlashes(value.trim());
 }
 
 function encodePathSegment(value: string): string {

package/server/tunnel/TunnelAgent.ts

@@ -38,6 +38,8 @@ const backoffMs = [1_000, 2_000, 4_000, 8_000, 15_000];
 
 const coldAttemptLimit = 10;
 
+const heartbeatRangeMs = { min: 1_000, max: 300_000 } as const;
+
 /** Dials out to the gateway, so its machine needs no public address, no inbound port and no NAT traversal. */
 export class TunnelAgent {
   readonly #options: TunnelAgentOptions;
@@ -123,7 +125,7 @@ export class TunnelAgent {
         this.#everReady = true;
         
         this.#attempts = 0;
-        this.#startHeartbeat(frame.heartbeatMs || tunnelWireContract.defaultHeartbeatMs);
+        this.#startHeartbeat(TunnelAgent.#heartbeatOf(frame.heartbeatMs));
         this.#grow();
         this.logger.info(`Tunnel ready: ${frame.urls.join(", ")}`);
         onReady(frame);
@@ -202,6 +204,12 @@ export class TunnelAgent {
     this.#heartbeat = null;
   }
 
+  static #heartbeatOf(requestedMs: number) {
+    return requestedMs >= heartbeatRangeMs.min && requestedMs <= heartbeatRangeMs.max
+      ? requestedMs
+      : tunnelWireContract.defaultHeartbeatMs;
+  }
+
   #say(frame: TunnelControlFromAgent) {
     if (this.#ws?.readyState !== WebSocket.OPEN) return;
     this.#ws.send(JSON.stringify(frame));

package/server/webRouter.ts

@@ -242,7 +242,7 @@ export function normalizeRscTargetUrlForHostBasePath(
     if (routeMatches(normalized)) return { url: normalized, basePath: candidate };
   }
 
-  return { url: targetUrl, basePath: basePath ?? targetBasePath };
+  return { url: targetUrl, basePath: targetBasePath };
 }
 
 export interface SsrRoutesInputs {
@@ -367,6 +367,7 @@ export class WebRouter {
     const localCsrDir = path.join(process.cwd(), "csr");
     const csrOutputDir = fs.existsSync(localCsrDir) ? localCsrDir : path.join(this.#artifactDir, "csr");
     const publicDir = path.join(process.env.AKAN_APP_DIR ?? path.dirname(Bun.main), "public");
+    const shippedPublicFiles = this.#prodMode ? WebRouter.#shippedFiles(publicDir) : null;
     const imageCacheDir = path.join(this.#artifactDir, "image-cache");
     const imageOptimizer = new ImageOptimizer({
       publicDir,
@@ -566,7 +567,7 @@ export class WebRouter {
         }
 
         const filePath = resolveStaticPath(publicDir, url.pathname);
-        if (filePath && (await Bun.file(filePath).exists())) {
+        if (filePath && (await WebRouter.#isPublicFile(filePath, url.pathname, shippedPublicFiles))) {
           this.#requestStats.staticAsset += 1;
           const contentType = Bun.file(filePath).type || "application/octet-stream";
           return WebRouter.#fileResponse(req, filePath, {
@@ -1116,6 +1117,20 @@ export class WebRouter {
     this.#logger.warn(`[csr] ${message}`);
     return new Response(message, { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } });
   }
+
+  static async #isPublicFile(filePath: string, pathname: string, shipped: Set<string> | null) {
+    if (shipped && !path.extname(pathname)) return shipped.has(filePath);
+    return await Bun.file(filePath).exists();
+  }
+
+  static #shippedFiles(dir: string): Set<string> {
+    const files = new Set<string>();
+    if (!fs.existsSync(dir)) return files;
+    const scan = new Bun.Glob("**/*").scanSync({ cwd: dir, onlyFiles: true, dot: true, followSymlinks: true });
+    for (const relative of scan) files.add(path.resolve(dir, relative));
+    return files;
+  }
+
   static #injectBeforeBodyEnd(html: string, snippet: string): string {
     const matches = [...html.matchAll(/<\/body\s*>/gi)];
     const last = matches.at(-1);

package/service/agent.service.ts

@@ -3,6 +3,7 @@ import type {
   AgentWireAttachment,
   AgentWireMessage,
   AgentWireReference,
+  AgentWireToolResult,
   LlmAccepts,
   LlmTurnRequest,
 } from "./predefinedAdaptor/llm.adaptor";
@@ -104,12 +105,21 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
 
   /** Swaps an attachment the provider cannot read for a note; dropped silently, it is guessed at from its name. */
   static readable(request: LlmTurnRequest, accepts: LlmAccepts | undefined): LlmTurnRequest {
-    if (!request.messages.some((message) => message.attachments?.length)) return request;
+    if (!request.messages.some(AgentService.carriesFiles)) return request;
     const messages = request.messages.map((message) => AgentService.readableMessage(message, accepts ?? {}));
     return { ...request, messages };
   }
 
+  private static carriesFiles(message: AgentWireMessage): boolean {
+    return !!message.attachments?.length || !!message.toolResults?.some((result) => result.attachments?.length);
+  }
+
   private static readableMessage(message: AgentWireMessage, accepts: LlmAccepts): AgentWireMessage {
+    if (message.role === "tool")
+      return {
+        ...message,
+        toolResults: (message.toolResults ?? []).map((result) => AgentService.readableResult(result, accepts)),
+      };
     const { attachments = [], ...rest } = message;
     if (!attachments.length) return message;
     const kept = attachments.filter((attachment) => AgentService.isReadable(attachment, accepts));
@@ -122,6 +132,16 @@ export class AgentService extends serve("agent" as const, ({ plug }) => ({
     };
   }
 
+  private static readableResult(result: AgentWireToolResult, accepts: LlmAccepts): AgentWireToolResult {
+    if (!result.attachments?.length) return result;
+    const attachments = result.attachments.map((attachment) =>
+      AgentService.isReadable(attachment, accepts)
+        ? attachment
+        : { name: attachment.name, mimeType: attachment.mimeType, text: AgentService.note(attachment) },
+    );
+    return { ...result, attachments };
+  }
+
   private static isReadable(attachment: AgentWireAttachment, accepts: LlmAccepts): boolean {
     if (attachment.text) return true;
     if (!attachment.data && !attachment.url) return false;

package/service/endpointCacheKeys.ts

@@ -0,0 +1,35 @@
+import { dayjs } from "akanjs/base";
+import type { CacheAdaptor } from "./predefinedAdaptor/cache.adaptor";
+
+export class EndpointCacheKeys {
+  static readonly topic = "cache";
+  static readonly generationTtlMs = 86_400_000;
+  static readonly #generationTopic = "cacheGeneration";
+
+  static async entryKey(cache: Pick<CacheAdaptor, "get" | "setIfAbsent">, endpoint: string, args: unknown[]) {
+    return `${endpoint}:${await EndpointCacheKeys.#generation(cache, endpoint)}:${JSON.stringify(args)}`;
+  }
+
+  static async invalidate(
+    cache: Pick<CacheAdaptor, "get" | "set" | "setIfAbsent" | "delete">,
+    endpoint: string,
+    args?: unknown[],
+  ) {
+    if (args) await cache.delete(EndpointCacheKeys.topic, await EndpointCacheKeys.entryKey(cache, endpoint, args));
+    else
+      await cache.set(EndpointCacheKeys.#generationTopic, endpoint, crypto.randomUUID(), EndpointCacheKeys.#expiry());
+  }
+
+  static async #generation(cache: Pick<CacheAdaptor, "get" | "setIfAbsent">, endpoint: string) {
+    const current = await cache.get<string>(EndpointCacheKeys.#generationTopic, endpoint);
+    if (current !== undefined) return current;
+    const fresh = crypto.randomUUID();
+    if (await cache.setIfAbsent(EndpointCacheKeys.#generationTopic, endpoint, fresh, EndpointCacheKeys.#expiry()))
+      return fresh;
+    return (await cache.get<string>(EndpointCacheKeys.#generationTopic, endpoint)) ?? fresh;
+  }
+
+  static #expiry() {
+    return { expireAt: dayjs().add(EndpointCacheKeys.generationTtlMs, "millisecond") };
+  }
+}

package/service/index.ts

@@ -1,6 +1,7 @@
 export * from "./adapt";
 export * from "./agent.service";
 export * from "./base.service";
+export * from "./endpointCacheKeys";
 export * from "./injectInfo";
 export * from "./ipcTypes";
 export * from "./liveSyncHub";

package/service/injectInfo.ts

@@ -91,8 +91,8 @@ export const getDefaultLiveRegistry = (): LiveRegistry => ({
 export class InjectInfo<
   Type extends InjectType = any,
   ReturnType = any,
-  Env extends { [key: string]: any } = never,
-  FieldValue = never,
+  _Env extends { [key: string]: any } = never,
+  _FieldValue = never,
 > {
   readonly type: Type;
   readonly generateFactory: (options: any) => ReturnType;