A local-first multi-agent app development platform, built on PenguinHarness
import { createStore } from "zustand/vanilla";
import { useStore } from "zustand/react";
/**
* Per-Session "the user has seen the latest reply" markers — the read/unread half of the
* sidebar's completion glyph.
*
* The server has no notion of a read receipt: there is no notifications table, no read/seen
* column on `sessions`, and `SessionInfo` carries no such field, so a server-side marker would
* need schema + API changes. This follows the precedent pinned-sessions.ts already set for a
* per-Session flag the API does not model: persist it per Project in localStorage under the
* `penguin.…` key naming, with injectable storage (vitest runs in Node, no localStorage).
*
* Consequences, deliberately accepted:
* - per BROWSER, not per user — the same account on another device starts with its own markers;
* - no cross-tab sync — the repo has no `storage` listener anywhere and says so on purpose
* (chat-defaults-event.ts: "Same-tab only by design"), so a second tab keeps its own view
* until it reloads.
*
* "Read" is a timestamp comparison rather than a flag, because the question is not "was this
* Session ever opened" but "was it opened SINCE its last reply": the marker holds when the user
* last looked, and `SessionInfo.lastActiveAt` (stamped by the server at run start and again at
* run end) holds when the Session last did anything. Later activity than the marker = unread.
*/
/** Minimal storage interface (the subset of localStorage used here); tests inject an in-memory implementation. */
export interface SessionSeenStorage {
getItem(key: string): string | null;
setItem(key: string, value: string): void;
}
/** Storage key of one Project's seen markers (sidebar key-naming convention, `penguin.pinnedSessions.<projectId>` &c.). */
export const sessionSeenKey = (projectId: string): string => `penguin.sessionSeen.${projectId}`;
/**
* Cap on remembered markers per Project. Only Sessions the user actually opened get one, so
* this is generous; past it the least recently seen are dropped, and a dropped Session falls
* back to `seededAt` — i.e. reads as read, not as a surprise unread.
*/
const MAX_MARKERS = 500;
/** One Project's markers: when the user last looked at each Session, plus the baseline below. */
export interface SessionSeenState {
/**
* Epoch ms first written for this Project. Everything that last ran at or before it counts as
* read without its own marker — otherwise enabling the feature would light up every historical
* conversation at once, which is noise, not information.
*/
seededAt: number;
/** sessionId → epoch ms the user last had it open. */
seen: ReadonlyMap<string, number>;
}
const EMPTY: SessionSeenState = { seededAt: 0, seen: new Map() };
function storageOf(injected?: SessionSeenStorage): SessionSeenStorage | null {
if (injected) return injected;
try {
// localStorage is resolved INSIDE the try, never as a default parameter: merely touching it
// throws a SecurityError when site data is blocked (or in a partitioned iframe).
return localStorage;
} catch {
return null; // No storage at all (privacy mode edge): every finished Session reads as read.
}
}
/** Parses one Project's stored blob; anything malformed degrades to "nothing remembered". */
export function parseSessionSeen(raw: string | null): SessionSeenState {
if (raw === null) return EMPTY;
try {
const parsed: unknown = JSON.parse(raw);
if (typeof parsed !== "object" || parsed === null) return EMPTY;
const o = parsed as { seededAt?: unknown; seen?: unknown };
const seededAt = typeof o.seededAt === "number" && Number.isFinite(o.seededAt) ? o.seededAt : 0;
const seen = new Map<string, number>();
if (typeof o.seen === "object" && o.seen !== null) {
for (const [id, at] of Object.entries(o.seen as Record<string, unknown>)) {
if (typeof at === "number" && Number.isFinite(at)) seen.set(id, at);
}
}
return { seededAt, seen };
} catch {
return EMPTY;
}
}
/** Serializes one Project's markers, keeping only the `MAX_MARKERS` most recently seen. */
export function serializeSessionSeen(state: SessionSeenState): string {
let entries = [...state.seen];
if (entries.length > MAX_MARKERS) {
entries.sort((a, b) => b[1] - a[1]);
entries = entries.slice(0, MAX_MARKERS);
}
return JSON.stringify({ seededAt: state.seededAt, seen: Object.fromEntries(entries) });
}
/**
* Records that the user is looking at a Session now.
*
* The marker is the LATER of the wall clock and the Session's own `lastActiveAt`, so opening a
* Session always marks it read even when this browser's clock lags the server's — a stuck unread
* badge is the failure users actually notice.
*/
export function markSessionSeen(
state: SessionSeenState,
sessionId: string,
lastActiveAt: string,
now: number = Date.now(),
): SessionSeenState {
const activeAt = Date.parse(lastActiveAt);
const at = Number.isNaN(activeAt) ? now : Math.max(now, activeAt);
if (state.seen.get(sessionId) === at) return state; // No-op: skip the write and the re-render.
return { seededAt: state.seededAt, seen: new Map(state.seen).set(sessionId, at) };
}
/** Prune on Session delete; returns the input state unchanged when nothing was remembered. */
export function forgetSessionSeen(state: SessionSeenState, sessionId: string): SessionSeenState {
if (!state.seen.has(sessionId)) return state;
const seen = new Map(state.seen);
seen.delete(sessionId);
return { seededAt: state.seededAt, seen };
}
/**
* Whether a Session has run since the user last looked at it.
*
* Unknown Sessions fall back to `seededAt`, so only activity after this browser first saw the
* Project counts as unread. An unparseable timestamp reads as read (never invent an alert).
*/
export function isSessionUnread(state: SessionSeenState, sessionId: string, lastActiveAt: string) {
const activeAt = Date.parse(lastActiveAt);
if (Number.isNaN(activeAt)) return false;
return activeAt > (state.seen.get(sessionId) ?? state.seededAt);
}
// —— Module-level store: storage key → markers, every subscriber re-renders on change ——
// The Map doubles as the lazy parse cache: read() seeds a missing key IN PLACE (no new
// reference, no notification — it runs inside a render via useSessionSeen's selector), while
// write() swaps in a new Map so subscribers are notified. Same shape as draft-sessions.ts.
const seenStore = createStore<{ cache: Map<string, SessionSeenState> }>(() => ({
cache: new Map(),
}));
function read(key: string, storage?: SessionSeenStorage): SessionSeenState {
const { cache } = seenStore.getState();
const hit = cache.get(key);
if (hit) return hit;
const s = storageOf(storage);
let state = EMPTY;
if (s) {
try {
state = parseSessionSeen(s.getItem(key));
} catch {
state = EMPTY;
}
}
cache.set(key, state);
return state;
}
function write(key: string, state: SessionSeenState, storage?: SessionSeenStorage): void {
const s = storageOf(storage);
if (s) {
try {
s.setItem(key, serializeSessionSeen(state));
} catch {
// Quota / private mode: the in-memory copy still serves this tab.
}
}
seenStore.setState((prev) => ({ cache: new Map(prev.cache).set(key, state) }));
}
/** Reactive read of one Project's markers (the EMPTY constant when no Project is selected). */
export function useSessionSeen(projectId: string | null): SessionSeenState {
return useStore(seenStore, () => (projectId ? read(sessionSeenKey(projectId)) : EMPTY));
}
/**
* Marks a Session read. Also stamps `seededAt` on a Project's first ever write, which is what
* makes pre-existing conversations start out read rather than all-unread.
*/
export function noteSessionSeen(
projectId: string | null,
sessionId: string,
lastActiveAt: string,
storage?: SessionSeenStorage,
): void {
if (projectId === null) return;
const key = sessionSeenKey(projectId);
const current = read(key, storage);
const seeded = current.seededAt === 0 ? { seededAt: Date.now(), seen: current.seen } : current;
const next = markSessionSeen(seeded, sessionId, lastActiveAt);
if (next === current) return;
write(key, next, storage);
}
/** Drops a deleted Session's marker so the id cannot linger in storage forever. */
export function forgetSession(
projectId: string | null,
sessionId: string,
storage?: SessionSeenStorage,
): void {
if (projectId === null) return;
const key = sessionSeenKey(projectId);
const current = read(key, storage);
const next = forgetSessionSeen(current, sessionId);
if (next === current) return;
write(key, next, storage);
}
/** Test seam: drops the in-memory parse cache so a fresh storage stub is re-read. */
export function resetSessionSeenCache(): void {
seenStore.setState({ cache: new Map() });
}