@orangecatai/adgen-canvas 0.0.33 → 0.0.35

package/dist/types/excalidraw/utils/referenceBudget.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Ranked slot allocation for the reference images attached to an image
+ * generation request.
+ *
+ * ## Why this exists
+ *
+ * The previous rule was a single boolean: if the user attached ANY reference,
+ * the brand logo, both font specimens, and every host-injected brand asset were
+ * deleted. Unconditionally — no size check, no count check. That made
+ * "replace their logo with ours" unsatisfiable, because the logo the prompt
+ * asked for was never attached.
+ *
+ * The real constraint was never "brand assets compete with the user" — it is
+ * the host proxy's platform request cap (Vercel rejects bodies over 4.5 MB at
+ * the edge with an opaque 413). Competition is solved by ORDER and by the
+ * prompt's precedence rules, not by deletion.
+ *
+ * ## The contract
+ *
+ * Priority, highest first:
+ *
+ *   1. `user`        — references the user attached themselves (max 6)
+ *   2. `source`      — the image being edited or resized (quick edit, resize)
+ *   3. `logo`        — the brand logo
+ *   4. `brandAsset`  — product / lifestyle photos from the brand bank
+ *   5. `adReference` — existing ad creatives and template thumbnails
+ *
+ * Everything is sent when it fits. Truncation happens ONLY when the count or
+ * byte budget is exceeded, and always from the bottom up — never touching
+ * `user`, and never touching `logo` unless the caller marks it droppable
+ * (quick edit and resize, where the source image matters more).
+ *
+ * Brand assets and ad references degrade gracefully: surplus copies go first,
+ * so one of each survives as long as possible, and only then is a whole tier
+ * given up — ad references before brand assets, per the priority order.
+ *
+ * The floor is therefore 6 user references + the logo.
+ *
+ * ## Compression first, always
+ *
+ * Dropping a reference is the last resort, not the first. `prepareReferences`
+ * downscales everything, then escalates compression on the largest offenders,
+ * and only starts shedding slots if the payload is *still* over budget.
+ */
+/** Reference tiers in descending priority. Index === priority rank. */
+export declare const REFERENCE_TIERS: readonly ["user", "source", "logo", "brandAsset", "adReference"];
+export type ReferenceTier = typeof REFERENCE_TIERS[number];
+export interface ReferenceSlot {
+    tier: ReferenceTier;
+    /**
+     * The image itself. Empty string marks a *placeholder* — a slot the host
+     * proxy will fill from the brand database, which the SDK can only reserve
+     * room for because it never sees the bytes. `bytes` carries the reservation.
+     */
+    dataUrl: string;
+    /** Human label used in the reference manifest. */
+    label?: string;
+    /** Wire-byte estimate. Derived from `dataUrl` when omitted. */
+    bytes?: number;
+}
+export interface DroppedSlot {
+    tier: ReferenceTier;
+    label?: string;
+    reason: "count" | "bytes";
+}
+/**
+ * Hard cap on user-supplied reference images per generation. Six covers every
+ * realistic ad brief and keeps the request inside the limits of the models we
+ * route to.
+ */
+export declare const MAX_USER_REFERENCE_IMAGES = 6;
+/**
+ * Ceiling on total attached references. 6 user + 1 source + 1 logo + 2 brand
+ * assets + 2 ad references. Comfortably under the ~20 images-per-request cap
+ * observed on OpenRouter.
+ */
+export declare const MAX_REFERENCE_IMAGES = 12;
+/**
+ * Wire-byte budget for the attached images alone.
+ *
+ * Vercel rejects at 4.5 MB. This leaves ~1.3 MB of headroom for the prompt,
+ * the brand context block, and the JSON envelope — all of which the caller can
+ * further reserve against via `reservedBytes`.
+ */
+export declare const REFERENCE_WIRE_BUDGET_BYTES: number;
+/**
+ * What the SDK assumes a host-injected brand asset costs on the wire, and the
+ * ceiling the host compresses each one down to before injecting it. Keeping
+ * both sides on the same number is what makes the SDK's reservation honest.
+ */
+export declare const HOST_ASSET_BYTE_RESERVATION: number;
+/** Sort into priority order, stable within a tier. */
+export declare function orderByPriority(slots: ReferenceSlot[]): ReferenceSlot[];
+/**
+ * The order in which slots may be shed, first to go listed first.
+ *
+ * `user` and `source` never appear — they are the request. `logo` appears only
+ * when `protectLogo` is false, and always last, so it outlives every brand
+ * asset.
+ */
+export declare function shedOrder(slots: ReferenceSlot[], protectLogo: boolean): ReferenceSlot[];
+export interface AllocateOptions {
+    /** Count ceiling. Defaults to {@link MAX_REFERENCE_IMAGES}. */
+    maxImages?: number;
+    /** Byte ceiling for images. Defaults to {@link REFERENCE_WIRE_BUDGET_BYTES}. */
+    maxBytes?: number;
+    /** Non-image payload (prompt, schemas) to charge against `maxBytes`. */
+    reservedBytes?: number;
+    /**
+     * False on surfaces where the source image outranks the logo — quick edit and
+     * resize. On generate flows the logo is part of the protected core.
+     */
+    protectLogo?: boolean;
+}
+export interface Allocation {
+    kept: ReferenceSlot[];
+    dropped: DroppedSlot[];
+    bytes: number;
+    /**
+     * True when the protected core alone still exceeds the budget. The caller
+     * should send anyway — a 413 with the user's own images is a better failure
+     * than silently generating without them.
+     */
+    overBudget: boolean;
+}
+/**
+ * Pure allocation: order, cap the user tier, then shed bottom-up until the
+ * count and byte budgets are met. No compression — see `prepareReferences`.
+ */
+export declare function allocateReferences(slots: ReferenceSlot[], options?: AllocateOptions): Allocation;
+/**
+ * Compress everything, escalate on the largest offenders, and only then shed
+ * slots. This is the entry point every image-generation surface should use.
+ *
+ * Placeholder slots (`dataUrl === ""`) are carried through untouched — the host
+ * compresses those on its side against {@link HOST_ASSET_BYTE_RESERVATION}.
+ */
+export declare function prepareReferences(slots: ReferenceSlot[], options?: AllocateOptions): Promise<Allocation>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecatai/adgen-canvas",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "type": "module",
   "types": "./dist/types/excalidraw/index.d.ts",
   "main": "./dist/prod/index.js",

package/dist/prod/data/image-ALVZ6E6S.js

@@ -1 +0,0 @@
-import{S as a,T as b,U as c}from"../chunk-MBLHWEZ7.js";import"../chunk-DB27YYNM.js";import"../chunk-SRAX5OIU.js";export{c as decodePngMetadata,b as encodePngMetadata,a as getTEXtChunk};