@withpotter/components 0.13.0-next.101

package/dist/potter/potter-context.d.ts

@@ -0,0 +1,162 @@
+import { type ReactNode } from 'react';
+import type { PotterReply } from './potter-answer';
+import type { PotterBlock } from './potter-blocks';
+import { type PotterThreadRecord } from './potter-history';
+/**
+ * ONE POTTER, however you got in.
+ *
+ * The dashboard used to carry two doors to the same non-existent room: a
+ * feedback bubble in the bottom-right whose sheet contained an "Ask Box"
+ * row, and an "Ask Box" button in the home's header that did nothing but
+ * `focus()` the search bar underneath it. Neither reached a conversation. A
+ * merchant looking for the assistant had to guess which corner it was in, and
+ * both guesses were wrong in different ways.
+ *
+ * So the state lives here, above both, and the doors are just doors. The home
+ * renders the surface inline under its ask bar; every other screen gets the
+ * corner launcher and an anchored panel. Same thread either way — walk from the
+ * home to Payments mid-conversation and the conversation is still there, which
+ * is the thing that makes it feel like an assistant rather than a widget that
+ * resets.
+ *
+ * Feedback did NOT get folded away in the merge, it got inverted. It used to
+ * own the corner and offer Box as a row inside it; now Box owns the
+ * corner and offers "report a bug" and "message the team" as rows inside the
+ * intro. The escape hatch to a human stays one tap deep, because the moment
+ * someone actually needs it is the moment they have least patience for a
+ * machine — but it is no longer the thing standing in the assistant's doorway.
+ */
+export interface PotterMessage {
+    id: string;
+    role: 'you' | 'potter';
+    text: string;
+    /** Only on Box's turns. Drives what is rendered under the sentence. */
+    reply?: PotterReply;
+    /**
+     * Object URLs for pictures sent WITH this question, drawn above its text.
+     *
+     * A sent turn has to show what went with it, and the only honest thing to
+     * show is the picture — the filename is `IMG_4821.jpg`, which is what John
+     * had this removed from the composer for in the first place.
+     *
+     * They are the same object URLs the composer was showing, deliberately NOT
+     * revoked on send: the thread renders them for as long as the tab is open,
+     * and revoking at the moment of sending would leave every sent turn holding
+     * five broken images. They die with the tab.
+     */
+    attachments?: string[];
+    /**
+     * Rendered under the sentence when the answer came from the merchant's own
+     * rows rather than from the help corpus. A closed union — see
+     * `potter-blocks`.
+     */
+    blocks?: PotterBlock[];
+    /**
+     * A turn that has been asked and not yet answered.
+     *
+     * New with the data tools: routing the help corpus is synchronous and had
+     * nothing to wait for, but a question that reads invoices is a round trip.
+     * The turn is pushed empty so the thread never shows a question with nothing
+     * under it, and filled by `resolve`.
+     */
+    pending?: boolean;
+    /**
+     * Which lookups produced this answer, in the order they ran.
+     *
+     * The audit trail under a Box turn — see `PotterSteps`. Optional because
+     * an answer from the help corpus read nothing, and a turn that read nothing
+     * must not draw a trail claiming it did.
+     */
+    toolsUsed?: string[];
+    /**
+     * When this turn was said, epoch ms.
+     *
+     * Added for the stamp above the conversation on the ask screen — `Today
+     * 08:01`, off Linear's thread. Optional, and it has to be: conversations
+     * archived before this existed are read back from storage without it, and a
+     * thread that refuses to render because it predates a field is a worse bug
+     * than a missing timestamp.
+     */
+    at?: number;
+}
+interface PotterValue {
+    open: boolean;
+    messages: PotterMessage[];
+    /** Opens the panel. Pass text to open with it already asked. */
+    openPotter: (seed?: string) => void;
+    /** Seed a question for the ask SCREEN without opening the panel. */
+    /**
+     * A question, and optionally the files it arrived with, on their way to the
+     * ask screen. The caller navigates; this only puts them down.
+     */
+    handOff: (text: string, files?: File[]) => void;
+    /**
+     * A spreadsheet on its way to the catalogue's importer.
+     *
+     * Held here for the same reason `seed` is: it has to survive a navigation.
+     * Box reads the file on the ask screen and the importer opens on
+     * `/dashboard/catalog`, and without this the merchant would pick the same
+     * file twice — once to be told what is in it, once to import it.
+     *
+     * A value with a separate clear, never a read-and-drop getter: the consumer
+     * can only read it in a render, and mutating during a read makes StrictMode's
+     * double invocation eat the file. Same trap `seed` documents.
+     */
+    pendingSheet: File | null;
+    handSheet: (file: File | null) => void;
+    /**
+     * Photographs waiting to be kept, which is a DIFFERENT slot from the sheet.
+     *
+     * They shared one while there could only be a single attachment, and that was
+     * always a coincidence rather than a design: a spreadsheet is on its way to
+     * the catalogue importer and a photograph is on its way to the media library.
+     * Two destinations, two slots — and only one of them can hold more than one
+     * file, which is the immediate reason they had to come apart.
+     */
+    pendingPhotos: File[];
+    handPhotos: (files: File[]) => void;
+    closePotter: () => void;
+    /** Adds a turn and returns its id, so a pending one can be filled later. */
+    say: (message: Omit<PotterMessage, 'id'>) => string;
+    /** Fill in a turn that was pushed pending. */
+    resolve: (id: string, patch: Partial<Omit<PotterMessage, 'id'>>) => void;
+    /** Back to the intro. The door stays open; only the thread is dropped. */
+    clear: () => void;
+    /**
+     * Text a door handed over, for the surface to ask on its next effect.
+     *
+     * Exposed as a value with a separate `clearSeed` rather than a read-and-drop
+     * getter. A getter would have to mutate during the read, and the only place
+     * the surface can read it is a render — so under StrictMode's double
+     * invocation one Enter became two identical turns. Read it in an effect,
+     * clear it there, and the double render is harmless.
+     */
+    seed: string | null;
+    /**
+     * Files handed over WITH the seed, unread.
+     *
+     * Raw `File`s rather than `PotterAttachment`s because reading one is async
+     * and the home's bar has nowhere to show the result — the screen reads them
+     * on arrival, where the thumbnail grid can render what comes back.
+     */
+    seedFiles: File[];
+    clearSeed: () => void;
+    /**
+     * Past conversations, newest first, for this workspace.
+     *
+     * Read from storage rather than held as the source of truth: the live thread
+     * is `messages`, and a second copy of it in state is a second thing to keep
+     * in step. This is the archive beside it.
+     */
+    threads: PotterThreadRecord[];
+    /** Park the current conversation and start an empty one. */
+    newThread: () => void;
+    /** Reopen an archived conversation as the live one. */
+    openThread: (id: string) => void;
+    deleteThread: (id: string) => void;
+}
+export declare function PotterProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function usePotter(): PotterValue;
+export {};

package/dist/potter/potter-context.js

@@ -0,0 +1,239 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { playSound } from "@withpotter/lib/sound";
+import { useAuth } from "@withpotter/lib/auth-context";
+import {
+  listThreads,
+  saveThread,
+  deleteThread as dropThread,
+  titleFor,
+  readActiveThreadId,
+  writeActiveThreadId
+} from "./potter-history";
+const PotterContext = createContext({
+  open: false,
+  messages: [],
+  openPotter: () => {
+  },
+  handOff: () => {
+  },
+  pendingSheet: null,
+  handSheet: () => {
+  },
+  pendingPhotos: [],
+  handPhotos: () => {
+  },
+  closePotter: () => {
+  },
+  say: () => "",
+  resolve: () => {
+  },
+  clear: () => {
+  },
+  seed: null,
+  seedFiles: [],
+  clearSeed: () => {
+  },
+  threads: [],
+  newThread: () => {
+  },
+  openThread: () => {
+  },
+  deleteThread: () => {
+  }
+});
+function PotterProvider({ children }) {
+  const { tenant } = useAuth();
+  const slug = tenant?.slug;
+  const [open, setOpen] = useState(false);
+  const [messages, setMessages] = useState([]);
+  const [seed, setSeed] = useState(null);
+  const [seedFiles, setSeedFiles] = useState([]);
+  const [pendingSheet, setPendingSheet] = useState(null);
+  const [pendingPhotos, setPendingPhotos] = useState([]);
+  const handPhotos = useCallback((files) => {
+    setPendingPhotos(files);
+  }, []);
+  const [threadId, setThreadId] = useState(null);
+  const [threads, setThreads] = useState([]);
+  const nextId = useRef(0);
+  const say = useCallback((message) => {
+    const id = `m${nextId.current++}`;
+    setMessages((prev) => [...prev, { at: Date.now(), ...message, id }]);
+    setThreadId((current) => current ?? `t${Date.now().toString(36)}`);
+    return id;
+  }, []);
+  const resolve = useCallback(
+    (id, patch) => {
+      setMessages(
+        (prev) => (
+          /**
+           * `pending` FALLS BACK to false rather than being forced to it.
+           *
+           * Every caller that finishes a turn omits it and still lands on false,
+           * which is what this always did. Streaming needs the other half: a
+           * partial answer arrives many times before it is finished, and each
+           * arrival is a `resolve` that must leave the turn pending or the
+           * thinking indicator flickers off and on with every fragment.
+           */
+          prev.map(
+            (m) => m.id === id ? { ...m, ...patch, pending: patch.pending ?? false } : m
+          )
+        )
+      );
+    },
+    []
+  );
+  useEffect(() => {
+    if (!slug || !threadId || messages.length === 0) return;
+    saveThread(slug, {
+      id: threadId,
+      title: titleFor(messages),
+      messages,
+      updatedAt: Date.now()
+    });
+    setThreads(listThreads(slug));
+  }, [slug, threadId, messages]);
+  useEffect(() => {
+    setThreads(listThreads(slug));
+  }, [slug]);
+  const restored = useRef(null);
+  const lastSlug = useRef(void 0);
+  useEffect(() => {
+    const previous = lastSlug.current;
+    lastSlug.current = slug;
+    if (previous === void 0 || previous === slug) return;
+    setMessages([]);
+    setThreadId(null);
+    setSeed(null);
+    setOpen(false);
+    restored.current = null;
+  }, [slug]);
+  useEffect(() => {
+    if (!slug || restored.current === slug) return;
+    restored.current = slug;
+    const id = readActiveThreadId(slug);
+    if (!id) return;
+    const found = listThreads(slug).find((t) => t.id === id);
+    if (!found || found.messages.length === 0) return;
+    nextId.current = found.messages.length;
+    setMessages(found.messages);
+    setThreadId(found.id);
+  }, [slug]);
+  useEffect(() => {
+    writeActiveThreadId(slug, threadId);
+  }, [slug, threadId]);
+  const openPotter = useCallback(
+    (withText) => {
+      if (withText?.trim()) setSeed(withText.trim());
+      if (!open) playSound("potter");
+      setOpen(true);
+    },
+    [open]
+  );
+  const closePotter = useCallback(() => setOpen(false), []);
+  const handOff = useCallback((text, files) => {
+    setSeedFiles(files ?? []);
+    if (text.trim()) setSeed(text.trim());
+  }, []);
+  const handSheet = useCallback(
+    (file) => setPendingSheet(file),
+    []
+  );
+  const clear = useCallback(() => {
+    setMessages([]);
+    setSeed(null);
+    setThreadId(null);
+  }, []);
+  const newThread = clear;
+  const openThread = useCallback(
+    (id) => {
+      const found = listThreads(slug).find((t) => t.id === id);
+      if (!found) return;
+      nextId.current = found.messages.length;
+      setMessages(found.messages);
+      setThreadId(found.id);
+      setSeed(null);
+      setOpen(true);
+    },
+    [slug]
+  );
+  const deleteThread = useCallback(
+    (id) => {
+      dropThread(slug, id);
+      setThreads(listThreads(slug));
+      setThreadId((current) => {
+        if (current !== id) return current;
+        setMessages([]);
+        return null;
+      });
+    },
+    [slug]
+  );
+  const clearSeed = useCallback(() => {
+    setSeed(null);
+    setSeedFiles([]);
+  }, []);
+  const value = useMemo(
+    () => ({
+      open,
+      messages,
+      openPotter,
+      handOff,
+      pendingSheet,
+      handSheet,
+      pendingPhotos,
+      handPhotos,
+      closePotter,
+      say,
+      resolve,
+      clear,
+      seed,
+      seedFiles,
+      clearSeed,
+      threads,
+      newThread,
+      openThread,
+      deleteThread
+    }),
+    [
+      open,
+      messages,
+      openPotter,
+      handOff,
+      pendingSheet,
+      handSheet,
+      pendingPhotos,
+      handPhotos,
+      closePotter,
+      say,
+      resolve,
+      clear,
+      seed,
+      seedFiles,
+      clearSeed,
+      threads,
+      newThread,
+      openThread,
+      deleteThread
+    ]
+  );
+  return /* @__PURE__ */ jsx(PotterContext.Provider, { value, children });
+}
+function usePotter() {
+  return useContext(PotterContext);
+}
+export {
+  PotterProvider,
+  usePotter
+};
+//# sourceMappingURL=potter-context.js.map

package/dist/potter/potter-context.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/potter/potter-context.tsx"],"sourcesContent":["'use client';\n\nimport {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type ReactNode,\n} from 'react';\nimport type { PotterReply } from './potter-answer';\nimport type { PotterBlock } from './potter-blocks';\nimport { playSound } from '@withpotter/lib/sound';\nimport { useAuth } from '@withpotter/lib/auth-context';\nimport {\n  listThreads,\n  saveThread,\n  deleteThread as dropThread,\n  titleFor,\n  readActiveThreadId,\n  writeActiveThreadId,\n  type PotterThreadRecord,\n} from './potter-history';\n\n/**\n * ONE POTTER, however you got in.\n *\n * The dashboard used to carry two doors to the same non-existent room: a\n * feedback bubble in the bottom-right whose sheet contained an \"Ask Box\"\n * row, and an \"Ask Box\" button in the home's header that did nothing but\n * `focus()` the search bar underneath it. Neither reached a conversation. A\n * merchant looking for the assistant had to guess which corner it was in, and\n * both guesses were wrong in different ways.\n *\n * So the state lives here, above both, and the doors are just doors. The home\n * renders the surface inline under its ask bar; every other screen gets the\n * corner launcher and an anchored panel. Same thread either way — walk from the\n * home to Payments mid-conversation and the conversation is still there, which\n * is the thing that makes it feel like an assistant rather than a widget that\n * resets.\n *\n * Feedback did NOT get folded away in the merge, it got inverted. It used to\n * own the corner and offer Box as a row inside it; now Box owns the\n * corner and offers \"report a bug\" and \"message the team\" as rows inside the\n * intro. The escape hatch to a human stays one tap deep, because the moment\n * someone actually needs it is the moment they have least patience for a\n * machine — but it is no longer the thing standing in the assistant's doorway.\n */\n\nexport interface PotterMessage {\n  id: string;\n  role: 'you' | 'potter';\n  text: string;\n  /** Only on Box's turns. Drives what is rendered under the sentence. */\n  reply?: PotterReply;\n  /**\n   * Object URLs for pictures sent WITH this question, drawn above its text.\n   *\n   * A sent turn has to show what went with it, and the only honest thing to\n   * show is the picture — the filename is `IMG_4821.jpg`, which is what John\n   * had this removed from the composer for in the first place.\n   *\n   * They are the same object URLs the composer was showing, deliberately NOT\n   * revoked on send: the thread renders them for as long as the tab is open,\n   * and revoking at the moment of sending would leave every sent turn holding\n   * five broken images. They die with the tab.\n   */\n  attachments?: string[];\n  /**\n   * Rendered under the sentence when the answer came from the merchant's own\n   * rows rather than from the help corpus. A closed union — see\n   * `potter-blocks`.\n   */\n  blocks?: PotterBlock[];\n  /**\n   * A turn that has been asked and not yet answered.\n   *\n   * New with the data tools: routing the help corpus is synchronous and had\n   * nothing to wait for, but a question that reads invoices is a round trip.\n   * The turn is pushed empty so the thread never shows a question with nothing\n   * under it, and filled by `resolve`.\n   */\n  pending?: boolean;\n  /**\n   * Which lookups produced this answer, in the order they ran.\n   *\n   * The audit trail under a Box turn — see `PotterSteps`. Optional because\n   * an answer from the help corpus read nothing, and a turn that read nothing\n   * must not draw a trail claiming it did.\n   */\n  toolsUsed?: string[];\n  /**\n   * When this turn was said, epoch ms.\n   *\n   * Added for the stamp above the conversation on the ask screen — `Today\n   * 08:01`, off Linear's thread. Optional, and it has to be: conversations\n   * archived before this existed are read back from storage without it, and a\n   * thread that refuses to render because it predates a field is a worse bug\n   * than a missing timestamp.\n   */\n  at?: number;\n}\n\ninterface PotterValue {\n  open: boolean;\n  messages: PotterMessage[];\n  /** Opens the panel. Pass text to open with it already asked. */\n  openPotter: (seed?: string) => void;\n  /** Seed a question for the ask SCREEN without opening the panel. */\n  /**\n   * A question, and optionally the files it arrived with, on their way to the\n   * ask screen. The caller navigates; this only puts them down.\n   */\n  handOff: (text: string, files?: File[]) => void;\n  /**\n   * A spreadsheet on its way to the catalogue's importer.\n   *\n   * Held here for the same reason `seed` is: it has to survive a navigation.\n   * Box reads the file on the ask screen and the importer opens on\n   * `/dashboard/catalog`, and without this the merchant would pick the same\n   * file twice — once to be told what is in it, once to import it.\n   *\n   * A value with a separate clear, never a read-and-drop getter: the consumer\n   * can only read it in a render, and mutating during a read makes StrictMode's\n   * double invocation eat the file. Same trap `seed` documents.\n   */\n  pendingSheet: File | null;\n  handSheet: (file: File | null) => void;\n  /**\n   * Photographs waiting to be kept, which is a DIFFERENT slot from the sheet.\n   *\n   * They shared one while there could only be a single attachment, and that was\n   * always a coincidence rather than a design: a spreadsheet is on its way to\n   * the catalogue importer and a photograph is on its way to the media library.\n   * Two destinations, two slots — and only one of them can hold more than one\n   * file, which is the immediate reason they had to come apart.\n   */\n  pendingPhotos: File[];\n  handPhotos: (files: File[]) => void;\n  closePotter: () => void;\n  /** Adds a turn and returns its id, so a pending one can be filled later. */\n  say: (message: Omit<PotterMessage, 'id'>) => string;\n  /** Fill in a turn that was pushed pending. */\n  resolve: (id: string, patch: Partial<Omit<PotterMessage, 'id'>>) => void;\n  /** Back to the intro. The door stays open; only the thread is dropped. */\n  clear: () => void;\n  /**\n   * Text a door handed over, for the surface to ask on its next effect.\n   *\n   * Exposed as a value with a separate `clearSeed` rather than a read-and-drop\n   * getter. A getter would have to mutate during the read, and the only place\n   * the surface can read it is a render — so under StrictMode's double\n   * invocation one Enter became two identical turns. Read it in an effect,\n   * clear it there, and the double render is harmless.\n   */\n  seed: string | null;\n  /**\n   * Files handed over WITH the seed, unread.\n   *\n   * Raw `File`s rather than `PotterAttachment`s because reading one is async\n   * and the home's bar has nowhere to show the result — the screen reads them\n   * on arrival, where the thumbnail grid can render what comes back.\n   */\n  seedFiles: File[];\n  clearSeed: () => void;\n\n  /**\n   * Past conversations, newest first, for this workspace.\n   *\n   * Read from storage rather than held as the source of truth: the live thread\n   * is `messages`, and a second copy of it in state is a second thing to keep\n   * in step. This is the archive beside it.\n   */\n  threads: PotterThreadRecord[];\n  /** Park the current conversation and start an empty one. */\n  newThread: () => void;\n  /** Reopen an archived conversation as the live one. */\n  openThread: (id: string) => void;\n  deleteThread: (id: string) => void;\n}\n\n/**\n * A no-op default rather than a throw. The dashboard layout returns several\n * loading and error trees before it reaches its providers, and a control\n * rendered under one of those must not crash for want of a context it was never\n * going to be given — the command palette's opener learned this the same way.\n */\nconst PotterContext = createContext<PotterValue>({\n  open: false,\n  messages: [],\n  openPotter: () => {},\n  handOff: () => {},\n  pendingSheet: null,\n  handSheet: () => {},\n  pendingPhotos: [],\n  handPhotos: () => {},\n  closePotter: () => {},\n  say: () => '',\n  resolve: () => {},\n  clear: () => {},\n  seed: null,\n  seedFiles: [],\n  clearSeed: () => {},\n  threads: [],\n  newThread: () => {},\n  openThread: () => {},\n  deleteThread: () => {},\n});\n\nexport function PotterProvider({ children }: { children: ReactNode }) {\n  const { tenant } = useAuth();\n  const slug = tenant?.slug;\n  const [open, setOpen] = useState(false);\n  const [messages, setMessages] = useState<PotterMessage[]>([]);\n  const [seed, setSeed] = useState<string | null>(null);\n  const [seedFiles, setSeedFiles] = useState<File[]>([]);\n  const [pendingSheet, setPendingSheet] = useState<File | null>(null);\n  const [pendingPhotos, setPendingPhotos] = useState<File[]>([]);\n  const handPhotos = useCallback((files: File[]) => {\n    setPendingPhotos(files);\n  }, []);\n  /**\n   * Which archived conversation this one IS.\n   *\n   * Generated on the first turn rather than at mount, so opening the panel and\n   * closing it again does not mint an id for a conversation that never\n   * happened. Held in state, not a ref, because the history list highlights it.\n   */\n  const [threadId, setThreadId] = useState<string | null>(null);\n  const [threads, setThreads] = useState<PotterThreadRecord[]>([]);\n  /**\n   * Ids from a counter, not from the clock or a hash of the text. Two identical\n   * questions in one thread are perfectly ordinary — \"who owes me money\" asked\n   * again after settling one — and keying on content would collapse them into\n   * one row that React then refuses to animate.\n   */\n  const nextId = useRef(0);\n\n  const say = useCallback((message: Omit<PotterMessage, 'id'>) => {\n    const id = `m${nextId.current++}`;\n    // Stamped HERE rather than by each caller, so every turn in every thread\n    // carries one and no door can forget.\n    setMessages((prev) => [...prev, { at: Date.now(), ...message, id }]);\n    // The id is minted by the first turn, so a panel that was opened and never\n    // spoken to leaves nothing behind.\n    setThreadId((current) => current ?? `t${Date.now().toString(36)}`);\n    return id;\n  }, []);\n\n  const resolve = useCallback(\n    (id: string, patch: Partial<Omit<PotterMessage, 'id'>>) => {\n      setMessages((prev) =>\n        /**\n         * `pending` FALLS BACK to false rather than being forced to it.\n         *\n         * Every caller that finishes a turn omits it and still lands on false,\n         * which is what this always did. Streaming needs the other half: a\n         * partial answer arrives many times before it is finished, and each\n         * arrival is a `resolve` that must leave the turn pending or the\n         * thinking indicator flickers off and on with every fragment.\n         */\n        prev.map((m) =>\n          m.id === id ? { ...m, ...patch, pending: patch.pending ?? false } : m,\n        ),\n      );\n    },\n    [],\n  );\n\n  /**\n   * The archive follows the live thread, it does not lead it.\n   *\n   * Writing on every turn rather than on close: a merchant who reloads\n   * mid-conversation, or whose tab is killed, has still asked the question and\n   * should still find the answer. Two turns land per ask, so this runs twice\n   * for one exchange — which is a `JSON.stringify` of at most twenty messages\n   * and cheaper than reasoning about which of the two was the last.\n   */\n  useEffect(() => {\n    if (!slug || !threadId || messages.length === 0) return;\n    saveThread(slug, {\n      id: threadId,\n      title: titleFor(messages),\n      messages,\n      updatedAt: Date.now(),\n    });\n    setThreads(listThreads(slug));\n  }, [slug, threadId, messages]);\n\n  // The archive for whichever workspace is current, read once per workspace.\n  useEffect(() => {\n    setThreads(listThreads(slug));\n  }, [slug]);\n\n  /**\n   * A CONVERSATION DOES NOT FOLLOW YOU BETWEEN BUSINESSES.\n   *\n   * The live thread lived in state and the archive was keyed per tenant, so\n   * switching workspace mid-conversation carried one business's answers into\n   * another's dock — and then the save effect wrote them under the NEW\n   * tenant's key. A merchant with four workspaces would find a spa's takings\n   * filed under their restaurant. The panel is not a place tenant data is\n   * allowed to bleed.\n   *\n   * Skips the first workspace so a normal boot does not wipe the thread the\n   * restore effect just brought back.\n   */\n  /** Which workspace the restore has already run for. */\n  const restored = useRef<string | null>(null);\n  const lastSlug = useRef<string | undefined>(undefined);\n  useEffect(() => {\n    const previous = lastSlug.current;\n    lastSlug.current = slug;\n    if (previous === undefined || previous === slug) return;\n    setMessages([]);\n    setThreadId(null);\n    setSeed(null);\n    setOpen(false);\n    restored.current = null;\n  }, [slug]);\n\n  /**\n   * Pick the conversation back up after a reload.\n   *\n   * Continuity was half-built: the archive survived, the thread you were\n   * actually in did not, so refreshing mid-conversation dropped you on an\n   * empty Box with the answer you had just read sitting one click away in\n   * History. Restores once per workspace and only onto an empty thread, so it\n   * can never overwrite something already being typed into.\n   */\n  useEffect(() => {\n    if (!slug || restored.current === slug) return;\n    restored.current = slug;\n    const id = readActiveThreadId(slug);\n    if (!id) return;\n    const found = listThreads(slug).find((t) => t.id === id);\n    if (!found || found.messages.length === 0) return;\n    nextId.current = found.messages.length;\n    setMessages(found.messages);\n    setThreadId(found.id);\n  }, [slug]);\n\n  // The pointer follows the live thread, including when it is dropped.\n  useEffect(() => {\n    writeActiveThreadId(slug, threadId);\n  }, [slug, threadId]);\n\n  const openPotter = useCallback(\n    (withText?: string) => {\n      if (withText?.trim()) setSeed(withText.trim());\n      // HERE, not on the launcher, because the door is not the only way in — a\n      // seeded open from the ask bar arrives through this same function, and a\n      // sound wired to the button would be silent for every other entrance.\n      // Only on the way IN: closing does not need announcing, and a sound on\n      // both edges of a panel people open a dozen times a day is a tic.\n      if (!open) playSound('potter');\n      setOpen(true);\n    },\n    [open],\n  );\n\n  const closePotter = useCallback(() => setOpen(false), []);\n\n  /**\n   * Hand a question to the ASK SCREEN, which is a route rather than a panel.\n   *\n   * `openPotter(text)` cannot do this job even though it looks like it should:\n   * it seeds AND sets `open`, and `open` is what mounts the launcher's floating\n   * panel. Sending from the home would arrive on `/dashboard/ask` with the\n   * corner panel hanging over it, asking the same question twice on two\n   * surfaces.\n   *\n   * So this sets the seed and nothing else. `PotterSurface` already consumes a\n   * seed on its next effect and drops it, which is exactly what the screen needs\n   * — the handoff is the seed, and the navigation is the caller's.\n   */\n  const handOff = useCallback((text: string, files?: File[]) => {\n    setSeedFiles(files ?? []);\n    if (text.trim()) setSeed(text.trim());\n  }, []);\n\n  const handSheet = useCallback(\n    (file: File | null) => setPendingSheet(file),\n    [],\n  );\n\n  /**\n   * Back to an empty conversation — WITHOUT destroying the one being left.\n   *\n   * `clear` used to be the only exit and it wiped the thread outright, which\n   * is why closing the home's answer lost it for good. It is already saved by\n   * the effect above; dropping the id is all that \"start again\" means now.\n   */\n  const clear = useCallback(() => {\n    setMessages([]);\n    setSeed(null);\n    setThreadId(null);\n  }, []);\n\n  const newThread = clear;\n\n  const openThread = useCallback(\n    (id: string) => {\n      const found = listThreads(slug).find((t) => t.id === id);\n      if (!found) return;\n      // Ids continue past the longest turn restored, so a reopened\n      // conversation cannot mint a key that collides with one already in it.\n      nextId.current = found.messages.length;\n      setMessages(found.messages);\n      setThreadId(found.id);\n      setSeed(null);\n      setOpen(true);\n    },\n    [slug],\n  );\n\n  const deleteThread = useCallback(\n    (id: string) => {\n      dropThread(slug, id);\n      setThreads(listThreads(slug));\n      // Deleting the conversation you are looking at leaves you on an empty\n      // one rather than on a thread with no home to go back to.\n      setThreadId((current) => {\n        if (current !== id) return current;\n        setMessages([]);\n        return null;\n      });\n    },\n    [slug],\n  );\n\n  const clearSeed = useCallback(() => {\n    setSeed(null);\n    setSeedFiles([]);\n  }, []);\n\n  const value = useMemo(\n    () => ({\n      open,\n      messages,\n      openPotter,\n      handOff,\n      pendingSheet,\n      handSheet,\n      pendingPhotos,\n      handPhotos,\n      closePotter,\n      say,\n      resolve,\n      clear,\n      seed,\n      seedFiles,\n      clearSeed,\n      threads,\n      newThread,\n      openThread,\n      deleteThread,\n    }),\n    [\n      open,\n      messages,\n      openPotter,\n      handOff,\n      pendingSheet,\n      handSheet,\n      pendingPhotos,\n      handPhotos,\n      closePotter,\n      say,\n      resolve,\n      clear,\n      seed,\n      seedFiles,\n      clearSeed,\n      threads,\n      newThread,\n      openThread,\n      deleteThread,\n    ],\n  );\n\n  return (\n    <PotterContext.Provider value={value}>{children}</PotterContext.Provider>\n  );\n}\n\nexport function usePotter(): PotterValue {\n  return useContext(PotterContext);\n}\n"],"mappings":"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","names":[]}

package/dist/potter/potter-conversation.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The conversation, as a conversation.
+ *
+ * WHAT WAS WRONG. Box had a thread renderer and no chat. You typed into a
+ * bar at the TOP of the page and the answers stacked downwards under it, so
+ * the composer was above the conversation and the newest turn was furthest
+ * from it — the inverse of every product a merchant has used, which is what
+ * John meant by *"theur no chat ui or what not like how claude does it or
+ * chatgpt or grok"*. There was no header, no way to start a second
+ * conversation, and no history at all: `clear()` deleted the thread and Close
+ * called `clear()`.
+ *
+ * WHAT THIS IS. The three parts every chat surface has and this one did not:
+ * a header that says whose conversation it is and lets you leave or start
+ * another, a scrolling transcript, and a composer pinned to the bottom of it.
+ * The transcript itself is still `PotterThread` — the reply bodies under
+ * Box's sentences are the substance of this product and none of that
+ * changes.
+ *
+ * IT OWNS NO WIDTH AND NO POSITION, like `PotterSurface` before it. The home
+ * renders it in the column where its ask bar was; the launcher renders it in
+ * an anchored panel. `maxHeight` is the one thing a caller must say, because
+ * only the caller knows how much room there is.
+ */
+export declare function PotterConversation({ maxHeight, fill, onClose, }: {
+    /** How tall the transcript may grow before it scrolls. Ignored when `fill`. */
+    maxHeight?: string;
+    /**
+     * Take the whole height the parent gives, rather than growing to fit.
+     *
+     * The dock is a full-height drawer, so its transcript should reach the
+     * composer at the bottom of the screen whether the conversation is two turns
+     * or forty. Left off, the panel is as tall as it needs to be — which is what
+     * the launcher's bottom sheet wants.
+     */
+    fill?: boolean;
+    /** Omitted where the surrounding panel already has its own dismiss. */
+    onClose?: () => void;
+}): import("react").JSX.Element;
+/**
+ * Past conversations, behind one control.
+ *
+ * Exported because the corner launcher has its own header and must not grow a
+ * second history list that can disagree with this one.
+ */
+export declare function PotterHistoryMenu({ 
+/**
+ * Draw the trigger as a rail item rather than a ghost icon button.
+ *
+ * The ask screen puts this beside "New conversation" in an `ActionRail`,
+ * where the two share one travelling chip and say their names on approach.
+ * The corner launcher's header has a single control in a crowded strip and
+ * keeps the plain glyph — a rail of one is a chip with nowhere to travel.
+ *
+ * `active` rather than hover is what holds the chip here: while this popover
+ * is up, the panel belongs to this glyph, and letting the chip go when the
+ * pointer moves away would leave the open list attached to nothing.
+ */
+rail, 
+/**
+ * Drawn as a round 28px control, to stand in the home bar's own row beside
+ * the paperclip, the mic and Send. Three shapes for one menu because it now
+ * appears in three frames — a ghost icon in the launcher's crowded header, a
+ * rail item on the ask screen, and this — and a control that does not match
+ * the row it sits in reads as something that was dropped there.
+ */
+bar, mobile, 
+/**
+ * Run after a conversation is chosen, once the thread is loaded.
+ *
+ * The home needs it: `openThread` puts the thread on the context and nothing
+ * else, which is the whole job on a surface that is already showing the
+ * conversation. On the home it would load a thread onto a page with nowhere
+ * to draw it, so the home passes a navigation.
+ */
+onOpened, }?: {
+    rail?: boolean;
+    bar?: boolean;
+    mobile?: boolean;
+    onOpened?: () => void;
+}): import("react").JSX.Element;