A local-first multi-agent app development platform, built on PenguinHarness
/**
* Sort mode and manual order of the sidebar's conversation rows (pure decisions, unit
* tested). Two settings work together:
*
* - Sort mode — "recent" (the default: rows keep the store's newest-first order) or
* "manual" (drag-reorderable). One global key like the grouping mode: a single user
* preference, not per Project.
* - Manual order — one array of Session ids per Project AND grouping mode (the modes cut
* the same Sessions into different partitions, so one shared array would let a drag in
* one mode scramble the other). Only the RELATIVE order of ids that render together in
* one partition ever matters (rows are compared only within a group's own list), so a
* drop simply rewrites the affected partition's sequence to the front of the array
* (applyManualReorder) — the caller must commit the partition's FULL loaded sequence,
* not the display-capped slice, or the hidden rows would fall out and return as
* "newcomers". Rows not in the array — new Sessions — go to the TOP of their partition
* keeping their recency order; stored ids that no longer exist stay inert (membership
* lookups only) and deletion prunes via removeFromSessionOrder.
*
* Ordering composes with the row pins (pinned-sessions.ts): the pinned cluster always
* renders first, and the manual order applies WITHIN the pinned cluster and within the
* rest independently — dragging never pins or unpins (orderSessionRows).
*
* Storage is injectable (model-group-expansion.ts convention: vitest runs in Node, no
* localStorage); malformed values degrade to the defaults.
*/
import { compareActivityDesc, pinnedFirst } from "./session-grouping";
import type { GroupMode } from "../components/ui/group-list";
export type SessionSortMode = "recent" | "manual";
/** The single global key (`penguin.…` naming, GROUP_MODE_KEY convention); holds "manual" / "recent". */
export const SESSION_SORT_MODE_KEY = "penguin.sidebarSortMode";
/** Minimal storage interface (the subset of localStorage used here); tests inject an in-memory implementation. */
export interface SessionOrderStorage {
getItem(key: string): string | null;
setItem(key: string, value: string): void;
}
/**
* Reads the persisted sort mode; only an explicit "manual" switches — anything else
* (absent / unrecognized / throwing storage) is the "recent" default, so a fresh profile
* looks unchanged. `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), and this runs from a useState initializer — an escaping throw
* would take the whole sidebar's first render down.
*/
export function initialSessionSortMode(storage?: SessionOrderStorage): SessionSortMode {
try {
const store = storage ?? localStorage;
return store.getItem(SESSION_SORT_MODE_KEY) === "manual" ? "manual" : "recent";
} catch {
return "recent";
}
}
export function storeSessionSortMode(mode: SessionSortMode, storage?: SessionOrderStorage): void {
try {
(storage ?? localStorage).setItem(SESSION_SORT_MODE_KEY, mode);
} catch {
/* best-effort persistence (quota limits / private browsing) */
}
}
/**
* Storage key of one Project's manual order (sidebar key-naming convention,
* `penguin.pinnedSessions.<projectId>` &c.), scoped BY GROUPING MODE: the stored
* sequence is only ever read within a partition, and the modes cut the same Sessions
* into different partitions — one shared array would let a drag in one mode scramble
* another mode's order.
*/
export const sessionOrderKey = (projectId: string, mode: GroupMode): string =>
`penguin.sessionOrder.${projectId}.${mode}`;
/**
* Reads a stored JSON string array, degrading to empty on anything unexpected: nothing
* stored, malformed JSON, a non-array shape, or storage that throws. Junk elements are
* dropped. `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), and these run from useState initializers — an escaping throw
* would take the sidebar's first render down. Shared with group-order.ts, which stores
* the same shape under its own key namespace.
*/
export function readStringArray(key: string, storage?: SessionOrderStorage): string[] {
try {
const store = storage ?? localStorage;
const parsed: unknown = JSON.parse(store.getItem(key) ?? "[]");
return Array.isArray(parsed) ? parsed.filter((x): x is string => typeof x === "string") : [];
} catch {
return [];
}
}
/** Writes a JSON string array, best-effort (quota limits / private browsing fail silently). Shared with group-order.ts. */
export function writeStringArray(
key: string,
value: readonly string[],
storage?: SessionOrderStorage,
): void {
try {
(storage ?? localStorage).setItem(key, JSON.stringify(value));
} catch {
/* best-effort persistence (quota limits / private browsing) */
}
}
/** Reads a Project+mode's persisted manual order; no Project, nothing stored, or corrupted storage degrade to empty (pure recency). Junk array elements are dropped. (localStorage resolved inside the try — see initialSessionSortMode.) */
export function loadSessionOrder(
projectId: string | null,
mode: GroupMode,
storage?: SessionOrderStorage,
): string[] {
if (projectId === null) return [];
return readStringArray(sessionOrderKey(projectId, mode), storage);
}
/** Writes a Project+mode's manual order on every drop (best-effort: quota limits / private browsing fail silently). */
export function saveSessionOrder(
projectId: string | null,
mode: GroupMode,
order: readonly string[],
storage?: SessionOrderStorage,
): void {
if (projectId === null) return;
writeStringArray(sessionOrderKey(projectId, mode), order, storage);
}
/**
* Applies the stored manual order to one partition's rows: rows absent from the order
* (new Sessions) come FIRST keeping their input (recency) order, then the listed rows
* by their stored position. Stale stored ids simply match nothing.
*/
export function applyManualOrder<T>(
rows: readonly T[],
keyOf: (row: T) => string,
order: readonly string[],
): T[] {
if (order.length === 0) return [...rows];
const pos = new Map(order.map((id, i) => [id, i]));
const unlisted: T[] = [];
const listed: T[] = [];
for (const row of rows) (pos.has(keyOf(row)) ? listed : unlisted).push(row);
listed.sort((a, b) => (pos.get(keyOf(a)) ?? 0) - (pos.get(keyOf(b)) ?? 0));
return [...unlisted, ...listed];
}
/**
* Applies a manual order WITHIN each pin partition: the pinned cluster renders first
* (pinnedFirst), then the stored sequence is applied to the pinned cluster and to the
* rest independently — so a drag can reorder but can never move an item across the pin
* boundary. An empty `order` is the identity: the pinned-first list, untouched.
*
* The rows (orderSessionRows, below) and the sidebar's GROUPS (group-order.ts's
* orderGroups) are the same operation one axis apart, so it lives here once. What
* differs between them is upstream of this call — the rows sort by recency first and
* gate on an explicit sort mode, the groups arrive in their own automatic order and have
* no toggle — and that stays with each caller.
*/
export function orderWithinPinPartitions<T>(
items: readonly T[],
keyOf: (item: T) => string,
pinned: ReadonlySet<string>,
order: readonly string[],
): T[] {
if (order.length === 0) return pinnedFirst(items, keyOf, pinned);
// pinnedFirst's concat would be undone by the two filters below (it preserves input
// order within each partition), so the manual path splits the input directly.
const pin = items.filter((item) => pinned.has(keyOf(item)));
const rest = items.filter((item) => !pinned.has(keyOf(item)));
return [...applyManualOrder(pin, keyOf, order), ...applyManualOrder(rest, keyOf, order)];
}
/**
* The full row-ordering pipeline of one group's active list:
*
* 1. recency — newest `recencyOf` first (the Session's `lastActiveAt`: 「最近更新」 means
* last ACTIVITY, not creation), ties broken by key descending. Both compare by code
* point (compareActivityDesc), the order the server pages in and the watermark cuts at:
* under a collation, rows sharing a stamp could display in another order than the cut
* reveals them, and a page that reveals a tied row would then insert it above one
* already shown. Applied in both modes: it IS the recent mode's order, and in manual
* mode it is the order rows not yet in the stored sequence arrive in.
* 2. the pinned cluster first (pinnedFirst), then
* 3. under manual sort, the stored order within the pinned cluster and within the rest
* independently, so a drag can never move a row across the pin boundary.
*
* Only rows already FETCHED — and shown: the sidebar cuts each merged list at its watermark
* first (session-grouping.ts's cutAtWatermark) — are ordered. The server pages the list in this
* same activity order (`order=activity`, sorted in memory per Agent; no index is involved), so
* a Session created long ago but active today is on the first page, and "More" only ever adds
* rows below the ones on screen.
*/
export function orderSessionRows<T>(
rows: readonly T[],
keyOf: (row: T) => string,
opts: {
pinned: ReadonlySet<string>;
sortMode: SessionSortMode;
order: readonly string[];
/** Recency key of a row (the sidebar passes `lastActiveAt`). Omitted = keep the caller's order. */
recencyOf?: (row: T) => string;
},
): T[] {
const recencyOf = opts.recencyOf;
const byRecency = recencyOf
? [...rows].sort((a, b) =>
compareActivityDesc(
{ lastActiveAt: recencyOf(a), sessionId: keyOf(a) },
{ lastActiveAt: recencyOf(b), sessionId: keyOf(b) },
),
)
: rows;
// Recent mode passes an empty order, which is orderWithinPinPartitions's identity.
return orderWithinPinPartitions(
byRecency,
keyOf,
opts.pinned,
opts.sortMode === "manual" ? opts.order : [],
);
}
/**
* Moves `dragId` next to `targetId` (after it when `after`, else before) in a displayed
* sequence. Returns the INPUT array unchanged (same reference) for every no-op — a
* missing id, a self-drop, or a drop that lands the row exactly where it already sat
* (dropping just above your next neighbour) — so callers skip the state update and the
* storage write instead of persisting a freshly allocated identical array.
*/
export function moveInSequence(
sequence: readonly string[],
dragId: string,
targetId: string,
after: boolean,
): readonly string[] {
if (dragId === targetId || !sequence.includes(dragId)) return sequence;
const without = sequence.filter((id) => id !== dragId);
const at = without.indexOf(targetId);
if (at < 0) return sequence;
without.splice(after ? at + 1 : at, 0, dragId);
return without.every((id, i) => id === sequence[i]) ? sequence : without;
}
/**
* Commits one partition's displayed sequence into the stored order after a drop: the
* sequence goes to the FRONT, the remaining stored ids follow unchanged. Correct
* because only the relative order of ids that co-render in one partition is ever
* read — ids of other groups keep their relative order among themselves.
*/
export function applyManualReorder(
order: readonly string[],
partitionSequence: readonly string[],
): string[] {
const inPartition = new Set(partitionSequence);
return [...partitionSequence, ...order.filter((id) => !inPartition.has(id))];
}
/** Prune on Session delete: drops the id, returning the INPUT array unchanged (same reference) when absent — callers skip the state update and storage write then. */
export function removeFromSessionOrder(
order: readonly string[],
sessionId: string,
): readonly string[] {
return order.includes(sessionId) ? order.filter((id) => id !== sessionId) : order;
}