@drawnagency/primitives 0.1.88 → 0.1.90

package/src/components/shell/SiteSettingsChatbot.tsx

@@ -1,10 +1,22 @@
 import { useEffect, useState } from "react";
 import { Button } from "../shared/Button";
 import { cn } from "../../lib/cn";
+import { contrastColor } from "../../lib/contrast";
 import ChatPanel from "../chat/ChatPanel";
 import type { SiteConfig, ChatbotConfig, ChatbotTask } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 import { audiencePasses } from "../../lib/pages";
+import { resolveChatbotName, DEFAULT_CHATBOT_NAME } from "../../lib/chatbot";
+
+/** Comma-separated textarea → schema list: trimmed, blanks dropped, clamped
+ *  to the schema caps (30 phrases × 80 chars). */
+function parseThinkingPhrases(text: string): string[] {
+  return text
+    .split(",")
+    .map((s) => s.trim().slice(0, 80))
+    .filter(Boolean)
+    .slice(0, 30);
+}
 
 interface Props {
   siteConfig: SiteConfig;
@@ -24,7 +36,7 @@ function AudienceChips({ audiences, selected, onToggle }: { audiences: Audience[
         <button key={a.name} type="button" onClick={() => onToggle(a.name)}
           className={cn("rounded-full border px-2 py-0.5 text-xs",
             selected.includes(a.name) ? "border-primary bg-primary text-primary-contrast" : "border-base-200 bg-base-accent text-base-contrast")}
-          style={a.color && selected.includes(a.name) ? { backgroundColor: a.color, borderColor: a.color } : undefined}>
+          style={a.color && selected.includes(a.name) ? { backgroundColor: a.color, borderColor: a.color, color: contrastColor(a.color) } : undefined}>
           {a.displayName}
         </button>
       ))}
@@ -38,6 +50,9 @@ export function SiteSettingsChatbot({ siteConfig, onSiteConfigChange, audiences,
   const [newTaskLabel, setNewTaskLabel] = useState("");
   const [showTest, setShowTest] = useState(false);
   const [previewAudience, setPreviewAudience] = useState("");
+  // Local text mirror of thinkingPhrases: parsing on every keystroke while
+  // round-tripping through the array would fight trailing commas/spaces.
+  const [thinkingText, setThinkingText] = useState(() => (chatbot.thinkingPhrases ?? []).join(", "));
 
   // A deselected audience can no longer chat — never keep simulating it.
   useEffect(() => {
@@ -77,6 +92,10 @@ export function SiteSettingsChatbot({ siteConfig, onSiteConfigChange, audiences,
     const v = chatbot.audiencePrompts[name];
     return typeof v === "string" ? v : "";
   };
+  const audienceNameValue = (name: string) => {
+    const v = chatbot.audienceNames?.[name];
+    return typeof v === "string" ? v : "";
+  };
 
   return (
     <div className="flex flex-col gap-4">
@@ -94,12 +113,39 @@ export function SiteSettingsChatbot({ siteConfig, onSiteConfigChange, audiences,
         Show the chat widget to viewers
       </label>
 
+      <div>
+        <label htmlFor="chatbot-name" className="mb-1 block text-sm font-medium text-base-contrast">Assistant name</label>
+        <input id="chatbot-name" aria-label="Assistant name" maxLength={60} value={chatbot.name}
+          onChange={(e) => patch({ name: e.target.value })}
+          placeholder={DEFAULT_CHATBOT_NAME}
+          className="w-full rounded border border-base-200 bg-base px-2 py-1 text-sm text-base-contrast" />
+        <p className="mt-1 text-xs text-base-contrast-light">Shown in the widget header. Leave blank for “{DEFAULT_CHATBOT_NAME}”. Audiences can override it below.</p>
+      </div>
+
+      <div>
+        <label htmlFor="chatbot-thinking-phrases" className="mb-1 block text-sm font-medium text-base-contrast">Thinking phrases</label>
+        <textarea id="chatbot-thinking-phrases" aria-label="Thinking phrases" rows={2}
+          value={thinkingText}
+          onChange={(e) => { setThinkingText(e.target.value); patch({ thinkingPhrases: parseThinkingPhrases(e.target.value) }); }}
+          placeholder="Mixing the palette, Checking the guide, Consulting the brand book"
+          className="w-full rounded border border-base-200 bg-base px-2 py-1 text-sm text-base-contrast" />
+        <p className="mt-1 text-xs text-base-contrast-light">Comma-separated; one is shown at random while the assistant thinks, with “…” added automatically. Leave blank for “Thinking…”.</p>
+      </div>
+
       <div>
         <p className="mb-1 text-sm font-medium text-base-contrast">Audiences</p>
         <p className="mb-2 text-xs text-base-contrast-light">Who sees the widget — only the selected audiences; none selected means no one.</p>
         <AudienceChips audiences={audiences} selected={chatbot.audiences} onToggle={(n) => patch({ audiences: toggleName(chatbot.audiences, n) })} />
         {chatbot.audiences.map((name) => (
           <div key={name} className="mt-2">
+            <label htmlFor={`audience-name-${name}`} className="mb-1 block text-xs font-medium text-base-contrast">
+              Assistant name for {name}
+            </label>
+            <input id={`audience-name-${name}`} aria-label={`Assistant name for ${name}`} maxLength={60}
+              value={audienceNameValue(name)}
+              onChange={(e) => patch({ audienceNames: { ...chatbot.audienceNames, [name]: e.target.value } })}
+              placeholder={resolveChatbotName(chatbot, null)}
+              className="mb-1 w-full rounded border border-base-200 bg-base px-2 py-1 text-sm text-base-contrast" />
             <label htmlFor={`audience-prompt-${name}`} className="mb-1 block text-xs font-medium text-base-contrast">
               Additional guidance for {name}
             </label>
@@ -175,6 +221,8 @@ export function SiteSettingsChatbot({ siteConfig, onSiteConfigChange, audiences,
         {showTest && platformEnabled && (
           <ChatPanel
             open onClose={() => setShowTest(false)} siteName={siteConfig.siteName}
+            botName={resolveChatbotName(chatbot, previewAudience || null)}
+            thinkingPhrases={chatbot.thinkingPhrases}
             tasks={chatbot.tasks
               .filter((t) => previewAudience === "" || audiencePasses(t.access, previewAudience))
               .map((t) => ({ id: t.id, label: t.label }))}

package/src/hooks/useBuildStatus.ts

@@ -23,6 +23,14 @@ const FADE_DURATION = 1000;
 // whose deploy was never confirmed (e.g. superseded by a later build) — show
 // idle rather than a phantom in-progress publish.
 const STALE_BUILD_MS = 15 * 60 * 1000;
+// Hard cap on an ACTIVE tracking session. Completion normally arrives via a terminal
+// poll (ready/error), which the Netlify webhook writes to the deploy-status row. If
+// that signal is lost/delayed (webhook dropped or unconfigured) the row stays
+// "building" forever and the elapsed counter would climb indefinitely. This backstop
+// stops the runaway counter and hides the indicator after the cap — the same "a build
+// shouldn't run longer than this" invariant as STALE_BUILD_MS, applied to the live
+// session rather than only on mount.
+const MAX_TRACKING_MS = STALE_BUILD_MS;
 
 export function useBuildStatus(): BuildStatusResult {
   const [state, setState] = useState<BuildState>("idle");
@@ -31,6 +39,7 @@ export function useBuildStatus(): BuildStatusResult {
   const clearRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const fadeRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const timerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const giveUpRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const isPolling = useRef(false);
   const mountedRef = useRef(true);
 
@@ -52,6 +61,23 @@ export function useBuildStatus(): BuildStatusResult {
     isPolling.current = false;
   }, []);
 
+  const clearGiveUp = useCallback(() => {
+    if (giveUpRef.current) { clearTimeout(giveUpRef.current); giveUpRef.current = null; }
+  }, []);
+
+  // Arm the runaway backstop: if the cap elapses before a terminal signal, stop
+  // polling + the timer and drop back to idle (hide the indicator). `elapsedMs` lets a
+  // build already in progress at mount count against the same absolute cap.
+  const armGiveUp = useCallback((elapsedMs = 0) => {
+    clearGiveUp();
+    giveUpRef.current = setTimeout(() => {
+      if (!mountedRef.current) return;
+      stopPolling();
+      stopTimer();
+      setState("idle");
+    }, Math.max(0, MAX_TRACKING_MS - elapsedMs));
+  }, [clearGiveUp, stopPolling, stopTimer]);
+
   const fetchStatus = useCallback(async (): Promise<BuildStatusResponse | null> => {
     try {
       const res = await fetch("/api/build-status");
@@ -86,6 +112,7 @@ export function useBuildStatus(): BuildStatusResult {
       if (data.state === "ready" || data.state === "error") {
         stopPolling();
         stopTimer();
+        clearGiveUp();
         if (data.state === "ready") {
           clearRef.current = setTimeout(() => {
             if (!mountedRef.current) return;
@@ -98,7 +125,7 @@ export function useBuildStatus(): BuildStatusResult {
         }
       }
     },
-    [stopPolling, stopTimer],
+    [stopPolling, stopTimer, clearGiveUp],
   );
 
   const startPolling = useCallback(() => {
@@ -130,6 +157,7 @@ export function useBuildStatus(): BuildStatusResult {
         // counts real elapsed time instead of sitting frozen at 0:00.
         startTimer(Number.isFinite(ageMs) ? Math.max(0, Math.floor(ageMs / 1000)) : 0);
         startPolling();
+        armGiveUp(Number.isFinite(ageMs) ? ageMs : 0);
         return;
       }
 
@@ -143,24 +171,27 @@ export function useBuildStatus(): BuildStatusResult {
       mountedRef.current = false;
       stopPolling();
       stopTimer();
+      clearGiveUp();
       if (clearRef.current) clearTimeout(clearRef.current);
       if (fadeRef.current) clearTimeout(fadeRef.current);
     };
-  }, [fetchStatus, handleStatusUpdate, startPolling, startTimer, stopPolling, stopTimer]);
+  }, [fetchStatus, handleStatusUpdate, startPolling, startTimer, stopPolling, stopTimer, armGiveUp, clearGiveUp]);
 
   const startTracking = useCallback(() => {
     if (clearRef.current) { clearTimeout(clearRef.current); clearRef.current = null; }
     setState("building");
     startTimer();
     startPolling();
-  }, [startPolling, startTimer]);
+    armGiveUp(0);
+  }, [startPolling, startTimer, armGiveUp]);
 
   const dismiss = useCallback(() => {
     if (clearRef.current) { clearTimeout(clearRef.current); clearRef.current = null; }
     setState("idle");
     stopPolling();
     stopTimer();
-  }, [stopPolling, stopTimer]);
+    clearGiveUp();
+  }, [stopPolling, stopTimer, clearGiveUp]);
 
   return { state, elapsedSeconds, startTracking, dismiss };
 }

package/src/hooks/useMediaPipeline.ts

@@ -76,6 +76,7 @@ export function useMediaPipeline({
   // Display-folder target per in-flight upload, keyed by content hash. Set at
   // enqueue time, consumed when the processing queue finalizes the item.
   const uploadTargetsRef = useRef<Map<string, string | null>>(new Map());
+  const hiddenUploadsRef = useRef<Map<string, boolean>>(new Map());
   const destroyedRef = useRef(false);
 
   // Shared persistence path for every pending media item — the processing
@@ -171,10 +172,12 @@ export function useMediaPipeline({
               alt: "",
               storage: "github",
               ...(targetFolderId ? { folderId: targetFolderId } : {}),
+              ...(hiddenUploadsRef.current.get(event.item.hash) ? { hidden: true } : {}),
             };
 
             const persisted = await finalizePendingMedia(item, localUrls, blobsMap);
             uploadTargetsRef.current.delete(event.item.hash);
+            hiddenUploadsRef.current.delete(event.item.hash);
             if (!persisted) return;
 
             const callback = uploadCallbacksRef.current.get(event.item.hash);
@@ -603,7 +606,7 @@ export function useMediaPipeline({
 
   // --- Unified enqueue ---
 
-  const enqueueFile = useCallback((file: File, onComplete?: (imageId: string) => void) => {
+  const enqueueFile = useCallback((file: File, onComplete?: (imageId: string) => void, opts?: { hidden?: boolean }) => {
     if (!siteConfig) return;
     const mediaConfig = siteConfig.media;
     if (file.size > mediaConfig.maxFileSize) return;
@@ -627,6 +630,7 @@ export function useMediaPipeline({
         if (onComplete) {
           uploadCallbacksRef.current.set(hash, onComplete);
         }
+        if (opts?.hidden) hiddenUploadsRef.current.set(hash, true);
 
         let kind: "image" | "animated" | "video" = "image";
         if (file.type === "image/gif" || file.type === "image/apng") kind = "animated";
@@ -646,12 +650,12 @@ export function useMediaPipeline({
       // Placeholder — EditorShell overrides this
     },
     uploadFile: (file: File) => handleMediaUpload([file]),
-    uploadFileWithCallback: (file: File, onComplete: (imageId: string) => void) => {
+    uploadFileWithCallback: (file: File, onComplete: (imageId: string) => void, opts?: { hidden?: boolean }) => {
       const blobUrl = URL.createObjectURL(file);
       enqueueFile(file, (imageId) => {
         URL.revokeObjectURL(blobUrl);
         onComplete(imageId);
-      });
+      }, opts);
       return blobUrl;
     },
     reportRejectedUploads: () => {

package/src/lib/authoring-defaults.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { StatusSchema } from "../schemas/site-config";
+import type { Audience } from "../auth/types";
+
+export const AuthoringDefaultsSchema = z.object({
+  status: StatusSchema,
+  access: z.array(z.string()),
+});
+
+export type AuthoringDefaults = z.infer<typeof AuthoringDefaultsSchema>;
+
+export const FALLBACK_AUTHORING_DEFAULTS: AuthoringDefaults = { status: "draft", access: [] };
+
+// Per-origin key — every client site is its own domain, so the preference is
+// automatically per-site.
+const STORAGE_KEY = "portal-authoring-defaults";
+
+export function loadAuthoringDefaults(): AuthoringDefaults {
+  if (typeof localStorage === "undefined") return FALLBACK_AUTHORING_DEFAULTS;
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return FALLBACK_AUTHORING_DEFAULTS;
+    return AuthoringDefaultsSchema.parse(JSON.parse(raw));
+  } catch {
+    return FALLBACK_AUTHORING_DEFAULTS;
+  }
+}
+
+export function saveAuthoringDefaults(defaults: AuthoringDefaults): void {
+  if (typeof localStorage === "undefined") return;
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(defaults));
+  } catch {
+    // Quota/private-mode failures just lose the preference.
+  }
+}
+
+// Stored default audiences can outlive the audiences themselves — drop any
+// name the site no longer has before stamping it onto a new section's access.
+export function filterAccessToKnown(access: string[], audiences: Audience[]): string[] {
+  return access.filter((name) => audiences.some((a) => a.name === name));
+}

package/src/lib/chatbot.ts

@@ -0,0 +1,30 @@
+// Pure, browser-safe chatbot display helpers shared by the viewer page
+// (server-side name resolution), brand-chat prompt assembly, and the widget.
+import type { ChatbotConfig } from "../schemas/site-config";
+
+export const DEFAULT_CHATBOT_NAME = "Portal Assistant";
+
+/** Resolve the assistant's display name for an audience (null = base name).
+ *  Record lookups can hit inherited Object.prototype members ("constructor"
+ *  is a legal audience name) — anything non-string, and blank strings,
+ *  behave as absent. */
+export function resolveChatbotName(
+  // Partial: pre-migration configs (and test fixtures) may predate the fields.
+  chatbot: Partial<Pick<ChatbotConfig, "name" | "audienceNames">>,
+  audience: string | null,
+): string {
+  const perAudience = audience !== null ? chatbot.audienceNames?.[audience] : undefined;
+  if (typeof perAudience === "string" && perAudience.trim()) return perAudience.trim();
+  if (typeof chatbot.name === "string" && chatbot.name.trim()) return chatbot.name.trim();
+  return DEFAULT_CHATBOT_NAME;
+}
+
+/** The widget's waiting phrases with "…" appended; falls back to "Thinking…". */
+export function resolveThinkingPhrases(phrases: readonly string[] | undefined): string[] {
+  const list = (phrases ?? [])
+    .filter((p): p is string => typeof p === "string")
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => `${p}…`);
+  return list.length > 0 ? list : ["Thinking…"];
+}

package/src/lib/container-grid.ts

@@ -42,6 +42,20 @@ export const gapClass: Record<string, string> = {
   lg: "gap-8",
 };
 
+/**
+ * Column count -> `columns-N` classes for masonry (CSS multi-column), mirroring
+ * `containerGridClass`'s collapse curve (`grid-cols-`→`columns-`). Full static
+ * strings so Tailwind's source scan generates them.
+ */
+export const masonryColumnsClass: Record<number, string> = {
+  1: "columns-1",
+  2: "columns-1 @sm:columns-2",
+  3: "columns-1 @sm:columns-2 @lg:columns-3",
+  4: "columns-1 @xs:columns-2 @lg:columns-4",
+  5: "columns-1 @xs:columns-2 @md:columns-3 @xl:columns-5",
+  6: "columns-1 @xs:columns-2 @md:columns-3 @2xl:columns-6",
+};
+
 /**
  * Per-column-count container-query classes that HIDE a spacer cell once the container
  * collapses to a single column (mobile). Mirrors `containerGridClass`'s collapse curve:

package/src/lib/contrast.ts

@@ -9,3 +9,15 @@ export function deriveContrast(hex: string): string {
   const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
   return luminance >= 0.5 ? "#1a1a1a" : "#f0f0f0";
 }
+
+/**
+ * Perceived-luminance contrast pick (same YIQ formula the admin dashboard
+ * uses). Returns near-black for light backgrounds, white for dark ones.
+ */
+export function contrastColor(hex: string): "#1a1a1a" | "#ffffff" {
+  const h = hex.replace("#", "");
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  return (r * 299 + g * 587 + b * 114) / 1000 > 150 ? "#1a1a1a" : "#ffffff";
+}

package/src/lib/index.ts

@@ -1,8 +1,9 @@
 export { env } from "./env";
 export { cn } from "./cn";
 export { audiencePasses } from "./pages";
+export { resolveChatbotName, resolveThinkingPhrases, DEFAULT_CHATBOT_NAME } from "./chatbot";
 export { generateNavLinks, toSectionId, type NavItem } from "./nav";
-export { deriveContrast } from "./contrast";
+export { deriveContrast, contrastColor } from "./contrast";
 export { sanitizeHtml, ensureSanitizer } from "./sanitize";
 export { gridColsClass } from "./grid";
 export { getIcon, curatedIcons, type IconEntry } from "./icons";

package/src/lib/migrate-sections-transform.ts

@@ -99,7 +99,8 @@ function upgradeGrid(section: Obj): Obj {
     type: "container",
     content: {
       columns: content.columns,
-      flow: "row",
+      layout: "grid",
+      equalizeRowHeight: false,
       children: media.map((item, i) => mapRefItem(item, id, i)),
     },
   };
@@ -126,7 +127,7 @@ function upgradeSplitContent(section: Obj): Obj {
   };
   const children = options.imagePosition === "right" ? [proseChild, mediaChild] : [mediaChild, proseChild];
 
-  const out: Obj = { id, type: "container", content: { columns: 2, flow: "row", children } };
+  const out: Obj = { id, type: "container", content: { columns: 2, layout: "grid", equalizeRowHeight: false, children } };
   if (section.layout !== undefined) out.layout = section.layout;
   return out;
 }
@@ -163,7 +164,8 @@ function upgradeDoDont(section: Obj): Obj {
     type: "container",
     content: {
       columns: 2,
-      flow: "row",
+      layout: "grid",
+      equalizeRowHeight: false,
       children: [
         dodontChild(doItems, id, 0, "do", childOptions),
         dodontChild(dontItems, id, 1, "dont", childOptions),

package/src/media/compose-preview.ts

@@ -0,0 +1,90 @@
+export interface PreviewImageInputs {
+  /** "logo" draws the resolved logo centered on a solid black/white bg;
+   *  "text" draws the site name in the heading font on the solid brand color. */
+  mode: "logo" | "text";
+  /** Solid background color: black/white for logo mode, brand color for text mode. */
+  background: string;
+  /** Loadable URL of the chosen logo variant (logo mode only). */
+  logoUrl: string | null;
+  /** Apply a CSS invert filter to the logo (dark bg + invertInDark, no dark variant). */
+  invertLogo: boolean;
+  siteName: string;
+  headingFont: string;
+  /** Computed contrasting text color (text mode). */
+  textColor: string;
+}
+
+const WIDTH = 1200;
+const HEIGHT = 630;
+
+/**
+ * Composes the 1200×630 social-preview raster in the browser (Canvas API only,
+ * no dependency). Returns a WebP blob. Must run client-side (uses document/Image
+ * and, for text mode, document.fonts). Falls back to the text treatment if the
+ * logo image fails to load.
+ */
+export async function composePreviewImage(inputs: PreviewImageInputs): Promise<Blob> {
+  const canvas = document.createElement("canvas");
+  canvas.width = WIDTH;
+  canvas.height = HEIGHT;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("2D canvas context unavailable");
+
+  ctx.fillStyle = inputs.background;
+  ctx.fillRect(0, 0, WIDTH, HEIGHT);
+
+  let drewLogo = false;
+  if (inputs.mode === "logo" && inputs.logoUrl) {
+    try {
+      const img = await loadImage(inputs.logoUrl);
+      // An SVG (or any image) with no intrinsic size yields width/height 0, which
+      // would make scale Infinity and drawImage silently paint nothing while
+      // drewLogo stays true — a blank solid-color card with no text fallback.
+      // Throw here so control drops to the catch below and the text treatment runs.
+      if (!(img.width > 0 && img.height > 0)) {
+        throw new Error("Logo image has no intrinsic size");
+      }
+      const maxW = WIDTH * 0.6;
+      const maxH = HEIGHT * 0.5;
+      const scale = Math.min(maxW / img.width, maxH / img.height);
+      const w = img.width * scale;
+      const h = img.height * scale;
+      ctx.filter = inputs.invertLogo ? "invert(1)" : "none";
+      ctx.drawImage(img, (WIDTH - w) / 2, (HEIGHT - h) / 2, w, h);
+      ctx.filter = "none";
+      drewLogo = true;
+    } catch {
+      // fall through to text treatment
+    }
+  }
+
+  if (!drewLogo) {
+    if (document.fonts?.ready) await document.fonts.ready;
+    // fillText doesn't itself trigger a font load — explicitly load the exact
+    // weight/family used below so it's available before we draw.
+    await document.fonts.load(`600 84px ${inputs.headingFont}`).catch(() => {});
+    ctx.fillStyle = inputs.textColor;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.font = `600 84px ${inputs.headingFont}, system-ui, sans-serif`;
+    ctx.fillText(inputs.siteName, WIDTH / 2, HEIGHT / 2, WIDTH * 0.86);
+  }
+
+  return await new Promise<Blob>((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => (blob ? resolve(blob) : reject(new Error("toBlob returned null"))),
+      "image/webp",
+      0.9,
+    );
+  });
+}
+
+function loadImage(url: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error(`failed to load ${url}`));
+    img.src = url;
+  });
+}

package/src/media/index.ts

@@ -6,6 +6,7 @@ export * from "./utils";
 export * from "./queue";
 export * from "./resolve";
 export { generateVideoPoster } from "./videoPoster";
+export { composePreviewImage, type PreviewImageInputs } from "./compose-preview";
 
 const MEDIA_KEY = Symbol.for("@drawnagency/primitives/media");
 const _g = globalThis as Record<symbol, MediaProvider | null>;

package/src/media/preview-inputs.ts

@@ -0,0 +1,77 @@
+import type { SiteConfig } from "../schemas/site-config";
+import { contrastColor } from "../lib/contrast";
+import type { PreviewImageInputs } from "./compose-preview";
+
+/**
+ * Derives the canvas composition inputs from a SiteConfig, plus a signature
+ * string over only the composition-relevant fields (so the editor recomposes
+ * when brand inputs change but not for unrelated edits like `description`).
+ *
+ * `resolveLogoUrl` maps a logo imageId to a loadable URL (or null if it can't
+ * be resolved yet); the caller supplies it so this stays pure/testable.
+ *
+ * With-logo background/variant rules (static raster; darkMode "optional" bakes
+ * the light default since a baked image can't follow the viewer's theme):
+ *   light | optional -> white bg + light variant
+ *   dark             -> black bg + (dark variant ?? invert(light) if invertInDark ?? light)
+ */
+export function derivePreviewInputs(
+  siteConfig: SiteConfig,
+  resolveLogoUrl: (imageId: string) => string | null,
+): { inputs: PreviewImageInputs; signature: string } {
+  const { logo, darkMode, primaryColor, siteName, headingFont } = siteConfig;
+  const dark = darkMode === "dark";
+
+  let mode: "logo" | "text" = "text";
+  let logoUrl: string | null = null;
+  let invertLogo = false;
+
+  if (logo) {
+    if (dark && logo.dark) {
+      logoUrl = resolveLogoUrl(logo.dark.imageId);
+    } else {
+      logoUrl = resolveLogoUrl(logo.light.imageId);
+      invertLogo = dark && !logo.dark && logo.invertInDark;
+    }
+    if (logoUrl) mode = "logo";
+  }
+
+  const inputs: PreviewImageInputs = {
+    mode,
+    background: mode === "logo" ? (dark ? "#000000" : "#ffffff") : primaryColor,
+    logoUrl,
+    invertLogo,
+    siteName,
+    headingFont,
+    textColor: contrastColor(primaryColor),
+  };
+
+  const signature = JSON.stringify({
+    mode: inputs.mode,
+    background: inputs.background,
+    logoUrl: inputs.logoUrl,
+    invertLogo: inputs.invertLogo,
+    siteName: inputs.siteName,
+    headingFont: inputs.headingFont,
+    textColor: inputs.textColor,
+  });
+
+  return { inputs, signature };
+}
+
+const PREVIEW_WIDTH = 1200;
+const PREVIEW_HEIGHT = 630;
+
+/**
+ * The actual largest variant width/height the /api/media route will serve for
+ * the 1200×630 preview, mirroring media/worker.ts: variants are generated for
+ * each configured size ≤ source width; if none qualify, the source width is
+ * used. The route 404s any non-variant width, so URLs must use this width.
+ * NOTE: keep in sync with worker.ts's applicableSizes logic.
+ */
+export function servedPreviewSize(sizes: number[]): { width: number; height: number } {
+  const applicable = sizes.filter((s) => s <= PREVIEW_WIDTH);
+  const width = applicable.length ? Math.max(...applicable) : PREVIEW_WIDTH;
+  const height = Math.round((PREVIEW_HEIGHT * width) / PREVIEW_WIDTH);
+  return { width, height };
+}

package/src/schemas/media.ts

@@ -41,6 +41,9 @@ export const MediaItemSchema = z.object({
   // Display folder (MediaFolderSchema key). Absent = root/unfiled. NOT the
   // git storage dir — that's `folder` above, which never changes.
   folderId: z.string().optional(),
+  // System-generated assets (e.g. the Phase 3 social-preview raster) set this
+  // so the media-library UI can exclude them. Absent on all user uploads.
+  hidden: z.boolean().optional(),
 });
 
 export type MediaItem = z.infer<typeof MediaItemSchema>;

package/src/schemas/site-config.ts

@@ -7,7 +7,7 @@ import { CORNER_RADIUS_OPTIONS } from "../lib/corner-radius";
 // document options block onto PageSchema.
 import { documentOptionsSchema } from "../document/engine/settings";
 
-const StatusSchema = z.enum(["draft", "live", "archived", "published"]).transform(
+export const StatusSchema = z.enum(["draft", "live", "archived", "published"]).transform(
   (val) => val === "published" ? "live" as const : val,
 );
 
@@ -164,6 +164,15 @@ export type ChatbotTask = z.infer<typeof ChatbotTaskSchema>;
 export const ChatbotConfigSchema = z
   .object({
     enabled: z.boolean().default(false),
+    // Assistant display name shown in the widget header and used in the system
+    // prompt. Blank falls back to "Portal Assistant" (resolveChatbotName).
+    name: z.string().max(60).default("Portal Assistant"),
+    // Per-audience name overrides, keyed by audience name — same inert-when-
+    // deselected semantics as audiencePrompts.
+    audienceNames: z.record(z.string(), z.string().max(60)).default({}),
+    // Brand-flavored waiting phrases, shown (with "…" appended) while the
+    // assistant streams no text yet. Empty = the widget's "Thinking…" default.
+    thinkingPhrases: z.array(z.string().max(80)).max(30).default([]),
     systemPrompt: z.string().max(8_000).default(""),
     // Audience names the widget is shown to — strict opt-in: [] = no viewer
     // sees it (editors always can via /edit). Gates: [...slug].astro + /api/chat.
@@ -225,10 +234,26 @@ export const SiteConfigSchema = z.object({
     .nullable()
     .default(null),
   media: MediaConfigSchema.default(MediaConfigSchema.parse({})),
+  // Composed social-preview raster, stored as a media-library reference so it
+  // participates in usage tracking + GC protection. Composed client-side at
+  // save time (Phase 3). `width`/`height` are the ACTUAL served variant size
+  // (the /api/media route only serves exact generated-variant widths), so the
+  // og:image URL + dimensions are correct. Defaults null so pre-existing
+  // configs keep parsing and sites without a preview emit no og:image tags.
+  previewImage: z
+    .object({
+      imageId: z.string(),
+      width: z.number().int().positive(),
+      height: z.number().int().positive(),
+    })
+    .nullable()
+    .default(null),
+  // Optional site description → og:description + <meta name="description">.
+  description: z.string().max(300).nullable().default(null),
   // Brand chatbot config (editor-owned; the platform kill switch lives in the
   // sites table, not here). Every field defaults so pre-existing
   // site-config.json files keep parsing.
-  chatbot: ChatbotConfigSchema.default({ enabled: false, systemPrompt: "", audiences: [], tasks: [], audiencePrompts: {} }),
+  chatbot: ChatbotConfigSchema.default({ enabled: false, name: "Portal Assistant", audienceNames: {}, thinkingPhrases: [], systemPrompt: "", audiences: [], tasks: [], audiencePrompts: {} }),
 });
 
 export type SiteConfig = z.infer<typeof SiteConfigSchema>;