@sudobility/sider_lib 0.0.12 → 0.0.13

package/dist/chat-history.d.ts

@@ -0,0 +1,80 @@
+/** A stored conversation, as much of one as the rules here need. */
+export interface ChatRecord {
+    id: string;
+    /** Registrable domain, e.g. `ebay.com`. The chat's identity. */
+    domain: string;
+    /** Epoch ms of the last message either way. The retention clock. */
+    lastActivityAt: number;
+    /** Epoch ms the chat was started. Shown, never used to expire. */
+    createdAt: number;
+    /** The page the conversation was last on, so reopening it returns there. */
+    lastUrl?: string;
+    /** First user message, for the list. Absent until they say something. */
+    title?: string;
+    /** How many messages it holds. A chat with none is not history. */
+    messageCount: number;
+}
+/** How long a chat survives without activity. */
+export declare const RETENTION_CHOICES: readonly [1, 3, 7];
+export type RetentionDays = (typeof RETENTION_CHOICES)[number];
+export declare const DEFAULT_RETENTION_DAYS: RetentionDays;
+/**
+ * How many chats are kept at most, whatever the retention says.
+ *
+ * localStorage is a handful of megabytes and a full one throws on write, which
+ * would lose the conversation being saved rather than an old one. A cap turns
+ * that into a prune of the least recently used, which is the outcome anyone
+ * would have chosen.
+ */
+export declare const MAX_CHATS = 100;
+/** Title shown before the user has said anything. */
+export declare const UNTITLED = "New chat";
+/**
+ * The domain a chat belongs to.
+ *
+ * Returns "" for anything without a real host — a new tab, a file, an
+ * extension page — which the caller reads as "no site here to chat about".
+ */
+export declare function registrableDomain(url: string): string;
+/**
+ * The chat to show for a domain: its most recently active one.
+ *
+ * Most recent rather than most recently created, because "bring chat1 back"
+ * means the conversation they were last having there, and a chat they started
+ * and abandoned should not outrank the one they actually used.
+ */
+export declare function latestChatFor<T extends ChatRecord>(chats: T[], domain: string): T | undefined;
+/** Whether a chat has aged out, measured from its last activity. */
+export declare function isExpired(chat: ChatRecord, retentionDays: RetentionDays, now: number): boolean;
+/**
+ * The history, swept.
+ *
+ * Two rules, in order. Anything untouched for longer than the retention goes —
+ * the clock runs from last activity, so a conversation still in use is never
+ * swept, however old it is. Then the cap: if what remains still exceeds
+ * MAX_CHATS, the least recently used go, because a write that throws would
+ * lose the NEW chat rather than an old one.
+ *
+ * `keepId` protects the chat currently on screen from both rules. Deleting the
+ * conversation someone is looking at is never the right answer to a storage
+ * limit.
+ */
+export declare function sweepChats<T extends ChatRecord>(chats: T[], options: {
+    retentionDays: RetentionDays;
+    now: number;
+    keepId?: string;
+}): T[];
+/** History as the list shows it: everything, newest activity first. */
+export declare function orderedHistory<T extends ChatRecord>(chats: T[]): T[];
+/**
+ * Whether a chat is worth remembering.
+ *
+ * An empty one is not. Starting a new chat twice in a row should not leave two
+ * blank rows in the list, and a chat nobody has spoken in has nothing to bring
+ * back.
+ */
+export declare function isWorthKeeping(chat: ChatRecord): boolean;
+/** How long a title may be before the list truncates it. */
+export declare const MAX_TITLE_LENGTH = 60;
+/** A chat's title: what the user first asked, or a placeholder until they do. */
+export declare function titleFrom(firstUserMessage: string | undefined): string;

package/dist/chat-history.js

@@ -0,0 +1,141 @@
+// Which conversation belongs to the site you are looking at.
+//
+// A chat is tied to a DOMAIN, not a tab or a URL: eBay's sign-in lives on
+// signin.ebay.com and its listings on www.ebay.com, and a conversation about
+// buying something has to survive the walk between them. Splitting per host
+// would have swapped the chat out mid-task — which we watched happen when
+// "Save this search" redirected to signin.ebay.com.
+//
+// Pure and storage-free on purpose. The extension owns localStorage and the
+// panel owns the animation; what lives here is the part worth testing without
+// either: which chat a domain gets, what a domain even is, and what has aged
+// out.
+/** How long a chat survives without activity. */
+export const RETENTION_CHOICES = [1, 3, 7];
+export const DEFAULT_RETENTION_DAYS = 3;
+/**
+ * How many chats are kept at most, whatever the retention says.
+ *
+ * localStorage is a handful of megabytes and a full one throws on write, which
+ * would lose the conversation being saved rather than an old one. A cap turns
+ * that into a prune of the least recently used, which is the outcome anyone
+ * would have chosen.
+ */
+export const MAX_CHATS = 100;
+/** Title shown before the user has said anything. */
+export const UNTITLED = "New chat";
+/**
+ * Suffixes where the registrable domain takes THREE labels, not two.
+ *
+ * Not the full public suffix list — that is thousands of entries and a
+ * dependency this package does not want. These cover the multi-part suffixes a
+ * user is realistically browsing; anything missed falls back to two labels,
+ * which errs toward one chat for `bbc.co.uk` rather than a chat per subdomain.
+ */
+const MULTI_PART_SUFFIXES = new Set([
+    "co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "net.uk", "sch.uk",
+    "com.au", "net.au", "org.au", "edu.au", "gov.au", "id.au",
+    "co.nz", "net.nz", "org.nz", "govt.nz", "ac.nz",
+    "co.jp", "or.jp", "ne.jp", "ac.jp", "go.jp",
+    "com.br", "net.br", "org.br", "gov.br",
+    "com.cn", "net.cn", "org.cn", "gov.cn", "edu.cn",
+    "co.in", "net.in", "org.in", "gov.in", "ac.in",
+    "com.mx", "com.ar", "com.tr", "com.sg", "com.hk", "com.tw", "com.my",
+    "co.za", "co.kr", "co.il", "co.id", "com.pl", "com.ua", "com.ph", "com.vn",
+]);
+/**
+ * The domain a chat belongs to.
+ *
+ * Returns "" for anything without a real host — a new tab, a file, an
+ * extension page — which the caller reads as "no site here to chat about".
+ */
+export function registrableDomain(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return "";
+    }
+    // Only pages the agent can actually drive. `chrome://extensions` parses
+    // perfectly well and yields a hostname of "extensions", which would open a
+    // chat about a browser settings page.
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        return "";
+    const host = parsed.hostname.toLowerCase();
+    if (!host || host === "localhost")
+        return host;
+    // An IP address has no registrable domain; it IS the identity.
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":"))
+        return host;
+    const labels = host.split(".").filter(Boolean);
+    if (labels.length <= 2)
+        return labels.join(".");
+    const lastTwo = labels.slice(-2).join(".");
+    const take = MULTI_PART_SUFFIXES.has(lastTwo) ? 3 : 2;
+    return labels.slice(-take).join(".");
+}
+/**
+ * The chat to show for a domain: its most recently active one.
+ *
+ * Most recent rather than most recently created, because "bring chat1 back"
+ * means the conversation they were last having there, and a chat they started
+ * and abandoned should not outrank the one they actually used.
+ */
+export function latestChatFor(chats, domain) {
+    if (!domain)
+        return undefined;
+    return chats
+        .filter(c => c.domain === domain)
+        .reduce((best, c) => (!best || c.lastActivityAt > best.lastActivityAt ? c : best), undefined);
+}
+/** Whether a chat has aged out, measured from its last activity. */
+export function isExpired(chat, retentionDays, now) {
+    return now - chat.lastActivityAt > retentionDays * 24 * 60 * 60 * 1000;
+}
+/**
+ * The history, swept.
+ *
+ * Two rules, in order. Anything untouched for longer than the retention goes —
+ * the clock runs from last activity, so a conversation still in use is never
+ * swept, however old it is. Then the cap: if what remains still exceeds
+ * MAX_CHATS, the least recently used go, because a write that throws would
+ * lose the NEW chat rather than an old one.
+ *
+ * `keepId` protects the chat currently on screen from both rules. Deleting the
+ * conversation someone is looking at is never the right answer to a storage
+ * limit.
+ */
+export function sweepChats(chats, options) {
+    const kept = chats.filter(c => c.id === options.keepId || !isExpired(c, options.retentionDays, options.now));
+    if (kept.length <= MAX_CHATS)
+        return kept;
+    const byRecency = [...kept].sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+    const survivors = new Set(byRecency.slice(0, MAX_CHATS).map(c => c.id));
+    if (options.keepId)
+        survivors.add(options.keepId);
+    return kept.filter(c => survivors.has(c.id));
+}
+/** History as the list shows it: everything, newest activity first. */
+export function orderedHistory(chats) {
+    return [...chats].sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+}
+/**
+ * Whether a chat is worth remembering.
+ *
+ * An empty one is not. Starting a new chat twice in a row should not leave two
+ * blank rows in the list, and a chat nobody has spoken in has nothing to bring
+ * back.
+ */
+export function isWorthKeeping(chat) {
+    return chat.messageCount > 0;
+}
+/** How long a title may be before the list truncates it. */
+export const MAX_TITLE_LENGTH = 60;
+/** A chat's title: what the user first asked, or a placeholder until they do. */
+export function titleFrom(firstUserMessage) {
+    const text = firstUserMessage?.replace(/\s+/g, " ").trim();
+    if (!text)
+        return UNTITLED;
+    return text.length <= MAX_TITLE_LENGTH ? text : `${text.slice(0, MAX_TITLE_LENGTH - 1)}…`;
+}

package/dist/chat-history.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/chat-history.test.js

@@ -0,0 +1,118 @@
+import { test, expect } from "bun:test";
+import { DEFAULT_RETENTION_DAYS, MAX_CHATS, UNTITLED, isWorthKeeping, latestChatFor, orderedHistory, registrableDomain, sweepChats, titleFrom, } from "./chat-history";
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = 1_760_000_000_000;
+const chat = (over = {}) => ({
+    id: "c1",
+    domain: "ebay.com",
+    createdAt: NOW,
+    lastActivityAt: NOW,
+    messageCount: 2,
+    ...over,
+});
+// --- what a domain is -------------------------------------------------------
+test("a chat spans a site's subdomains", () => {
+    // The case that motivated this: "Save this search" redirected to
+    // signin.ebay.com, and a per-host rule would have swapped the chat out
+    // mid-task.
+    expect(registrableDomain("https://www.ebay.com/sch/i.html")).toBe("ebay.com");
+    expect(registrableDomain("https://signin.ebay.com/ws/eBayISAPI.dll")).toBe("ebay.com");
+    expect(registrableDomain("http://ebay.com")).toBe("ebay.com");
+});
+test("different sites are different chats", () => {
+    expect(registrableDomain("https://www.amazon.com")).not.toBe(registrableDomain("https://www.ebay.com"));
+});
+test("handles suffixes where the domain takes three labels", () => {
+    // Two labels would make every bbc.co.uk subdomain its own chat, and worse,
+    // would merge unrelated sites under "co.uk".
+    expect(registrableDomain("https://www.bbc.co.uk/news")).toBe("bbc.co.uk");
+    expect(registrableDomain("https://shop.coles.com.au")).toBe("coles.com.au");
+});
+test("says nothing for a page that is not a site", () => {
+    // A new tab, a local file, the extension's own pages: nothing to chat about.
+    expect(registrableDomain("about:blank")).toBe("");
+    expect(registrableDomain("chrome://extensions")).toBe("");
+    expect(registrableDomain("not a url")).toBe("");
+});
+test("an address with no domain is its own identity", () => {
+    expect(registrableDomain("http://127.0.0.1:8080/app")).toBe("127.0.0.1");
+    expect(registrableDomain("http://localhost:7177")).toBe("localhost");
+});
+// --- which chat comes back --------------------------------------------------
+test("switching back to a site brings back the chat you were having there", () => {
+    const chats = [
+        chat({ id: "ebay-old", lastActivityAt: NOW - 2 * DAY }),
+        chat({ id: "ebay-recent", lastActivityAt: NOW - 1000 }),
+        chat({ id: "amazon", domain: "amazon.com", lastActivityAt: NOW }),
+    ];
+    expect(latestChatFor(chats, "ebay.com")?.id).toBe("ebay-recent");
+    expect(latestChatFor(chats, "amazon.com")?.id).toBe("amazon");
+});
+test("a site with no chat yet has none, and a new one is started", () => {
+    expect(latestChatFor([chat()], "target.com")).toBeUndefined();
+    expect(latestChatFor([chat()], "")).toBeUndefined();
+});
+test("most recently USED wins, not most recently started", () => {
+    // A chat someone opened and abandoned should not outrank the one they were
+    // actually having.
+    const chats = [
+        chat({ id: "abandoned", createdAt: NOW, lastActivityAt: NOW - DAY }),
+        chat({ id: "in-use", createdAt: NOW - 5 * DAY, lastActivityAt: NOW }),
+    ];
+    expect(latestChatFor(chats, "ebay.com")?.id).toBe("in-use");
+});
+// --- what ages out ----------------------------------------------------------
+test("a chat untouched for longer than the retention is swept", () => {
+    const chats = [
+        chat({ id: "stale", lastActivityAt: NOW - 4 * DAY }),
+        chat({ id: "fresh", lastActivityAt: NOW - 1 * DAY }),
+    ];
+    const kept = sweepChats(chats, { retentionDays: DEFAULT_RETENTION_DAYS, now: NOW });
+    expect(kept.map(c => c.id)).toEqual(["fresh"]);
+});
+test("a chat you are still using is never swept, however old", () => {
+    // The clock runs from last activity, so a week-old conversation used this
+    // morning survives a one-day retention.
+    const chats = [chat({ id: "old-but-live", createdAt: NOW - 30 * DAY, lastActivityAt: NOW - 1000 })];
+    expect(sweepChats(chats, { retentionDays: 1, now: NOW })).toHaveLength(1);
+});
+test("the chat on screen survives the sweep even when it has aged out", () => {
+    // Deleting the conversation someone is looking at is never the right answer.
+    const chats = [chat({ id: "current", lastActivityAt: NOW - 30 * DAY })];
+    const kept = sweepChats(chats, { retentionDays: 1, now: NOW, keepId: "current" });
+    expect(kept.map(c => c.id)).toEqual(["current"]);
+});
+test("beyond the cap the least recently used go", () => {
+    // A full localStorage throws on WRITE, which would lose the new chat rather
+    // than an old one. Pruning turns that into the outcome anyone would choose.
+    const many = Array.from({ length: MAX_CHATS + 10 }, (_, i) => chat({ id: `c${i}`, lastActivityAt: NOW - i * 1000 }));
+    const kept = sweepChats(many, { retentionDays: 7, now: NOW });
+    expect(kept).toHaveLength(MAX_CHATS);
+    expect(kept.some(c => c.id === "c0")).toBe(true);
+    expect(kept.some(c => c.id === `c${MAX_CHATS + 5}`)).toBe(false);
+});
+// --- the list ---------------------------------------------------------------
+test("history is every domain, newest activity first", () => {
+    const chats = [
+        chat({ id: "a", domain: "amazon.com", lastActivityAt: NOW - DAY }),
+        chat({ id: "b", domain: "ebay.com", lastActivityAt: NOW }),
+        chat({ id: "c", domain: "nvidia.com", lastActivityAt: NOW - 2 * DAY }),
+    ];
+    expect(orderedHistory(chats).map(c => c.id)).toEqual(["b", "a", "c"]);
+});
+test("an empty chat is not history", () => {
+    // Starting a new chat twice should not leave two blank rows.
+    expect(isWorthKeeping(chat({ messageCount: 0 }))).toBe(false);
+    expect(isWorthKeeping(chat({ messageCount: 1 }))).toBe(true);
+});
+test("a chat is titled by what was first asked", () => {
+    expect(titleFrom("Find me a gaming PC with a 5090")).toBe("Find me a gaming PC with a 5090");
+    expect(titleFrom(undefined)).toBe(UNTITLED);
+    expect(titleFrom("   ")).toBe(UNTITLED);
+});
+test("a long first message is truncated, not wrapped across the list", () => {
+    const long = "x".repeat(200);
+    const title = titleFrom(long);
+    expect(title.length).toBeLessThanOrEqual(60);
+    expect(title.endsWith("…")).toBe(true);
+});

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./recipe";
 export * from "./gates";
 export * from "./execute";
 export * from "./composite";
+export * from "./chat-history";

package/dist/index.js

@@ -20,3 +20,6 @@ export * from "./recipe";
 export * from "./gates";
 export * from "./execute";
 export * from "./composite";
+// Client-side chat history: which conversation belongs to the site in front
+// of you, and what has aged out. Storage and UI live in the extension.
+export * from "./chat-history";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudobility/sider_lib",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Sider business logic — recipe compiler, egress gates, tokenizer, clustering. Pure, no Chrome/DOM/server.",
   "license": "BUSL-1.1",
   "publishConfig": {

package/src/chat-history.test.ts

@@ -0,0 +1,153 @@
+import { test, expect } from "bun:test";
+import {
+  DEFAULT_RETENTION_DAYS,
+  MAX_CHATS,
+  UNTITLED,
+  isWorthKeeping,
+  latestChatFor,
+  orderedHistory,
+  registrableDomain,
+  sweepChats,
+  titleFrom,
+  type ChatRecord,
+} from "./chat-history";
+
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = 1_760_000_000_000;
+
+const chat = (over: Partial<ChatRecord> = {}): ChatRecord => ({
+  id: "c1",
+  domain: "ebay.com",
+  createdAt: NOW,
+  lastActivityAt: NOW,
+  messageCount: 2,
+  ...over,
+});
+
+// --- what a domain is -------------------------------------------------------
+
+test("a chat spans a site's subdomains", () => {
+  // The case that motivated this: "Save this search" redirected to
+  // signin.ebay.com, and a per-host rule would have swapped the chat out
+  // mid-task.
+  expect(registrableDomain("https://www.ebay.com/sch/i.html")).toBe("ebay.com");
+  expect(registrableDomain("https://signin.ebay.com/ws/eBayISAPI.dll")).toBe("ebay.com");
+  expect(registrableDomain("http://ebay.com")).toBe("ebay.com");
+});
+
+test("different sites are different chats", () => {
+  expect(registrableDomain("https://www.amazon.com")).not.toBe(registrableDomain("https://www.ebay.com"));
+});
+
+test("handles suffixes where the domain takes three labels", () => {
+  // Two labels would make every bbc.co.uk subdomain its own chat, and worse,
+  // would merge unrelated sites under "co.uk".
+  expect(registrableDomain("https://www.bbc.co.uk/news")).toBe("bbc.co.uk");
+  expect(registrableDomain("https://shop.coles.com.au")).toBe("coles.com.au");
+});
+
+test("says nothing for a page that is not a site", () => {
+  // A new tab, a local file, the extension's own pages: nothing to chat about.
+  expect(registrableDomain("about:blank")).toBe("");
+  expect(registrableDomain("chrome://extensions")).toBe("");
+  expect(registrableDomain("not a url")).toBe("");
+});
+
+test("an address with no domain is its own identity", () => {
+  expect(registrableDomain("http://127.0.0.1:8080/app")).toBe("127.0.0.1");
+  expect(registrableDomain("http://localhost:7177")).toBe("localhost");
+});
+
+// --- which chat comes back --------------------------------------------------
+
+test("switching back to a site brings back the chat you were having there", () => {
+  const chats = [
+    chat({ id: "ebay-old", lastActivityAt: NOW - 2 * DAY }),
+    chat({ id: "ebay-recent", lastActivityAt: NOW - 1000 }),
+    chat({ id: "amazon", domain: "amazon.com", lastActivityAt: NOW }),
+  ];
+  expect(latestChatFor(chats, "ebay.com")?.id).toBe("ebay-recent");
+  expect(latestChatFor(chats, "amazon.com")?.id).toBe("amazon");
+});
+
+test("a site with no chat yet has none, and a new one is started", () => {
+  expect(latestChatFor([chat()], "target.com")).toBeUndefined();
+  expect(latestChatFor([chat()], "")).toBeUndefined();
+});
+
+test("most recently USED wins, not most recently started", () => {
+  // A chat someone opened and abandoned should not outrank the one they were
+  // actually having.
+  const chats = [
+    chat({ id: "abandoned", createdAt: NOW, lastActivityAt: NOW - DAY }),
+    chat({ id: "in-use", createdAt: NOW - 5 * DAY, lastActivityAt: NOW }),
+  ];
+  expect(latestChatFor(chats, "ebay.com")?.id).toBe("in-use");
+});
+
+// --- what ages out ----------------------------------------------------------
+
+test("a chat untouched for longer than the retention is swept", () => {
+  const chats = [
+    chat({ id: "stale", lastActivityAt: NOW - 4 * DAY }),
+    chat({ id: "fresh", lastActivityAt: NOW - 1 * DAY }),
+  ];
+  const kept = sweepChats(chats, { retentionDays: DEFAULT_RETENTION_DAYS, now: NOW });
+  expect(kept.map(c => c.id)).toEqual(["fresh"]);
+});
+
+test("a chat you are still using is never swept, however old", () => {
+  // The clock runs from last activity, so a week-old conversation used this
+  // morning survives a one-day retention.
+  const chats = [chat({ id: "old-but-live", createdAt: NOW - 30 * DAY, lastActivityAt: NOW - 1000 })];
+  expect(sweepChats(chats, { retentionDays: 1, now: NOW })).toHaveLength(1);
+});
+
+test("the chat on screen survives the sweep even when it has aged out", () => {
+  // Deleting the conversation someone is looking at is never the right answer.
+  const chats = [chat({ id: "current", lastActivityAt: NOW - 30 * DAY })];
+  const kept = sweepChats(chats, { retentionDays: 1, now: NOW, keepId: "current" });
+  expect(kept.map(c => c.id)).toEqual(["current"]);
+});
+
+test("beyond the cap the least recently used go", () => {
+  // A full localStorage throws on WRITE, which would lose the new chat rather
+  // than an old one. Pruning turns that into the outcome anyone would choose.
+  const many = Array.from({ length: MAX_CHATS + 10 }, (_, i) =>
+    chat({ id: `c${i}`, lastActivityAt: NOW - i * 1000 }),
+  );
+  const kept = sweepChats(many, { retentionDays: 7, now: NOW });
+  expect(kept).toHaveLength(MAX_CHATS);
+  expect(kept.some(c => c.id === "c0")).toBe(true);
+  expect(kept.some(c => c.id === `c${MAX_CHATS + 5}`)).toBe(false);
+});
+
+// --- the list ---------------------------------------------------------------
+
+test("history is every domain, newest activity first", () => {
+  const chats = [
+    chat({ id: "a", domain: "amazon.com", lastActivityAt: NOW - DAY }),
+    chat({ id: "b", domain: "ebay.com", lastActivityAt: NOW }),
+    chat({ id: "c", domain: "nvidia.com", lastActivityAt: NOW - 2 * DAY }),
+  ];
+  expect(orderedHistory(chats).map(c => c.id)).toEqual(["b", "a", "c"]);
+});
+
+test("an empty chat is not history", () => {
+  // Starting a new chat twice should not leave two blank rows.
+  expect(isWorthKeeping(chat({ messageCount: 0 }))).toBe(false);
+  expect(isWorthKeeping(chat({ messageCount: 1 }))).toBe(true);
+});
+
+test("a chat is titled by what was first asked", () => {
+  expect(titleFrom("Find me a gaming PC with a 5090")).toBe("Find me a gaming PC with a 5090");
+  expect(titleFrom(undefined)).toBe(UNTITLED);
+  expect(titleFrom("   ")).toBe(UNTITLED);
+});
+
+test("a long first message is truncated, not wrapped across the list", () => {
+  const long = "x".repeat(200);
+  const title = titleFrom(long);
+  expect(title.length).toBeLessThanOrEqual(60);
+  expect(title.endsWith("…")).toBe(true);
+});

package/src/chat-history.ts

@@ -0,0 +1,170 @@
+// Which conversation belongs to the site you are looking at.
+//
+// A chat is tied to a DOMAIN, not a tab or a URL: eBay's sign-in lives on
+// signin.ebay.com and its listings on www.ebay.com, and a conversation about
+// buying something has to survive the walk between them. Splitting per host
+// would have swapped the chat out mid-task — which we watched happen when
+// "Save this search" redirected to signin.ebay.com.
+//
+// Pure and storage-free on purpose. The extension owns localStorage and the
+// panel owns the animation; what lives here is the part worth testing without
+// either: which chat a domain gets, what a domain even is, and what has aged
+// out.
+
+/** A stored conversation, as much of one as the rules here need. */
+export interface ChatRecord {
+  id: string;
+  /** Registrable domain, e.g. `ebay.com`. The chat's identity. */
+  domain: string;
+  /** Epoch ms of the last message either way. The retention clock. */
+  lastActivityAt: number;
+  /** Epoch ms the chat was started. Shown, never used to expire. */
+  createdAt: number;
+  /** The page the conversation was last on, so reopening it returns there. */
+  lastUrl?: string;
+  /** First user message, for the list. Absent until they say something. */
+  title?: string;
+  /** How many messages it holds. A chat with none is not history. */
+  messageCount: number;
+}
+
+/** How long a chat survives without activity. */
+export const RETENTION_CHOICES = [1, 3, 7] as const;
+export type RetentionDays = (typeof RETENTION_CHOICES)[number];
+export const DEFAULT_RETENTION_DAYS: RetentionDays = 3;
+
+/**
+ * How many chats are kept at most, whatever the retention says.
+ *
+ * localStorage is a handful of megabytes and a full one throws on write, which
+ * would lose the conversation being saved rather than an old one. A cap turns
+ * that into a prune of the least recently used, which is the outcome anyone
+ * would have chosen.
+ */
+export const MAX_CHATS = 100;
+
+/** Title shown before the user has said anything. */
+export const UNTITLED = "New chat";
+
+/**
+ * Suffixes where the registrable domain takes THREE labels, not two.
+ *
+ * Not the full public suffix list — that is thousands of entries and a
+ * dependency this package does not want. These cover the multi-part suffixes a
+ * user is realistically browsing; anything missed falls back to two labels,
+ * which errs toward one chat for `bbc.co.uk` rather than a chat per subdomain.
+ */
+const MULTI_PART_SUFFIXES = new Set([
+  "co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "net.uk", "sch.uk",
+  "com.au", "net.au", "org.au", "edu.au", "gov.au", "id.au",
+  "co.nz", "net.nz", "org.nz", "govt.nz", "ac.nz",
+  "co.jp", "or.jp", "ne.jp", "ac.jp", "go.jp",
+  "com.br", "net.br", "org.br", "gov.br",
+  "com.cn", "net.cn", "org.cn", "gov.cn", "edu.cn",
+  "co.in", "net.in", "org.in", "gov.in", "ac.in",
+  "com.mx", "com.ar", "com.tr", "com.sg", "com.hk", "com.tw", "com.my",
+  "co.za", "co.kr", "co.il", "co.id", "com.pl", "com.ua", "com.ph", "com.vn",
+]);
+
+/**
+ * The domain a chat belongs to.
+ *
+ * Returns "" for anything without a real host — a new tab, a file, an
+ * extension page — which the caller reads as "no site here to chat about".
+ */
+export function registrableDomain(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return "";
+  }
+  // Only pages the agent can actually drive. `chrome://extensions` parses
+  // perfectly well and yields a hostname of "extensions", which would open a
+  // chat about a browser settings page.
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return "";
+  const host = parsed.hostname.toLowerCase();
+  if (!host || host === "localhost") return host;
+  // An IP address has no registrable domain; it IS the identity.
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return host;
+
+  const labels = host.split(".").filter(Boolean);
+  if (labels.length <= 2) return labels.join(".");
+
+  const lastTwo = labels.slice(-2).join(".");
+  const take = MULTI_PART_SUFFIXES.has(lastTwo) ? 3 : 2;
+  return labels.slice(-take).join(".");
+}
+
+/**
+ * The chat to show for a domain: its most recently active one.
+ *
+ * Most recent rather than most recently created, because "bring chat1 back"
+ * means the conversation they were last having there, and a chat they started
+ * and abandoned should not outrank the one they actually used.
+ */
+export function latestChatFor<T extends ChatRecord>(chats: T[], domain: string): T | undefined {
+  if (!domain) return undefined;
+  return chats
+    .filter(c => c.domain === domain)
+    .reduce<T | undefined>((best, c) => (!best || c.lastActivityAt > best.lastActivityAt ? c : best), undefined);
+}
+
+/** Whether a chat has aged out, measured from its last activity. */
+export function isExpired(chat: ChatRecord, retentionDays: RetentionDays, now: number): boolean {
+  return now - chat.lastActivityAt > retentionDays * 24 * 60 * 60 * 1000;
+}
+
+/**
+ * The history, swept.
+ *
+ * Two rules, in order. Anything untouched for longer than the retention goes —
+ * the clock runs from last activity, so a conversation still in use is never
+ * swept, however old it is. Then the cap: if what remains still exceeds
+ * MAX_CHATS, the least recently used go, because a write that throws would
+ * lose the NEW chat rather than an old one.
+ *
+ * `keepId` protects the chat currently on screen from both rules. Deleting the
+ * conversation someone is looking at is never the right answer to a storage
+ * limit.
+ */
+export function sweepChats<T extends ChatRecord>(
+  chats: T[],
+  options: { retentionDays: RetentionDays; now: number; keepId?: string },
+): T[] {
+  const kept = chats.filter(
+    c => c.id === options.keepId || !isExpired(c, options.retentionDays, options.now),
+  );
+  if (kept.length <= MAX_CHATS) return kept;
+
+  const byRecency = [...kept].sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+  const survivors = new Set(byRecency.slice(0, MAX_CHATS).map(c => c.id));
+  if (options.keepId) survivors.add(options.keepId);
+  return kept.filter(c => survivors.has(c.id));
+}
+
+/** History as the list shows it: everything, newest activity first. */
+export function orderedHistory<T extends ChatRecord>(chats: T[]): T[] {
+  return [...chats].sort((a, b) => b.lastActivityAt - a.lastActivityAt);
+}
+
+/**
+ * Whether a chat is worth remembering.
+ *
+ * An empty one is not. Starting a new chat twice in a row should not leave two
+ * blank rows in the list, and a chat nobody has spoken in has nothing to bring
+ * back.
+ */
+export function isWorthKeeping(chat: ChatRecord): boolean {
+  return chat.messageCount > 0;
+}
+
+/** How long a title may be before the list truncates it. */
+export const MAX_TITLE_LENGTH = 60;
+
+/** A chat's title: what the user first asked, or a placeholder until they do. */
+export function titleFrom(firstUserMessage: string | undefined): string {
+  const text = firstUserMessage?.replace(/\s+/g, " ").trim();
+  if (!text) return UNTITLED;
+  return text.length <= MAX_TITLE_LENGTH ? text : `${text.slice(0, MAX_TITLE_LENGTH - 1)}…`;
+}

package/src/index.ts

@@ -37,3 +37,7 @@ export * from "./recipe";
 export * from "./gates";
 export * from "./execute";
 export * from "./composite";
+
+// Client-side chat history: which conversation belongs to the site in front
+// of you, and what has aged out. Storage and UI live in the extension.
+export * from "./chat-history";