@drawnagency/primitives 0.1.87 → 0.1.89

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/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/registry.ts

@@ -176,6 +176,12 @@ export interface SectionDefinition<T = unknown> {
    * top-level `description`. Presentation/metadata only — not validated.
    */
   authoringNote?: string;
+  /**
+   * When true, this section must run client-side on the viewer page: the viewer
+   * renderer hydrates it as an Astro island (`client:visible`) instead of
+   * emitting static HTML. Opt-in per type; default (absent/false) stays zero-JS.
+   */
+  interactive?: boolean;
 }
 
 // --- defineSection ---
@@ -204,6 +210,7 @@ type DefineSectionInput<S extends ZodType> = {
   settingsTabs?: { label: string; fields: string[] }[];
   presets?: SectionPreset[];
   authoringNote?: string;
+  interactive?: boolean;
 };
 
 export function defineSection<S extends ZodType>(

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

@@ -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>;