@agent-native/core 0.90.1 → 0.90.3

package/corpus/templates/analytics/changelog/2026-07-07-session-replays-load-sooner-show-clearer-activity-timelines-.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-07-07
+---
+
+Session replays load sooner, show clearer activity timelines, and keep Dev Tools fast on large recordings.

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,

package/corpus/templates/assets/actions/_preset-skeleton-validation.ts

@@ -0,0 +1,64 @@
+import { inArray } from "drizzle-orm";
+
+import { schema } from "../server/db/index.js";
+
+export async function assertPresetSkeletonAssetsValid(input: {
+  db: any;
+  libraryId: string;
+  settings: unknown;
+}) {
+  const spec =
+    input.settings && typeof input.settings === "object"
+      ? (input.settings as { skeletonSpec?: unknown }).skeletonSpec
+      : null;
+  if (!spec || typeof spec !== "object") return;
+  const skeleton = spec as {
+    background?: { type?: unknown; assetId?: unknown };
+    mask?: { type?: unknown; assetId?: unknown };
+  };
+  const backgroundAssetId =
+    skeleton.background?.type === "asset" &&
+    typeof skeleton.background.assetId === "string"
+      ? skeleton.background.assetId
+      : "";
+  const maskAssetId =
+    skeleton.mask?.type === "asset" && typeof skeleton.mask.assetId === "string"
+      ? skeleton.mask.assetId
+      : "";
+  if (!backgroundAssetId || !maskAssetId) return;
+
+  const rows = await input.db
+    .select({
+      id: schema.assets.id,
+      libraryId: schema.assets.libraryId,
+      width: schema.assets.width,
+      height: schema.assets.height,
+    })
+    .from(schema.assets)
+    .where(inArray(schema.assets.id, [backgroundAssetId, maskAssetId]));
+  const background = rows.find((asset: any) => asset.id === backgroundAssetId);
+  const mask = rows.find((asset: any) => asset.id === maskAssetId);
+  if (
+    !background ||
+    !mask ||
+    background.libraryId !== input.libraryId ||
+    mask.libraryId !== input.libraryId
+  ) {
+    throw new Error(
+      "Skeleton image and mask must belong to this asset library.",
+    );
+  }
+  if (
+    typeof background.width !== "number" ||
+    typeof background.height !== "number" ||
+    typeof mask.width !== "number" ||
+    typeof mask.height !== "number"
+  ) {
+    return;
+  }
+  if (background.width !== mask.width || background.height !== mask.height) {
+    throw new Error(
+      "Skeleton inpainting mask must be the same pixel size as the background plate.",
+    );
+  }
+}

package/corpus/templates/assets/actions/create-generation-preset.ts

@@ -13,7 +13,9 @@ import {
   IMAGE_MODELS,
   IMAGE_SIZES,
 } from "../shared/api.js";
+import { generationPresetSettingsSchema } from "./_generation-preset-settings.js";
 import { serializeGenerationPreset } from "./_helpers.js";
+import { assertPresetSkeletonAssetsValid } from "./_preset-skeleton-validation.js";
 
 export default defineAction({
   description:
@@ -38,13 +40,14 @@ export default defineAction({
       .describe(
         "When true, images generated with this preset composite the library's canonical logo (no-op if the library has no canonical logo).",
       ),
-    settings: z.record(z.string(), z.unknown()).optional(),
+    settings: generationPresetSettingsSchema.optional(),
     sortOrder: z.coerce.number().optional(),
   }),
   run: async (args) => {
+    const db = getDb();
     await assertAccess("asset-library", args.libraryId, "editor");
     if (args.collectionId) {
-      const [collection] = await getDb()
+      const [collection] = await db
         .select()
         .from(schema.assetCollections)
         .where(eq(schema.assetCollections.id, args.collectionId))
@@ -53,6 +56,11 @@ export default defineAction({
         throw new Error("Collection does not belong to this asset library.");
       }
     }
+    await assertPresetSkeletonAssetsValid({
+      db,
+      libraryId: args.libraryId,
+      settings: args.settings,
+    });
     const now = nowIso();
     const row = {
       id: nanoid(),
@@ -78,7 +86,7 @@ export default defineAction({
       createdAt: now,
       updatedAt: now,
     };
-    await getDb().insert(schema.assetGenerationPresets).values(row);
+    await db.insert(schema.assetGenerationPresets).values(row);
     return serializeGenerationPreset(row);
   },
 });

package/corpus/templates/assets/actions/generate-image-batch.ts

@@ -62,7 +62,7 @@ export default defineAction({
             .enum(ASPECT_RATIOS)
             .optional()
             .describe(
-              "Slot aspect ratio. When a presetId is set, omit this — the preset's aspect ratio is used unless the user explicitly asks for a different ratio for this slot.",
+              "Slot aspect ratio. When a presetId is set, omit this — the preset's aspect ratio is used unless the user explicitly asks for a different ratio for this slot. Note: gpt-image-2 supports only 1:1, 2:3, and 3:2; use a Gemini model for other ratios.",
             ),
           imageSize: z.enum(IMAGE_SIZES).optional(),
           categories: z.array(z.enum(IMAGE_CATEGORIES)).optional(),
@@ -82,7 +82,12 @@ export default defineAction({
       .describe(
         "Internal UI state scope for live candidate slots. Usually omitted; embedded picker UIs pass a browser-tab scope.",
       ),
-    model: z.enum(IMAGE_MODELS).optional(),
+    model: z
+      .enum(IMAGE_MODELS)
+      .optional()
+      .describe(
+        "Image model applied to every slot. Omit to use the user's picker default. Gemini models accept any aspectRatio; gpt-image-2 supports ONLY 1:1, 2:3, and 3:2, so don't select it when any slot needs a different ratio — use a Gemini model instead.",
+      ),
     tier: z.enum(IMAGE_QUALITY_TIERS).optional(),
     intent: z.enum(GENERATION_INTENTS).default("generate"),
     styleStrength: z.enum(STYLE_STRENGTHS).default("balanced"),