@agent-native/core 0.90.1 → 0.90.2

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 2089
-- template files: 4676
+- template files: 4797

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @agent-native/core
 
+## 0.90.2
+
+### Patch Changes
+
+- 74d3e5a: Prevent client fetch storms during high-volume background mutations: `useActionMutation` accepts `skipActionQueryInvalidation` so background mutations can perform narrow invalidation instead of refetching every action query, `useDbSync` accepts `suppressActionInvalidationFor` to skip whole-action-cache invalidation for named high-volume action sync events, and action-query retries are bounded to one attempt for network-level failures (Chrome reports connection-pool exhaustion as a generic fetch failure, so unbounded retries sustained the storm).
+- 16f7429: Defer collaborative rich-markdown seed writes to a timer task so initial Y.Doc seeding does not call `setContent` from React lifecycle.
+- 254f061: Defer agent-authored URL navigation out of React effects to avoid lifecycle flushSync warnings.
+- 69e1e38: Defer collaborative awareness presence updates so editor creation does not trigger React render-time state warnings.
+- 8976a28: Log framework route failures with route, status, message, and development stacks before returning JSON errors.
+- d61ca0c: The collaborative reconcile applies external content on a timer task instead of a microtask, so `setContent` can no longer run inside a React lifecycle flush ("flushSync was called from inside a lifecycle method" console errors during collab reconciliation).
+- 66ffcd9: Treat client-aborted framework route requests as disconnects instead of logging and returning 500 errors.
+- a74a885: `useDbSync` batches consisting entirely of suppressed action events (via `suppressActionInvalidationFor`) now skip the fixed framework invalidation list (extension, slot, tool, and app-state keys) as well as the whole-action-cache invalidation — high-volume background mutations no longer refetch framework queries on every poll tick. Events are still forwarded to `onEvent` and per-source change versions still bump.
+- d44ad4e: Concurrent top-level async transactions on the better-sqlite3 driver are serialized per connection. Previously a transaction starting while another was open saw `inTransaction` and opened a savepoint inside the other task's transaction, which then committed out from under it ("no such savepoint" 500s under concurrent reads/writes). Same-task nesting is detected via AsyncLocalStorage and keeps the direct savepoint path.
+
 ## 0.90.1
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.90.1",
+  "version": "0.90.2",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/client/AgentPanel.tsx

@@ -2154,7 +2154,7 @@ function URLSync({ browserTabId }: { browserTabId?: string }) {
       // Replace rather than push so repeated agent URL updates don't
       // clutter the history stack and can't trigger extra remounts from
       // router navigation lifecycle.
-      navigate(url, { replace: true, flushSync: true });
+      window.setTimeout(() => navigate(url, { replace: true }), 0);
     } catch {
       // Malformed command — ignore.
     }

package/corpus/core/src/client/rich-markdown-editor/useCollabReconcile.ts

@@ -307,15 +307,17 @@ export function useCollabReconcile({
     // Seed only when the shared doc is genuinely empty — either the fragment has
     // no nodes yet, or it holds no semantic markdown (an empty paragraph, or an
     // app's sentinel-empty filler via a custom `shouldSeed`).
-    seededRef.current = true;
     if (
       !shouldSeed({ value, currentMarkdown, fragmentLength: fragment.length })
     ) {
+      seededRef.current = true;
       return;
     }
 
     let cancelled = false;
-    queueMicrotask(() => {
+    // Defer via a timer task (NOT a microtask — microtasks can still run
+    // inside React's commit and trigger flushSync-from-lifecycle warnings).
+    const seedTimer = setTimeout(() => {
       if (cancelled || editor.isDestroyed) return;
       isSettingContentRef.current = true;
       try {
@@ -329,9 +331,11 @@ export function useCollabReconcile({
       lastAppliedValueRef.current = value;
       lastAppliedSerializedRef.current = serialized;
       if (contentUpdatedAt) lastAppliedUpdatedAtRef.current = contentUpdatedAt;
-    });
+      seededRef.current = true;
+    }, 0);
     return () => {
       cancelled = true;
+      clearTimeout(seedTimer);
     };
   }, [
     collab,
@@ -466,10 +470,10 @@ export function useCollabReconcile({
         return;
       }
 
-      queueMicrotask(() => {
+      const applyTimer = setTimeout(() => {
         if (cancelled || editor.isDestroyed) return;
         // Re-check doc-equivalence at apply time. Between the decision above and
-        // this microtask a peer/Yjs edit (or our own prior apply) may have made
+        // this task a peer/Yjs edit (or our own prior apply) may have made
         // the editor already represent this value — re-applying would be a
         // wasted setContent that, for non-idempotent input, re-triggers the
         // loop. Skip when the editor's current serialization already matches the
@@ -521,7 +525,8 @@ export function useCollabReconcile({
         if (contentUpdatedAt) {
           lastAppliedUpdatedAtRef.current = contentUpdatedAt;
         }
-      });
+      }, 0);
+      retry = applyTimer;
     };
 
     apply();

package/corpus/core/src/client/use-action.ts

@@ -68,9 +68,41 @@ export function defaultActionQueryRetry(
   // A timeout already made the user wait the full timeout window once;
   // silently retrying would multiply that wait. Surface it instead.
   if (isActionTimeout(error)) return false;
+  if (isBrowserResourceExhaustion(error)) return false;
+  // Network-level failures never carry an HTTP `status` (actionFetch only
+  // sets it after a response arrives). Chrome reports connection-pool
+  // exhaustion (net::ERR_INSUFFICIENT_RESOURCES) as a generic "Failed to
+  // fetch", indistinguishable from a transient blip — allow one retry, not
+  // three, so an exhausted tab cannot sustain its own fetch storm.
+  if (isNetworkLevelFailure(error)) return failureCount < 1;
   return failureCount < 3;
 }
 
+/** @internal alias kept for existing specs. */
+export const shouldRetryActionQueryForError = defaultActionQueryRetry;
+
+function isBrowserResourceExhaustion(error: unknown): boolean {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : "";
+  return /ERR_INSUFFICIENT_RESOURCES|insufficient resources/i.test(message);
+}
+
+function isNetworkLevelFailure(error: unknown): boolean {
+  // Match the exact shape actionFetch produces for fetch-level failures (its
+  // catch wraps the cause as "Action <name> failed: <cause>" and never sets a
+  // status). Other status-less errors (test doubles, transport internals)
+  // keep the standard three-retry policy.
+  return (
+    error instanceof Error &&
+    (error as { status?: unknown }).status === undefined &&
+    /^Action .+ failed: /.test(error.message)
+  );
+}
+
 /**
  * Default retry backoff for action queries. React Query's stock retryDelay
  * (1s → 2s → 4s) makes a failing query sit on a spinner for ~7s before the
@@ -436,12 +468,14 @@ export function useActionMutation<
     "mutationFn"
   > & {
     method?: "POST" | "PUT" | "DELETE";
+    skipActionQueryInvalidation?: boolean;
   },
 ) {
   const queryClient = useQueryClient();
   const {
     method: methodOpt,
     onSuccess,
+    skipActionQueryInvalidation = false,
     ...restOptions
   } = options ?? ({} as any);
   const method = methodOpt ?? "POST";
@@ -454,8 +488,11 @@ export function useActionMutation<
     mutationFn: (params) =>
       actionFetch<D>(actionName, method, params as Record<string, any>),
     onSuccess: (...args: [any, any, any]) => {
-      // Invalidate related action queries
-      queryClient.invalidateQueries({ queryKey: ["action"] });
+      // Most mutations change app data broadly. High-volume background
+      // mutations can opt out and perform narrower invalidation in onSuccess.
+      if (!skipActionQueryInvalidation) {
+        queryClient.invalidateQueries({ queryKey: ["action"] });
+      }
       (onSuccess as Function)?.(...args);
     },
   });

package/corpus/core/src/client/use-db-sync.ts

@@ -561,6 +561,9 @@ export function subscribeSyncEvents(
  *   compatibility invalidate triggered by `action` events. Use this to keep
  *   expensive active queries on explicit-refresh semantics while still letting
  *   normal source-versioned queries react through `useChangeVersion`.
+ * @param options.suppressActionInvalidationFor - Action names whose sync events
+ *   should not invalidate all action queries. Use only for high-volume
+ *   background actions that perform their own narrow client invalidation.
  */
 export function useDbSync(
   options: {
@@ -576,6 +579,7 @@ export function useDbSync(
     pauseWhenHidden?: boolean;
     ignoreSource?: string;
     actionInvalidatePredicate?: (query: Query) => boolean;
+    suppressActionInvalidationFor?: string[];
   } = {},
 ): void {
   const {
@@ -599,6 +603,11 @@ export function useDbSync(
     options.actionInvalidatePredicate,
   );
   actionInvalidatePredicateRef.current = options.actionInvalidatePredicate;
+  const suppressActionInvalidationForRef = useRef(
+    options.suppressActionInvalidationFor,
+  );
+  suppressActionInvalidationForRef.current =
+    options.suppressActionInvalidationFor;
 
   useEffect(() => {
     const id = Symbol("useDbSync");
@@ -621,6 +630,18 @@ export function useDbSync(
       const relevant = ignore
         ? events.filter((e) => e.requestSource !== ignore)
         : events;
+      const suppressedActions = new Set(
+        suppressActionInvalidationForRef.current ?? [],
+      );
+      const isSuppressedActionEvent = (evt: SyncEvent) =>
+        evt.source === "action" &&
+        typeof evt.key === "string" &&
+        suppressedActions.has(evt.key);
+      const nonAwareness = relevant.filter((e) => e.source !== "awareness");
+      const suppressesWholeBatch =
+        nonAwareness.length > 0 &&
+        nonAwareness.every((evt) => evt.source === "action") &&
+        nonAwareness.every(isSuppressedActionEvent);
 
       // Bump per-source change counters. Components that read these via
       // `useChangeVersion(source)` and fold the value into a React Query
@@ -642,7 +663,7 @@ export function useDbSync(
 
       if (invalidating.length > 0 && queryClient) {
         const hasActionEvent = invalidating.some(
-          (evt) => evt.source === "action",
+          (evt) => evt.source === "action" && !isSuppressedActionEvent(evt),
         );
         if (hasActionEvent) {
           // Custom apps frequently start with raw `useQuery` calls before
@@ -661,23 +682,28 @@ export function useDbSync(
         // etc.). Templates' own data queries do NOT live here — they react
         // through `useChangeVersion(source)` in their query keys instead, so
         // a single change event doesn't fan out into "refetch everything".
-        queryClient.invalidateQueries({ queryKey: ["action"] });
-        queryClient.invalidateQueries({ queryKey: ["extension"] });
-        queryClient.invalidateQueries({ queryKey: ["extensions"] });
-        queryClient.invalidateQueries({ queryKey: ["extension-slots"] });
-        queryClient.invalidateQueries({ queryKey: ["slot-installs"] });
-        queryClient.invalidateQueries({ queryKey: ["slot-available"] });
-        queryClient.invalidateQueries({ queryKey: ["tool"] });
-        queryClient.invalidateQueries({ queryKey: ["tools"] });
-        queryClient.invalidateQueries({ queryKey: ["app-state"] });
-        if (hasAppStateEvent(invalidating, "navigate")) {
-          queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
-        }
-        if (hasAppStateEvent(invalidating, "show-questions")) {
-          queryClient.invalidateQueries({ queryKey: ["show-questions"] });
-        }
-        if (hasAppStateEvent(invalidating, "__set_url__")) {
-          queryClient.invalidateQueries({ queryKey: ["__set_url__"] });
+        // Suppressed-action-only batches skip this whole list (their
+        // mutations perform their own narrow invalidation) — but events must
+        // STILL reach the onEvent forwarding below, so guard, don't return.
+        if (!suppressesWholeBatch) {
+          queryClient.invalidateQueries({ queryKey: ["action"] });
+          queryClient.invalidateQueries({ queryKey: ["extension"] });
+          queryClient.invalidateQueries({ queryKey: ["extensions"] });
+          queryClient.invalidateQueries({ queryKey: ["extension-slots"] });
+          queryClient.invalidateQueries({ queryKey: ["slot-installs"] });
+          queryClient.invalidateQueries({ queryKey: ["slot-available"] });
+          queryClient.invalidateQueries({ queryKey: ["tool"] });
+          queryClient.invalidateQueries({ queryKey: ["tools"] });
+          queryClient.invalidateQueries({ queryKey: ["app-state"] });
+          if (hasAppStateEvent(invalidating, "navigate")) {
+            queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
+          }
+          if (hasAppStateEvent(invalidating, "show-questions")) {
+            queryClient.invalidateQueries({ queryKey: ["show-questions"] });
+          }
+          if (hasAppStateEvent(invalidating, "__set_url__")) {
+            queryClient.invalidateQueries({ queryKey: ["__set_url__"] });
+          }
         }
       }
 

package/corpus/core/src/db/create-get-db.ts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
 import { drizzle as drizzleD1 } from "drizzle-orm/d1";
 import type { LibSQLDatabase } from "drizzle-orm/libsql";
 
@@ -320,15 +322,26 @@ function getBetterSqliteDrizzle() {
  * The patched transaction also patches the tx object it passes to the callback
  * so that nested async calls (tx.transaction(async …)) work recursively.
  */
-function patchBetterSqliteTransactions<
+/** @internal exported for the async-tx concurrency spec */
+export function patchBetterSqliteTransactions<
   DB extends { transaction: (...args: any[]) => any; session: any },
 >(db: DB, sqlite: { inTransaction: boolean; exec: (sql: string) => void }): DB {
   let savepointSeq = 0;
+  // Concurrent TOP-LEVEL async transactions on the single better-sqlite3
+  // connection must not interleave: a second transaction starting while the
+  // first is open would see `inTransaction` and open a savepoint INSIDE the
+  // first transaction, which then commits out from under it ("no such
+  // savepoint"). Serialize top-level transactions through a promise chain;
+  // genuine same-task nesting (tx.transaction or db.transaction inside an
+  // open callback) is detected via AsyncLocalStorage and keeps the direct
+  // savepoint path so it cannot deadlock on the queue.
+  const txContext = new AsyncLocalStorage<boolean>();
+  let txChain: Promise<unknown> = Promise.resolve();
 
   function makeAsyncTransaction(
     originalTransaction: (...args: any[]) => any,
   ): (...args: any[]) => Promise<unknown> {
-    return async function asyncTransaction(
+    async function runTransactionBody(
       cb: (tx: unknown) => unknown,
     ): Promise<unknown> {
       // Extract the drizzle tx proxy synchronously — call the original with a
@@ -392,6 +405,23 @@ function patchBetterSqliteTransactions<
         }
         throw err;
       }
+    }
+
+    return function asyncTransaction(
+      cb: (tx: unknown) => unknown,
+    ): Promise<unknown> {
+      if (txContext.getStore()) {
+        // Same-task nesting: run directly (savepoint path inside the open
+        // transaction). Queueing here would deadlock behind the outer tx.
+        return runTransactionBody(cb);
+      }
+      const run = () => txContext.run(true, () => runTransactionBody(cb));
+      const next = txChain.then(run, run);
+      txChain = next.then(
+        () => undefined,
+        () => undefined,
+      );
+      return next;
     };
   }
 

package/corpus/core/src/server/framework-request-handler.ts

@@ -364,6 +364,48 @@ function installPluginReadyPlaceholders(
   }
 }
 
+function logFrameworkRouteError(args: {
+  method: string | undefined;
+  route: string;
+  status: number;
+  error: unknown;
+}): void {
+  const error = args.error as any;
+  const message = error?.message || String(args.error);
+  const prefix = `[agent-native] ${args.method ?? ""} ${args.route} failed (${args.status})`;
+  if (process.env.NODE_ENV === "production") {
+    console.error(`${prefix}: ${message}`);
+    return;
+  }
+  console.error(`${prefix}: ${message}`, error?.stack || args.error);
+}
+
+function isClientAbortError(error: unknown, event: H3Event): boolean {
+  const err = error as any;
+  const message = typeof err?.message === "string" ? err.message : "";
+  const code = typeof err?.code === "string" ? err.code : "";
+  const node = (event as any).node;
+  return (
+    message === "aborted" ||
+    code === "ECONNRESET" ||
+    node?.req?.destroyed === true ||
+    node?.res?.destroyed === true
+  );
+}
+
+function debugClientAbort(args: {
+  method: string | undefined;
+  route: string;
+  error: unknown;
+}): void {
+  if (process.env.NODE_ENV === "production") return;
+  const err = args.error as any;
+  const message = err?.message || String(args.error);
+  console.debug?.(
+    `[agent-native] ${args.method ?? ""} ${args.route} aborted by client: ${message}`,
+  );
+}
+
 /**
  * Await all tracked plugin initializations. Called by the readiness gate
  * middleware before dispatching framework routes.
@@ -500,10 +542,16 @@ function registerMiddleware(
           : typeof e?.status === "number"
             ? e.status
             : 500;
-      console.error(
-        `[agent-native] ${event.method ?? ""} ${reqPath} failed (${status}):`,
-        e?.stack || e?.message || e,
-      );
+      if (isClientAbortError(err, event)) {
+        debugClientAbort({ method: event.method, route: reqPath, error: err });
+        return undefined;
+      }
+      logFrameworkRouteError({
+        method: event.method,
+        route: reqPath,
+        status,
+        error: err,
+      });
       // Forward 5xx to server-side Sentry — Nitro's own `error` hook may not
       // fire here because we convert the throw into a normal JSON response,
       // and a console.error alone is invisible in deployed environments.

package/corpus/templates/assets/.agents/skills/asset-generation/SKILL.md

@@ -73,6 +73,11 @@ or generated image/video assets that another app can reference by ID and URL.
    `assets.metadata.isStyleAnchor`.
 6. Pass `tier: "fast"` for exploration, `tier: "best"` for final/high-value
    output, or `tier: "auto"` when there is no clear preference.
+   - Model/ratio compatibility: Gemini image models accept any `aspectRatio`, but
+     `gpt-image-2` supports only `1:1`, `2:3`, and `3:2`. When the user needs
+     another ratio (16:9, 9:16, 4:5, 21:9, …), pick a Gemini model rather than
+     `gpt-image-2` — an unsupported pairing is rejected upstream. Source of truth
+     is `supportedAspectRatiosForModel` / `MODEL_ASPECT_RATIOS` in `shared/api.ts`.
 7. Preserve returned `assetId`, `runId`, `previewUrl`, and `downloadUrl`.
 8. Use `refine-image` for feedback on an existing asset, `edit-image` for
    targeted changes, and `restyle-image` with `subjectAssetId` and

package/corpus/templates/assets/.agents/skills/logo-composite/SKILL.md

@@ -11,11 +11,39 @@ LLMs — including Gemini Pro — degrade complex logos. They smear gradients, d
 
 1. The library has a `canonicalLogoUrl` (set via `set-canonical-logo --libraryId --assetId`). The asset's role is `logo_reference`.
 2. **Logo compositing is a preset option.** A generation preset carries `includeLogo` (stored in the preset `settings` and surfaced as a first-class field). When a generation resolves to a preset with `includeLogo: true`, `generate-image` composites the logo. A generate call's own `includeLogo` arg, when passed, overrides the preset for that run; when omitted, the preset's value wins.
-3. When logo compositing is on, the prompt envelope adds:
+3. **Preset skeletons generalize logo compositing.** A preset can also carry `settings.skeletonSpec`: background first, generated subject second, foreground layers last. If the skeleton already has a `foreground` layer with `source: "canonicalLogo"`, `includeLogo` is treated as a no-op for that run so the logo is not stamped twice. If the skeleton does not include the logo and `includeLogo` is true, the existing canonical-logo layer is appended at the default upper-right position during compositing.
+4. When logo compositing is on, the prompt envelope adds:
    > Leave a clean uncluttered area in the upper-right for the real brand logo; do not draw or approximate the logo yourself.
-4. Gemini returns an image with empty space in that corner.
-5. `compositeLogo()` from `server/lib/image-processing.ts` (Sharp) loads the canonical logo PNG / SVG, resizes it to ~16% of the image width with reasonable inset, and composites it onto the generated image.
-6. Output: the image with the actual logo, pixel-perfect, vector-quality if the source is SVG.
+5. Gemini returns an image with empty space in that corner.
+6. `compositeLogo()` from `server/lib/image-processing.ts` (Sharp) loads the canonical logo PNG / SVG, resizes it to ~16% of the image width with reasonable inset, and composites it onto the generated image. Skeleton runs use `applyPresetSkeleton()` at the same seam.
+7. Output: the image with the actual logo, pixel-perfect, vector-quality if the source is SVG.
+
+## Preset skeletons
+
+`settings.skeletonSpec` is the prototype storage shape:
+
+```ts
+{
+  background: { type: "asset"; assetId: string };
+  mask?: { type: "asset"; assetId: string };
+  contentMode: "fill" | "cutout";
+  contentRegion?: { x: number; y: number; w: number; h: number };
+  dropShadow?: boolean;
+  foreground?: Array<{
+    source: "canonicalLogo" | { assetId: string };
+    x: number;
+    y: number;
+    w: number;
+  }>;
+}
+```
+
+- The background is an uploaded or selected brand-library image asset. The compositor cover-fits it to the preset canvas and throws if the asset pixels are unavailable.
+- `fill` drops an opaque generation into the content region, so it works through the normal managed provider path.
+- When the resolved skeleton model is `gpt-image-2`, the action sends a managed edit/inpaint request instead of generate-then-composite: the uploaded plate is the `edit_target`, an optional same-size `mask` asset becomes the editable-area mask, and `maskFromPlateAlpha()` is only the fallback when no manual mask is set. Transparent mask pixels are editable, opaque pixels are sent as preserved regions, and the returned image is final. The manual mask or plate fallback must have transparent pixels.
+- Other `cutout` skeletons ask for an isolated transparent subject, force `gpt-image-1`, attach the background plate as a `background_reference`/composition reference, request `background: "transparent"` through the managed Builder image provider, and only fall back to OpenAI BYOK when the managed provider fails. They clamp only the provider subject ratio to `1:1`, `2:3`, or `3:2`. The final skeleton canvas still uses the preset's requested aspect ratio.
+- The prompt envelope for cutout mode asks for an isolated subject on an empty transparent background. The gpt-image-2 inpaint branch instead asks the model to render the requested foreground content inside the mask's transparent/open region while preserving logos, text, framing, and other opaque plate content.
+- Background and foreground `assetId` values must belong to the selected brand kit and must be images.
 
 ## When to use it
 
@@ -26,8 +54,8 @@ LLMs — including Gemini Pro — degrade complex logos. They smear gradients, d
 ## When NOT to use it
 
 - **Logo on a product** (a t-shirt mockup, a billboard scene, a coffee cup).
-  Compositing onto a flat corner is fine; compositing onto a curved or perspective surface needs mask-based inpainting that Gemini doesn't expose. v2 will use OpenAI `gpt-image-1`'s edit API for this. v1: tell the user to mock that up in design.
-- **Multi-logo scenes** (a partner-logo wall, a footer sponsor row). Same reason. v2.
+  Compositing onto a flat corner is fine; compositing onto a curved or perspective surface needs mask-based inpainting. Use a gpt-image-2 skeleton plate with transparent editable regions when that exact layout is required.
+- **Multi-logo scenes** (a partner-logo wall, a footer sponsor row). Same reason: use a prepared plate plus mask-inpaint skeleton, or ask the user to mock it up in design.
 
 ## Setting a canonical logo
 

package/corpus/templates/assets/AGENTS.md

@@ -43,10 +43,11 @@ prompt, aspectRatio }`.
   `brand-kit` references to `libraryId`, `preset` references to `presetId`, and
   `media-type` references to choosing image (`generate-image` /
   `generate-image-batch`) or video (`generate-video`) generation. The current
-  library view auto-tags its brand kit as a visible removable chip when the
-  composer is empty. The image model is the only remaining composer-side
-  default; the image-model picker writes `imageGenerationModel`, which image
-  generation actions may use when `model` is omitted.
+  library view auto-tags its brand kit as a visible removable chip, and the
+  generation preset editor auto-tags both its brand kit and preset. The image
+  model is the only remaining composer-side default; the image-model picker
+  writes `imageGenerationModel`, which image generation actions may use when
+  `model` is omitted.
 - When a `preset` is tagged, the server embeds that preset's aesthetics and
   creative philosophy (brand style brief, prompt template, text/logo policy,
   output format) into your message inside a `<tagged-generation-presets>` block.
@@ -66,6 +67,24 @@ prompt, aspectRatio }`.
   model never draws the logo itself. Pass `includeLogo` on a generate call only
   to override the preset for that one run; otherwise omit it. See the
   `logo-composite` skill.
+- Preset skeletons live in `settings.skeletonSpec` on generation presets and
+  are edited from `/brand-kits/:libraryId/presets/:presetId`. They composite a
+  generated subject onto an uploaded brand background image and optional
+  foreground layers. When the resolved skeleton model is `gpt-image-2`, the
+  action uses managed mask inpainting: the uploaded plate is the edit source,
+  an optional same-size mask asset controls the editable area, and the plate's
+  alpha channel is used as the fallback mask when no manual mask is set. Opaque
+  mask pixels are sent as preserved regions, transparent mask pixels are
+  editable, and no local compositing runs. Other `cutout` skeletons force
+  `gpt-image-1`, request
+  transparent output through the managed Builder image provider, attach the
+  plate as a composition/background reference for layout awareness, clamp only
+  the provider subject ratio to a supported `gpt-image-1` ratio, and keep the
+  final skeleton canvas at the preset's requested ratio. See the
+  `logo-composite` skill.
+- Humans can edit an existing generation preset from
+  `/brand-kits/:libraryId/presets/:presetId`. Use `navigate` with
+  `{ view: "preset", libraryId, presetId }` when sending a user to that editor.
 - `asset-variants` is the shared live generation tray state. New image
   candidates should appear there through `generate-image` or
   `generate-image-batch`; do not invent page-local progress surfaces.

package/corpus/templates/assets/actions/_generation-preset-settings.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+const fractionSchema = z.coerce.number().min(0).max(1);
+const positiveFractionSchema = z.coerce.number().min(0.02).max(1);
+
+export const presetSkeletonSpecSchema = z.object({
+  background: z.object({
+    type: z.literal("asset"),
+    assetId: z.string().min(1),
+  }),
+  mask: z
+    .object({
+      type: z.literal("asset"),
+      assetId: z.string().min(1),
+    })
+    .optional(),
+  contentMode: z.enum(["cutout", "fill"]),
+  contentRegion: z
+    .object({
+      x: fractionSchema,
+      y: fractionSchema,
+      w: positiveFractionSchema,
+      h: positiveFractionSchema,
+    })
+    .optional(),
+  dropShadow: z.coerce.boolean().optional(),
+  foreground: z
+    .array(
+      z.object({
+        source: z.union([
+          z.literal("canonicalLogo"),
+          z.object({ assetId: z.string().min(1) }),
+        ]),
+        x: fractionSchema,
+        y: fractionSchema,
+        w: positiveFractionSchema,
+      }),
+    )
+    .max(8)
+    .optional(),
+});
+
+export const generationPresetSettingsSchema = z
+  .object({
+    includeLogo: z.coerce.boolean().optional(),
+    skeletonSpec: presetSkeletonSpecSchema.nullable().optional(),
+  })
+  .catchall(z.unknown());

package/corpus/templates/assets/actions/_helpers.ts

@@ -26,9 +26,14 @@ function accessContext(ctx?: AccessCtx) {
 }
 
 export async function requireLibrary(id: string, ctx?: AccessCtx) {
+  const access = await requireLibraryAccess(id, ctx);
+  return access.resource;
+}
+
+export async function requireLibraryAccess(id: string, ctx?: AccessCtx) {
   const access = await resolveAccess("asset-library", id, accessContext(ctx));
   if (!access) throw new Error("Asset library not found or not accessible.");
-  return access.resource;
+  return access;
 }
 
 export async function requireGenerationSessionInLibrary(
@@ -103,6 +108,7 @@ export function serializeLibrary(row: any) {
     canonicalLogoAssetId: row.canonicalLogoAssetId,
     coverAssetId: row.coverAssetId,
     visibility: row.visibility,
+    accessRole: typeof row.accessRole === "string" ? row.accessRole : undefined,
     archivedAt: row.archivedAt ?? null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
@@ -362,6 +368,7 @@ export function serializeAsset(
       row.mediaType ?? (row.mimeType?.startsWith("video/") ? "video" : "image"),
     role: row.role,
     status: row.status,
+    category: metadata.category ?? null,
     title: row.title,
     description: row.description ?? metadata.description ?? null,
     altText: row.altText,