@drawnagency/primitives 0.1.93 → 0.1.95

package/src/components/shell/EditorShell.tsx

@@ -37,7 +37,8 @@ import { SectionTypePicker } from "./SectionTypePicker";
 import { ensureSectionsRegistered } from "../sections/register";
 import { getSection, getAllSections, getSchema } from "../../lib/registry";
 import { cornerRadiusValue } from "../../lib/corner-radius";
-import { primaryVarValue, accentVarValue } from "../../lib/theme-vars";
+import { primaryVarValue, accentVarValue, onPrimaryVarValue } from "../../lib/theme-vars";
+import { rebaseMediaManifest } from "../../lib/media-folders";
 import { childInsertableTypes, insertChildAt } from "../../lib/container-ops";
 import { buildInsertMenuOptions, resolveInsertedContent } from "../../lib/insert-menu";
 
@@ -88,7 +89,7 @@ import { useBuildStatus } from "../../hooks/useBuildStatus";
 import { useMediaPipeline } from "../../hooks/useMediaPipeline";
 import { formatTimestamp } from "../../lib/timestamp";
 import { generateSiteNav } from "../../lib/nav";
-import { siteNavChangeEvent, pageSelectEvent, darkModeEvent, siteNameChangeEvent, historySelectEvent } from "../../lib/events";
+import { siteNavChangeEvent, pageSelectEvent, darkModeEvent, siteNameChangeEvent, historySelectEvent, historyRestoreEvent, historyRestoreFailedEvent, editorDirtyEvent } from "../../lib/events";
 import {
   homePage, pageById, pageBySlug, pageDisplayTitle, addSectionToPage, removeSectionFromPages,
   reorderSectionInPage, audiencePasses,
@@ -260,6 +261,10 @@ export default function EditorShell({
   // writes onto the latest config instead of a stale closure.
   const siteConfigRef = useRef<SiteConfig | null>(siteConfig);
   useEffect(() => { siteConfigRef.current = siteConfig; }, [siteConfig]);
+  // Mirrors mediaManifest so recoverConflict can rebase it synchronously and the
+  // immediate 409 retry assembles the saved manifest against the rebased copy.
+  const mediaManifestRef = useRef<MediaManifest>(mediaManifest);
+  useEffect(() => { mediaManifestRef.current = mediaManifest; }, [mediaManifest]);
   // Guards the debounced preview-image composition effect (below): skips
   // recomposing on the very first run when a preview already exists, and
   // dedupes concurrent runs against the same composition signature.
@@ -487,6 +492,11 @@ export default function EditorShell({
         if (applied.droppedDirtyIds.length > 0) await deleteSectionRows(applied.droppedDirtyIds);
       }
 
+      const rebasedManifest = remote.mediaManifest
+        ? rebaseMediaManifest(mediaManifestRef.current, remote.mediaManifest)
+        : null;
+      if (rebasedManifest) setMediaManifest(rebasedManifest);
+
       setSections(mergedSections);
       setSiteIndex(mergedIndex);
       setSavedSha(remote.savedBranchSha);
@@ -497,6 +507,7 @@ export default function EditorShell({
       // (and onBaselineCommitted reads the diff refs right after it), before
       // React flushes the setState calls above into their mirror effects.
       savedShaRef.current = remote.savedBranchSha;
+      if (rebasedManifest) mediaManifestRef.current = rebasedManifest;
       sectionsRef.current = mergedSections;
       siteIndexRef.current = mergedIndex;
       changedSectionIdsRef.current = new Set(remote.changedSectionIds);
@@ -581,6 +592,11 @@ export default function EditorShell({
       });
 
       // The rebased result goes into React state (live view)...
+      if (remote.mediaManifest) {
+        const rebasedManifest = rebaseMediaManifest(mediaManifestRef.current, remote.mediaManifest);
+        setMediaManifest(rebasedManifest);
+        mediaManifestRef.current = rebasedManifest;
+      }
       setSections(result.sections);
       setSiteIndex(result.index);
       setSavedSha(remote.savedBranchSha);
@@ -778,6 +794,7 @@ export default function EditorShell({
       focusedSectionIdRef.current = null;
     },
     mediaManifest,
+    mediaManifestRef,
     manifestDirty: mediaPipeline.manifestDirty,
     clearManifestDirty: () => mediaPipeline.setManifestDirty(false),
     pendingMediaItems: mediaPipeline.pendingMediaItems,
@@ -890,6 +907,7 @@ export default function EditorShell({
     const accentVar = accentVarValue(config);
     root.style.setProperty("--color-primary", primaryVar);
     root.style.setProperty("--color-primary-contrast", accentVar);
+    root.style.setProperty("--color-on-primary", onPrimaryVarValue(config));
     root.style.setProperty("--font-heading", `${config.headingFont}, system-ui, sans-serif`);
     root.style.setProperty("--font-body", `${config.bodyFont}, system-ui, sans-serif`);
     root.style.setProperty("--heading-text-transform", config.uppercaseHeadings ? "uppercase" : "none");
@@ -1456,12 +1474,42 @@ export default function EditorShell({
       if (!response.ok) throw new Error(`Restore failed: ${response.status}`);
       await discardLocalChanges();
       window.location.reload();
+      return true;
     } catch (err) {
       console.error("Failed to restore:", err);
       setIsRestoring(false);
+      return false;
     }
   }, []);
 
+  // Restore requested straight from the history navigator. The navigator has
+  // already confirmed with the user, so this loads the content at that sha and
+  // runs the same restore path the HistoryToolbar uses.
+  useEffect(() => {
+    return historyRestoreEvent.listen(async ({ sha }) => {
+      try {
+        const res = await fetch(`/api/content/history?sha=${sha}`);
+        if (!res.ok) throw new Error(`Failed to load version: ${res.status}`);
+        const data = await res.json();
+        const ok = await handleHistoryRestore({
+          sections: data.sections,
+          index: data.index,
+          siteConfig: data.siteConfig,
+        });
+        // On success the page reloads, so only a failure ever reaches here.
+        if (!ok) historyRestoreFailedEvent.dispatch({ message: "Couldn't publish the restore." });
+      } catch (err) {
+        console.error("Failed to restore from history:", err);
+        historyRestoreFailedEvent.dispatch({ message: "Couldn't load that version." });
+      }
+    });
+  }, [handleHistoryRestore]);
+
+  // Publish unsaved-draft state to the other islands (see editorDirtyEvent).
+  useEffect(() => {
+    editorDirtyEvent.dispatch({ hasUnsavedChanges: dirtySectionIds.size > 0 });
+  }, [dirtySectionIds]);
+
   // --- Render ---
 
   if (shellState.phase === "loading-content") {
@@ -2269,6 +2317,7 @@ function GlobalModal() {
       isOpen={modalState !== null}
       onClose={closeModal}
       title={modalState?.title ?? ""}
+      tabbed={modalState?.tabbed}
     >
       {modalState?.content}
     </EditorModal>

package/src/components/shell/SiteSettingsModal.tsx

@@ -106,7 +106,7 @@ export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigCha
   const tabItems = allTabs.filter((t) => t.show).map(({ id, label, content }) => ({ id, label, content }));
 
   return (
-    <EditorModal isOpen={isOpen} onClose={onClose} title="Site Settings" size="settings" noPadding>
+    <EditorModal isOpen={isOpen} onClose={onClose} title="Site Settings" size="settings" noPadding tabbed>
       <div className="flex flex-1 flex-col overflow-hidden">
         <Tabs tabs={tabItems} />
 

package/src/hooks/useEditorPublish.ts

@@ -70,6 +70,10 @@ interface PublishDeps {
    *    clears only those (a deletion scheduled mid-save must stay scheduled). */
   onSuccess: (savedSectionIds: string[], meta: { editToken: number; sentDeletedIds: string[] }) => void;
   mediaManifest: MediaManifest;
+  /** Optional ref mirror of `mediaManifest`, read at save time. recoverConflict
+   *  refreshes it synchronously, so the immediate 409 retry assembles against
+   *  the rebased manifest instead of this render's pre-conflict copy. */
+  mediaManifestRef?: React.RefObject<MediaManifest>;
   manifestDirty: boolean;
   clearManifestDirty: () => void;
   pendingMediaItems: MediaItem[];
@@ -126,6 +130,7 @@ export function useEditorPublish({
   deletedSectionIds,
   onSuccess,
   mediaManifest,
+  mediaManifestRef,
   manifestDirty,
   clearManifestDirty,
   pendingMediaItems,
@@ -201,11 +206,12 @@ export function useEditorPublish({
     if (hasMediaChanges) {
       // Preserves folders (and any future manifest keys) and heals dangling
       // folder refs — never rebuild the manifest as a bare { images }.
-      // KNOWN LIMITATION (deferred): the assembly starts from THIS editor's
-      // view of the manifest, so concurrent media changes by another editor
-      // are last-writer-wins — a manifest entry they added since our load is
-      // dropped from the write (their files remain; the entry orphans). Fixing
-      // this needs a merge against the remote manifest at save time.
+      // The assembly starts from THIS editor's view, so what we send can be
+      // missing entries another writer added since we loaded. That is no longer
+      // destructive: applyContentWrite folds this into the manifest already on
+      // the branch, so a save can only add, update, or explicitly delete. The
+      // client side of the same story is rebaseMediaManifest, which refreshes
+      // our view on 409 recovery and on a peer's saved-event.
       updatedManifest = assembleSavedManifest(
         manifest,
         mediaUploads.map((u) => u.item),
@@ -390,7 +396,10 @@ export function useEditorPublish({
     return performSave({
       siteConfig: siteConfig!,
       siteIndexRef, deletedSectionIds, isConfigDirty,
-      pendingMediaItems, pendingMediaDeletions, mediaManifest, manifestDirty,
+      pendingMediaItems, pendingMediaDeletions, manifestDirty,
+      // Read through the ref (when the shell supplies one) so the 409 retry
+      // below sees recoverConflict's rebased manifest, not this render's copy.
+      mediaManifest: mediaManifestRef?.current ?? mediaManifest,
       saveChunkBudget,
     });
   }

package/src/hooks/useMediaPipeline.ts

@@ -13,6 +13,7 @@ import {
   removePendingMediaDeletion,
 } from "../lib/dexie";
 import { generateVideoPoster } from "../media/videoPoster";
+import { ASSET_CACHE_CONTROL } from "../storage/types";
 import { tallyImageIds, collectImageIds, clearImageIds, applyLogoDeletion } from "../lib/image-refs";
 import {
   createFolderId, uniqueFolderName, effectiveParentId, canMoveFolder,
@@ -285,6 +286,9 @@ export function useMediaPipeline({
           const xhr = new XMLHttpRequest();
           xhr.open("PUT", uploadUrl);
           xhr.setRequestHeader("Content-Type", file.type);
+          // Without this the object is stored as `no-cache` and every later
+          // play is billed origin egress — see ASSET_CACHE_CONTROL.
+          xhr.setRequestHeader("Cache-Control", ASSET_CACHE_CONTROL);
           xhr.upload.onprogress = (e) => {
             if (e.lengthComputable) setUploadProgress((prev) => ({ ...prev, [hash as string]: e.loaded / e.total }));
           };

package/src/lib/events.ts

@@ -23,5 +23,16 @@ export const navChangeEvent = createEvent<NavItem[]>("sitenavchange");
 export const darkModeEvent = createEvent<string>("sitedarkmode");
 export const siteNameChangeEvent = createEvent<string>("sitenamechange");
 export const historySelectEvent = createEvent<{ sha: string; date: string }>("history-select");
+/** Restore straight from the history navigator, skipping the browse-then-restore
+ *  detour. The shell loads the content at `sha` and runs the same restore path
+ *  HistoryToolbar uses. Confirmation happens before this is dispatched. */
+export const historyRestoreEvent = createEvent<{ sha: string; date: string }>("history-restore");
+/** Restore failed. The navigator is a separate island from the shell that does
+ *  the writing, so without this the failure is invisible and the UI sits on
+ *  "Restoring…" forever. */
+export const historyRestoreFailedEvent = createEvent<{ message: string }>("history-restore-failed");
+/** Unsaved-draft state, published by the shell for other islands (the history
+ *  navigator warns before restoring, which discards drafts irrecoverably). */
+export const editorDirtyEvent = createEvent<{ hasUnsavedChanges: boolean }>("editor-dirty");
 export const siteNavChangeEvent = createEvent<SiteNav>("sitenavchange-v2");
 export const pageSelectEvent = createEvent<string>("pageselect");

package/src/lib/history-buckets.ts

@@ -0,0 +1,190 @@
+export interface HistoryCommit {
+  sha: string;
+  date: string;
+  /** First parent's sha; null for the repo's root commit. */
+  parent: string | null;
+}
+
+export type NodeKind = "commit" | "day" | "week" | "month" | "year";
+
+export interface HistoryNode {
+  /** Stable React key, unique within the tree. */
+  id: string;
+  kind: NodeKind;
+  label: string;
+  sublabel: string | null;
+  count: number;
+  /** Newest commit in this node — what "browse" opens. */
+  newestSha: string | null;
+  /** Compare base: parent of this node's oldest commit. Null at repo root. */
+  baseSha: string | null;
+  children: HistoryNode[];
+}
+
+export type GroupId =
+  | "today" | "this-week" | "previous-weeks" | "earlier-months" | "previous-years";
+
+export interface HistoryGroup {
+  id: GroupId;
+  label: string;
+  nodes: HistoryNode[];
+}
+
+const GROUPS: { id: GroupId; label: string }[] = [
+  { id: "today", label: "Today" },
+  { id: "this-week", label: "Earlier this week" },
+  { id: "previous-weeks", label: "Previous weeks" },
+  { id: "earlier-months", label: "Earlier months" },
+  { id: "previous-years", label: "Previous years" },
+];
+
+// Calendar-day arithmetic (not fixed-ms) so DST transitions don't shift boundaries.
+const startOfDay = (d: Date) => new Date(d.getFullYear(), d.getMonth(), d.getDate());
+const addDays = (d: Date, n: number) =>
+  new Date(d.getFullYear(), d.getMonth(), d.getDate() + n);
+const startOfYear = (d: Date) => new Date(d.getFullYear(), 0, 1);
+
+const WEEKDAY = new Intl.DateTimeFormat(undefined, { weekday: "long" });
+const MONTH = new Intl.DateTimeFormat(undefined, { month: "long" });
+const MON_DAY = new Intl.DateTimeFormat(undefined, { month: "short", day: "numeric" });
+const TIME = new Intl.DateTimeFormat(undefined, { hour: "numeric", minute: "2-digit" });
+
+interface Dated extends HistoryCommit {
+  at: Date;
+}
+
+/** Oldest-first list → node metadata shared by every non-commit node. */
+function rollup(sorted: Dated[]): Pick<HistoryNode, "count" | "newestSha" | "baseSha"> {
+  return {
+    count: sorted.length,
+    newestSha: sorted.length ? sorted[sorted.length - 1].sha : null,
+    baseSha: sorted.length ? sorted[0].parent : null,
+  };
+}
+
+function commitNode(c: Dated): HistoryNode {
+  return {
+    id: `c:${c.sha}`,
+    kind: "commit",
+    label: TIME.format(c.at),
+    sublabel: null,
+    count: 1,
+    newestSha: c.sha,
+    baseSha: c.parent,
+    children: [],
+  };
+}
+
+/** Bucket by a key derived from each commit's date, newest bucket first. */
+function bucketBy(sorted: Dated[], key: (d: Date) => string): Map<string, Dated[]> {
+  const out = new Map<string, Dated[]>();
+  for (const c of sorted) {
+    const k = key(c.at);
+    const list = out.get(k);
+    if (list) list.push(c);
+    else out.set(k, [c]);
+  }
+  // sorted is oldest-first, so reverse the insertion order for newest-first display.
+  return new Map([...out.entries()].reverse());
+}
+
+const dayKey = (d: Date) => `${d.getFullYear()}-${d.getMonth()}-${d.getDate()}`;
+const monthKey = (d: Date) => `${d.getFullYear()}-${d.getMonth()}`;
+const yearKey = (d: Date) => `${d.getFullYear()}`;
+
+/** Day nodes whose children are commit nodes. `weekday` picks the label style. */
+function dayNodes(sorted: Dated[], weekday: boolean): HistoryNode[] {
+  return [...bucketBy(sorted, dayKey).entries()].map(([k, list]) => ({
+    id: `d:${k}`,
+    kind: "day" as const,
+    label: weekday ? WEEKDAY.format(list[0].at) : MON_DAY.format(list[0].at),
+    sublabel: weekday ? MON_DAY.format(list[0].at) : null,
+    ...rollup(list),
+    children: [...list].reverse().map(commitNode),
+  }));
+}
+
+function monthNodes(sorted: Dated[], withYear: boolean): HistoryNode[] {
+  return [...bucketBy(sorted, monthKey).entries()].map(([k, list]) => ({
+    id: `m:${k}`,
+    kind: "month" as const,
+    label: MONTH.format(list[0].at),
+    sublabel: withYear ? String(list[0].at.getFullYear()) : null,
+    ...rollup(list),
+    children: dayNodes(list, false),
+  }));
+}
+
+function yearNodes(sorted: Dated[]): HistoryNode[] {
+  return [...bucketBy(sorted, yearKey).entries()].map(([k, list]) => ({
+    id: `y:${k}`,
+    kind: "year" as const,
+    label: k,
+    sublabel: null,
+    ...rollup(list),
+    children: monthNodes(list, false),
+  }));
+}
+
+/**
+ * Up to three 7-day windows, newest first. Windows with no commits are dropped
+ * rather than rendered empty — an editor scanning history wants the edits, not
+ * a fixed-width calendar.
+ */
+function weekNodes(sorted: Dated[], windowStart: Date): HistoryNode[] {
+  const out: HistoryNode[] = [];
+  for (let i = 1; i <= 3; i++) {
+    const start = addDays(windowStart, -7 * i);
+    const end = addDays(windowStart, -7 * (i - 1));
+    const list = sorted.filter((c) => c.at >= start && c.at < end);
+    if (list.length === 0) continue;
+    out.push({
+      id: `w:${dayKey(start)}`,
+      kind: "week",
+      label: `${MON_DAY.format(start)} – ${MON_DAY.format(addDays(end, -1))}`,
+      sublabel: null,
+      ...rollup(list),
+      children: dayNodes(list, false),
+    });
+  }
+  return out;
+}
+
+export function buildHistoryTree(commits: HistoryCommit[], now: Date): HistoryGroup[] {
+  // Oldest-first throughout; each builder reverses for display.
+  const sorted: Dated[] = commits
+    .map((c) => ({ ...c, at: new Date(c.date) }))
+    .filter((c) => !Number.isNaN(c.at.getTime()))
+    .sort((a, b) => a.at.getTime() - b.at.getTime());
+
+  const t0 = startOfDay(now);          // today begins
+  const t1 = addDays(t0, -6);          // "earlier this week" window begins
+  const t2 = addDays(t1, -21);         // "previous weeks" window begins
+  const y0 = startOfYear(now);         // current year begins
+  const monthsEnd = t2;                // earlier-months covers [y0, t2)
+  const yearsEnd = t2 < y0 ? t2 : y0;  // previous-years covers [-inf, yearsEnd)
+
+  const inRange = (lo: Date | null, hi: Date) =>
+    sorted.filter((c) => (lo === null || c.at >= lo) && c.at < hi);
+
+  const byId: Record<GroupId, HistoryNode[]> = {
+    "today": [...sorted.filter((c) => c.at >= t0)].reverse().map(commitNode),
+    "this-week": dayNodes(inRange(t1, t0), true),
+    "previous-weeks": weekNodes(sorted, t1),
+    "earlier-months": monthsEnd > y0 ? monthNodes(inRange(y0, monthsEnd), true) : [],
+    "previous-years": yearNodes(inRange(null, yearsEnd)),
+  };
+
+  return GROUPS.map((g) => ({ ...g, nodes: byId[g.id] }));
+}
+
+/** Largest node count anywhere in the tree; never 0, so callers can divide by it. */
+export function maxNodeCount(groups: HistoryGroup[]): number {
+  let max = 1;
+  const walk = (n: HistoryNode) => {
+    if (n.count > max) max = n.count;
+    n.children.forEach(walk);
+  };
+  groups.forEach((g) => g.nodes.forEach(walk));
+  return max;
+}

package/src/lib/index.ts

@@ -12,7 +12,7 @@ export {
   suggestAccessibleOn,
   type WcagLevel,
 } from "./contrast";
-export { primaryVarValue, accentVarValue } from "./theme-vars";
+export { primaryVarValue, accentVarValue, onPrimaryVarValue } from "./theme-vars";
 export { sanitizeHtml, ensureSanitizer } from "./sanitize";
 export { gridColsClass } from "./grid";
 export { getIcon, curatedIcons, type IconEntry } from "./icons";

package/src/lib/media-folders.ts

@@ -178,6 +178,22 @@ export function healMediaManifest(manifest: MediaManifest): MediaManifest {
   return { ...manifest, images, folders };
 }
 
+/**
+ * Rebase a local manifest onto a freshly-fetched remote one, so media another
+ * writer added is in our copy before the next save assembles from it. Without
+ * this a rebased session still writes its pre-conflict manifest, which silently
+ * drops their entries and orphans the files they committed.
+ *
+ * Images union, ours winning, so local alt/folder-move edits survive; a pending
+ * local deletion isn't removed from the manifest until save, so the union can't
+ * resurrect one. Folders stay ours verbatim — deleting a folder removes it from
+ * our map with no wire signal, so unioning would undo the delete. Mirrors the
+ * server-side merge in core's content-ops.
+ */
+export function rebaseMediaManifest(local: MediaManifest, remote: MediaManifest): MediaManifest {
+  return { ...local, images: { ...remote.images, ...local.images } };
+}
+
 /**
  * Save-time manifest assembly: merge uploaded pending items, apply deletions,
  * preserve every other manifest key (folders!), then heal.

package/src/lib/registry.ts

@@ -77,12 +77,20 @@ export type Thumbnail =
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type CustomSettingsFormProps = Record<string, any>;
 
+export interface ModalOptions {
+  /** Content is a tab set — lock the modal height so tab switches don't resize it. */
+  tabbed?: boolean;
+}
+
+/** Signature of the editor's modal opener as threaded down to sections. */
+export type OpenModal = (title: string, content: ReactNode, options?: ModalOptions) => void;
+
 export interface SectionProps<T = unknown> {
   content: T;
   options?: Record<string, unknown>;
   onChange?: (content: T) => void;
   isEditMode: boolean;
-  openModal?: (title: string, content: ReactNode) => void;
+  openModal?: OpenModal;
   /** Delete this whole section. Used e.g. when a colors section's last swatch
    *  is dragged into another section, leaving it empty. */
   onDelete?: () => void;

package/src/lib/theme-vars.ts

@@ -1,11 +1,13 @@
 import type { SiteConfig } from "../schemas/site-config";
+import { suggestAccessibleOn } from "./contrast";
 
 /**
  * Computes the CSS value for the brand `--color-primary` / `--color-primary-contrast`
- * custom properties. When darkMode is "optional" AND a dark variant is set, the
- * value is a CSS `light-dark(<light>, <dark>)` expression — the browser resolves
- * it per the element's `color-scheme` (the `.dark` class sets `color-scheme: dark`;
- * `:root` sets `color-scheme: light`). Otherwise it's the plain light hex.
+ * / `--color-on-primary` custom properties. When darkMode is "optional" AND a dark
+ * variant is set, the value is a CSS `light-dark(<light>, <dark>)` expression — the
+ * browser resolves it per the element's `color-scheme` (the `.dark` class sets
+ * `color-scheme: dark`; `:root` sets `color-scheme: light`). Otherwise it's the
+ * plain light hex.
  *
  * Single source of truth for every injection site: Layout.astro / LoginLayout.astro
  * (SSR inline `<html style>`) and EditorShell (live setProperty + localStorage).
@@ -29,3 +31,22 @@ export function primaryVarValue(c?: Partial<ThemeColorConfig> | null): string {
 export function accentVarValue(c?: Partial<ThemeColorConfig> | null): string {
   return lightDark(c?.primaryContrast ?? DEFAULT_CONTRAST, c?.primaryContrastDark, c?.darkMode === "optional");
 }
+
+/**
+ * Foreground ink for text drawn ON a `--color-primary`-filled surface (branded
+ * plates, primary cards). Derived from `primaryColor` with the same
+ * black/white WCAG pick the editor's accent "Suggest" button uses, so a
+ * primary-filled surface is legible on every brand without configuration.
+ *
+ * This exists because `--color-primary-contrast` cannot serve the role: it is
+ * the *accent* — brands legitimately repoint it at a decorative colour (Siete's
+ * gold on aubergine) that reads as a highlight but cannot carry body copy.
+ * Sections should consume `var(--color-on-primary)` for text on primary and
+ * keep `--color-primary-contrast` for accents, and derive softer inks by mixing
+ * the two brand tokens: `color-mix(in srgb, var(--color-on-primary) 70%, var(--color-primary))`.
+ */
+export function onPrimaryVarValue(c?: Partial<ThemeColorConfig> | null): string {
+  const light = suggestAccessibleOn(c?.primaryColor ?? DEFAULT_PRIMARY);
+  const dark = c?.primaryColorDark ? suggestAccessibleOn(c.primaryColorDark) : null;
+  return lightDark(light, dark, c?.darkMode === "optional");
+}

package/src/storage/index.ts

@@ -1,2 +1,2 @@
 export type { StorageProvider, FileWrite, AssetStore } from "./types";
-export { StorageConflictError } from "./types";
+export { StorageConflictError, ASSET_CACHE_CONTROL } from "./types";

package/src/storage/types.ts

@@ -39,6 +39,21 @@ export type FileWrite = {
   encoding?: "utf-8" | "base64";
 };
 
+/**
+ * `Cache-Control` every bucket upload must set. Object paths are content-hashed
+ * ("media/{hash}/original.mp4"), so a given URL's bytes never change — replacing
+ * a video mints a new hash and therefore a new URL. That makes `immutable` safe
+ * and a one-year max-age correct.
+ *
+ * This is NOT cosmetic. A bucket upload sent with no `cache-control` request
+ * header is stored as `no-cache`, which means neither the browser nor a CDN will
+ * ever reuse a response — every play of every video becomes origin egress,
+ * including a plain page reload. That default is what exhausted the Supabase
+ * project's egress quota while the bucket sat at 46% of its size limit. Any new
+ * upload path MUST send this header.
+ */
+export const ASSET_CACHE_CONTROL = "max-age=31536000, immutable";
+
 /**
  * Optional large-asset store (Supabase Storage bucket). Holds video originals
  * too big for the git path; deliberately generic so future large kinds (zips)