@agent-native/core 0.98.0 → 0.98.2

package/corpus/templates/analytics/server/lib/dashboard-catalog.ts

@@ -938,7 +938,7 @@ export const dashboardCatalogEntries: DashboardCatalogEntry[] = [
       "referrals",
       "virality",
     ],
-    panelCount: 51,
+    panelCount: 36,
     version: CATALOG_VERSION,
     recommended: true,
     visibleInCatalog: false,

package/corpus/templates/analytics/server/lib/dashboard-report.ts

@@ -42,9 +42,8 @@ const DASHBOARD_REPORT_SCREENSHOT_PARAM = "reportScreenshot";
 const DASHBOARD_REPORT_SETTINGS_PARAM = "reportSettings";
 const DASHBOARD_REPORT_CID = "dashboard-report-snapshot";
 const LOCAL_SCREENSHOT_TIMEOUT_MS = 90_000;
-const SERVERLESS_SCREENSHOT_TIMEOUT_MS = 60_000;
-const SERVERLESS_SECOND_READY_TIMEOUT_MS = 30_000;
-const MAX_SCREENSHOT_VIEWPORT_HEIGHT = 30_000;
+const SERVERLESS_SCREENSHOT_TIMEOUT_MS = 90_000;
+const SERVERLESS_SECOND_READY_TIMEOUT_MS = 45_000;
 const SCREENSHOT_VIEWPORT_PADDING = 64;
 
 type DashboardScreenshotAttempt = {
@@ -328,42 +327,27 @@ async function scrollDashboardForLazyRendering(page: any): Promise<void> {
   })()`);
 }
 
-async function fitViewportToDashboardCapture(
+async function fitViewportWidthToDashboardCapture(
   page: any,
   capture: any,
-  minViewport: { width: number; height: number },
+  viewport: { width: number; height: number },
 ): Promise<void> {
   const box = await capture.boundingBox();
   if (!box) return;
 
-  const size = {
-    width: Math.max(
-      minViewport.width,
-      Math.min(1800, Math.ceil(box.width + SCREENSHOT_VIEWPORT_PADDING)),
-    ),
-    height: Math.max(
-      minViewport.height,
-      Math.min(
-        MAX_SCREENSHOT_VIEWPORT_HEIGHT,
-        Math.ceil(box.height + SCREENSHOT_VIEWPORT_PADDING),
-      ),
-    ),
-  };
-  await page.setViewportSize(size);
-  await page.waitForTimeout(250);
-
-  const resizedBox = await capture.boundingBox();
-  if (!resizedBox) return;
-  const resizedHeight = Math.ceil(
-    resizedBox.height + SCREENSHOT_VIEWPORT_PADDING,
+  const width = Math.max(
+    viewport.width,
+    Math.min(1800, Math.ceil(box.width + SCREENSHOT_VIEWPORT_PADDING)),
   );
-  if (resizedHeight > size.height) {
-    await page.setViewportSize({
-      width: size.width,
-      height: Math.min(MAX_SCREENSHOT_VIEWPORT_HEIGHT, resizedHeight),
-    });
-    await page.waitForTimeout(250);
-  }
+  if (width === viewport.width) return;
+
+  // Keep the render surface bounded. Playwright's locator screenshot captures
+  // the full element beyond the viewport, while growing Chromium to the full
+  // dashboard height can exhaust memory and close the browser on serverless
+  // workers. Width-only fitting preserves the full dashboard without that
+  // oversized render surface.
+  await page.setViewportSize({ width, height: viewport.height });
+  await page.waitForTimeout(250);
 }
 
 async function captureDashboardPng(
@@ -412,7 +396,7 @@ async function captureDashboardPng(
     await scrollDashboardForLazyRendering(page);
     await waitForDashboardReportReady(page, secondReadyTimeoutMs());
 
-    await fitViewportToDashboardCapture(page, capture, attempt.viewport);
+    await fitViewportWidthToDashboardCapture(page, capture, attempt.viewport);
     await capture.scrollIntoViewIfNeeded();
     const image = await capture.screenshot({
       type: "png",

package/corpus/templates/analytics/server/lib/demo-dashboards.ts

@@ -104,6 +104,15 @@ function publicState(state: DemoDashboardState): Record<string, unknown> {
   };
 }
 
+function stateContent(state: DemoDashboardState): string {
+  return JSON.stringify({
+    version: state.version,
+    initializedAt: state.initializedAt,
+    dashboards: state.dashboards ?? {},
+    deleted: state.deleted ?? {},
+  });
+}
+
 export function demoDashboardIdForUser(
   email: string,
   demoId: DemoDashboardId,
@@ -291,14 +300,18 @@ export async function ensureDemoDashboardsForUser(
     });
   }
 
-  const updatedState: DemoDashboardState = {
+  const updatedStateContent: DemoDashboardState = {
     version: DEMO_DASHBOARD_VERSION,
     initializedAt: state.initializedAt ?? nowIso(),
-    updatedAt: nowIso(),
     dashboards,
     deleted,
   };
-  await writeDemoState(ctx.email, updatedState);
+  if (reset || stateContent(state) !== stateContent(updatedStateContent)) {
+    await writeDemoState(ctx.email, {
+      ...updatedStateContent,
+      updatedAt: nowIso(),
+    });
+  }
 
   const firstActive = results.find((row) => row.installed && !row.archivedAt);
   return {

package/corpus/templates/analytics/server/lib/session-replay-agent-context.ts

@@ -50,6 +50,7 @@ const MOUSE_INTERACTION = {
   DblClick: 4,
   Focus: 5,
 } as const;
+const SCROLL_MARKER_BURST_MS = 1_000;
 
 function appBasePath(): string {
   const raw = process.env.VITE_APP_BASE_PATH || process.env.APP_BASE_PATH || "";
@@ -499,6 +500,7 @@ function capReplayTimelineMarkers(
 function buildReplayTimeline(events: AgentReplayEvent[]) {
   const startedAt = replayStartedAt(events);
   const markers: ReplayTimelineMarker[] = [];
+  const lastScrollByTarget = new Map<string, number>();
 
   for (const event of events) {
     const timestamp = Number(event.timestamp ?? 0);
@@ -568,6 +570,15 @@ function buildReplayTimeline(events: AgentReplayEvent[]) {
       event.type === RRWEB_EVENT_TYPE.IncrementalSnapshot &&
       event.data?.source === INCREMENTAL_SOURCE.Scroll
     ) {
+      const target = String(event.data?.id ?? "viewport");
+      const previousTimestamp = lastScrollByTarget.get(target);
+      if (
+        previousTimestamp !== undefined &&
+        timestamp - previousTimestamp <= SCROLL_MARKER_BURST_MS
+      ) {
+        lastScrollByTarget.set(target, timestamp);
+        continue;
+      }
       markers.push({
         timestamp,
         offsetMs: Math.max(0, timestamp - startedAt),
@@ -575,6 +586,7 @@ function buildReplayTimeline(events: AgentReplayEvent[]) {
         label: "Scroll",
         detail: null,
       });
+      lastScrollByTarget.set(target, timestamp);
     } else if (
       event.type === RRWEB_EVENT_TYPE.IncrementalSnapshot &&
       event.data?.source === INCREMENTAL_SOURCE.MouseInteraction &&

package/corpus/templates/analytics/server/lib/session-replay.ts

@@ -16,7 +16,19 @@ import {
   roleSatisfies,
   type ShareRole,
 } from "@agent-native/core/sharing";
-import { and, asc, desc, eq, gte, isNull, lt, lte, or, sql } from "drizzle-orm";
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  gte,
+  inArray,
+  isNull,
+  lt,
+  lte,
+  or,
+  sql,
+} from "drizzle-orm";
 
 import {
   isFailedSessionReplayNetworkStatus,
@@ -229,6 +241,10 @@ const DEFAULT_REPLAY_EVENTS_READ = 10_000;
 const MAX_REPLAY_EVENTS_READ = 100_000;
 const MAX_REPLAY_EVENTS_RESPONSE_BYTES =
   MAX_BLOB_REPLAY_CHUNK_BYTES + 512 * 1024;
+export const MAX_REPLAY_CHUNK_READ_BATCH_SIZE = 20;
+export const MAX_REPLAY_CHUNK_READ_BATCH_BYTES =
+  MAX_REPLAY_EVENTS_RESPONSE_BYTES;
+const REPLAY_CHUNK_READ_CONCURRENCY = 10;
 const DEFAULT_SESSION_RECORDINGS_LIMIT = 50;
 const MAX_SESSION_RECORDINGS_LIMIT = 100;
 const DEFAULT_REPLAY_RETENTION_DAYS = 30;
@@ -1954,7 +1970,16 @@ async function readSessionReplayChunkBytesForRecording(
     const ref = decodeReplayBlobRef(row.storageRef);
     if (!ref)
       throw replayError("Session replay blob reference is invalid", 500);
-    const blob = await readPrivateBlob(ref.handle);
+    const blob = await readPrivateBlob(ref.handle).catch((error) => {
+      console.error(
+        `[session-replay] Failed to decrypt blob chunk ${recording.id}/${row.seq}:`,
+        error,
+      );
+      throw replayError(
+        "Session replay storage could not be decrypted with this environment's encryption key. When using a production Analytics database locally, set ANALYTICS_SECRETS_ENCRYPTION_KEY to the matching production key.",
+        503,
+      );
+    });
     return {
       recording,
       seq: row.seq,
@@ -1972,6 +1997,187 @@ async function readSessionReplayChunkBytesForRecording(
   };
 }
 
+export interface SessionReplayChunkBatchItem {
+  seq: number;
+  checksum: string;
+  byteLength: number;
+  eventCount: number;
+  events: unknown[];
+  unavailable?: true;
+}
+
+export interface SessionReplayChunkBatchResult {
+  chunks: SessionReplayChunkBatchItem[];
+  unavailableChunks: number;
+}
+
+function validateReplayChunkReadSeqs(seqs: number[]): number[] {
+  if (!seqs.length) {
+    throw replayError("At least one replay chunk seq is required", 400);
+  }
+  if (seqs.length > MAX_REPLAY_CHUNK_READ_BATCH_SIZE) {
+    throw replayError(
+      `At most ${MAX_REPLAY_CHUNK_READ_BATCH_SIZE} replay chunks may be read per request`,
+      400,
+    );
+  }
+  const unique = new Set<number>();
+  for (const seq of seqs) {
+    if (!Number.isSafeInteger(seq) || seq < 0) {
+      throw replayError("Replay chunk seqs must be non-negative integers", 400);
+    }
+    if (unique.has(seq)) {
+      throw replayError("Replay chunk seqs must be unique", 400);
+    }
+    unique.add(seq);
+  }
+  return [...seqs];
+}
+
+function unavailableReplayChunkBatchItem(
+  seq: number,
+  row?: any,
+): SessionReplayChunkBatchItem {
+  return {
+    seq,
+    checksum: row?.checksum ?? "",
+    byteLength: Number(row?.byteLength ?? 0),
+    eventCount: Number(row?.eventCount ?? 0),
+    events: [],
+    unavailable: true,
+  };
+}
+
+async function readReplayChunkBatchRow(
+  recording: SessionRecordingSummary,
+  row: any,
+): Promise<SessionReplayChunkBatchItem> {
+  let json: string;
+  if (row.storageKind === "blob" && row.storageRef) {
+    const ref = decodeReplayBlobRef(row.storageRef);
+    if (!ref) return unavailableReplayChunkBatchItem(row.seq, row);
+    let blob: Awaited<ReturnType<typeof readPrivateBlob>>;
+    try {
+      blob = await readPrivateBlob(ref.handle);
+    } catch (error) {
+      console.error(
+        `[session-replay] Failed to read blob chunk ${recording.id}/${row.seq}:`,
+        error,
+      );
+      throw replayError(
+        "Session replay storage could not be read with this environment's storage configuration or encryption key.",
+        503,
+      );
+    }
+    try {
+      json = gunzipSync(Buffer.from(blob.data)).toString("utf8");
+    } catch {
+      return unavailableReplayChunkBatchItem(row.seq, row);
+    }
+  } else if (row.inlineData) {
+    json = row.inlineData;
+  } else {
+    return unavailableReplayChunkBatchItem(row.seq, row);
+  }
+
+  return {
+    seq: row.seq,
+    checksum: row.checksum,
+    byteLength: row.byteLength,
+    eventCount: row.eventCount,
+    events: parseInlineReplayEvents(json),
+  };
+}
+
+async function readSessionReplayChunkBatchForRecording(
+  recording: SessionRecordingSummary,
+  requestedSeqs: number[],
+): Promise<SessionReplayChunkBatchResult> {
+  const seqs = validateReplayChunkReadSeqs(requestedSeqs);
+  const db = getDb() as any;
+  // guard:allow-unscoped -- rows are loaded only after one recording-scoped resolveAccess check or a signed recording-scoped agent token verifies access.
+  const rows = await db
+    .select()
+    .from(schema.sessionReplayChunks)
+    .where(
+      and(
+        eq(schema.sessionReplayChunks.recordingId, recording.id),
+        inArray(schema.sessionReplayChunks.seq, seqs),
+      ),
+    )
+    .orderBy(asc(schema.sessionReplayChunks.seq));
+
+  const declaredBytes = rows.reduce(
+    (total: number, row: any) => total + Math.max(0, Number(row.byteLength)),
+    0,
+  );
+  if (declaredBytes > MAX_REPLAY_CHUNK_READ_BATCH_BYTES) {
+    throw replayError(
+      `Replay chunk batches must be ${MAX_REPLAY_CHUNK_READ_BATCH_BYTES} bytes or smaller`,
+      413,
+    );
+  }
+
+  const rowBySeq = new Map<number, any>(
+    rows.map((row: any) => [Number(row.seq), row]),
+  );
+  const chunks = new Array<SessionReplayChunkBatchItem>(seqs.length);
+  let nextIndex = 0;
+
+  async function worker(): Promise<void> {
+    while (nextIndex < seqs.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const seq = seqs[index];
+      const row = rowBySeq.get(seq);
+      chunks[index] = row
+        ? await readReplayChunkBatchRow(recording, row)
+        : unavailableReplayChunkBatchItem(seq);
+    }
+  }
+
+  await Promise.all(
+    Array.from(
+      {
+        length: Math.min(REPLAY_CHUNK_READ_CONCURRENCY, seqs.length),
+      },
+      worker,
+    ),
+  );
+
+  const result = {
+    chunks,
+    unavailableChunks: chunks.filter((chunk) => chunk.unavailable).length,
+  };
+  if (
+    Buffer.byteLength(JSON.stringify(result), "utf8") >
+    MAX_REPLAY_CHUNK_READ_BATCH_BYTES
+  ) {
+    throw replayError(
+      `Replay chunk batch responses must be ${MAX_REPLAY_CHUNK_READ_BATCH_BYTES} bytes or smaller`,
+      413,
+    );
+  }
+  return result;
+}
+
+export async function readSessionReplayChunkBatch(
+  recordingId: string,
+  seqs: number[],
+  scope: SessionReplayScope,
+): Promise<SessionReplayChunkBatchResult> {
+  const recording = await getSessionReplaySummary(recordingId, scope);
+  return readSessionReplayChunkBatchForRecording(recording, seqs);
+}
+
+export async function readSessionReplayTokenizedChunkBatch(
+  recordingId: string,
+  seqs: number[],
+): Promise<SessionReplayChunkBatchResult> {
+  const recording = await getSessionReplayTokenizedSummary(recordingId);
+  return readSessionReplayChunkBatchForRecording(recording, seqs);
+}
+
 export async function getSessionReplayEvents(
   recordingId: string,
   scope: SessionReplayScope,

package/corpus/templates/analytics/server/plugins/onboarding.ts

@@ -1,24 +1,17 @@
 /**
  * Custom onboarding plugin for Analytics.
  *
- * Overrides the framework's default onboarding plugin to add an optional
- * "Session replay storage" step and register the S3 file upload provider. Must
- * live in server/plugins/ so the framework skips its default onboarding plugin,
- * and all registrations share the same module context as the onboarding route
- * handlers (which read from the same in-memory Map).
- *
- * The step is `required: false` because session replay is opt-in: capturing
- * replays only matters once a site embeds the tracking SDK with replay enabled,
- * so we surface storage setup without forcing it into the onboarding checklist.
+ * Overrides the framework's default onboarding plugin to register the S3 file
+ * upload provider. Must live in server/plugins/ so the framework skips its
+ * default onboarding plugin, and all registrations share the same module
+ * context as the onboarding route handlers (which read from the same in-memory
+ * Map). Analytics only needs storage when someone enables session replay, so
+ * replay setup lives with that workflow instead of onboarding.
  */
 
 import { registerFileUploadProvider } from "@agent-native/core/file-upload";
-import {
-  createOnboardingPlugin,
-  registerOnboardingStep,
-} from "@agent-native/core/onboarding";
+import { createOnboardingPlugin } from "@agent-native/core/onboarding";
 
-import { hasRequestReplayStorage } from "../lib/replay-storage.js";
 import { s3FileUploadProvider } from "../lib/s3-upload-provider.js";
 
 const basePlugin = createOnboardingPlugin();
@@ -29,69 +22,4 @@ export default async (nitroApp: any): Promise<void> => {
 
   // Register S3-compatible file upload provider for session-replay chunks.
   registerFileUploadProvider(s3FileUploadProvider);
-
-  // Add the optional "Session replay storage" onboarding step.
-  registerOnboardingStep({
-    id: "replay-storage",
-    order: 15,
-    required: false,
-    title: "Session replay storage",
-    description:
-      "Store session replay recordings with Builder.io or S3-compatible storage.",
-    methods: [
-      {
-        id: "builder",
-        kind: "builder-cli-auth",
-        label: "Connect Builder.io",
-        description:
-          "Builder.io's free tier includes object storage for replay chunks.",
-        primary: true,
-        badge: "free",
-        payload: { scope: "browser" },
-      },
-      {
-        id: "s3",
-        kind: "form",
-        label: "Use S3-compatible storage",
-        description:
-          "AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, or any S3-compatible service.",
-        payload: {
-          writeScope: "workspace",
-          fields: [
-            {
-              key: "S3_ENDPOINT",
-              label: "Endpoint URL",
-              placeholder: "https://s3.us-east-1.amazonaws.com",
-            },
-            {
-              key: "S3_BUCKET",
-              label: "Bucket name",
-              placeholder: "my-replays-bucket",
-            },
-            {
-              key: "S3_ACCESS_KEY_ID",
-              label: "Access key ID",
-              placeholder: "AKIA...",
-            },
-            {
-              key: "S3_SECRET_ACCESS_KEY",
-              label: "Secret access key",
-              secret: true,
-            },
-            {
-              key: "S3_REGION",
-              label: "Region (optional)",
-              placeholder: "us-east-1",
-            },
-            {
-              key: "S3_PUBLIC_BASE_URL",
-              label: "Public base URL (optional)",
-              placeholder: "https://cdn.example.com",
-            },
-          ],
-        },
-      },
-    ],
-    isComplete: hasRequestReplayStorage,
-  });
 };

package/corpus/templates/analytics/server/routes/api/session-replay/recordings/[recordingId]/chunks.get.ts

@@ -0,0 +1 @@
+export { handleSessionReplayChunkBatch as default } from "../../../../../handlers/session-replay";

package/corpus/templates/assets/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/assets/app/global.css

@@ -257,14 +257,14 @@
   [data-agent-empty-state="centered"]
   .agent-composer-area {
   width: 100%;
-  max-width: min(760px, 90%);
+  max-width: min(570px, 90%);
   padding: 0;
 }
 
 .assets-create-chat-panel
   [data-agent-empty-state="centered"]
   .agent-composer-root {
-  min-height: 10.5rem;
+  min-height: 7.875rem;
   border-color: hsl(var(--border));
   border-radius: 1rem;
   background: hsl(var(--card));
@@ -274,7 +274,7 @@
 .assets-create-chat-panel
   [data-agent-empty-state="centered"]
   .agent-composer-prosemirror {
-  min-height: 6.75rem;
+  min-height: 5.0625rem;
   font-size: 1rem;
   line-height: 1.625rem;
 }
@@ -305,6 +305,6 @@
   .assets-create-chat-panel
     [data-agent-empty-state="centered"]
     .agent-composer-root {
-    min-height: 9rem;
+    min-height: 6.75rem;
   }
 }

package/corpus/templates/assets/app/routes/brand-kits.$id.tsx

@@ -429,7 +429,6 @@ export function BrandKitDetailRoute({
         signal,
       });
     },
-    refetchInterval: 1000,
   });
 
   useEffect(() => {

package/corpus/templates/assets/app/routes/library.tsx

@@ -1617,7 +1617,6 @@ function LibraryCandidateStage({
         { signal },
       );
     },
-    refetchInterval: 1000,
   });
   const isAllAssetsStage = !activeLibraryId;
   const liveLibraryId = activeLibraryId ?? variants?.libraryId ?? null;

package/corpus/templates/brain/.agents/skills/real-time-sync/SKILL.md

@@ -30,7 +30,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
    useDbSync({ queryClient });
    ```
 
-   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries for ordinary domain events — that caused a request storm in production. The exception is `source: "action"`: a successful mutating action is the framework-wide "agent changed app data" signal, so `useDbSync` also refreshes active React Query observers as a compatibility safety net for custom apps that have not yet moved every read to `useActionQuery` or source-versioned query keys.
+   For each non-own event, `useDbSync` bumps a per-source counter (e.g. `dashboards`, `analyses`, `settings`, `action`) and invalidates a small fixed list of framework-internal prefixes (`["action"]`, `["app-state"]`, `["__set_url__"]`, etc.). It does **not** blanket-invalidate templates' own data queries — that caused request storms in production. A successful mutating action refreshes active `useActionQuery` observers under the `["action"]` prefix. Browser actions carry a tab id so their originating tab ignores the sync echo while other tabs refresh. Legacy apps can opt into broader compatibility with `actionInvalidatePredicate`, but first-party apps should use action-backed or source-versioned query keys. Idle fallback polling runs once per minute; active agent work temporarily uses the faster cadence.
 
 3. **Templates fold per-source counters into their query keys.** This is the pattern that makes "agent writes show up without a manual refresh" reliable:
 
@@ -117,7 +117,7 @@ useQuery({
 | UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Does the affected query have an active observer?         |
 | Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
 | SSE not connecting                 | Is `/_agent-native/events` accessible and authenticated? Polling should still keep the UI fresh as fallback.   |
-| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries to debounce refetches.                                |
+| High CPU / event storms            | Use targeted source keys, settle bursty list counters, and avoid broad action invalidation.                   |
 
 ## Jitter Prevention
 

package/corpus/templates/brain/app/global.css

@@ -135,7 +135,7 @@
 .brain-chat-panel [data-agent-empty-state="centered"] .brain-chat-intro {
   display: grid;
   width: 100%;
-  max-width: min(760px, 90%);
+  max-width: min(570px, 90%);
   gap: 0.5rem;
   margin: 0 auto 1rem;
   text-align: center;
@@ -165,12 +165,12 @@
 
 .brain-chat-panel [data-agent-empty-state="centered"] .agent-composer-area {
   width: 100%;
-  max-width: min(760px, 90%);
+  max-width: min(570px, 90%);
   padding: 0;
 }
 
 .brain-chat-panel [data-agent-empty-state="centered"] .agent-composer-root {
-  min-height: 10.5rem;
+  min-height: 7.875rem;
   border-color: hsl(var(--border));
   border-radius: 1rem;
   background: hsl(var(--card));
@@ -187,7 +187,7 @@
 .brain-chat-panel
   [data-agent-empty-state="centered"]
   .agent-composer-prosemirror {
-  min-height: 6.75rem;
+  min-height: 5.0625rem;
   font-size: 1rem;
   line-height: 1.625rem;
 }
@@ -212,6 +212,6 @@
   }
 
   .brain-chat-panel [data-agent-empty-state="centered"] .agent-composer-root {
-    min-height: 9rem;
+    min-height: 6.75rem;
   }
 }

package/corpus/templates/brain/app/root.tsx

@@ -204,9 +204,6 @@ export default function Root() {
           // Brain has a faster sync cadence for source distillation status;
           // 20 s keeps the source list fresh without hammering the server.
           staleTime: 20_000,
-          // Brain shows live ingestion progress — refetch on focus to pick
-          // up background sync jobs that don't emit DB events.
-          refetchOnWindowFocus: true,
           // Flat retry: Brain data fetches are rarely auth failures so a
           // flat count is sufficient.
           retry: 1,