vidspotai-shared 1.0.118 → 1.0.120

package/lib/libs/storage/MediaStorage.d.ts

@@ -12,11 +12,12 @@
  * notes/R2_MEDIA_MIGRATION_PLAN.md §9 "Stage 2 decision log — R2-primary flip"):
  *   • BYTES      = R2 — the only place object bytes are written, read, or
  *     deleted for anything going through `put`/`putFromFile`/`delete` below.
- *   • URL MINTER = GCS — used ONLY to mint the V4-signed URL *shape* that
+ *   • URL MINTER = GCS — used ONLY to mint the V2-signed URL *shape* that
  *     the `cdn.vidspotai.com` Worker already recognizes, including its
- *     private-access gate (which just checks the signature param is
+ *     private-access gate (which just checks a signature param is
  *     present — see worker.js `privateRequestAllowed()`, it never
- *     cryptographically verifies it). V4 signing is a local crypto
+ *     cryptographically verifies it). V2 (not V4 — V4 caps expiry at 7
+ *     days, and these need a far-future expiry) signing is a local crypto
  *     operation against the service-account key: no network call, and the
  *     object does NOT need to exist in the GCS bucket for a valid-shaped
  *     URL to be minted. So this eliminates real GCS *storage* (and its

package/lib/libs/storage/MediaStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MediaStorage.d.ts","sourceRoot":"","sources":["../../../src/libs/storage/MediaStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,qBAAa,YAAY;IACvB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe;IAK9D;;;;;;OAMG;IACG,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAKlB;;;;;OAKG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAMzC;;;;;;;OAOG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;OAKG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;OAMG;IACG,kBAAkB,CACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAShB,iDAAiD;IACjD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlD;;;;;;;;OAQG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C;;;;;OAKG;YACW,gBAAgB;CAa/B;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,cAAsD,CAAC"}
+{"version":3,"file":"MediaStorage.d.ts","sourceRoot":"","sources":["../../../src/libs/storage/MediaStorage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,qBAAa,YAAY;IACvB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe;IAK9D;;;;;;OAMG;IACG,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAKlB;;;;;OAKG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAMzC;;;;;;;OAOG;IACG,WAAW,CACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;OAKG;IACG,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAQhB;;;;;;OAMG;IACG,kBAAkB,CACtB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,QAAQ,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAShB,iDAAiD;IACjD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIlD;;;;;;;;OAQG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C;;;;;OAKG;YACW,gBAAgB;CAa/B;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,cAAsD,CAAC"}

package/lib/services/agent/index.d.ts

@@ -28,6 +28,7 @@ export * from "./extendChain";
 export * from "./editExisting";
 export * from "./repurpose";
 export * from "./covers";
+export * from "./poster";
 export * from "./providerTaskCache";
 export * from "./planDiff";
 export * from "./taskPoller";

package/lib/services/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/lib/services/agent/index.js

@@ -44,6 +44,7 @@ __exportStar(require("./extendChain"), exports);
 __exportStar(require("./editExisting"), exports);
 __exportStar(require("./repurpose"), exports);
 __exportStar(require("./covers"), exports);
+__exportStar(require("./poster"), exports);
 __exportStar(require("./providerTaskCache"), exports);
 __exportStar(require("./planDiff"), exports);
 __exportStar(require("./taskPoller"), exports);

package/lib/services/agent/poster/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./posterAgent.schema";
+export * from "./posterPlanner";
+//# sourceMappingURL=index.d.ts.map

package/lib/services/agent/poster/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/poster/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC"}

package/lib/services/agent/poster/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./posterAgent.schema"), exports);
+__exportStar(require("./posterPlanner"), exports);

package/lib/services/agent/poster/posterAgent.schema.d.ts

@@ -0,0 +1,482 @@
+import { z } from "zod";
+/**
+ * AI Poster Studio — contracts for the prompt-first poster agent.
+ *
+ * One prompt ("summer sale, 40% off sneakers, ends Sunday") → the agent infers
+ * the use case, writes the copy, picks format/layout/palette/type, and writes
+ * the art prompt(s). Two render modes, chosen per run:
+ *   - "editable": art is generated WITHOUT text (negative space left where the
+ *     copy goes) and the copy is placed as real editable text layers on the
+ *     canvas. Always spelled right; restyle in one click; animatable later
+ *     (the video-poster / ad-studio path).
+ *   - "flat": the copy is baked into the prompt and a typography-strong image
+ *     model renders the whole poster as one image.
+ *
+ * Image-only for now; kept deliberately free of video concepts so a later
+ * "video poster / ad" mode can extend PosterVariantPlan rather than fork it.
+ */
+export declare const POSTER_USE_CASE_IDS: readonly ["instagram-post", "instagram-story", "facebook-post", "linkedin-post", "x-post", "pinterest-pin", "youtube-thumbnail", "event-flyer", "sale-promo", "product-launch", "restaurant-food", "hiring", "webinar", "real-estate", "concert-gig", "fitness-class", "print-poster", "announcement"];
+export declare const PosterUseCaseSchema: z.ZodEnum<{
+    "real-estate": "real-estate";
+    "instagram-post": "instagram-post";
+    "instagram-story": "instagram-story";
+    "facebook-post": "facebook-post";
+    "linkedin-post": "linkedin-post";
+    "x-post": "x-post";
+    "pinterest-pin": "pinterest-pin";
+    "youtube-thumbnail": "youtube-thumbnail";
+    "event-flyer": "event-flyer";
+    "sale-promo": "sale-promo";
+    "product-launch": "product-launch";
+    "restaurant-food": "restaurant-food";
+    hiring: "hiring";
+    webinar: "webinar";
+    "concert-gig": "concert-gig";
+    "fitness-class": "fitness-class";
+    "print-poster": "print-poster";
+    announcement: "announcement";
+}>;
+export type PosterUseCase = z.infer<typeof PosterUseCaseSchema>;
+/** Aspect ratios every poster-agent image model accepts. */
+export declare const POSTER_IMAGE_ASPECTS: readonly ["1:1", "3:4", "4:3", "9:16", "16:9"];
+export type PosterImageAspect = (typeof POSTER_IMAGE_ASPECTS)[number];
+export interface PosterFormat {
+    width: number;
+    height: number;
+}
+export interface PosterUseCaseSpec {
+    id: PosterUseCase;
+    label: string;
+    /** Canvas size the poster opens at (the user can still resize). */
+    format: PosterFormat;
+    /** Design guidance injected into the planner prompt for this use case. */
+    guidance: string;
+}
+export declare const POSTER_USE_CASES: Record<PosterUseCase, PosterUseCaseSpec>;
+/**
+ * Curated families the editor canvas + server render preload
+ * (vidspotai-remotion-components CURATED_FONT_FAMILIES). The planner may ONLY
+ * pick from these so every poster renders with the intended face.
+ */
+export declare const POSTER_FONT_FAMILIES: readonly ["Inter", "Anton", "Bebas Neue", "Playfair Display", "Caveat", "Permanent Marker", "IBM Plex Sans", "Space Grotesk", "Archivo Black", "Outfit", "Fraunces", "DM Serif Display", "Poppins"];
+export declare const PosterFontSchema: z.ZodEnum<{
+    Poppins: "Poppins";
+    Inter: "Inter";
+    Anton: "Anton";
+    "Bebas Neue": "Bebas Neue";
+    "Playfair Display": "Playfair Display";
+    Caveat: "Caveat";
+    "Permanent Marker": "Permanent Marker";
+    "IBM Plex Sans": "IBM Plex Sans";
+    "Space Grotesk": "Space Grotesk";
+    "Archivo Black": "Archivo Black";
+    Outfit: "Outfit";
+    Fraunces: "Fraunces";
+    "DM Serif Display": "DM Serif Display";
+}>;
+export type PosterFont = z.infer<typeof PosterFontSchema>;
+/**
+ * Layout archetypes. Each maps to fixed normalized text boxes on the client
+ * (poster-studio/agent/poster-layouts.ts), so layout is deterministic and
+ * always legible; the planner only chooses which one fits the art.
+ *
+ *   hero-top      big headline block in the top ~40%, art below
+ *   hero-bottom   art up top, copy stacked in the bottom ~40%
+ *   center-stack  everything centered over the art (needs a calm center)
+ *   split-left    copy in the left ~45% column, subject on the right
+ *   split-right   mirror of split-left
+ *   framed        copy on a solid panel/band across the lower third
+ *   minimal-corner small refined copy block anchored bottom-left
+ */
+export declare const POSTER_LAYOUT_IDS: readonly ["hero-top", "hero-bottom", "center-stack", "split-left", "split-right", "framed", "minimal-corner"];
+export declare const PosterLayoutSchema: z.ZodEnum<{
+    framed: "framed";
+    "hero-top": "hero-top";
+    "hero-bottom": "hero-bottom";
+    "center-stack": "center-stack";
+    "split-left": "split-left";
+    "split-right": "split-right";
+    "minimal-corner": "minimal-corner";
+}>;
+export type PosterLayout = z.infer<typeof PosterLayoutSchema>;
+export declare const PosterRenderModeSchema: z.ZodEnum<{
+    flat: "flat";
+    editable: "editable";
+}>;
+export type PosterRenderMode = z.infer<typeof PosterRenderModeSchema>;
+export declare const PosterPaletteSchema: z.ZodObject<{
+    background: z.ZodString;
+    primary: z.ZodString;
+    accent: z.ZodString;
+    text: z.ZodString;
+    onAccent: z.ZodString;
+}, z.core.$strip>;
+export type PosterPalette = z.infer<typeof PosterPaletteSchema>;
+export declare const PosterCopySchema: z.ZodObject<{
+    headline: z.ZodString;
+    subheadline: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    cta: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    footer: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PosterCopy = z.infer<typeof PosterCopySchema>;
+export declare const PosterVariantPlanSchema: z.ZodObject<{
+    concept: z.ZodString;
+    layout: z.ZodEnum<{
+        framed: "framed";
+        "hero-top": "hero-top";
+        "hero-bottom": "hero-bottom";
+        "center-stack": "center-stack";
+        "split-left": "split-left";
+        "split-right": "split-right";
+        "minimal-corner": "minimal-corner";
+    }>;
+    palette: z.ZodObject<{
+        background: z.ZodString;
+        primary: z.ZodString;
+        accent: z.ZodString;
+        text: z.ZodString;
+        onAccent: z.ZodString;
+    }, z.core.$strip>;
+    typography: z.ZodObject<{
+        headingFont: z.ZodEnum<{
+            Poppins: "Poppins";
+            Inter: "Inter";
+            Anton: "Anton";
+            "Bebas Neue": "Bebas Neue";
+            "Playfair Display": "Playfair Display";
+            Caveat: "Caveat";
+            "Permanent Marker": "Permanent Marker";
+            "IBM Plex Sans": "IBM Plex Sans";
+            "Space Grotesk": "Space Grotesk";
+            "Archivo Black": "Archivo Black";
+            Outfit: "Outfit";
+            Fraunces: "Fraunces";
+            "DM Serif Display": "DM Serif Display";
+        }>;
+        bodyFont: z.ZodEnum<{
+            Poppins: "Poppins";
+            Inter: "Inter";
+            Anton: "Anton";
+            "Bebas Neue": "Bebas Neue";
+            "Playfair Display": "Playfair Display";
+            Caveat: "Caveat";
+            "Permanent Marker": "Permanent Marker";
+            "IBM Plex Sans": "IBM Plex Sans";
+            "Space Grotesk": "Space Grotesk";
+            "Archivo Black": "Archivo Black";
+            Outfit: "Outfit";
+            Fraunces: "Fraunces";
+            "DM Serif Display": "DM Serif Display";
+        }>;
+        headingCase: z.ZodEnum<{
+            title: "title";
+            upper: "upper";
+            sentence: "sentence";
+        }>;
+    }, z.core.$strip>;
+    copy: z.ZodObject<{
+        headline: z.ZodString;
+        subheadline: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        cta: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        footer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    scrim: z.ZodEnum<{
+        none: "none";
+        soft: "soft";
+        strong: "strong";
+    }>;
+    imagePrompt: z.ZodString;
+    negativePrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PosterVariantPlan = z.infer<typeof PosterVariantPlanSchema>;
+export declare const PosterPlanSchema: z.ZodObject<{
+    useCase: z.ZodEnum<{
+        "real-estate": "real-estate";
+        "instagram-post": "instagram-post";
+        "instagram-story": "instagram-story";
+        "facebook-post": "facebook-post";
+        "linkedin-post": "linkedin-post";
+        "x-post": "x-post";
+        "pinterest-pin": "pinterest-pin";
+        "youtube-thumbnail": "youtube-thumbnail";
+        "event-flyer": "event-flyer";
+        "sale-promo": "sale-promo";
+        "product-launch": "product-launch";
+        "restaurant-food": "restaurant-food";
+        hiring: "hiring";
+        webinar: "webinar";
+        "concert-gig": "concert-gig";
+        "fitness-class": "fitness-class";
+        "print-poster": "print-poster";
+        announcement: "announcement";
+    }>;
+    mode: z.ZodEnum<{
+        flat: "flat";
+        editable: "editable";
+    }>;
+    format: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    imageAspect: z.ZodEnum<{
+        "9:16": "9:16";
+        "1:1": "1:1";
+        "16:9": "16:9";
+        "4:3": "4:3";
+        "3:4": "3:4";
+    }>;
+    audience: z.ZodString;
+    goal: z.ZodString;
+    tone: z.ZodString;
+    variants: z.ZodArray<z.ZodObject<{
+        concept: z.ZodString;
+        layout: z.ZodEnum<{
+            framed: "framed";
+            "hero-top": "hero-top";
+            "hero-bottom": "hero-bottom";
+            "center-stack": "center-stack";
+            "split-left": "split-left";
+            "split-right": "split-right";
+            "minimal-corner": "minimal-corner";
+        }>;
+        palette: z.ZodObject<{
+            background: z.ZodString;
+            primary: z.ZodString;
+            accent: z.ZodString;
+            text: z.ZodString;
+            onAccent: z.ZodString;
+        }, z.core.$strip>;
+        typography: z.ZodObject<{
+            headingFont: z.ZodEnum<{
+                Poppins: "Poppins";
+                Inter: "Inter";
+                Anton: "Anton";
+                "Bebas Neue": "Bebas Neue";
+                "Playfair Display": "Playfair Display";
+                Caveat: "Caveat";
+                "Permanent Marker": "Permanent Marker";
+                "IBM Plex Sans": "IBM Plex Sans";
+                "Space Grotesk": "Space Grotesk";
+                "Archivo Black": "Archivo Black";
+                Outfit: "Outfit";
+                Fraunces: "Fraunces";
+                "DM Serif Display": "DM Serif Display";
+            }>;
+            bodyFont: z.ZodEnum<{
+                Poppins: "Poppins";
+                Inter: "Inter";
+                Anton: "Anton";
+                "Bebas Neue": "Bebas Neue";
+                "Playfair Display": "Playfair Display";
+                Caveat: "Caveat";
+                "Permanent Marker": "Permanent Marker";
+                "IBM Plex Sans": "IBM Plex Sans";
+                "Space Grotesk": "Space Grotesk";
+                "Archivo Black": "Archivo Black";
+                Outfit: "Outfit";
+                Fraunces: "Fraunces";
+                "DM Serif Display": "DM Serif Display";
+            }>;
+            headingCase: z.ZodEnum<{
+                title: "title";
+                upper: "upper";
+                sentence: "sentence";
+            }>;
+        }, z.core.$strip>;
+        copy: z.ZodObject<{
+            headline: z.ZodString;
+            subheadline: z.ZodOptional<z.ZodString>;
+            body: z.ZodOptional<z.ZodString>;
+            cta: z.ZodOptional<z.ZodString>;
+            details: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            footer: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        scrim: z.ZodEnum<{
+            none: "none";
+            soft: "soft";
+            strong: "strong";
+        }>;
+        imagePrompt: z.ZodString;
+        negativePrompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PosterPlan = z.infer<typeof PosterPlanSchema>;
+export declare const PosterAgentRequestSchema: z.ZodObject<{
+    prompt: z.ZodString;
+    useCase: z.ZodOptional<z.ZodEnum<{
+        "real-estate": "real-estate";
+        "instagram-post": "instagram-post";
+        "instagram-story": "instagram-story";
+        "facebook-post": "facebook-post";
+        "linkedin-post": "linkedin-post";
+        "x-post": "x-post";
+        "pinterest-pin": "pinterest-pin";
+        "youtube-thumbnail": "youtube-thumbnail";
+        "event-flyer": "event-flyer";
+        "sale-promo": "sale-promo";
+        "product-launch": "product-launch";
+        "restaurant-food": "restaurant-food";
+        hiring: "hiring";
+        webinar: "webinar";
+        "concert-gig": "concert-gig";
+        "fitness-class": "fitness-class";
+        "print-poster": "print-poster";
+        announcement: "announcement";
+    }>>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        flat: "flat";
+        editable: "editable";
+    }>>;
+    variants: z.ZodDefault<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    referenceImageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    useBrandKit: z.ZodDefault<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PosterAgentRequest = z.infer<typeof PosterAgentRequestSchema>;
+export declare const PosterRefineRequestSchema: z.ZodObject<{
+    plan: z.ZodObject<{
+        useCase: z.ZodEnum<{
+            "real-estate": "real-estate";
+            "instagram-post": "instagram-post";
+            "instagram-story": "instagram-story";
+            "facebook-post": "facebook-post";
+            "linkedin-post": "linkedin-post";
+            "x-post": "x-post";
+            "pinterest-pin": "pinterest-pin";
+            "youtube-thumbnail": "youtube-thumbnail";
+            "event-flyer": "event-flyer";
+            "sale-promo": "sale-promo";
+            "product-launch": "product-launch";
+            "restaurant-food": "restaurant-food";
+            hiring: "hiring";
+            webinar: "webinar";
+            "concert-gig": "concert-gig";
+            "fitness-class": "fitness-class";
+            "print-poster": "print-poster";
+            announcement: "announcement";
+        }>;
+        mode: z.ZodEnum<{
+            flat: "flat";
+            editable: "editable";
+        }>;
+        format: z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        imageAspect: z.ZodEnum<{
+            "9:16": "9:16";
+            "1:1": "1:1";
+            "16:9": "16:9";
+            "4:3": "4:3";
+            "3:4": "3:4";
+        }>;
+        audience: z.ZodString;
+        goal: z.ZodString;
+        tone: z.ZodString;
+        variants: z.ZodArray<z.ZodObject<{
+            concept: z.ZodString;
+            layout: z.ZodEnum<{
+                framed: "framed";
+                "hero-top": "hero-top";
+                "hero-bottom": "hero-bottom";
+                "center-stack": "center-stack";
+                "split-left": "split-left";
+                "split-right": "split-right";
+                "minimal-corner": "minimal-corner";
+            }>;
+            palette: z.ZodObject<{
+                background: z.ZodString;
+                primary: z.ZodString;
+                accent: z.ZodString;
+                text: z.ZodString;
+                onAccent: z.ZodString;
+            }, z.core.$strip>;
+            typography: z.ZodObject<{
+                headingFont: z.ZodEnum<{
+                    Poppins: "Poppins";
+                    Inter: "Inter";
+                    Anton: "Anton";
+                    "Bebas Neue": "Bebas Neue";
+                    "Playfair Display": "Playfair Display";
+                    Caveat: "Caveat";
+                    "Permanent Marker": "Permanent Marker";
+                    "IBM Plex Sans": "IBM Plex Sans";
+                    "Space Grotesk": "Space Grotesk";
+                    "Archivo Black": "Archivo Black";
+                    Outfit: "Outfit";
+                    Fraunces: "Fraunces";
+                    "DM Serif Display": "DM Serif Display";
+                }>;
+                bodyFont: z.ZodEnum<{
+                    Poppins: "Poppins";
+                    Inter: "Inter";
+                    Anton: "Anton";
+                    "Bebas Neue": "Bebas Neue";
+                    "Playfair Display": "Playfair Display";
+                    Caveat: "Caveat";
+                    "Permanent Marker": "Permanent Marker";
+                    "IBM Plex Sans": "IBM Plex Sans";
+                    "Space Grotesk": "Space Grotesk";
+                    "Archivo Black": "Archivo Black";
+                    Outfit: "Outfit";
+                    Fraunces: "Fraunces";
+                    "DM Serif Display": "DM Serif Display";
+                }>;
+                headingCase: z.ZodEnum<{
+                    title: "title";
+                    upper: "upper";
+                    sentence: "sentence";
+                }>;
+            }, z.core.$strip>;
+            copy: z.ZodObject<{
+                headline: z.ZodString;
+                subheadline: z.ZodOptional<z.ZodString>;
+                body: z.ZodOptional<z.ZodString>;
+                cta: z.ZodOptional<z.ZodString>;
+                details: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                footer: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+            scrim: z.ZodEnum<{
+                none: "none";
+                soft: "soft";
+                strong: "strong";
+            }>;
+            imagePrompt: z.ZodString;
+            negativePrompt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    variantIndex: z.ZodNumber;
+    instruction: z.ZodString;
+    referenceImageUrls: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    useBrandKit: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type PosterRefineRequest = z.infer<typeof PosterRefineRequestSchema>;
+/** Brand context the controller resolves from the user's brand kit. */
+export interface PosterBrandContext {
+    brandName?: string;
+    colors?: {
+        primary?: string;
+        secondary?: string;
+        accent?: string;
+        palette?: string[];
+    };
+    fonts?: {
+        heading?: string;
+        body?: string;
+    };
+    tone?: string;
+    hasLogo?: boolean;
+    /** Brand-kit banned claims — never appear in the copy. */
+    avoidPhrases?: string[];
+}
+/** Pick the image aspect closest to a canvas format. */
+export declare function nearestPosterAspect(format: PosterFormat): PosterImageAspect;
+//# sourceMappingURL=posterAgent.schema.d.ts.map

package/lib/services/agent/poster/posterAgent.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posterAgent.schema.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/poster/posterAgent.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AAIH,eAAO,MAAM,mBAAmB,wSAmBtB,CAAC;AACX,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;EAA8B,CAAC;AAC/D,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,4DAA4D;AAC5D,eAAO,MAAM,oBAAoB,gDAAiD,CAAC;AACnF,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,aAAa,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,YAAY,CAAC;IACrB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,aAAa,EAAE,iBAAiB,CA2HrE,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,qMAcvB,CAAC;AACX,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;EAA+B,CAAC;AAC7D,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,+GAQpB,CAAC;AACX,eAAO,MAAM,kBAAkB;;;;;;;;EAA4B,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB;;;EAA+B,CAAC;AACnE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAItE,eAAO,MAAM,mBAAmB;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,gBAAgB;;;;;;;iBAQ3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmBlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkBnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACvF,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,iBAAiB,CAa3E"}

package/lib/services/agent/poster/posterAgent.schema.js

@@ -0,0 +1,296 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PosterRefineRequestSchema = exports.PosterAgentRequestSchema = exports.PosterPlanSchema = exports.PosterVariantPlanSchema = exports.PosterCopySchema = exports.PosterPaletteSchema = exports.PosterRenderModeSchema = exports.PosterLayoutSchema = exports.POSTER_LAYOUT_IDS = exports.PosterFontSchema = exports.POSTER_FONT_FAMILIES = exports.POSTER_USE_CASES = exports.POSTER_IMAGE_ASPECTS = exports.PosterUseCaseSchema = exports.POSTER_USE_CASE_IDS = void 0;
+exports.nearestPosterAspect = nearestPosterAspect;
+const zod_1 = require("zod");
+/**
+ * AI Poster Studio — contracts for the prompt-first poster agent.
+ *
+ * One prompt ("summer sale, 40% off sneakers, ends Sunday") → the agent infers
+ * the use case, writes the copy, picks format/layout/palette/type, and writes
+ * the art prompt(s). Two render modes, chosen per run:
+ *   - "editable": art is generated WITHOUT text (negative space left where the
+ *     copy goes) and the copy is placed as real editable text layers on the
+ *     canvas. Always spelled right; restyle in one click; animatable later
+ *     (the video-poster / ad-studio path).
+ *   - "flat": the copy is baked into the prompt and a typography-strong image
+ *     model renders the whole poster as one image.
+ *
+ * Image-only for now; kept deliberately free of video concepts so a later
+ * "video poster / ad" mode can extend PosterVariantPlan rather than fork it.
+ */
+// ── Use cases ──────────────────────────────────────────────────────────────
+exports.POSTER_USE_CASE_IDS = [
+    "instagram-post",
+    "instagram-story",
+    "facebook-post",
+    "linkedin-post",
+    "x-post",
+    "pinterest-pin",
+    "youtube-thumbnail",
+    "event-flyer",
+    "sale-promo",
+    "product-launch",
+    "restaurant-food",
+    "hiring",
+    "webinar",
+    "real-estate",
+    "concert-gig",
+    "fitness-class",
+    "print-poster",
+    "announcement",
+];
+exports.PosterUseCaseSchema = zod_1.z.enum(exports.POSTER_USE_CASE_IDS);
+/** Aspect ratios every poster-agent image model accepts. */
+exports.POSTER_IMAGE_ASPECTS = ["1:1", "3:4", "4:3", "9:16", "16:9"];
+exports.POSTER_USE_CASES = {
+    "instagram-post": {
+        id: "instagram-post",
+        label: "Instagram post",
+        format: { width: 1080, height: 1350 },
+        guidance: "Feed-scroll stopper. One bold idea, headline readable at thumbnail size, max ~8 headline words. Keep critical copy away from the bottom 10% (UI overlays).",
+    },
+    "instagram-story": {
+        id: "instagram-story",
+        label: "Instagram / TikTok story",
+        format: { width: 1080, height: 1920 },
+        guidance: "Full-screen vertical. Keep the top 250px and bottom 340px free of text (profile bar + reply bar). Big central headline, a clear CTA like 'Swipe up' / 'Link in bio'.",
+    },
+    "facebook-post": {
+        id: "facebook-post",
+        label: "Facebook post",
+        format: { width: 1200, height: 1500 },
+        guidance: "Friendly and direct, slightly more copy tolerated than Instagram. Clear CTA.",
+    },
+    "linkedin-post": {
+        id: "linkedin-post",
+        label: "LinkedIn post",
+        format: { width: 1200, height: 1200 },
+        guidance: "Professional, credible, uncluttered. Prefer clean sans type, generous whitespace, data or benefit-led headline. Avoid hype and emoji.",
+    },
+    "x-post": {
+        id: "x-post",
+        label: "X / Twitter post",
+        format: { width: 1600, height: 900 },
+        guidance: "Landscape card; headline must survive being cropped to the center 16:9.",
+    },
+    "pinterest-pin": {
+        id: "pinterest-pin",
+        label: "Pinterest pin",
+        format: { width: 1000, height: 1500 },
+        guidance: "Tall and aspirational. Headline in the top third, image-led, soft editorial look.",
+    },
+    "youtube-thumbnail": {
+        id: "youtube-thumbnail",
+        label: "YouTube thumbnail",
+        format: { width: 1280, height: 720 },
+        guidance: "3 words or fewer in huge heavy type, extreme contrast, one expressive subject. Nothing important in the bottom-right corner (timestamp badge).",
+    },
+    "event-flyer": {
+        id: "event-flyer",
+        label: "Event flyer",
+        format: { width: 1240, height: 1754 },
+        guidance: "Hierarchy: event name → date/time → venue → CTA (tickets/RSVP). Details as short scannable lines. Put date, time, and place in `details`.",
+    },
+    "sale-promo": {
+        id: "sale-promo",
+        label: "Sale / promotion",
+        format: { width: 1080, height: 1350 },
+        guidance: "The offer IS the headline (e.g. '40% OFF'). Urgency line (ends Sunday), a promo code or 'Shop now' CTA. High-energy palette, heavy display type.",
+    },
+    "product-launch": {
+        id: "product-launch",
+        label: "Product launch",
+        format: { width: 1080, height: 1350 },
+        guidance: "Hero the product with studio lighting and room around it. Headline = the product's single biggest benefit; subheadline names the product; CTA 'Available now' / 'Pre-order'.",
+    },
+    "restaurant-food": {
+        id: "restaurant-food",
+        label: "Restaurant / food special",
+        format: { width: 1080, height: 1350 },
+        guidance: "Appetite appeal first: close, warm, glossy food photography. Dish name as headline, price in `details`, hours/location in footer.",
+    },
+    hiring: {
+        id: "hiring",
+        label: "We're hiring",
+        format: { width: 1200, height: 1200 },
+        guidance: "Headline 'We're hiring' or the role name. List 2–4 roles or perks as `details`. CTA 'Apply now' + where. Human, welcoming tone.",
+    },
+    webinar: {
+        id: "webinar",
+        label: "Webinar / talk",
+        format: { width: 1200, height: 1200 },
+        guidance: "Topic as headline, speaker name/title as subheadline, date + time + timezone in `details`, CTA 'Register free'. Clean, trustworthy.",
+    },
+    "real-estate": {
+        id: "real-estate",
+        label: "Real estate listing",
+        format: { width: 1080, height: 1350 },
+        guidance: "Bright, wide architectural photography. Headline 'Just listed' / 'Open house', price and key specs (beds/baths/sqft) as `details`, agent contact as footer.",
+    },
+    "concert-gig": {
+        id: "concert-gig",
+        label: "Concert / gig poster",
+        format: { width: 1240, height: 1754 },
+        guidance: "Expressive and genre-driven (grunge, neon, psychedelic, minimal Swiss…). Artist name huge; date, venue, support acts in `details`; 'Tickets' CTA.",
+    },
+    "fitness-class": {
+        id: "fitness-class",
+        label: "Fitness class / gym",
+        format: { width: 1080, height: 1350 },
+        guidance: "Energetic motion, strong athletic subject, bold condensed type. Class name, schedule in `details`, 'First class free'-style CTA.",
+    },
+    "print-poster": {
+        id: "print-poster",
+        label: "Print poster (A-series)",
+        format: { width: 1754, height: 2480 },
+        guidance: "Viewed from distance: headline legible from 3m, strong focal image, keep a 5% margin clear of text for print trim.",
+    },
+    announcement: {
+        id: "announcement",
+        label: "Announcement",
+        format: { width: 1080, height: 1350 },
+        guidance: "One clear message. Short headline, one supporting line, optional CTA.",
+    },
+};
+// ── Design vocabulary the renderer understands ────────────────────────────
+/**
+ * Curated families the editor canvas + server render preload
+ * (vidspotai-remotion-components CURATED_FONT_FAMILIES). The planner may ONLY
+ * pick from these so every poster renders with the intended face.
+ */
+exports.POSTER_FONT_FAMILIES = [
+    "Inter",
+    "Anton",
+    "Bebas Neue",
+    "Playfair Display",
+    "Caveat",
+    "Permanent Marker",
+    "IBM Plex Sans",
+    "Space Grotesk",
+    "Archivo Black",
+    "Outfit",
+    "Fraunces",
+    "DM Serif Display",
+    "Poppins",
+];
+exports.PosterFontSchema = zod_1.z.enum(exports.POSTER_FONT_FAMILIES);
+/**
+ * Layout archetypes. Each maps to fixed normalized text boxes on the client
+ * (poster-studio/agent/poster-layouts.ts), so layout is deterministic and
+ * always legible; the planner only chooses which one fits the art.
+ *
+ *   hero-top      big headline block in the top ~40%, art below
+ *   hero-bottom   art up top, copy stacked in the bottom ~40%
+ *   center-stack  everything centered over the art (needs a calm center)
+ *   split-left    copy in the left ~45% column, subject on the right
+ *   split-right   mirror of split-left
+ *   framed        copy on a solid panel/band across the lower third
+ *   minimal-corner small refined copy block anchored bottom-left
+ */
+exports.POSTER_LAYOUT_IDS = [
+    "hero-top",
+    "hero-bottom",
+    "center-stack",
+    "split-left",
+    "split-right",
+    "framed",
+    "minimal-corner",
+];
+exports.PosterLayoutSchema = zod_1.z.enum(exports.POSTER_LAYOUT_IDS);
+exports.PosterRenderModeSchema = zod_1.z.enum(["editable", "flat"]);
+const hex = zod_1.z.string().regex(/^#[0-9a-fA-F]{6}$/);
+exports.PosterPaletteSchema = zod_1.z.object({
+    /** Fallback canvas fill + scrim/panel base. */
+    background: hex,
+    /** Headline color. */
+    primary: hex,
+    /** CTA pill / highlights. */
+    accent: hex,
+    /** Body/subheadline/details color. */
+    text: hex,
+    /** Text color on top of the accent (CTA label). */
+    onAccent: hex,
+});
+exports.PosterCopySchema = zod_1.z.object({
+    headline: zod_1.z.string().min(1).max(80),
+    subheadline: zod_1.z.string().max(140).optional(),
+    body: zod_1.z.string().max(260).optional(),
+    cta: zod_1.z.string().max(32).optional(),
+    /** Short scannable lines: date, time, venue, price, specs, roles. */
+    details: zod_1.z.array(zod_1.z.string().max(60)).max(5).optional(),
+    footer: zod_1.z.string().max(100).optional(),
+});
+exports.PosterVariantPlanSchema = zod_1.z.object({
+    /** One-line creative idea, shown to the user on the variant card. */
+    concept: zod_1.z.string().max(160),
+    layout: exports.PosterLayoutSchema,
+    palette: exports.PosterPaletteSchema,
+    typography: zod_1.z.object({
+        headingFont: exports.PosterFontSchema,
+        bodyFont: exports.PosterFontSchema,
+        headingCase: zod_1.z.enum(["upper", "title", "sentence"]),
+    }),
+    copy: exports.PosterCopySchema,
+    /** Legibility layer between art and text (editable mode). */
+    scrim: zod_1.z.enum(["none", "soft", "strong"]),
+    /**
+     * Editable: the art prompt, explicitly text-free, describing where the
+     * negative space is. Flat: the full poster prompt with the exact copy.
+     */
+    imagePrompt: zod_1.z.string().min(10).max(2400),
+    negativePrompt: zod_1.z.string().max(400).optional(),
+});
+exports.PosterPlanSchema = zod_1.z.object({
+    useCase: exports.PosterUseCaseSchema,
+    mode: exports.PosterRenderModeSchema,
+    format: zod_1.z.object({ width: zod_1.z.number().int().positive(), height: zod_1.z.number().int().positive() }),
+    imageAspect: zod_1.z.enum(exports.POSTER_IMAGE_ASPECTS),
+    /** Who it's for + what it must make them do — shown as the agent's brief. */
+    audience: zod_1.z.string().max(160),
+    goal: zod_1.z.string().max(160),
+    tone: zod_1.z.string().max(80),
+    variants: zod_1.z.array(exports.PosterVariantPlanSchema).min(1).max(4),
+});
+// ── Requests ───────────────────────────────────────────────────────────────
+exports.PosterAgentRequestSchema = zod_1.z.object({
+    prompt: zod_1.z.string().trim().min(3).max(2000),
+    /** Absent → the agent infers it from the prompt. */
+    useCase: exports.PosterUseCaseSchema.optional(),
+    mode: exports.PosterRenderModeSchema.default("editable"),
+    variants: zod_1.z.number().int().min(1).max(4).default(2),
+    /** Canvas size override (e.g. the user already picked a format). */
+    format: zod_1.z
+        .object({
+        width: zod_1.z.number().int().min(200).max(8000),
+        height: zod_1.z.number().int().min(200).max(8000),
+    })
+        .optional(),
+    /** Product photos / references the art should feature. */
+    referenceImageUrls: zod_1.z.array(zod_1.z.string().url()).max(4).optional(),
+    useBrandKit: zod_1.z.boolean().default(true),
+    /** BCP-47. Absent → copy follows the prompt's language. */
+    language: zod_1.z.string().max(16).optional(),
+});
+exports.PosterRefineRequestSchema = zod_1.z.object({
+    plan: exports.PosterPlanSchema,
+    variantIndex: zod_1.z.number().int().min(0).max(3),
+    instruction: zod_1.z.string().trim().min(2).max(1000),
+    referenceImageUrls: zod_1.z.array(zod_1.z.string().url()).max(4).optional(),
+    useBrandKit: zod_1.z.boolean().default(true),
+});
+/** Pick the image aspect closest to a canvas format. */
+function nearestPosterAspect(format) {
+    const r = format.width / format.height;
+    let best = "3:4";
+    let bestDiff = Infinity;
+    for (const a of exports.POSTER_IMAGE_ASPECTS) {
+        const [w = 1, h = 1] = a.split(":").map(Number);
+        const diff = Math.abs(Math.log(r / (w / h)));
+        if (diff < bestDiff) {
+            bestDiff = diff;
+            best = a;
+        }
+    }
+    return best;
+}

package/lib/services/agent/poster/posterPlanner.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { LlmCaller } from "../llmCaller";
+import { PosterAgentRequest, PosterBrandContext, PosterPlan, PosterRenderMode, PosterVariantPlan } from "./posterAgent.schema";
+/**
+ * AI Poster Studio — the poster agent's reasoning core. Pure functions over an
+ * injected LlmCaller (same shape as covers/coverPlanner.ts) so the Functions
+ * controller, scripts, and a no-spend eval can all drive it.
+ *
+ *   planPosterCore          prompt → brief + N distinct poster variants
+ *   refinePosterVariantCore one variant + a plain-language instruction →
+ *                           the updated variant + whether the art must be
+ *                           regenerated (copy/color/layout-only edits in
+ *                           editable mode don't need new art — no spend).
+ *
+ * The LLM answers into LOOSE schemas; `repairVariant` clamps fonts / colors /
+ * lengths into the strict PosterVariantPlanSchema so a slightly-off answer is
+ * fixed, not rejected.
+ */
+declare const LooseVariantSchema: z.ZodObject<{
+    concept: z.ZodString;
+    layout: z.ZodString;
+    palette: z.ZodObject<{
+        background: z.ZodString;
+        primary: z.ZodString;
+        accent: z.ZodString;
+        text: z.ZodString;
+        onAccent: z.ZodString;
+    }, z.core.$strip>;
+    typography: z.ZodObject<{
+        headingFont: z.ZodString;
+        bodyFont: z.ZodString;
+        headingCase: z.ZodString;
+    }, z.core.$strip>;
+    copy: z.ZodObject<{
+        headline: z.ZodString;
+        subheadline: z.ZodOptional<z.ZodString>;
+        body: z.ZodOptional<z.ZodString>;
+        cta: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        footer: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    scrim: z.ZodString;
+    imagePrompt: z.ZodString;
+    negativePrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type LooseVariant = z.infer<typeof LooseVariantSchema>;
+export declare function repairVariant(v: LooseVariant, mode: PosterRenderMode): PosterVariantPlan;
+export declare function planPosterCore(llm: LlmCaller, args: {
+    request: PosterAgentRequest;
+    brand?: PosterBrandContext;
+    maxRetries?: number;
+}): Promise<PosterPlan>;
+export interface PosterRefineResult {
+    variant: PosterVariantPlan;
+    /** False → copy/color/layout-only edit; client re-applies without new art. */
+    regenerateArt: boolean;
+    /** One sentence describing what changed, shown in the agent thread. */
+    summary: string;
+}
+export declare function refinePosterVariantCore(llm: LlmCaller, args: {
+    plan: PosterPlan;
+    variantIndex: number;
+    instruction: string;
+    brand?: PosterBrandContext;
+    hasReferenceImages?: boolean;
+}): Promise<PosterRefineResult>;
+export {};
+//# sourceMappingURL=posterPlanner.d.ts.map

package/lib/services/agent/poster/posterPlanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posterPlanner.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/poster/posterPlanner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAe,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAML,kBAAkB,EAClB,kBAAkB,EAIlB,UAAU,EAEV,gBAAgB,EAEhB,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;GAcG;AAIH,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BtB,CAAC;AACH,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAkKvD,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,gBAAgB,GAAG,iBAAiB,CAyCxF;AAeD,wBAAsB,cAAc,CAClC,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;IACJ,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GACA,OAAO,CAAC,UAAU,CAAC,CAqDrB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,8EAA8E;IAC9E,aAAa,EAAE,OAAO,CAAC;IACvB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;IACJ,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GACA,OAAO,CAAC,kBAAkB,CAAC,CAsD7B"}

package/lib/services/agent/poster/posterPlanner.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.repairVariant = repairVariant;
+exports.planPosterCore = planPosterCore;
+exports.refinePosterVariantCore = refinePosterVariantCore;
+const zod_1 = require("zod");
+const logger_1 = require("../../../utils/logger");
+const modelRouter_1 = require("../modelRouter");
+const posterAgent_schema_1 = require("./posterAgent.schema");
+/**
+ * AI Poster Studio — the poster agent's reasoning core. Pure functions over an
+ * injected LlmCaller (same shape as covers/coverPlanner.ts) so the Functions
+ * controller, scripts, and a no-spend eval can all drive it.
+ *
+ *   planPosterCore          prompt → brief + N distinct poster variants
+ *   refinePosterVariantCore one variant + a plain-language instruction →
+ *                           the updated variant + whether the art must be
+ *                           regenerated (copy/color/layout-only edits in
+ *                           editable mode don't need new art — no spend).
+ *
+ * The LLM answers into LOOSE schemas; `repairVariant` clamps fonts / colors /
+ * lengths into the strict PosterVariantPlanSchema so a slightly-off answer is
+ * fixed, not rejected.
+ */
+// ── Loose LLM output shapes ───────────────────────────────────────────────
+const LooseVariantSchema = zod_1.z.object({
+    concept: zod_1.z.string(),
+    layout: zod_1.z.string(),
+    palette: zod_1.z.object({
+        background: zod_1.z.string(),
+        primary: zod_1.z.string(),
+        accent: zod_1.z.string(),
+        text: zod_1.z.string(),
+        onAccent: zod_1.z.string(),
+    }),
+    typography: zod_1.z.object({
+        headingFont: zod_1.z.string(),
+        bodyFont: zod_1.z.string(),
+        headingCase: zod_1.z.string(),
+    }),
+    copy: zod_1.z.object({
+        headline: zod_1.z.string(),
+        subheadline: zod_1.z.string().optional(),
+        body: zod_1.z.string().optional(),
+        cta: zod_1.z.string().optional(),
+        details: zod_1.z.array(zod_1.z.string()).optional(),
+        footer: zod_1.z.string().optional(),
+    }),
+    scrim: zod_1.z.string(),
+    imagePrompt: zod_1.z.string(),
+    negativePrompt: zod_1.z.string().optional(),
+});
+const LoosePlanSchema = zod_1.z.object({
+    useCase: zod_1.z.string(),
+    audience: zod_1.z.string(),
+    goal: zod_1.z.string(),
+    tone: zod_1.z.string(),
+    variants: zod_1.z.array(LooseVariantSchema).min(1),
+});
+const LooseRefineSchema = zod_1.z.object({
+    variant: LooseVariantSchema,
+    regenerateArt: zod_1.z.boolean(),
+    summary: zod_1.z.string(),
+});
+// ── Prompt building ───────────────────────────────────────────────────────
+const DESIGN_PRINCIPLES = [
+    "You are a senior graphic designer and conversion copywriter who makes posters that work.",
+    "Principles you always apply:",
+    "- ONE focal point and a 3-level hierarchy: headline → supporting line → details/CTA. Readable in 3 seconds.",
+    "- Headlines are short and concrete (benefit, offer, or event name). No filler, no clichés ('Unleash', 'Elevate').",
+    "- Copy is REAL and specific to the user's prompt. Never invent facts (prices, dates, addresses, names) the user didn't give — if the design needs one, omit that line instead.",
+    "- Contrast: text color must pass WCAG AA against what sits behind it. Pick palettes deliberately; 1 accent color max.",
+    "- Type pairing: one display face for the headline, one clean face for body. Condensed/heavy display for energy, serif for elegance/editorial, sans for tech/professional.",
+    "- Variants must be genuinely different creative directions (concept, layout, palette), not tweaks of one idea.",
+].join("\n");
+function modeInstructions(mode) {
+    if (mode === "editable") {
+        return [
+            "RENDER MODE: EDITABLE.",
+            "The image model renders ONLY the artwork. The copy is placed afterwards as live text layers by the layout you pick.",
+            "So `imagePrompt` MUST:",
+            "- contain NO text, letters, words, logos, signage, or typography of any kind (say so explicitly: 'no text, no lettering').",
+            "- describe the subject, lighting, style, composition, and color palette in rich concrete detail.",
+            "- reserve calm negative space exactly where the layout puts the copy: hero-top → empty upper 40%; hero-bottom → empty lower 40%;",
+            "  center-stack → calm uncluttered center; split-left → subject on the right, left half empty; split-right → mirror;",
+            "  framed → lower third can be covered by a solid panel; minimal-corner → quiet bottom-left corner.",
+            "Put 'text, letters, watermark, logo, signature' in `negativePrompt`.",
+            "Choose `scrim`: 'none' if the negative space is already flat and calm, 'soft' for mild texture, 'strong' for busy photography.",
+        ].join("\n");
+    }
+    return [
+        "RENDER MODE: FLAT.",
+        "A typography-capable image model renders the ENTIRE poster, text included, as one image.",
+        "So `imagePrompt` MUST be a complete poster brief:",
+        "- quote every piece of copy EXACTLY, in double quotes, and say where each sits and how big (e.g. 'large bold condensed headline \"40% OFF\" across the top').",
+        "- name the type style (heavy condensed sans / elegant serif …), the palette hex colors, the layout, subject, lighting, and style.",
+        "- keep total on-image copy short (≤ ~20 words) — long copy renders badly. Drop body text if needed.",
+        "- end with 'professional poster design, crisp legible typography, correct spelling'.",
+        "Set `scrim` to 'none' (not used in flat mode). `layout` still describes the composition you asked for.",
+    ].join("\n");
+}
+function brandLines(brand) {
+    if (!brand)
+        return "";
+    const lines = [];
+    if (brand.brandName)
+        lines.push(`Brand name: ${brand.brandName}.`);
+    const c = brand.colors;
+    const colors = [c?.primary, c?.secondary, c?.accent, ...(c?.palette ?? [])].filter(Boolean);
+    if (colors.length)
+        lines.push(`Brand colors (build the palette from these): ${colors.join(", ")}.`);
+    if (brand.fonts?.heading || brand.fonts?.body) {
+        lines.push(`Brand fonts: heading "${brand.fonts?.heading ?? "—"}", body "${brand.fonts?.body ?? "—"}" — pick the closest match from the allowed font list.`);
+    }
+    if (brand.tone)
+        lines.push(`Brand voice: ${brand.tone}.`);
+    if (brand.avoidPhrases?.length) {
+        lines.push(`NEVER use these phrases or claims: ${brand.avoidPhrases.map((p) => `"${p}"`).join(", ")}.`);
+    }
+    if (brand.hasLogo)
+        lines.push("The brand logo will be placed on the poster automatically — don't describe a logo in the art.");
+    return lines.length ? `BRAND KIT:\n${lines.join("\n")}` : "";
+}
+function schemaLines() {
+    return [
+        "Field rules:",
+        `- layout: one of ${posterAgent_schema_1.POSTER_LAYOUT_IDS.join(", ")}.`,
+        `- typography.headingFont / bodyFont: one of ${posterAgent_schema_1.POSTER_FONT_FAMILIES.join(", ")}.`,
+        "- typography.headingCase: upper | title | sentence.",
+        "- palette: 6-digit hex colors (#RRGGBB). `onAccent` = text color that reads on `accent`.",
+        "- copy.headline ≤ 60 chars; subheadline ≤ 120; body ≤ 220 (often omit); cta ≤ 24 (a verb: 'Shop now', 'Get tickets'); details: up to 4 short lines; footer ≤ 90 (website/handle/address, only if given).",
+        "- scrim: none | soft | strong.",
+        "- concept: ONE sentence, ≤ 120 chars, naming the creative direction.",
+    ].join("\n");
+}
+function buildPlanMessages(request, brand, feedback) {
+    const useCaseList = posterAgent_schema_1.POSTER_USE_CASE_IDS.map((id) => `- ${id}: ${posterAgent_schema_1.POSTER_USE_CASES[id].label} — ${posterAgent_schema_1.POSTER_USE_CASES[id].guidance}`).join("\n");
+    const system = [
+        DESIGN_PRINCIPLES,
+        "",
+        modeInstructions(request.mode),
+        "",
+        "USE CASES (pick the best fit and follow its guidance):",
+        useCaseList,
+        "",
+        schemaLines(),
+    ].join("\n");
+    const user = [
+        `USER PROMPT: ${request.prompt}`,
+        request.useCase
+            ? `USE CASE (fixed by the user): ${request.useCase}.`
+            : "USE CASE: infer it from the prompt.",
+        `Produce exactly ${request.variants} variant(s).`,
+        request.language
+            ? `Write all copy in this language (BCP-47 "${request.language}").`
+            : "Write the copy in the same language as the user's prompt.",
+        request.referenceImageUrls?.length
+            ? `The user attached ${request.referenceImageUrls.length} reference image(s) (e.g. their product). The image model receives them — write the imagePrompt to feature "the product/subject from the reference image" faithfully rather than inventing a different one.`
+            : "",
+        brandLines(brand),
+        feedback ? `\nYOUR PREVIOUS ANSWER HAD PROBLEMS — FIX THESE:\n${feedback}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    return [
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ];
+}
+// ── Repair ────────────────────────────────────────────────────────────────
+const HEX_RE = /^#?([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$/;
+function normHex(v, fallback) {
+    const m = (v ?? "").trim().match(HEX_RE);
+    if (!m)
+        return fallback;
+    const raw = m[1] ?? "";
+    const full = raw.length === 3 ? raw.split("").map((c) => c + c).join("") : raw;
+    return `#${full.toUpperCase()}`;
+}
+function normFont(v, fallback) {
+    const key = (v ?? "").toLowerCase().replace(/[^a-z]/g, "");
+    return (posterAgent_schema_1.POSTER_FONT_FAMILIES.find((f) => f.toLowerCase().replace(/[^a-z]/g, "") === key) ?? fallback);
+}
+function normEnum(v, allowed, fallback) {
+    const s = (v ?? "").trim().toLowerCase();
+    return allowed.includes(s) ? s : fallback;
+}
+const clip = (s, n) => {
+    const t = (s ?? "").trim();
+    return t ? t.slice(0, n) : undefined;
+};
+function repairVariant(v, mode) {
+    const details = (v.copy.details ?? [])
+        .map((d) => d.trim().slice(0, 60))
+        .filter(Boolean)
+        .slice(0, 5);
+    const negative = mode === "editable"
+        ? clip([v.negativePrompt, "text, letters, words, typography, watermark, logo, signature"]
+            .filter(Boolean)
+            .join(", "), 400)
+        : clip(v.negativePrompt, 400);
+    return posterAgent_schema_1.PosterVariantPlanSchema.parse({
+        concept: clip(v.concept, 160) ?? "Poster concept",
+        layout: normEnum(v.layout, posterAgent_schema_1.POSTER_LAYOUT_IDS, "hero-top"),
+        palette: {
+            background: normHex(v.palette.background, "#111111"),
+            primary: normHex(v.palette.primary, "#FFFFFF"),
+            accent: normHex(v.palette.accent, "#7C3AED"),
+            text: normHex(v.palette.text, "#F5F5F5"),
+            onAccent: normHex(v.palette.onAccent, "#FFFFFF"),
+        },
+        typography: {
+            headingFont: normFont(v.typography.headingFont, "Anton"),
+            bodyFont: normFont(v.typography.bodyFont, "Inter"),
+            headingCase: normEnum(v.typography.headingCase, ["upper", "title", "sentence"], "title"),
+        },
+        copy: {
+            headline: clip(v.copy.headline, 80) ?? "Untitled",
+            ...(clip(v.copy.subheadline, 140) ? { subheadline: clip(v.copy.subheadline, 140) } : {}),
+            ...(clip(v.copy.body, 260) ? { body: clip(v.copy.body, 260) } : {}),
+            ...(clip(v.copy.cta, 32) ? { cta: clip(v.copy.cta, 32) } : {}),
+            ...(details.length ? { details } : {}),
+            ...(clip(v.copy.footer, 100) ? { footer: clip(v.copy.footer, 100) } : {}),
+        },
+        scrim: mode === "flat" ? "none" : normEnum(v.scrim, ["none", "soft", "strong"], "soft"),
+        imagePrompt: (v.imagePrompt ?? "").trim().slice(0, 2400),
+        ...(negative ? { negativePrompt: negative } : {}),
+    });
+}
+function variantProblems(v, i, mode) {
+    const p = [];
+    if (!v.copy.headline?.trim())
+        p.push(`variant ${i}: headline is empty.`);
+    if ((v.imagePrompt ?? "").trim().length < 40)
+        p.push(`variant ${i}: imagePrompt is too thin — describe subject, style, lighting, composition.`);
+    if (mode === "flat" && v.copy.headline && !v.imagePrompt.includes(v.copy.headline.trim().slice(0, 12))) {
+        p.push(`variant ${i}: flat mode — the imagePrompt must quote the headline exactly.`);
+    }
+    if (!posterAgent_schema_1.POSTER_LAYOUT_IDS.includes(v.layout))
+        p.push(`variant ${i}: unknown layout "${v.layout}".`);
+    return p;
+}
+// ── Public API ────────────────────────────────────────────────────────────
+async function planPosterCore(llm, args) {
+    const { request, brand } = args;
+    const router = new modelRouter_1.ModelRouter();
+    const maxRetries = args.maxRetries ?? 1;
+    let feedback;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const res = await llm.structured({
+            model: router.pickFor("planner"),
+            fallbackModel: router.fallbackFor("planner"),
+            schema: LoosePlanSchema,
+            schemaName: "PosterPlan",
+            messages: buildPlanMessages(request, brand, feedback),
+            temperature: 0.8,
+            maxTokens: 6000,
+        });
+        const loose = res.data;
+        const variantsIn = loose.variants.slice(0, request.variants);
+        const problems = variantsIn.flatMap((v, i) => variantProblems(v, i, request.mode));
+        if (problems.length && attempt < maxRetries) {
+            feedback = problems.join("\n");
+            logger_1.logger.warn("poster.planner: retrying", { attempt, problems });
+            continue;
+        }
+        const useCase = request.useCase ??
+            normEnum(loose.useCase, posterAgent_schema_1.POSTER_USE_CASE_IDS, "announcement");
+        const format = request.format ?? posterAgent_schema_1.POSTER_USE_CASES[useCase].format;
+        const plan = posterAgent_schema_1.PosterPlanSchema.parse({
+            useCase,
+            mode: request.mode,
+            format,
+            imageAspect: (0, posterAgent_schema_1.nearestPosterAspect)(format),
+            audience: clip(loose.audience, 160) ?? "",
+            goal: clip(loose.goal, 160) ?? "",
+            tone: clip(loose.tone, 80) ?? "",
+            variants: variantsIn.map((v) => repairVariant(v, request.mode)),
+        });
+        logger_1.logger.info("poster.planner: plan accepted", {
+            attempt,
+            useCase,
+            mode: request.mode,
+            variants: plan.variants.length,
+            imperfect: problems.length > 0,
+        });
+        return plan;
+    }
+    // Unreachable: the final attempt always returns above.
+    throw new Error("poster planner produced no plan");
+}
+async function refinePosterVariantCore(llm, args) {
+    const { plan, variantIndex, instruction, brand } = args;
+    const current = plan.variants[variantIndex];
+    if (!current)
+        throw new Error(`variant ${variantIndex} not found`);
+    const router = new modelRouter_1.ModelRouter();
+    const system = [
+        DESIGN_PRINCIPLES,
+        "",
+        modeInstructions(plan.mode),
+        "",
+        schemaLines(),
+        "",
+        "You are revising ONE existing poster variant based on the user's feedback.",
+        "Change only what the feedback asks for (plus anything required to keep the design coherent); keep everything else identical.",
+        "Keep `imagePrompt` byte-for-byte identical unless the artwork itself must change.",
+        plan.mode === "editable"
+            ? "Set `regenerateArt` to true ONLY if the artwork itself must change (subject, scene, style, lighting, composition/negative-space position because the layout moved). Copy, colors of text, fonts, CTA, scrim, or layout changes that keep the same negative space do NOT need new art → false."
+            : "Flat mode: any visible change requires a re-render, so `regenerateArt` is true unless the feedback asks for nothing visual.",
+        "`summary`: one short sentence telling the user what you changed.",
+    ].join("\n");
+    const user = [
+        `USE CASE: ${posterAgent_schema_1.POSTER_USE_CASES[plan.useCase].label}. Audience: ${plan.audience}. Goal: ${plan.goal}. Tone: ${plan.tone}.`,
+        `CURRENT VARIANT (JSON):\n${JSON.stringify(current, null, 2)}`,
+        `USER FEEDBACK: ${instruction}`,
+        args.hasReferenceImages ? "Reference image(s) of the user's product/subject are attached to the image model." : "",
+        brandLines(brand),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    const res = await llm.structured({
+        model: router.pickFor("planner"),
+        fallbackModel: router.fallbackFor("planner"),
+        schema: LooseRefineSchema,
+        schemaName: "PosterRefinement",
+        messages: [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ],
+        temperature: 0.4,
+        maxTokens: 3000,
+    });
+    const variant = repairVariant(res.data.variant, plan.mode);
+    // If the art prompt changed materially the art must follow, whatever the
+    // model claimed — otherwise a new prompt would silently never render.
+    const promptChanged = variant.imagePrompt.trim() !== current.imagePrompt.trim();
+    return {
+        variant,
+        regenerateArt: res.data.regenerateArt || promptChanged,
+        summary: (res.data.summary ?? "").trim().slice(0, 240) || "Updated the poster.",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vidspotai-shared",
-  "version": "1.0.118",
+  "version": "1.0.120",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {
@@ -13,10 +13,6 @@
   "files": [
     "lib"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "watch": "tsc -p tsconfig.json --watch"
-  },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.98.0",
     "@aws-sdk/client-s3": "^3.1119.0",
@@ -49,5 +45,9 @@
   "peerDependencies": {
     "firebase-admin": "^13.5.0",
     "ioredis": "^5.8.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc -p tsconfig.json --watch"
   }
-}
+}