Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Toast notification system — replaces react-hot-toast
* Supports: toast(), toast.success(), toast.error(), toast.loading(), toast.dismiss(), <Toaster />
* Render-prop toasts: toast((t) => <Component t={t} />, opts) — t has { id }
*
* A `duration: Infinity` toast collapses to a corner pill after
* COLLAPSE_AFTER_MS so it stops blocking clicks on the page beneath it. Such a
* toast with render-prop content MUST pass `label` — the pill can't name itself
* from JSX, and `a11yConventions.test.js` enforces it. Content that runs its
* own dismiss timer passes `collapseAfter` to fold on its schedule instead.
*/
import { Loader2 } from 'lucide-react';
import { useState, useEffect, useRef } from 'react';
import { uuidv4 } from '../../lib/uuid.js';
import { isEditableTarget } from '../../lib/a11yKeyboard.js';
let toasts = [];
let toastSeq = 0;
const listeners = new Set();
function notify() {
listeners.forEach(fn => fn([...toasts]));
}
const DEFAULT_DURATION = 4000;
const DEDUP_WINDOW_MS = 1500;
// How long a `duration: Infinity` toast stays at full size before folding into
// a corner pill. The stack is `fixed`, `z-[9999]` and `pointer-events-auto`, so
// a toast that never dismisses is a permanent click sink over the page: an
// install whose `outOfSync` notice parked in the bottom-right corner covered
// the CoS task form's Screenshot and Attach buttons, and clicking them did
// nothing at all — no picker, no error, nothing in the console.
//
// Only unbounded toasts collapse. A finite duration is a bound the caller
// already chose and it clears itself, so folding one early would hide an action
// the caller meant to keep offering for the whole time (the manuscript
// Undo-fix toast runs 10s and its Undo button is the only one there is).
//
// A toast whose bound lives INSIDE its content rather than in `duration` passes
// `collapseAfter` to say so. `useAgentFeedbackToast` is the case: it sets
// `duration: Infinity` only because the card runs its own 15s dismiss, so the
// default 8s would fold the rating controls away for the last 7s of a life the
// caller did bound. Worse, re-opening the pill does NOT restart that inner
// timer, so a card re-expanded at 10s vanished 5s later, mid-click. Passing the
// content's own bound lines the two up. It is a delay, never an opt-out: when
// that card is expanded it clears its dismiss timer and becomes truly
// unbounded — the widest click sink of the set — so it still has to fold.
export const COLLAPSE_AFTER_MS = 8000;
// Fingerprint → expiry timestamp. Same content+type within DEDUP_WINDOW_MS is
// silently dropped so a single user action that flows through multiple error
// channels (API client toast + socket error:occurred + error:notified) doesn't
// stack 3-4 identical red toasts. Render-prop content (functions) is never
// deduped — those are intentional custom UIs and the caller controls identity.
const recentFingerprints = new Map();
const fingerprintFor = (content, type) =>
typeof content === 'string' ? `${type}::${content}` : null;
function add(content, opts = {}, type = 'default') {
// `uuidv4`, not `crypto.randomUUID` — the latter is undefined on insecure
// origins (PortOS over plain HTTP via Tailscale), where it threw out of
// every toast, including the ones the API client raises to report a failure.
const id = opts.id || uuidv4();
const duration = opts.duration !== undefined ? opts.duration : (type === 'loading' ? Infinity : DEFAULT_DURATION);
// Skip if an identical toast was just shown — but only when the caller
// didn't supply an explicit id (explicit id = caller is intentionally
// updating the same toast, e.g. a loading-then-success swap).
if (!opts.id) {
const fp = fingerprintFor(content, type);
if (fp) {
const now = Date.now();
// Sweep expired entries opportunistically.
for (const [k, exp] of recentFingerprints) {
if (exp <= now) recentFingerprints.delete(k);
}
const expiry = recentFingerprints.get(fp);
if (expiry && expiry > now) return id;
recentFingerprints.set(fp, now + DEDUP_WINDOW_MS);
}
}
// `label` names the toast once it collapses to a pill — required for
// render-prop content, whose JSX the pill can't summarise on its own.
// `collapseAfter` is validated, not merely read: a non-finite value (a stray
// `Infinity` meaning "never fold") would disable the fold entirely and hand
// back the click-eating overlay, so anything but a finite positive number
// falls back to the default rather than being honoured.
const collapseAfter = Number.isFinite(opts.collapseAfter) && opts.collapseAfter > 0
? opts.collapseAfter
: COLLAPSE_AFTER_MS;
// `seq` marks WHEN this entry was last touched, independent of its
// position in `toasts` — a same-id re-add (loading→success) replaces the
// entry IN PLACE at its original array index so the stack doesn't jump, so
// array order alone can't answer "which toast is newest" once an update
// has happened. The Alt+Shift+N jump below reads this instead of `[last]`.
const entry = { id, type, content, icon: opts.icon, duration, style: opts.style, label: opts.label, collapseAfter, seq: ++toastSeq };
const idx = toasts.findIndex(t => t.id === id);
toasts = idx !== -1
? [...toasts.slice(0, idx), entry, ...toasts.slice(idx + 1)]
: [...toasts, entry];
notify();
// The finite-duration dismiss timer used to be armed HERE, at creation, and
// never touched again — so hovering or focusing a toast (the `held` state
// below) could not pause it, and a keyboard user reaching for an Undo
// button lost it mid-reach. It now lives in `ToastItem`'s own effect, which
// can see `held` and pause/resume around it (#8117).
return id;
}
function dismiss(id) {
toasts = id !== undefined ? toasts.filter(t => t.id !== id) : [];
notify();
}
export const toast = Object.assign(
(content, opts = {}) => add(content, opts, 'default'),
{
success: (content, opts = {}) => add(content, opts, 'success'),
error: (content, opts = {}) => add(content, opts, 'error'),
loading: (content, opts = {}) => add(content, opts, 'loading'),
warning: (content, opts = {}) => add(content, opts, 'warning'),
info: (content, opts = {}) => add(content, opts, 'info'),
dismiss,
}
);
export default toast;
const TYPE_ICON = { success: '✓', error: '✕', warning: '⚠', info: 'ℹ' };
const TYPE_CLASS = { success: 'text-port-success', error: 'text-port-error', loading: 'text-gray-400', warning: 'text-port-warning', info: 'text-port-accent' };
export function Toaster({ position = 'bottom-right', toastOptions = {} }) {
const [items, setItems] = useState([]);
const regionRef = useRef(null);
// Where to send focus back on Escape — only set while focus is parked
// inside the notification region via the Alt+Shift+N jump below.
const returnFocusRef = useRef(null);
useEffect(() => {
const fn = ts => setItems(ts);
listeners.add(fn);
return () => listeners.delete(fn);
}, []);
// The keyboard path into the notification region (#8117): the Toaster is
// mounted last in `main.jsx` so its buttons sit at the very end of tab
// order, and nothing previously moved focus there directly. Alt+Shift+N
// focuses the newest toast's first control (falling back to the toast body,
// which is always `tabIndex={-1}`); Escape while focus is inside a toast
// returns it to whatever held it before the jump.
useEffect(() => {
function onKeyDown(e) {
if (e.altKey && e.shiftKey && !e.metaKey && !e.ctrlKey && e.code === 'KeyN') {
// `code`, not `key` — macOS remaps Option+letter to a different
// character (Option+Shift+N is typically `˜`), which would silently
// break the shortcut on every Mac if matched on `key`. Not routed
// through `shouldIgnoreGlobalKey`: that predicate drops every
// Alt-chorded keydown by default, and Alt is exactly the chord this
// shortcut needs, so the editable-target guard is applied directly
// instead.
if (isEditableTarget(e.target)) return;
// An open `aria-modal` dialog owns the focus trap (WCAG 2.4.3) —
// jumping focus out to a toast behind it would break that trap, so
// this stands down exactly like `shouldIgnoreGlobalKey`'s dialog
// guard does for the shortcut hooks that route through it.
if (document.querySelector('[aria-modal="true"]')) return;
const region = regionRef.current;
// `seq`, not array position — a same-id re-add (loading→success)
// replaces the entry in place at its original index, so the LAST
// item isn't necessarily the one most recently touched.
const newest = items.reduce((a, b) => (!a || b.seq > a.seq ? b : a), null);
if (!region || !newest) return;
const toastEl = region.querySelector(`[data-toast-id="${newest.id}"]`);
if (!toastEl) return;
const focusTarget = toastEl.tagName === 'BUTTON'
? toastEl
: (toastEl.querySelector('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])') ?? toastEl);
e.preventDefault();
returnFocusRef.current = document.activeElement;
focusTarget.focus();
return;
}
if (e.key === 'Escape' && returnFocusRef.current && regionRef.current?.contains(document.activeElement)) {
const toReturn = returnFocusRef.current;
returnFocusRef.current = null;
toReturn.focus();
}
}
document.addEventListener('keydown', onKeyDown);
return () => document.removeEventListener('keydown', onKeyDown);
}, [items]);
const posClass = {
'bottom-right': 'bottom-4 right-4 items-end',
'bottom-left': 'bottom-4 left-4 items-start',
'bottom-center': 'bottom-4 left-1/2 -translate-x-1/2 items-center',
'top-right': 'top-4 right-4 items-end',
'top-left': 'top-4 left-4 items-start',
'top-center': 'top-4 left-1/2 -translate-x-1/2 items-center',
}[position] ?? 'bottom-4 right-4 items-end';
return (
// Notification region. Each toast is its own live region: role="alert"
// (implicitly assertive) for errors, role="status" (implicitly polite)
// otherwise, so screen readers announce toasts as they arrive. The role's
// implicit live semantics are relied on WITHOUT a redundant aria-live —
// pairing both on one node double-announces in iOS VoiceOver. Announcing
// per-toast rather than on the container avoids the whole stack being
// re-read when one entry changes.
<div
ref={regionRef}
className={`fixed ${posClass} z-[9999] flex flex-col gap-2 pointer-events-none`}
role="region"
aria-label="Notifications"
aria-keyshortcuts="Alt+Shift+N"
>
{items.map(t => (
<ToastItem key={t.id} t={t} toastOptions={toastOptions} />
))}
</div>
);
}
function ToastItem({ t, toastOptions }) {
const style = { padding: '12px 16px', borderRadius: '8px', ...toastOptions.style, ...t.style };
const iconStr = t.icon ?? (t.type !== 'default' ? TYPE_ICON[t.type] : null);
// The loading icon is `Loader2` — the same spinner the rest of the UI spins
// (ConfirmButtonPair, TabPills) — and no longer the `⟳` glyph it used to be.
// `animate-spin` rotates about the center of the element's box, and a glyph's
// ink is not centered in its line box: the font's ascent/descent padding above
// and below it is asymmetric, so the character is drawn off the box's midpoint
// and spinning it traces a visible wobble instead of a clean circle ("PortOS is
// restarting..." made it obvious, since that toast spins for the whole
// restart). An icon whose arc is centered in a square viewBox puts the visual
// center on the rotation origin, so it turns in place.
// A caller-supplied `icon` still wins over the spinner — it's an explicit
// override, and the type only picks the default.
const showSpinner = t.type === 'loading' && !t.icon;
const iconNode = showSpinner ? <Loader2 size={14} className="animate-spin" /> : iconStr;
const iconClass = t.type !== 'default' ? TYPE_CLASS[t.type] : '';
// The icon is 14px; centering it on the `text-sm` line box keeps it level
// with the first line of the message rather than riding above it.
const iconBoxClass = showSpinner ? 'inline-flex h-5 items-center' : '';
// Only a toast that never dismisses itself can outstay its welcome and start
// eating clicks — see COLLAPSE_AFTER_MS.
const collapsible = t.duration === Infinity;
const [collapsed, setCollapsed] = useState(false);
// Held open while the pointer is over the toast or focus is inside it —
// collapsing out from under a hover would yank the buttons the user is
// reaching for, and collapsing while focus is inside would drop that focus
// to <body>.
//
// Two flags, not one: hover and focus are independent holds, and a single
// shared boolean lets whichever ends last clear the other's. Tab to the
// toast's button, then sweep the pointer over the toast and off again, and
// `mouseleave` would release a hold that focus still owns — 8s later the
// still-focused button gets `display: none` and focus lands on <body>, the
// exact thing this is here to prevent.
const [hovered, setHovered] = useState(false);
const [focusWithin, setFocusWithin] = useState(false);
const held = hovered || focusWithin;
const collapseAfter = t.collapseAfter ?? COLLAPSE_AFTER_MS;
useEffect(() => {
if (!collapsible || collapsed || held) return undefined;
const timer = setTimeout(() => setCollapsed(true), collapseAfter);
return () => clearTimeout(timer);
}, [collapsible, collapsed, held, collapseAfter]);
// The finite-duration dismiss timer, moved here from `add()` (#8117) so it
// can pause while `held` and resume with the time that was actually left,
// instead of firing on a fixed wall-clock deadline a hovering mouse or a
// focused button couldn't touch.
//
// `remainingRef` is the ms left on the countdown; it survives across
// pause/resume because a ref, unlike state, doesn't trigger its own
// re-render/effect cycle. `prevSeqRef` detects a same-id re-add that needs
// a fresh countdown — `t.seq` (assigned in `add()`) bumps on EVERY call for
// this id, including one whose content/type/duration are byte-identical to
// what's already showing, matching the old behaviour where `add()` armed a
// brand-new timer on every call regardless of whether anything visibly
// changed. Comparing `content`/`type`/`duration` by value instead would
// miss that case (nothing would look different to React) and also miss a
// swap that keeps identical content/type but changes just the duration —
// e.g. an Infinity toast re-added as finite — where `remainingRef` would
// otherwise keep holding `Infinity`; `setTimeout(fn, Infinity)` clamps to 0
// in JS, so that toast would dismiss almost immediately instead of
// honouring its new duration.
const remainingRef = useRef(t.duration);
const prevSeqRef = useRef(t.seq);
useEffect(() => {
const isNewArm = prevSeqRef.current !== t.seq;
prevSeqRef.current = t.seq;
if (t.duration === Infinity) return undefined;
if (isNewArm) remainingRef.current = t.duration;
if (held) return undefined;
const start = Date.now();
const timer = setTimeout(() => dismiss(t.id), remainingRef.current);
return () => {
clearTimeout(timer);
remainingRef.current = Math.max(0, remainingRef.current - (Date.now() - start));
};
}, [t.id, t.duration, t.seq, held]);
// Re-entering `add()` with the same id replaces the entry in place (a
// loading→success swap, a coalesced AI-status error picking up another
// failure). That toast has something new to say, so unfold it — otherwise the
// update lands inside a pill nobody opens. `content`/`type` only change
// identity when `add()` actually ran, so this doesn't fire on re-renders.
useEffect(() => { setCollapsed(false); }, [t.content, t.type]);
// Collapsing HIDES the body, it does not unmount it: render-prop toasts own
// their lifecycle (useAgentFeedbackToast's card runs its own auto-dismiss),
// and unmounting would destroy those timers and strand the pill forever.
// `display: none` inline beats the `flex` utility class, and takes the body
// out of the a11y tree and out of hit-testing — which is the whole point.
//
// `collapsible` is re-read during render, not just in the effect, so a
// loading→success swap on the same id (Infinity → 4000) unfolds in the same
// commit. The reset effect below would get there a paint later, which shows
// as a frame of pill over the new message.
const isCollapsed = collapsed && collapsible;
const bodyStyle = isCollapsed ? { ...style, display: 'none' } : style;
// Expanding the pill unmounts the pill. If the keyboard had focus on it,
// focus falls to <body> and the toast's own Reconcile/Reload/Ignore buttons
// drop out of the tab sequence — the next Tab restarts from the top of the
// document, past everything. So hand focus to the body it just revealed.
//
// Only for a KEYBOARD activation, detected by `detail === 0` — the click a
// browser synthesizes from Enter/Space carries no click count, while a real
// pointer click carries at least 1. `document.activeElement === the pill` is
// NOT a usable substitute: Chrome focuses a button on mouse-down, so it reads
// true for an ordinary click. Measured in headless Chrome against the running
// page, that mis-detection moved focus into the body on a plain mouse click,
// `onFocus` took the focus hold, and the toast never folded again — the exact
// parked overlay this file exists to remove, handed back to the mouse users
// who reported it. jsdom hides this: `fireEvent.click` doesn't focus the
// button, so an activeElement-based guard passes the unit test and fails the
// browser. The tests below therefore pass `detail` explicitly.
const bodyRef = useRef(null);
const refocusOnExpand = useRef(false);
useEffect(() => {
if (isCollapsed || !refocusOnExpand.current) return;
refocusOnExpand.current = false;
// Runs after commit, so the body is no longer `display: none` and can
// actually take focus.
bodyRef.current?.focus();
}, [isCollapsed]);
return (
<>
{isCollapsed && (
// The pill deliberately carries no hover handlers: the timer effect
// short-circuits on `collapsed` before it reads `held`, so they couldn't
// change anything — and the pill unmounts on click, where no
// `mouseleave` ever fires, which would strand `held` at true and
// suppress the re-collapse below. Re-expanding doesn't pin the toast
// open either; the timer just restarts, so a tap on a touch device
// folds it away again on its own.
<button
type="button"
data-toast-id={t.id}
onClick={e => {
refocusOnExpand.current = e.detail === 0;
setCollapsed(false);
}}
aria-label={collapsedLabel(t)}
className="pointer-events-auto flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-port-card border border-port-border shadow-lg text-sm"
>
<span className={iconClass} aria-hidden="true">{iconNode ?? '•'}</span>
</button>
)}
<div
ref={bodyRef}
data-toast-id={t.id}
style={bodyStyle}
// Focusable only programmatically (see the refocus effect); -1 keeps
// the body itself out of the tab sequence so it never sits between the
// page's own controls.
tabIndex={-1}
role={t.type === 'error' ? 'alert' : 'status'}
onMouseEnter={() => setHovered(true)}
onMouseLeave={() => setHovered(false)}
// onFocus/onBlur bubble in React, so these fire for the toast's buttons
// too. Moving between two buttons inside the toast fires blur then
// focus; both land in one batch, so the hold never blips false.
onFocus={() => setFocusWithin(true)}
onBlur={() => setFocusWithin(false)}
className="pointer-events-auto flex items-start gap-2 shadow-lg text-sm max-w-[calc(100vw-2rem)] sm:max-w-[520px] max-h-[min(75vh,520px)] overflow-y-auto bg-port-card border border-port-border">
{iconNode && <span className={`shrink-0 ${iconClass} ${iconBoxClass}`} aria-hidden="true">{iconNode}</span>}
<div className="flex-1 min-w-0">
{typeof t.content === 'function' ? t.content({ id: t.id }) : <span>{t.content}</span>}
{/* Render-prop toasts are the actionable ones — an Undo/Reconcile/
Rate button that a screen-reader user hears announced but can't
reach in the normal tab order (the Toaster mounts last in
`main.jsx`). Naming the shortcut in the same live announcement
tells them how to get there without needing sighted discovery of
a global shortcuts list. */}
{typeof t.content === 'function' && (
<span className="sr-only"> Press Alt+Shift+N to reach its actions.</span>
)}
</div>
</div>
</>
);
}
// Accessible name for the collapsed pill. String content names itself; a
// render-prop toast has to supply `label` or it collapses to an anonymous badge.
function collapsedLabel(t) {
if (t.label) return `Show notification: ${t.label}`;
if (typeof t.content === 'string') return `Show notification: ${t.content}`;
return 'Show notification';
}