@drawnagency/primitives 0.1.111 → 0.1.112

package/src/deck-builder/starter-deck.ts

@@ -0,0 +1,86 @@
+import { DECK_SCHEMA_VERSION, DeckSchema, type Deck } from "../schemas/deck";
+
+/**
+ * A new deck's seed. Three slides using the two text-only Layouts, so a New
+ * Deck is publishable and presentable before the author has said anything —
+ * and so the starter never cites media that a given site may not have (a
+ * reference the manifest cannot resolve renders as a gap, which is a poor
+ * first impression of the runtime).
+ *
+ * Parsed rather than cast: this is the one deck the product itself authors, so
+ * a schema change that breaks it should break a test, not a client's first
+ * deck.
+ */
+export function starterDeck(id: string, title: string): Deck {
+  return DeckSchema.parse({
+    schemaVersion: DECK_SCHEMA_VERSION,
+    id,
+    title,
+    slides: [
+      {
+        id: "cover",
+        title: "Cover",
+        layout: {
+          type: "centeredText",
+          background: "brand",
+          content: {
+            type: "richText",
+            kicker: "New deck",
+            heading: title,
+            subheading: "Rename this slide's heading, or ask the assistant to rewrite the whole deck.",
+          },
+        },
+      },
+      {
+        id: "context",
+        title: "Context",
+        layout: {
+          type: "centeredText",
+          content: {
+            type: "richText",
+            kicker: "Context",
+            heading: "What this deck is for",
+            paragraphs: [
+              "Every slide uses one of the portal's prebuilt Layouts, so it inherits the brand's type, color and spacing automatically.",
+            ],
+          },
+        },
+      },
+      {
+        id: "next",
+        title: "Next",
+        layout: {
+          type: "centeredText",
+          content: {
+            type: "richText",
+            kicker: "Next",
+            heading: "Three things to try",
+            bullets: [
+              "Click a thumbnail below to move through the deck",
+              "Publish when you want the deck kept for you",
+              "Everything you change stays on this device until you do",
+            ],
+          },
+        },
+      },
+    ],
+  });
+}
+
+/**
+ * A deck id for a new deck: a slug of the title plus a short random suffix.
+ *
+ * Random rather than sequential because the id is a directory name on a shared
+ * branch that this browser cannot enumerate (a viewer only ever sees their own
+ * decks), so "next free number" is not something the builder can know. The
+ * charset is `DeckIdSchema`'s.
+ */
+export function newDeckId(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  const suffix = Math.random().toString(36).slice(2, 8).replace(/[^a-z0-9]/g, "0").padEnd(6, "0");
+  return slug ? `${slug}-${suffix}` : `deck-${suffix}`;
+}

package/src/deck-builder/types.ts

@@ -0,0 +1,24 @@
+import type { Deck } from "../schemas/deck";
+
+/**
+ * One row of the builder's deck grid: whatever this browser has staged, joined
+ * to whatever the decks branch holds.
+ *
+ * The join is by deck id and both sides are optional, because the three states
+ * are all real: a draft never published (published side absent), a deck
+ * published from another device (draft side absent), and the normal case where
+ * both exist and may differ.
+ */
+export interface DeckGridEntry {
+  id: string;
+  title: string;
+  slideCount: number;
+  /** ISO timestamp behind the card's "… ago" line. */
+  updatedAt: string;
+  /** Present when this browser has the deck staged. */
+  draft: { deck: Deck; baseVersion: string | null } | null;
+  /** Present when the decks branch holds it. */
+  published: { version: string } | null;
+  /** The draft differs from what was published (or was never published). */
+  unpublishedChanges: boolean;
+}

package/src/deck-builder/useSortableSlide.ts

@@ -0,0 +1,102 @@
+import { useEffect, useRef, useState } from "react";
+import { computeReorderTarget } from "../lib/reorder";
+
+interface Options {
+  index: number;
+  onReorder: (fromIndex: number, toIndex: number) => void;
+  /** False while a chat turn streams — the strip goes inert, like the stage. */
+  enabled: boolean;
+}
+
+const DRAG_TYPE = "deck-filmstrip-slide";
+
+/**
+ * Drag-to-reorder for one filmstrip thumbnail.
+ *
+ * A sibling of `useSortableRow` rather than an option on it: the filmstrip is
+ * HORIZONTAL, so it reads left/right edges where every existing consumer reads
+ * top/bottom, and widening that hook's `closestEdge` type would change the two
+ * shipped editor modals that render `DropEdgeIndicator` from it. The Deck
+ * Builder is a sealed subtree; a second small hook here costs less than a type
+ * change under two surfaces this ticket is not touching.
+ *
+ * The pointer-math is NOT duplicated: `computeReorderTarget` is written in
+ * before/after terms, so left maps to "top" and right to "bottom" and the
+ * unit-tested decrement stays the one implementation. The whole atlaskit
+ * adapter is imported lazily, as it is everywhere else — jsdom cannot run it,
+ * which is why `moveDeckSlide` and the move affordances carry the coverage.
+ */
+export function useSortableSlide<E extends HTMLElement>({ index, onReorder, enabled }: Options) {
+  const ref = useRef<E>(null);
+  // Held in a ref so the effect does not depend on it. `onReorder` is rebuilt
+  // whenever the draft refreshes — i.e. after every single edit — and depending
+  // on it tore down and re-registered the drag adapter on every thumbnail in
+  // the strip each time.
+  const onReorderRef = useRef(onReorder);
+  onReorderRef.current = onReorder;
+  const [isDragging, setIsDragging] = useState(false);
+  const [closestEdge, setClosestEdge] = useState<"left" | "right" | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const element = ref.current;
+    if (!element) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    void Promise.all([
+      import("@atlaskit/pragmatic-drag-and-drop/element/adapter"),
+      import("@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge"),
+    ]).then(([{ draggable, dropTargetForElements }, { attachClosestEdge, extractClosestEdge }]) => {
+      if (cancelled) return;
+
+      const edgeOf = (data: Record<string | symbol, unknown>): "left" | "right" | null => {
+        const edge = extractClosestEdge(data);
+        return edge === "left" || edge === "right" ? edge : null;
+      };
+
+      const cleanupDraggable = draggable({
+        element,
+        getInitialData: () => ({ dragType: DRAG_TYPE, index }),
+        onGenerateDragPreview: () => {
+          element.style.opacity = "0.4";
+          requestAnimationFrame(() => {
+            element.style.opacity = "";
+          });
+        },
+        onDragStart: () => setIsDragging(true),
+        onDrop: () => setIsDragging(false),
+      });
+
+      const cleanupDropTarget = dropTargetForElements({
+        element,
+        canDrop: ({ source }) => source.data.dragType === DRAG_TYPE,
+        getData: ({ input, element: target }) =>
+          attachClosestEdge({ index }, { input, element: target, allowedEdges: ["left", "right"] }),
+        onDragEnter: ({ self }) => setClosestEdge(edgeOf(self.data)),
+        onDrag: ({ self }) => setClosestEdge(edgeOf(self.data)),
+        onDragLeave: () => setClosestEdge(null),
+        onDrop: ({ source, self }) => {
+          setClosestEdge(null);
+          const fromIndex = source.data.index as number;
+          const edge = edgeOf(self.data);
+          const toIndex = computeReorderTarget(fromIndex, index, edge === "right" ? "bottom" : edge === "left" ? "top" : null);
+          if (toIndex !== null) onReorderRef.current(fromIndex, toIndex);
+        },
+      });
+
+      cleanup = () => {
+        cleanupDraggable();
+        cleanupDropTarget();
+      };
+    });
+
+    return () => {
+      cancelled = true;
+      cleanup?.();
+    };
+  }, [index, enabled]);
+
+  return { ref, isDragging, closestEdge };
+}

package/src/lib/deck-access.ts

@@ -0,0 +1,132 @@
+import type { DeckOwner } from "../schemas/deck-meta";
+
+/**
+ * Who is asking. Built from the request's identity — a signed audience cookie
+ * (with the credential username when the site has named credentials) or an
+ * editor session — and deliberately NOT an Astro `locals`: the decision below
+ * is pure, so it is testable the way `audiencePasses` is.
+ *
+ * `audience` (no username) is the env-mode standalone case: a shared password
+ * per audience means there is no person to attribute to (ADR 0002).
+ */
+export type DeckIdentity =
+  | { kind: "viewer"; username: string; audience: string }
+  | { kind: "editor"; userId: string }
+  | { kind: "audience"; audience: string };
+
+/** The owner to record on a deck this identity is creating. */
+export function deckOwnerFor(identity: DeckIdentity): DeckOwner {
+  switch (identity.kind) {
+    case "viewer":
+      return { kind: "viewer", username: identity.username, audience: identity.audience };
+    case "editor":
+      return { kind: "editor", userId: identity.userId };
+    case "audience":
+      return { kind: "audience", audience: identity.audience };
+  }
+}
+
+/**
+ * Ownership. Credential-keyed for viewers (the username is the person-level
+ * key — an audience change must not hand a deck to someone else, and must not
+ * take it away from its author), user-id-keyed for editors, and audience-keyed
+ * for the env-mode fallback.
+ *
+ * An audience-owned deck is owned by everyone in that audience, which is
+ * exactly the attribution loss ADR 0002 accepts for env-mode portals. The
+ * reverse does not hold: an identity with no username cannot claim a
+ * credential-owned deck.
+ */
+export function isDeckOwner(owner: DeckOwner, identity: DeckIdentity): boolean {
+  switch (owner.kind) {
+    case "viewer":
+      return identity.kind === "viewer" && identity.username === owner.username;
+    case "editor":
+      return identity.kind === "editor" && identity.userId === owner.userId;
+    case "audience":
+      return (identity.kind === "viewer" || identity.kind === "audience") && identity.audience === owner.audience;
+  }
+}
+
+/**
+ * May this identity see and change this deck? Owner, or any editor — editors
+ * are super-admins over every deck on the site regardless of audience config
+ * (feasibility decision 9).
+ *
+ * One function for read and for write because today they are the same rule:
+ * a deck is private to its owner (Deck Visibility). Audience grants and Public
+ * Links (#36/#37) widen READ only, and that is when the two split.
+ */
+export function canAccessDeck(owner: DeckOwner, identity: DeckIdentity): boolean {
+  return identity.kind === "editor" || isDeckOwner(owner, identity);
+}
+
+/**
+ * May this identity CREATE a deck? Editors always (super-admins); everyone else
+ * only from a deck-enabled audience — `deckBuilder.audiences`, strict opt-in
+ * exactly like `chatbot.audiences`, so an empty list means no viewer may.
+ *
+ * Creation rights are AUDIENCE-keyed while ownership of the result is
+ * CREDENTIAL-keyed (`deckOwnerFor`); the two deliberately do not share a key.
+ * An `audience` identity (env-mode standalone, shared password, no named
+ * credential) passes when its audience is listed: that is a deliberate opt-in
+ * by the editor, and the resulting deck is audience-owned — the attribution
+ * loss ADR 0002 accepts, not an accident. What the list prevents is the DEFAULT
+ * audience being enabled implicitly, i.e. anyone holding the site password
+ * writing to the client's repo.
+ */
+export function canCreateDeck(identity: DeckIdentity, deckAudiences: readonly string[]): boolean {
+  if (identity.kind === "editor") return true;
+  return deckAudiences.includes(identity.audience);
+}
+
+/** FNV-1a, twice, at different offsets — 16 hex chars with no crypto import and
+ *  no async. Partitioning only; see `deckDraftScope` for why that is enough. */
+function digest(input: string): string {
+  const half = (offset: number): string => {
+    let hash = offset;
+    for (let i = 0; i < input.length; i++) {
+      hash ^= input.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, "0");
+  };
+  return half(0x811c9dc5) + half(0x7fffffff);
+}
+
+/**
+ * The Deck Draft partition key for an identity.
+ *
+ * A Deck Draft lives in one browser until it is published (ADR 0002), and a
+ * browser PROFILE is shared between people far more often than an account is.
+ * Keyed by site alone, two viewers signing into the same portal on one machine
+ * saw each other's unpublished drafts in the grid, could open and read them,
+ * and could publish another person's never-published draft under their own
+ * ownership; a signed-out user's drafts simply waited for whoever came next.
+ *
+ * The partition mirrors `deckOwnerFor` exactly, so a draft can only ever be
+ * published under the identity that staged it.
+ *
+ * DIGESTED, not spelled out, because the value becomes an IndexedDB database
+ * NAME and any script on the origin can enumerate those — a raw username there
+ * would disclose who last used the browser. This is NOT a security boundary:
+ * IndexedDB is per-origin and isolates nothing between people sharing a
+ * profile. It bounds accidents, not somebody with the keyboard.
+ *
+ * Switching identity leaves the previous identity's database in place,
+ * untouched and unread. That is deliberate — the alternative is destroying a
+ * colleague's unpublished work on sign-in — so orphaned drafts persist until
+ * the browser's own storage eviction takes them.
+ */
+export function deckDraftScope(identity: DeckIdentity): string {
+  switch (identity.kind) {
+    case "viewer":
+      return digest(`viewer:${identity.username}@${identity.audience}`);
+    case "editor":
+      return digest(`editor:${identity.userId}`);
+    case "audience":
+      // Env-mode standalone: a shared password means there is no person to
+      // separate, and ownership degrades the same way (ADR 0002).
+      return digest(`audience:${identity.audience}`);
+  }
+}

package/src/lib/deck-dexie.ts

@@ -0,0 +1,190 @@
+import Dexie from "dexie";
+import { serializeDeck, type Deck } from "../schemas/deck";
+
+/**
+ * Deck Draft staging — the deck builder's half of the editor's unsaved-state
+ * model (`./dexie.ts`), and the reason the authoring loop performs no server
+ * writes at all (ADR 0002). A draft lives in this browser only until an
+ * explicit publish; nothing here ever talks to the network.
+ *
+ * A SEPARATE database from the editor's `brand-portal-{siteId}`, not a table on
+ * it. The builder is a VIEWER surface: opening the editor's connection from it
+ * would run the editor's upgrade chain (11 versions, several of which clear
+ * caches) in a viewer's browser, and would hold a connection open that blocks
+ * the editor's next schema bump. Nothing here needs the editor's rows.
+ *
+ * Keyed by site AND by identity scope (`deckDraftScope`). One browser profile
+ * routinely serves several people, and drafts are unpublished work — see that
+ * function for what the scope is, why it is a digest, and what happens to the
+ * databases an identity leaves behind.
+ */
+
+export interface DeckDraftRow {
+  /** Deck id — also the directory name on the decks branch. */
+  deckId: string;
+  deck: Deck;
+  /**
+   * The published version this draft was based on, and the `baseVersion` the
+   * next publish sends. `null` means the deck has never been published, which
+   * is exactly what POST /api/decks wants to be told to create it.
+   */
+  baseVersion: string | null;
+  /**
+   * The published deck's serialized bytes AT `baseVersion`, or null when it has
+   * never been published. Stored rather than a dirty flag because the flag has
+   * to survive a reload, and re-deriving it would mean a server read — which is
+   * the one thing a draft must not need. Comparing bytes also makes an
+   * edit-then-undo correctly report "no unpublished changes".
+   */
+  publishedText: string | null;
+  updatedAt: string;
+}
+
+class DeckDraftDatabase extends Dexie {
+  drafts!: Dexie.Table<DeckDraftRow, string>;
+
+  constructor(name: string) {
+    super(name);
+    this.version(1).stores({ drafts: "deckId" });
+  }
+}
+
+/** `scope` is a `deckDraftScope` digest — never a raw username or user id. */
+function databaseName(siteId: string, scope: string): string {
+  return `brand-portal-decks-${siteId}-${scope}`;
+}
+
+let db: DeckDraftDatabase | null = null;
+
+export function initDeckDraftStore(siteId: string, scope: string): void {
+  const name = databaseName(siteId, scope);
+  // Re-initialising for the database we already hold is a no-op — replacing the
+  // instance would leave the old connection open, and an open connection on the
+  // previous version is what makes the next schema bump hang on `blocked`.
+  // (Same reasoning as initEditorStore.) Switching identity DOES replace it,
+  // which is the point: the previous identity's rows become unreachable here.
+  if (db?.name === name) return;
+  db?.close();
+  db = new DeckDraftDatabase(name);
+}
+
+function getDb(): DeckDraftDatabase {
+  if (!db) throw new Error("Deck draft store not initialized. Call initDeckDraftStore first.");
+  return db;
+}
+
+/** Every staged draft, newest first. Drives the builder's deck grid. */
+export async function listDeckDrafts(): Promise<DeckDraftRow[]> {
+  const rows = await getDb().drafts.toArray();
+  return rows.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export async function getDeckDraft(deckId: string): Promise<DeckDraftRow | null> {
+  return (await getDb().drafts.get(deckId)) ?? null;
+}
+
+/**
+ * Stage a deck edit. `baseVersion`/`publishedText` are carried forward from the
+ * existing row rather than taken as arguments: an edit never changes what the
+ * server holds, and letting a caller pass them is how a draft would come to
+ * claim it was published when it was not.
+ */
+export async function putDeckDraft(deck: Deck): Promise<DeckDraftRow> {
+  const db = getDb();
+  // Transactional, not get-then-put: this races `recordDeckPublish` on exactly
+  // the fields it carries forward. Two overlapping read-modify-writes both
+  // reading the pre-publish row would revert `baseVersion` to null, and the next
+  // publish would then send `baseVersion: null` for a deck that already exists —
+  // a 409 the author cannot explain. IDB serializes readwrite transactions on
+  // the store, so the two can only ever run one after the other.
+  return db.transaction("rw", db.drafts, async () => {
+    const existing = await db.drafts.get(deck.id);
+    const row: DeckDraftRow = {
+      deckId: deck.id,
+      deck,
+      baseVersion: existing?.baseVersion ?? null,
+      publishedText: existing?.publishedText ?? null,
+      updatedAt: new Date().toISOString(),
+    };
+    await db.drafts.put(row);
+    return row;
+  });
+}
+
+/**
+ * Record what the server now holds — after a publish, or after loading a
+ * published deck into the draft. The deck body is restated from `deck` so the
+ * row and its published baseline can never disagree.
+ *
+ * `updatedAt` is an argument because the two callers mean different things by
+ * it. A publish genuinely changed the deck, so "now" is right. Merely OPENING a
+ * published deck changes nothing, and stamping "now" there sorted it to the top
+ * of the grid — reading a deck must not reorder the library — so that caller
+ * passes the sidecar's own timestamp.
+ */
+export async function markDeckDraftPublished(deck: Deck, version: string, updatedAt?: string): Promise<DeckDraftRow> {
+  const row: DeckDraftRow = {
+    deckId: deck.id,
+    deck,
+    baseVersion: version,
+    publishedText: serializeDeck(deck),
+    updatedAt: updatedAt ?? new Date().toISOString(),
+  };
+  await getDb().drafts.put(row);
+  return row;
+}
+
+/**
+ * Record a successful publish WITHOUT touching the working deck (#39).
+ *
+ * The difference from `markDeckDraftPublished` is the whole point: that
+ * function restates the body from its argument, which is a pre-request snapshot
+ * at the publish call site, so an edit landing during the round-trip was
+ * silently discarded. #35 could answer that with a lock because its only other
+ * writer was a chat turn; inline editing cannot — locking a text field the
+ * author is mid-word in is worse than the race it prevents.
+ *
+ * So this re-reads the row and writes back only the publish BASELINE: what the
+ * server now holds (`baseVersion`) and the bytes it holds (`publishedText`,
+ * serialized from the deck that was actually sent). `deck` stays whatever is
+ * current by now, which makes `hasUnpublishedChanges` correctly report the
+ * mid-flight edit as unpublished rather than losing it.
+ *
+ * Returns null when the row is gone (deleted during the round-trip) — recreating
+ * it would resurrect a deck the author just removed.
+ */
+export async function recordDeckPublish(deckId: string, publishedDeck: Deck, version: string): Promise<DeckDraftRow | null> {
+  const db = getDb();
+  // Transactional for the same reason `putDeckDraft` is, and it is the half
+  // that bites hardest: an inline commit whose put lands between this read and
+  // this write is REVERTED here — the row goes back to the pre-edit deck with a
+  // matching `publishedText`, so the edit is gone AND the deck reports itself
+  // clean. Re-reading inside the transaction is what makes "leave `deck` alone"
+  // mean the deck as of the write, not as of the request.
+  return db.transaction("rw", db.drafts, async () => {
+    const existing = await db.drafts.get(deckId);
+    if (!existing) return null;
+    const row: DeckDraftRow = {
+      ...existing,
+      baseVersion: version,
+      publishedText: serializeDeck(publishedDeck),
+      // "Now", as the previous implementation stamped: a publish is activity the
+      // deck grid should sort on, even though it did not change the body.
+      updatedAt: new Date().toISOString(),
+    };
+    await db.drafts.put(row);
+    return row;
+  });
+}
+
+export async function deleteDeckDraft(deckId: string): Promise<void> {
+  await getDb().drafts.delete(deckId);
+}
+
+/**
+ * Does this row differ from what was published? A never-published draft always
+ * has changes — there is nothing on the server to match.
+ */
+export function hasUnpublishedChanges(row: DeckDraftRow): boolean {
+  return row.publishedText === null || serializeDeck(row.deck) !== row.publishedText;
+}