A local-first multi-agent app development platform, built on PenguinHarness
/**
* Scoping browser-persisted UI state to the data root it was made against.
*
* The report this exists for: a user deleted their data files, restarted, and the app came
* back with the old Workspace still selected. `localStorage` has no relationship to the
* data root at all — in the desktop app it lives in Electron's userData directory, so no
* amount of deleting `PENGUIN_HOME` touches it — and every key that names an entity names
* it with a compile-time constant (`admin`, `default_project`). A wipe-and-restart
* re-provisions the same user and the same Project, the keys line up again, and the old
* draft, Workspace registry, pins and seen markers all come back.
*
* So the server names its root (`<root>/install-id`, served by `GET /api/install`) and this
* module compares that name against the one this browser last saw. A DIFFERENT name means
* the state here was made against a root that is gone, and the keys that reference server
* entities are cleared. Same name — including every ordinary restart — clears nothing.
*
* Why one stored id and a sweep, rather than putting the id into every key name:
* - key names stay as they are, so no module that builds a key changes and there is no
* migration for keys already on disk;
* - a key carrying a dead install id would be an orphan nothing ever reads or deletes,
* and each wipe would leave another full set behind. The sweep is the one place
* orphans are collected, and it collects them by walking the store;
* - the classification below stays readable as a table instead of being spread across
* twenty call sites.
*
* TWO THINGS THE SWEEP ALONE DOES NOT COVER, both of them a live copy of state the store no
* longer holds:
* - modules evaluated before the sweep ran (the whole static import graph finishes before
* main.tsx's first statement) — a swept boot RELOADS rather than renders, see
* bootInstallScope;
* - other tabs, still open against the root that is gone — see watchInstallScope.
*
* FIRST SIGHT (a browser with keys but no stored id — every user upgrading into this
* release) is indistinguishable from a wiped root, so it ADOPTS the current id and sweeps
* nothing. Destroying legitimate state on upgrade would be a far worse bug than the one
* being fixed. The practical consequence, which the changelog states plainly: state that is
* ALREADY stale when this ships stays stale; only wipes from here on are handled.
*/
import * as api from "../api/endpoints";
/** Where this browser records the data root it last saw. Never swept — it IS the marker. */
export const INSTALL_ID_KEY = "penguin.installId";
/**
* What a stored key is tied to.
*
* - `install` — it references server-side entities (Session ids, Agent ids, Workspace
* paths, Project ids, terminal ids, provider group names) that a new data root does not
* have. Against a new root it is at best inert and at worst a lie, which is the bug.
* - `browser` — a display or input preference of this browser. It names nothing on the
* server, so a new root can honour it exactly as the old one did, and wiping a data root
* is not a request to reset someone's theme.
*/
export type KeyScope = "install" | "browser";
/**
* One classification rule. `kind: "exact"` matches the key itself; `kind: "family"` matches
* a key prefix that ends in `.` and covers every id-suffixed key under it.
*
* Plain prefix matching would be wrong twice over, which is why the distinction exists:
* `penguin.sidebarCollapsed` (a preference) is a prefix of
* `penguin.sidebarCollapsedGroups.<projectId>` (install-scoped), and `penguin.terminal.`
* covers both `penguin.terminal.theme` (a preference) and `penguin.terminal.page.id`
* (a terminal id).
*/
export interface KeyRule {
kind: "exact" | "family";
key: string;
scope: KeyScope;
/** Why this scope — one line, kept next to the rule so the two cannot drift apart. */
why: string;
}
/**
* Every `penguin.*` key the web app persists in `localStorage`, classified.
*
* ADDING A KEY: add it here too. An unclassified key is left alone by the sweep (never
* deleting something we do not understand is the safe default), so a forgotten
* install-scoped key silently reintroduces the bug this module fixes. That is enforced
* rather than asked for: install-scope.test.ts scans `packages/web/src` for key literals and
* fails on any this table does not cover.
*
* Two `penguin.*` strings in the source are NOT here on purpose:
* - `penguin.chatRouteApplied.<field>` (features/chat/draft-view.tsx) is `sessionStorage`,
* not `localStorage`: it is scoped to one tab's history and dies with the tab, so it
* cannot outlive a data root.
* - `penguin.ooo` (the shared UI package's remark-autolink-boundary.ts) is the product's
* domain inside an example URL in a doc comment. It is not a storage key.
*/
export const KEY_RULES: readonly KeyRule[] = [
// ---------------------------------------------------------------- browser preferences
{
kind: "exact",
key: "penguin.theme",
scope: "browser",
why: "Colour-scheme choice for this browser; names nothing on the server.",
},
{
kind: "exact",
key: "penguin.themeId",
scope: "browser",
why: "Which theme renders the app (the key lives in @adelie/ui/boot); pure appearance.",
},
{
kind: "exact",
key: "penguin.textSize",
scope: "browser",
why: "Root text size (five steps) — a readability preference of this display.",
},
{
kind: "exact",
key: "penguin.fontScale",
scope: "browser",
why: "The three-step text size of earlier releases; read once, migrated to penguin.textSize and removed.",
},
{
kind: "exact",
key: "penguin.fontLatin",
scope: "browser",
why: "Latin font face chosen over the theme's own; pure appearance.",
},
{
kind: "exact",
key: "penguin.fontCjk",
scope: "browser",
why: "CJK font face chosen over the theme's own; pure appearance.",
},
{
kind: "exact",
key: "penguin.accent",
scope: "browser",
why: "Accent colour; pure appearance.",
},
{
kind: "exact",
key: "penguin.currency",
scope: "browser",
why: "Display currency for prices; a formatting choice, prices are stored in USD either way.",
},
{
kind: "exact",
key: "penguin.toolAliases",
scope: "browser",
why: "Whether tool cards name the built-in tools by their short alias; a display choice of this browser, naming nothing on the server.",
},
{
kind: "exact",
key: "penguin.sseFrames",
scope: "browser",
why: "Whether the Trace panel's Transport view records SSE frames; a debugging instrument of this browser, naming nothing on the server.",
},
{
kind: "exact",
key: "penguin.terminal.theme",
scope: "browser",
why: "Terminal appearance pin (light/dark/follow-app); appearance only.",
},
{
kind: "exact",
key: "penguin.lang",
scope: "browser",
why: "UI language — the one preference a user would be most annoyed to lose.",
},
{
kind: "exact",
key: "penguin.sidebarCollapsed",
scope: "browser",
why: "Whether the sidebar is a narrow rail; chrome layout, holds no entity.",
},
{
kind: "exact",
key: "penguin.panelWidth",
scope: "browser",
why: "Side-panel width in px; its own module calls it a layout preference, not session data.",
},
{
kind: "exact",
key: "penguin.dock.launcherY",
scope: "browser",
why: "Where the floating dock launcher rests along the chat body's edge; chrome layout, holds no entity.",
},
{
kind: "exact",
key: "penguin.dock.launcherHidden",
scope: "browser",
why: "Whether the floating dock launcher shows at all; an appearance choice of this browser, and losing it would put a dismissed button back.",
},
{
kind: "exact",
key: "penguin.files.treeVisible",
scope: "browser",
why: "Whether the Files panel shows its directory tree beside the preview; chrome layout, holds no entity.",
},
{
kind: "exact",
key: "penguin.files.treeWidth",
scope: "browser",
why: "How wide that tree pane was dragged, in px; the same layout preference, one axis over.",
},
{
kind: "exact",
key: "penguin.files.editorWrap",
scope: "browser",
why: "Whether the Files panel's editor soft-wraps long lines; a reading habit, valid against any root.",
},
{
kind: "exact",
key: "penguin.sidebarGroupMode",
scope: "browser",
why: "Group sessions by Workspace/Agent/time — the MODE, not the groups; valid against any root.",
},
{
kind: "exact",
key: "penguin.sidebarSortMode",
scope: "browser",
why: "Recent vs manual ordering — again the mode; the manual order itself is separate and install-scoped.",
},
{
kind: "exact",
key: "penguin.sidebarNavGroupCollapsed",
scope: "browser",
why: "Whether the static page-nav group is folded; the nav is built from a compile-time manifest.",
},
{
kind: "exact",
key: "penguin.sidebarNavPinned",
scope: "browser",
why: "Which nav entries stay out of the fold; keyed by the compile-time manifest, names nothing on the server.",
},
{
kind: "exact",
key: "penguin.steerMode",
scope: "browser",
why: "Steer vs queue-as-follow-up when sending mid-run; a per-user input habit.",
},
{
kind: "exact",
key: "penguin.notifications",
scope: "browser",
why: "Whether task-completion notifications were asked for; it pairs with an OS permission that belongs to this browser rather than to any data root, and clearing it would silently stop notifications the user opted into.",
},
// --------------------------------------------------------------- install-scoped state
{
kind: "family",
key: "penguin.chatDraft.",
scope: "install",
why: "The new-chat and per-Session drafts: Workspace path, Agent id, model ref, Session id in the key. The reported bug.",
},
{
kind: "family",
key: "penguin.chatDrafts.",
scope: "install",
why: "Parked draft conversations — the same contents as an active draft, kept as a list.",
},
{
kind: "family",
key: "penguin.channelDraft.",
scope: "install",
why: "A channel composer's unsent text, keyed by user, Project, organization and channel — all four name things that live in one data root.",
},
{
kind: "family",
key: "penguin.sidebarWorkspaces.",
scope: "install",
why: "Manually registered Workspace paths per Project; a new root has no such Project.",
},
{
kind: "family",
key: "penguin.finderQuickAccess.",
scope: "install",
why: "Folders added to and removed from the Workspace finder's Quick access, keyed by machine id and holding paths on the machines of this root — the same kind of state as the registered Workspace paths.",
},
{
kind: "family",
key: "penguin.pinnedSessions.",
scope: "install",
why: "Pinned Session ids.",
},
{
kind: "family",
key: "penguin.machineSessions.",
scope: "install",
why: "The Sessions each machine was last seen holding, shown until its connection is held again. Project id and machine id in the key, Session ids in the value — a new root knows none of them.",
},
{
kind: "exact",
key: "penguin.sandboxBackendPromptDismissed",
scope: "install",
why: "The machines whose Sandbox card no longer offers to install a backend — machine ids of this root.",
},
{
kind: "family",
key: "penguin.machineAgents.",
scope: "install",
why: "The Agents each machine was last seen running, offered by the composer until its connection is held again. Keyed by the same Project and machine a new root would not have.",
},
{
kind: "family",
key: "penguin.sessionOrder.",
scope: "install",
why: "Manual Session order — an array of Session ids.",
},
{
kind: "family",
key: "penguin.sessionSeen.",
scope: "install",
why: "Read markers keyed by Session id; against a new root every Session is new by definition.",
},
{
kind: "family",
key: "penguin.groupOrder.",
scope: "install",
why: "Manual group order — group keys are Agent ids and Workspace paths.",
},
{
kind: "family",
key: "penguin.sidebarCollapsedGroups.",
scope: "install",
why: "Collapsed sidebar groups, keyed by those same Agent ids and Workspace paths.",
},
{
kind: "family",
key: "penguin.sidebarExpandedFolderGroups.",
scope: "install",
why: "Folder-only sidebar groups the user opened, keyed by those same Agent ids and Workspace paths.",
},
{
kind: "family",
key: "penguin.sidebarPinnedGroups.",
scope: "install",
why: "Pinned sidebar groups, same key space.",
},
{
kind: "exact",
key: "penguin.lastProjectId",
scope: "install",
why: "The Project id last selected.",
},
{
kind: "exact",
key: "penguin.workMode",
scope: "browser",
why: "Development vs company mode — the MODE, mirrored from ui_prefs; valid against any root.",
},
{
kind: "exact",
key: "penguin.keybindings",
scope: "browser",
why: "The account's shortcut overrides, mirrored from ui_prefs for the first keystroke and for cross-tab sync; names nothing on the server, and the server copy is the truth.",
},
{
kind: "exact",
key: "penguin.companyBetaNoticeShown",
scope: "browser",
why: "That company mode's beta notice has been shown in this browser; it names nothing on the server, and a wipe is not a request to show it again.",
},
{
kind: "exact",
key: "penguin.lastOrgKey",
scope: "install",
why: "The organization last opened in company mode, as <projectId>/<orgId> of this root.",
},
{
kind: "family",
key: "penguin.orgCreateDraft.",
scope: "install",
why: "An unsubmitted create-organization form, keyed by user and Project id and holding a Workspace path and model ref of this root.",
},
{
kind: "family",
key: "penguin.orgPageHint.",
scope: "install",
why: "A dismissed empty-page note, keyed by user, Project and organization id of this root.",
},
{
kind: "family",
key: "penguin.orgTempSessions.",
scope: "install",
why: "The company sidebar's Temporary group of ticket sessions, keyed by user, Project and organization id and naming Sessions and Agents of this root.",
},
{
kind: "family",
key: "penguin.lastAgentId.",
scope: "install",
why: "The Agent id last selected, per Project.",
},
{
kind: "family",
key: "penguin.memoryCollapsed.",
scope: "install",
why: "Collapsed Memory scopes, keyed by user x Project x Agent and holding scope keys.",
},
{
kind: "family",
key: "penguin.modelsExpandedGroups.",
scope: "install",
why: "Expanded provider groups of a Project's model table; includes user-defined group names that live in that Project's config.",
},
{
kind: "family",
key: "penguin.modelsGroupOrder.",
scope: "install",
why: "Manual order of those same per-Project provider groups.",
},
{
kind: "exact",
key: "penguin.dock.layout",
scope: "install",
why: "Dock tab arrangements keyed by conversation, holding Session ids and terminal ids.",
},
{
kind: "exact",
key: "penguin.terminal.page.id",
scope: "install",
why: "The terminal (shell) id the standalone terminal page reattaches to.",
},
];
/**
* The scope of a stored key, or null when no rule covers it. Exact rules are consulted
* first so a preference is never captured by a family it merely shares a stem with.
*/
export function scopeOfKey(key: string): KeyScope | null {
for (const rule of KEY_RULES) {
if (rule.kind === "exact" && rule.key === key) return rule.scope;
}
for (const rule of KEY_RULES) {
if (rule.kind === "family" && key.startsWith(rule.key)) return rule.scope;
}
return null;
}
/**
* The subset of `localStorage` this module uses. Enumeration (`length` + `key`) is what
* lets one rule cover every id-suffixed key under it and clean up orphans left by earlier
* roots. Tests inject an in-memory implementation — vitest runs in Node, with no DOM
* (the model-group-expansion.ts convention).
*/
export interface InstallScopeStorage {
readonly length: number;
key(index: number): string | null;
getItem(key: string): string | null;
setItem(key: string, value: string): void;
removeItem(key: string): void;
}
/**
* What one boot's comparison did.
*
* - `unknown` — no id to compare (the server could not establish one, or the request
* failed). Nothing read, nothing written, nothing removed.
* - `adopted` — this browser had no id recorded. First sight; the id is stored and nothing
* is swept.
* - `unchanged` — same root as last time. The ordinary case, including every restart.
* - `swept` — a different root. Install-scoped keys removed, preferences kept, and the new
* id recorded, so the next load is an ordinary `unchanged` one.
* - `swept-unrecorded` — the same removal, except the new id could not be written back
* (quota, blocked site data), so the next load compares and sweeps again. Split from
* `swept` for one reason: `swept` reloads the page (bootInstallScope) and this one must
* not, or every pass would sweep, fail to record, and reload again.
*/
export type InstallScopeResult = "unknown" | "adopted" | "unchanged" | "swept" | "swept-unrecorded";
/** Reads one key, treating a throwing store as empty (blocked site data, partitioned iframe). */
function read(storage: InstallScopeStorage, key: string): string | null {
try {
return storage.getItem(key);
} catch {
return null;
}
}
/**
* Removes every install-scoped key. Keys are collected before anything is removed:
* `removeItem` renumbers the store, so deleting during the walk would skip entries.
* Returns the keys removed (the caller logs the count; tests assert on it).
*/
function sweep(storage: InstallScopeStorage): string[] {
const doomed: string[] = [];
try {
for (let i = 0; i < storage.length; i += 1) {
const key = storage.key(i);
if (key !== null && scopeOfKey(key) === "install") doomed.push(key);
}
} catch {
return [];
}
const removed: string[] = [];
for (const key of doomed) {
try {
storage.removeItem(key);
removed.push(key);
} catch {
/* best-effort: a key that refuses to go is swept again on the next load */
}
}
return removed;
}
/**
* Compares the server's install id against the one this browser recorded, and acts on the
* difference. Pure with respect to everything but the store, so the whole decision table is
* testable without a DOM.
*
* `installId` of null means the server could not establish one; that is "unknown", never
* "new", so nothing is touched. The sweep runs BEFORE the id is stored: if the write fails
* (quota, private browsing) the next load repeats the comparison and sweeps again, which is
* idempotent — whereas recording an id we had not finished acting on would not be.
*/
export function reconcileInstallScope(
installId: string | null,
storage: InstallScopeStorage,
): InstallScopeResult {
if (installId === null) return "unknown";
const stored = read(storage, INSTALL_ID_KEY);
if (stored === installId) return "unchanged";
const swept = stored !== null;
if (swept) sweep(storage);
try {
storage.setItem(INSTALL_ID_KEY, installId);
} catch {
/* best-effort: unrecorded means the next load compares again, which is harmless */
}
if (!swept) return "adopted";
// Read the marker BACK rather than trust the write: a swept boot reloads, and a sweep
// whose marker did not stick would sweep, fail to record and reload again on every pass.
return read(storage, INSTALL_ID_KEY) === installId ? "swept" : "swept-unrecorded";
}
/** How long to wait for the identity before rendering anyway — see syncInstallScope. */
const INSTALL_ID_TIMEOUT_MS = 3000;
/**
* Asks the server for this data root's identity and reconciles the browser's state against
* it. Never rejects and never throws: a boot step that can break the whole app is worse
* than the surprise it prevents.
*
* Bounded by a timeout because the caller renders nothing until this settles. The page's
* own HTML came from this same server milliseconds earlier, so an answer that takes longer
* than three seconds means something is badly wrong — and in that state showing the app
* with unswept state beats showing a blank page. Giving up resolves to `unknown`, which
* changes nothing; the next load tries again.
*/
export async function syncInstallScope(storage?: InstallScopeStorage): Promise<InstallScopeResult> {
let installId: string | null = null;
try {
const timeout = new Promise<null>((resolve) => {
setTimeout(() => resolve(null), INSTALL_ID_TIMEOUT_MS);
});
const answered = await Promise.race([api.getInstall().then((res) => res.installId), timeout]);
installId = answered;
} catch {
// A server that cannot answer is one we cannot identify: sweep nothing.
return "unknown";
}
try {
// `localStorage` is resolved INSIDE the try, never as a default parameter: merely
// touching it throws a SecurityError when site data is blocked (the convention every
// storage module here follows).
return reconcileInstallScope(installId, storage ?? localStorage);
} catch {
return "unknown";
}
}
/** What the boot does with the page once this browser's state has been reconciled. */
export type BootAction = "mount" | "reload";
/**
* The whole pre-mount step as one call: ask the server for the data root's identity,
* reconcile this browser's stored state against it, and say whether the page may render or
* has to start over.
*
* A RECORDED SWEEP RELOADS. ES module evaluation of the entire static import graph finishes
* before main.tsx's first statement runs, so a module that reads `localStorage` at module
* scope — features/dock/dock-state.ts parses `penguin.dock.layout` into module state there —
* is already holding a copy of keys the sweep then deletes, and its first write puts the
* whole map back. The id matches by then, so nothing ever sweeps it again and the
* resurrection is permanent. A reload re-evaluates every module against the cleaned store
* and the second pass reconciles to `unchanged`. Making that one module lazy would fix that
* one module and leave the class open for the next one; this holds however the import graph
* grows, and it costs one extra load only when the data root was actually replaced.
*
* `swept-unrecorded` deliberately mounts: reloading on a sweep whose marker did not stick
* would sweep, fail to record and reload again, forever.
*/
export async function bootInstallScope(storage?: InstallScopeStorage): Promise<BootAction> {
return (await syncInstallScope(storage)) === "swept" ? "reload" : "mount";
}
/** The `storage` event fields the cross-tab decision needs (tests pass a plain object). */
export interface InstallIdChange {
key: string | null;
oldValue: string | null;
newValue: string | null;
}
/**
* What another tab's `storage` event means here, and whether this tab must reload.
*
* The sweep runs once per page load, so a tab that was ALREADY open when a second tab
* recognised the new root still holds the old root's state in module and component memory
* and writes it back on the next pin, reorder or draft keystroke — restoring keys the other
* tab removed, under an id that now matches and will never be swept again. A `storage` event
* fires in every OTHER tab of this origin, which is exactly the set that has to hear about
* it: sweep whatever this tab has already put back, and report that it must reload, so no
* live copy survives to write it a second time.
*
* Only an id REPLACED by a different id is a root that was wiped. A first recording
* (`oldValue` null) is that tab's adoption, which swept nothing; a removal (`newValue` null)
* is site data being cleared, which the next load adopts from scratch. Neither concerns the
* state held here.
*/
export function reactToInstallIdChange(
change: InstallIdChange,
storage: InstallScopeStorage,
): boolean {
if (change.key !== INSTALL_ID_KEY) return false;
if (change.oldValue === null || change.newValue === null) return false;
if (change.oldValue === change.newValue) return false;
sweep(storage);
return true;
}
/**
* Wires reactToInstallIdChange to this browser's cross-tab `storage` events for the life of
* the page. A no-op where there is no window (tests, prerendering).
*/
export function watchInstallScope(storage?: InstallScopeStorage): void {
if (typeof window === "undefined") return;
window.addEventListener("storage", (event) => {
let stale = false;
try {
// `localStorage` is resolved INSIDE the try for the same reason syncInstallScope does.
stale = reactToInstallIdChange(event, storage ?? localStorage);
} catch {
return; // blocked site data: there was nothing readable to restore either
}
if (stale) location.reload();
});
}