Skip to content

Self-improving AI Employees for everyone

fix(shell): keep animating while the window is visible but unfocused

trohitga39e451e97f9
diff --git a/CLAUDE.md b/CLAUDE.md
index 118ce180..bf1494a9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,7 +17,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Node Allowlist](./docs-internal/node_allowlist.md)** | Single-config UI visibility — `server/config/node_allowlist.json` controls which nodes / credential categories / skill folders show in the UI. Five lists with two enforcement tiers (mode-gated allowlist + absolute blocklist). `useNodeAllowlist` hook exposes `isVisible` / `isBlocked` / `isAllowed` / `isCredentialCategoryDisabled` / `isSkillFolderDisabled`. Adding a new disabled domain = single JSON edit, no code change. |
| **[Normal Mode (Home)](./docs-internal/normal_mode.md)** | The owner-facing landing screen: describe a job, an LLM on the server drafts a setup screen (a JSON UI spec the client parses, normalises and renders from a fixed catalogue), and Hire builds, validates, saves and starts one workflow per AI employee (`services/employees/`, graph built from `config/employee_apps.json` plus the owner's skill library and a Canvas node, and checked against `node_allowlist.json` `enabled_nodes`). Covers the screen switch (`app/`, `shellMode` / `ui_shell_mode`, `VITE_NORMAL_MODE=false` kill switch, Home shows light/dark only), the employee page (the shared chat, `features/chat`, with the employee named in the header beside New conversation; Stop is in the Workspace header), deleting an employee from the team sidebar (stopped through Reset first, then gone from every tab), the live Ask first rule (`workflow_rules`, the chat's Ask first chip via `set_ask_first`; app replies wait in `approvalGate`, sending tool calls are held as drafts by `services/approvals/tool_calls.py` and sent after a 5 s Undo window by `ApprovedToolCallWorkflow`; cards in the chat; builder v3 gates every app reply, attaches every app tool and gives the talk agent `chatUi` and the registry's `talk_send` tools, with instructions identical whatever the rule; older employees are upgraded on Apply / Turn on Talk / Start by `services/employees/upgrade.py`), run records for "done today" (`machina-run-record-v1`), automatic-pause reasons, Settings (Profile fields; usage-only Billing via `get_employee_usage`; Skills, the user-skills library each new hire copies onto a Skills node; consumer Connectors with `publisher` / `verified`; Plugins, the starter bundles in `hire/starters.json`; the last three share one catalog page), the Workspace dock (an employee's Canvas board, named by the summary's `canvas_node_id`; a live Browser tab with user takeover, shared with Dev mode; Mobile shows the managed local Android phone; a footer timeline of the employee's steps from the step log `services/workspace_steps.py`, read with `workspace_steps_list` and again on `workspace_step`, and Take over, which takes the screen and stops the employee until Hand back), the "Web browser" app (attached whole, each call read-only while the owner asks first through its approval spec's `restrict_while_asking`; while the agent waits in `request_user` the summary's `browser_request` shows Needs you and Help in browser), Talk on the employee page (a thread over the chat session whose id is the workflow id, rows written through `services/chat_thread.py` and, for the owner's messages and their chat runs, `services/chat/ledger.py` (see [Chat Protocol](./docs-internal/chat_protocol.md)); the talk line is chatTrigger → an agent → `chatReply` "Reply in Chat": a chat hire's own agent is its talk agent, other hires get a "Talk with {name}" agent sharing the worker's tools and skills with its own Context, and schedule hires also "Post to Talk"), Turn on Talk (for talk `off`) and Apply (while the summary's `pending_changes` is true) via `enable_employee_talk` / `apply_employee_changes`, each a restart on the saved graph through `services/deployment/restart.py`, self-extension from Talk through the Agent Builder within the Hire rule (`services/employees/policy.py`), the 3D orb, the wire contract and the `employee_lifecycle` / `approval_lifecycle` / `chat.updated` / `workspace_step` broadcasts. |
| **[Chat Protocol](./docs-internal/chat_protocol.md)** | The wire contract between the chat runtime (`server/services/chat/`) and the shared chat UI: AG-UI's event model on the existing WebSocket, snake_case, in the CloudEvents envelope. A message a deployed chat trigger will answer starts a **chat run** admitted with it in one reserved write transaction (`Database.reserved_session`, SQLite `BEGIN IMMEDIATE`): one live run per session (the lane, also a partial unique index; a second send answers `run_in_progress`), idempotent `client_message_id`, claimed and finished by the MachinaWorkflow that answers it behind `machina-chat-run-v1` (the run id is trusted only from an event whose source is `opencompany://services/chat`; `run_scope` rides every node context; only the claimant finishes), the reply saved as `a_<run id>` by `chatReply`, every message appended after the session's active leaf (`chat_threads`) so concurrent writes never fork the thread. `chat_run_event` frames reach only sockets that passed `chat_subscribe`'s owner check (`services/chat/hub.py`: per-run `seq`, `hub_epoch`, bounded per-socket queues with a resync), never the status broadcast; a standalone worker sends its run events, `chat.updated` and `approval_lifecycle` to the backend over `/ws/internal` (`services/chat/relay.py`, `chat_run_publish`, ordered, dropped events resynced). A watchdog (`services/chat/watchdog.py`, started by `main.py`) ends runs nothing will finish (`not_delivered`, `timed_out`, `interrupted`). The agent wired into Reply in Chat (`answers_chat_run`) streams its answer as `text.*` events (`services/chat/stream.py`, activity input only, no workflow patch), its tool calls show as steps (`services/chat/steps.py`; label from the plugin's `chat_step`), and `stop_chat_run` stops a run cooperatively: its LLM step polls the run and returns what was shown, unstarted tools are skipped, the reply is saved `stopped`, and the watchdog cancels a run still stopping after `runs.stop_grace_s`. Generated UI: the `show_ui` tool (`chatUi`) is checked against `config/chat_genui_catalog.json` (`services/genui/spec.py`; refused with every reason so the model retries), saved as a run part, streamed as `activity.*` RFC 6902 patches and sealed into the reply (`services/chat/parts.py`); `chat_ui_state` keeps what the owner set, and a button press comes back as `send_chat_message{ui_event}` -> a `[ui-event]` turn. The answering agent's system prompt ends with a fixed guide (`services/chat/guide.py`), what the owner set reaches its next turn as a `[ui-state]` note (`chat_notes`, `services/chat/notes.py`: claimed by the payload, told when the run answered), a trailing `<followups>` block becomes `parts.followups`, and a `chat_sources` tool's results are numbered per conversation for `[n]` citations (`services/chat/sources.py`). Approvals (`services/approvals/`, its own section): a plugin's `approval` spec marks a tool call that sends; while the workflow asks first it is held as a `tool_call` draft, shown as a card on the reply that made it, sent once after the Undo window by `ApprovedToolCallWorkflow`, with the outcome told to the employee as an `[update]` note. Branches (`services/chat/branches.py`): `get_chat_messages` returns the path to the thread's active leaf, each message with its versions (`siblings`), `editable` and the owner's rating; `edit_chat_message` / `regenerate_chat_reply` / `switch_chat_branch` move the path in one reserved transaction under the conversation store's lock, taking each agent's stored conversation back to the cursor its run recorded at `prepare_payload` (`chat_runs.context_cursors`) or restoring the branch's kept copy (`chat_branch_snapshots`), refused on `revision_conflict`, `run_in_progress`, `cannot_rewind`, `branch_unavailable` or `older_generation`; `set_chat_feedback` keeps a rating and tells the next turn (`[feedback]` note). Attachments (`services/chat/attachments.py`): the chat uploads files under `uploads/` and sends only their paths, the server rebuilds each reference from the file (refusing anything else, at most six), the answering agent reads an `[attachments]` line and images ride the opening user message for a provider with `vision.user_images`; `options.web: false` drops the `search` tools for that run; Home's model picker (`services/chat/choice.py`, `get_chat_models`) sends `options.model` / `options.effort`, resolved at admission (Auto = the owner's default model; refused with `model_unavailable`, never swapped) and applied only to the answering agent, effort only to a provider's `effort_models`; `get_chat_context` gives slash commands (generic plus the apps' `commands`) and capabilities; dictation is the speech plugin's `dictation_status` / `transcribe_audio`. Lists every event, handler, part and error code (among them `engine_unavailable`: with Temporal not connected a workflow's chat saves nothing, since nothing could deliver it). |
-| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (set by `app/usePageActivitySync.ts`, mounted in `App.tsx` above the sign-in gate so it covers every screen, while the tab is hidden or the window is blurred; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 inline SVG glyph strings across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
+| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (set by `app/usePageActivitySync.ts`, mounted in `App.tsx` above the sign-in gate so it covers every screen, while the page is hidden per the Page Visibility API, never merely because the window lost focus; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 inline SVG glyph strings across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), 12-theme docs (`guidelines/THEMES.md`), **the merged handoff brief (`HANDOFF.md` — glow-ladder traps, step-edge contract, toolbar layout traps, canvas-layer asymmetries, plus the recorded product amendments)**, and **the panel×theme fidelity target (`reference-mockup/Panel Theme Matrix.dc.html` — 17 panels × 12 themes, open in a browser)**. `reference/themes/` no longer vendors CSS snapshots — it points at the authoritative [client/src/themes/](./client/src/themes/). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |
| **[Schema Source of Truth RFC](./docs-internal/ARCHIVE/schema_source_of_truth_rfc.md)** | *Archived — shipped.* Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons; `VITE_NODESPEC_BACKEND` defaults on and the frontend node definitions are gone. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Current reference: [Plugin System](./docs-internal/plugin_system.md). |
| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern; `request()` supports `json` / `data` / `files` — the last for multipart uploads, threaded through the auth-retry rebuild). `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use); live count via `len(services.plugin.credential.CREDENTIAL_REGISTRY)` — do not hand-maintain a number here. `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live plugin count via `len(services.node_registry.NODE_METADATA)`; a bare `__init__.py` glob overcounts by also matching group packages); handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `triggers.py` generic trigger-node handler, `todo.py` writeTodos shim — `google_auth.py` was retired into `nodes/google/_auth_helper.py`). **Wave 11.H added "self-contained plugin folders"** — generic registries (live list via `grep -rn '^def register_' server/services server/core`; the plugin-facing ones are `ws_handler_registry.{register_ws_handlers,register_router,register_option_loader,register_oauth_callback_path}`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`, `edge_walker.{register_agent_context_builder,register_master_skill_expander}`, `register_webhook_source`, `register_canary_trigger_type`, `register_poll_coroutine_factory`, `register_social_send_handler`, `register_shutdown_hook`, `register_service_factory`, `register_log_source_tag`, `register_conversation_listener`) so rich plugins like telegram own their entire surface area without core-services edits. |
diff --git a/client/src/app/__tests__/shellEffects.test.tsx b/client/src/app/__tests__/shellEffects.test.tsx
index 4cde3c38..38a048d4 100644
--- a/client/src/app/__tests__/shellEffects.test.tsx
+++ b/client/src/app/__tests__/shellEffects.test.tsx
@@ -28,6 +28,12 @@ import { useWorkflowSettingsStore } from '../../stores/workflowSettingsStore';
const root = document.documentElement;
const hidden = () => root.hasAttribute('data-page-hidden');
+/** The tab goes to the background (`true`) or comes back. */
+function setTabHidden(isHidden: boolean) {
+ vi.spyOn(document, 'hidden', 'get').mockReturnValue(isHidden);
+ document.dispatchEvent(new Event('visibilitychange'));
+}
+
describe('usePageActivitySync', () => {
beforeEach(() => {
vi.useFakeTimers({ toFake: ['requestAnimationFrame', 'cancelAnimationFrame', 'setTimeout', 'clearTimeout'] });
@@ -35,21 +41,18 @@ describe('usePageActivitySync', () => {
afterEach(() => {
vi.useRealTimers();
+ vi.restoreAllMocks();
root.removeAttribute('data-page-hidden');
pageActivity.set(true);
});
- it('pauses on blur and resumes two frames after focus', () => {
+ it('pauses while the tab is hidden and resumes two frames after it shows', () => {
renderHook(() => usePageActivitySync());
- act(() => {
- window.dispatchEvent(new Event('blur'));
- });
+ act(() => setTabHidden(true));
expect(hidden()).toBe(true);
expect(pageActivity.isActive()).toBe(false);
- act(() => {
- window.dispatchEvent(new Event('focus'));
- });
+ act(() => setTabHidden(false));
expect(hidden()).toBe(true);
act(() => {
vi.advanceTimersToNextFrame();
@@ -59,12 +62,21 @@ describe('usePageActivitySync', () => {
expect(pageActivity.isActive()).toBe(true);
});
- it('a hide during the resume frames wins', () => {
+ it('keeps animating while the window is visible but not focused', () => {
renderHook(() => usePageActivitySync());
act(() => {
window.dispatchEvent(new Event('blur'));
- window.dispatchEvent(new Event('focus'));
- window.dispatchEvent(new Event('blur'));
+ });
+ expect(hidden()).toBe(false);
+ expect(pageActivity.isActive()).toBe(true);
+ });
+
+ it('a hide during the resume frames wins', () => {
+ renderHook(() => usePageActivitySync());
+ act(() => {
+ setTabHidden(true);
+ setTabHidden(false);
+ setTabHidden(true);
});
act(() => {
vi.advanceTimersToNextFrame();
@@ -79,8 +91,8 @@ describe('usePageActivitySync', () => {
const cancel = vi.spyOn(window, 'cancelAnimationFrame');
const { unmount } = renderHook(() => usePageActivitySync());
act(() => {
- window.dispatchEvent(new Event('blur'));
- window.dispatchEvent(new Event('focus'));
+ setTabHidden(true);
+ setTabHidden(false);
});
unmount();
expect(cancel).toHaveBeenCalled();
diff --git a/client/src/app/usePageActivitySync.ts b/client/src/app/usePageActivitySync.ts
index 90e04354..a12d5656 100644
--- a/client/src/app/usePageActivitySync.ts
+++ b/client/src/app/usePageActivitySync.ts
@@ -1,6 +1,6 @@
/**
* Keeps `<html data-page-hidden>` and the `pageActivity` store in step with
- * whether anyone can see the app.
+ * whether the page can be seen.
*
* Why the attribute exists (Wave 33): browsers keep advancing CSS keyframe
* timing on hidden tabs, and when the tab returns every paused frame of
@@ -10,11 +10,11 @@
* pauses every CSS animation while the attribute is present. Script-driven
* motion (lib/motion, the Home orb) reads `pageActivity` for the same signal.
*
- * "Not visible" is the tab being hidden OR the window being blurred:
- * `visibilitychange` alone misses window-minimize on Windows and app
- * switching on macOS, which do fire blur/focus. On resume the attribute is
- * removed two frames later, so the first input dispatches before the
- * composite resumes.
+ * "Can be seen" is the Page Visibility API alone. Chrome also reports a
+ * minimised or fully covered window as hidden, so a window that is only
+ * unfocused (the app beside an editor, or DevTools focused) stays visible
+ * and keeps animating. On resume the attribute is removed two frames later,
+ * so the first input dispatches before the composite resumes.
*
* Moved from Dashboard so it runs on both screens, with two fixes: the
* resume frames are cancelled on unmount and on every new signal (they
@@ -28,7 +28,6 @@ import { pageActivity } from '../lib/pageActivity';
export function usePageActivitySync(): void {
useEffect(() => {
const root = document.documentElement;
- let blurred = false;
let outer = 0;
let inner = 0;
@@ -41,7 +40,7 @@ export function usePageActivitySync(): void {
const apply = () => {
cancelResume();
- if (document.hidden || blurred) {
+ if (document.hidden) {
root.setAttribute('data-page-hidden', '');
pageActivity.set(false);
return;
@@ -50,32 +49,18 @@ export function usePageActivitySync(): void {
outer = 0;
inner = requestAnimationFrame(() => {
inner = 0;
- if (document.hidden || blurred) return;
+ if (document.hidden) return;
root.removeAttribute('data-page-hidden');
pageActivity.set(true);
});
});
};
- const onVisibility = () => apply();
- const onBlur = () => {
- blurred = true;
- apply();
- };
- const onFocus = () => {
- blurred = false;
- apply();
- };
-
// A page opened in a background tab starts hidden.
if (document.hidden) apply();
- document.addEventListener('visibilitychange', onVisibility);
- window.addEventListener('blur', onBlur);
- window.addEventListener('focus', onFocus);
+ document.addEventListener('visibilitychange', apply);
return () => {
- document.removeEventListener('visibilitychange', onVisibility);
- window.removeEventListener('blur', onBlur);
- window.removeEventListener('focus', onFocus);
+ document.removeEventListener('visibilitychange', apply);
cancelResume();
root.removeAttribute('data-page-hidden');
pageActivity.set(true);
diff --git a/client/src/features/home/orb/orbEngine.ts b/client/src/features/home/orb/orbEngine.ts
index b1fd40ee..851c1f8d 100644
--- a/client/src/features/home/orb/orbEngine.ts
+++ b/client/src/features/home/orb/orbEngine.ts
@@ -17,8 +17,8 @@
*
* The host is measured every frame and the drawing buffer follows it;
* nothing is drawn until the host has a size, so a first 0x0 measure never
- * leaves a 1x1 buffer. Frames stop while the page is hidden or the window
- * is blurred (lib/pageActivity).
+ * leaves a 1x1 buffer. Frames stop while the page is hidden
+ * (lib/pageActivity); a visible window keeps them going, focused or not.
*
* The browser can take the WebGL context away (after sleep, or when a
* laptop switches GPU) and hand it back. The engine asks for it back and
diff --git a/client/src/lib/pageActivity.ts b/client/src/lib/pageActivity.ts
index 0b5af935..2cf6c5a5 100644
--- a/client/src/lib/pageActivity.ts
+++ b/client/src/lib/pageActivity.ts
@@ -2,11 +2,12 @@
* Page activity — whether anyone can currently see the app.
*
* `html[data-page-hidden] * { animation-play-state: paused }` (themes/base.css)
- * pauses CSS keyframe animations while the tab is hidden or the window is
- * blurred, but it cannot reach Web Animations started from script or
- * requestAnimationFrame loops (the Home orb). Those subscribe here instead.
- * `App.tsx` keeps this in sync (`usePageActivitySync`) with the same
- * visibility / focus events that toggle `data-page-hidden`.
+ * pauses CSS keyframe animations while the page is hidden, but it cannot
+ * reach Web Animations started from script or requestAnimationFrame loops
+ * (the Home orb). Those subscribe here instead. `App.tsx` keeps this in sync
+ * (`usePageActivitySync`) with the same `visibilitychange` events that
+ * toggle `data-page-hidden`; a visible window that is only unfocused counts
+ * as active.
*
* A plain module store: read it without re-rendering (`isActive()`), or
* subscribe for changes. Deliberately not React state.
diff --git a/client/src/themes/base.css b/client/src/themes/base.css
index 1e4f08b9..2034247e 100644
--- a/client/src/themes/base.css
+++ b/client/src/themes/base.css
@@ -355,11 +355,11 @@
* input events queue but don't dispatch — first click on tab return
* appears unresponsive.
*
- * The Dashboard mounts a small `visibilitychange` listener that toggles
- * this attribute on `<html>`. Setting `animation-play-state: paused`
- * flushes the keyframe queue so resume has nothing to catch up on. The
- * dashboard defers the unpause via `requestAnimationFrame` so input
- * dispatch happens before composite.
+ * `usePageActivitySync` (app/usePageActivitySync.ts, mounted by App)
+ * toggles this attribute on `<html>` on `visibilitychange`. Setting
+ * `animation-play-state: paused` flushes the keyframe queue so resume has
+ * nothing to catch up on. It defers the unpause via
+ * `requestAnimationFrame` so input dispatch happens before composite.
* ============================================================================ */
html[data-page-hidden] *,
diff --git a/docs-internal/normal_mode.md b/docs-internal/normal_mode.md
index 0747721a..3cd86be9 100644
--- a/docs-internal/normal_mode.md
+++ b/docs-internal/normal_mode.md
@@ -191,8 +191,8 @@ a double heartbeat in the core, the heads breathing out and back in turn
(each head and its crescent are one group), one searching ping per line,
slightly dimmer, blended in and out over about a second with no jump. The
engine measures its host every frame, draws nothing until the host has a size,
-and stops its frames while the page is hidden or the window blurred
-(`lib/pageActivity`). The logo itself is one
+and stops its frames while the page is hidden (`lib/pageActivity`); a visible
+window keeps it moving whether or not it has focus. The logo itself is one
colour; in dark the orb keeps colours of its own (a purple-to-cyan ring; pink,
yellow and green heads) with white particles and packets; in light it is
glossy piano-black under a white rim light. Its glows and particles blend
diff --git a/docs-internal/theme_system.md b/docs-internal/theme_system.md
index 64516047..06e60b19 100644
--- a/docs-internal/theme_system.md
+++ b/docs-internal/theme_system.md
@@ -296,7 +296,7 @@ the surrounding chrome. Every other surface uses Tailwind + tokens. New themes c
### Done
- **`--node-pulse-color` contract** — executing-node glow color is independent of `--node-color` (the plugin accent). Each decorated skin overrides `--node-pulse-color` to its highest-contrast accent (light/dark deliberately keep the base.css `var(--info)` fallback) (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine `--lapis-bright`, Atomic turquoise, etc.) so the glow stays visible against any canvas background. Defined in [base.css](../client/src/themes/base.css) at `:root`, overridden in each per-theme file. The executing keyframes (`node-pulse` + per-theme `cyber-pulse-exec` / `surv-pulse-exec` / `ren-pulse-exec`) and the per-theme `--pulse-keyframe` / `--pulse-duration` / `--pulse-timing` tokens live in [animations.css](../client/src/themes/animations.css); base.css's `.sq-node[data-executing] .sq-node-box` / `.react-flow__node.executing .{sq-node-box,node}` rule reads `var(--pulse-keyframe, node-pulse)`, so a theme picks its pulse by overriding ONE token (Cyber → `cyber-pulse-exec`, Surveillance → `surv-pulse-exec`, Renaissance → `ren-pulse-exec`) — no high-specificity per-theme animation rule. `node-pulse` is a triple-layer expanding box-shadow (12px ring + 32px mid halo + 56px outer halo) consuming `var(--node-pulse-color)` + the shared `--tint-pulse-*` alphas. Trigger nodes use a separate continuous `.opencompany-trigger-armed` "listening" heartbeat (`trigger-listening` keyframe) while waiting, plus `.opencompany-bolt` on the ⚡ badge — distinct from the one-shot execution pulse. **Never animate `opacity` on whole-node selectors** — it fades the node icon + content, not just the glow.
-- **`data-page-hidden` animation pause** — `usePageActivitySync()` ([app/usePageActivitySync.ts](../client/src/app/usePageActivitySync.ts)), mounted once in [App.tsx](../client/src/App.tsx), above the sign-in gate, so it covers every screen (sign-in and Connecting included), listens to `visibilitychange` plus window `blur` / `focus` and toggles `data-page-hidden` on `<html>`; [base.css](../client/src/themes/base.css) declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important; }`. Without this, paused CSS keyframes accumulate frames in the compositor queue while the tab is hidden; on tab return all 50+ executing nodes' triple-layer pulses + Cyber's full-viewport `cyber-flicker` / `cyber-roll` resume simultaneously, stalling the GPU compositor 100-200ms and blocking input dispatch (first-click-feels-frozen pattern). The unpause is deferred two `requestAnimationFrame` ticks so input dispatch wins the frame before composite resumes.
+- **`data-page-hidden` animation pause** — `usePageActivitySync()` ([app/usePageActivitySync.ts](../client/src/app/usePageActivitySync.ts)), mounted once in [App.tsx](../client/src/App.tsx), above the sign-in gate, so it covers every screen (sign-in and Connecting included), listens to `visibilitychange` alone and toggles `data-page-hidden` on `<html>` (Chrome reports a minimised or fully covered window as hidden too; a visible window that is only unfocused, such as the app beside an editor, keeps animating); [base.css](../client/src/themes/base.css) declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important; }`. Without this, paused CSS keyframes accumulate frames in the compositor queue while the tab is hidden; on tab return all 50+ executing nodes' triple-layer pulses + Cyber's full-viewport `cyber-flicker` / `cyber-roll` resume simultaneously, stalling the GPU compositor 100-200ms and blocking input dispatch (first-click-feels-frozen pattern). The unpause is deferred two `requestAnimationFrame` ticks so input dispatch wins the frame before composite resumes.
- **Parameter panel theme contract** — MasterSkillEditor, OutputPanel, MiddleSection, ParameterPanel removed `useAppTheme()`. Every surface renders against Tailwind tokens + new-contract CSS custom props. Section headers carry the display-typography triplet (`font-display tracking-[var(--type-tracking-display)] [text-transform:var(--type-uppercase)] text-fg-default`); action buttons use `<ActionButton intent="run|stop|save|config|tools">`; backgrounds use `bg-bg-elevated` / `bg-bg-panel` / `bg-bg-input` from the surface tier table above. EditableNodeLabel emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire under either topology. Per-theme scrollbar webkit rules (`::-webkit-scrollbar-thumb` etc.) declared in all 12 themes — gold (Renaissance), square-cornered (Atomic / Edo / Greek / Wasteland / Plague), metallic (Steampunk), phosphor (Rot), neon (Cyber), REC-red (Surveillance), shadcn neutral (Light / Dark).
- **Canvas-node class topology alignment** (W26) — TriggerNode, StartNode, ToolkitNode migrated from `.node` (rectangular spec-card) topology to `.sq-node` / `.sq-node-box` (square-icon node) topology so per-theme decorations (Steampunk brass rivets, Edo hanko seal, Surveillance REC LED, Renaissance gold emblem) reach them. Status pips, gear buttons, and React Flow handles on every node component now carry `.sq-node-pip` / `.sq-node-gear` / `.sq-node-handle.in/.out` (square nodes) or `.node-pip` / `.node-gear` / `.node-handle.in/.out` (rectangular nodes — AIAgentNode, TeamMonitorNode; the former `GenericNode` was retired with the spec-driven canvas). Pip background is data-driven via `data-status="idle | executing | waiting | success | error"` — base.css picks the colour from shadcn semantic tokens; per-theme files override. Inline JS-computed `backgroundColor` / `border` / `animation` on these elements stripped — CSS owns visuals. Cyber's `.node-trigger` rule extended to dual-target both rectangular and square topologies (`.sq-node.node-trigger .sq-node-box`). Orphan `.node-output` rule removed. EditableNodeLabel now emits both `sq-node-label` and `node-label` classNames so per-theme typography rules fire. StartNode reads `nodeColor` from `definition?.defaults?.color` instead of hardcoded `theme.dracula.cyan`; the NodeSpec adapter never fills that field, so it resolves to `var(--node-workflow)`.
- **Audio fix** (W20) — `--sound-pack: chime` typo in `light.css` + `dark.css` was silently falling through to `'none'` (`chime` not in the engine's pack registry), making sound silent for the most-used themes. Renamed `light` → `parchment`, `dark` → `terminal`. Added `Sounds.unlock()` exported from [lib/sound.ts](../client/src/lib/sound.ts) plus a one-shot `pointerdown / keydown / touchstart` capture-phase listener in `useSoundSync()` ([hooks/useSound.ts](../client/src/hooks/useSound.ts)) so the AudioContext resumes on the user's first gesture (Chrome / Safari autoplay policy compliance).