App.tsx

import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
import { flushSync } from 'react-dom';
import { AnimatePresence, motion, MotionConfig } from 'motion/react';
import { useAnalytics } from './analytics/provider';
import {
  trackFileUploadResult,
  trackProjectCreateResult,
} from './analytics/events';
import { deriveUploadCohort } from './analytics/upload-tracking';
import { setPendingDesignSystemCreateEntry } from './analytics/ds-create-entry';
import { detectClientType } from './analytics/identity';
import {
  stashOnboardingEntryForProject,
  type OnboardingEntry,
} from './onboarding/onboarding-entry';
import {
  deriveConfigureGlobals,
  projectKindFromMetadataToTracking,
  fidelityToTracking,
} from '@open-design/contracts/analytics';
import type {
  AmrModelsResponse,
  ChatSessionMode,
  RunContextSelection,
  TeamProject,
  WorkspaceTeamProjectsResponse,
  WorkspaceCollabContext,
  WorkspaceProjectSummary,
} from '@open-design/contracts';
import { DEFAULT_UNSELECTED_SCENARIO_PLUGIN_ID } from '@open-design/contracts';
import { EntryView } from './components/EntryView';
import type { ProjectTitleHint } from './components/EntryShell';
import type { IntegrationTab } from './components/IntegrationsView';
import { MarketplaceView } from './components/MarketplaceView';
import { PluginDetailView } from './components/PluginDetailView';
import type { CreateInput, ImportClaudeDesignOutcome } from './components/NewProjectPanel';
import { MemoryToast } from './components/MemoryToast';
import { Toast } from './components/Toast';
import { CenteredLoader } from './components/Loading';
import { PetOverlay, type PetTaskCenter } from './components/pet/PetOverlay';
import { buildPetTaskCenter } from './components/pet/taskCenter';
import { migrateCustomPetAtlas } from './components/pet/pets';
import {
  ProjectView,
  type ProjectNameAuthorityResolution,
} from './components/ProjectView';
import { AmrArtifactUpgradeGate } from './components/AmrArtifactUpgradeGate';
import { AmrArtifactUpgradeHomeCard } from './components/AmrArtifactUpgradeHomeCard';
import { TooltipLayer } from './components/TooltipLayer';
import { UpdateDialog } from './components/UpdateDialog';
import { openWorkspaceTab, WorkspaceTabsBar } from './components/WorkspaceTabsBar';
import {
  DesignSystemCreationFlow,
  DesignSystemDetailView,
} from './components/DesignSystemFlow';
import {
  IframeKeepAliveProvider,
  useIframeKeepAlivePool,
} from './components/IframeKeepAlivePool';
import {
  SettingsDialog,
  switchApiProtocolConfig,
  updateCurrentApiProtocolConfig,
  type SettingsSection,
  type SettingsHighlight,
} from './components/SettingsDialog';
import { PrivacyConsentModal } from './components/PrivacyConsentModal';
import {
  daemonIsLive,
  fetchAppVersionInfo,
  fetchAgentsStream,
  fetchDesignSystems,
  fetchDesignTemplates,
  fetchPromptTemplates,
  fetchSkills,
  openExternalUrl,
  uploadProjectFiles,
  replaceProjectWorkingDir,
} from './providers/registry';
import { openFirstPartyExternalLinkFromClick } from './first-party-external-link';
import {
  RUNS_CHANGED_EVENT,
  fetchAmrModels,
  fetchVelaLoginStatus,
  listProjectRuns,
  type VelaLoginStatus,
} from './providers/daemon';
import { AMR_LOGIN_STATUS_EVENT } from './components/amrLoginPolling';
import { CollabDemoView } from './collab/CollabDemoView';
import {
  beginWorkspaceScopedRead,
  useWorkspaceBilling,
  useWorkspaceContext,
  workspaceIdentityCacheKey,
} from './collab/useWorkspaceContext';
import { resolvePlanTier } from './collab/team-plan';
import { deriveTabIdentityScope, UNSET_ACCOUNT_BUCKET } from './collab/tab-scope';
import { CommunityView } from './components/CommunityView';
import { seedHomeComposerPrompt } from './components/HomeView';
import { goBack, navigate, useRoute, type Route } from './router';
import {
  fetchDaemonConfig,
  DEFAULT_PET,
  fetchMediaProvidersFromDaemon,
  hasAnyConfiguredProvider,
  fetchComposioConfigFromDaemon,
  loadConfig,
  mergeDaemonConfig,
  mergeDaemonMediaProviders,
  saveConfig,
  shouldSyncLocalMediaProvidersToDaemon,
  syncComposioConfigToDaemon,
  syncConfigToDaemon,
  syncMediaProvidersToDaemon,
} from './state/config';
import { applyAppearanceToDocument } from './state/appearance';
import { isMacPlatform } from './utils/platform';
import { summarizeProjectNameFromPrompt } from './utils/projectName';
import {
  amrArtifactUpgradeHomeMockOffer,
  type AmrArtifactUpgradeHomeOffer,
} from './runtime/amr-artifact-upgrade';
import {
  amrBalanceGateScopeForWorkspaceContext,
  amrBalanceGateScopesMatch,
  type AmrBalanceGateScope,
} from './runtime/amr-balance-gate';
import { installFontRecovery } from './runtime/font-recovery';
import {
  createDesignSystemProjectFromProject,
  createProject,
  createPluginShareProject,
  deleteProject as deleteProjectApi,
  duplicateProject,
  getProject,
  importClaudeDesignZip,
  importFolderProject,
  listWorkspaceProjectSummaries,
  listProjects,
  listTemplates,
  deleteTemplate,
  duplicatePluginAsProject,
  patchProject,
  resolvedWorkspaceContextForWrite,
} from './state/projects';
import { useModalWindowDragGuard } from './hooks/useModalWindowDragGuard';
import { resumeThumbnailLoads, suspendThumbnailLoads } from './lib/thumbnail-load-gate';
import type {
  PluginShareAction,
  PluginShareProjectOutcome,
  WorkspaceProjectListView,
} from './state/projects';
import { getOpenDesignHost, type OpenDesignHostProjectImportSuccess } from '@open-design/host';
import { useI18n } from './i18n';
import { liveArtifactTabId } from './types';
import type {
  AgentInfo,
  AgentModelChoice,
  ApiProtocol,
  AppConfig,
  AppVersionInfo,
  ChatAttachment,
  DesignSystemGenerationJob,
  DesignSystemSummary,
  Project,
  ProjectMetadata,
  ProjectTemplate,
  ProviderModelOption,
  PromptTemplateSummary,
  SkillSummary,
} from './types';

type AppCreateProjectInput = Omit<CreateInput, 'metadata'> & {
  metadata?: CreateInput['metadata'];
  pendingPrompt?: string;
  pluginId?: string;
  pluginType?: string;
  appliedPluginSnapshotId?: string;
  pluginInputs?: Record<string, unknown>;
  initialRunContext?: RunContextSelection | null;
  conversationMode?: ChatSessionMode;
  autoSendFirstMessage?: boolean;
  /** Exact workspace/member authority checked by the Home AMR preflight. */
  amrGatePrecheckWitness?: AmrBalanceGateScope;
  requestId?: string;
  pendingFiles?: File[];
  userWorkingDirToken?: string;
  linkedDirs?: string[] | null;
  onboardingEntry?: OnboardingEntry;
};

const APP_CONFIG_CHANGED_EVENT = 'open-design:app-config-changed';
const AMR_AGENT_ID = 'amr';
const AMR_PROFILE_ENV_KEY = 'OPEN_DESIGN_AMR_PROFILE';
const AGENT_FOCUS_REFRESH_THROTTLE_MS = 10_000;

/**
 * Whether this launch should hand the user to the first-run onboarding flow.
 *
 * Two conditions, both about the *user*, neither about where they happen to be
 * in the app: they have never completed onboarding (on either the local or the
 * daemon copy — `mergeDaemonConfig` ratchets the two before this runs), and
 * they did not arrive through an explicit deep link that onboarding must not
 * hijack (the collab demo and the community gallery are shareable URLs).
 *
 * Deliberately a pure predicate over a resolved config: the redirect belongs to
 * the one-shot boot pass, and expressing it as a function of "who the user is"
 * rather than "what just happened" keeps it from being re-decided mid-session.
 */
export function shouldRouteToFirstRunOnboarding(
  config: AppConfig,
  pathname: string,
): boolean {
  if (config.onboardingCompleted === true) return false;
  if (pathname.startsWith('/collab-demo') || pathname.startsWith('/community')) return false;
  return true;
}

function workspaceProjectListViewForRoute(route: Route): WorkspaceProjectListView {
  if (route.kind === 'home' && route.view === 'all-projects') return 'all';
  if (route.kind === 'home' && route.view === 'drafts') return 'drafts';
  if (route.kind === 'project') return 'all';
  return 'recent';
}

export function shouldSyncMediaProvidersOnSave(
  mediaProviders: AppConfig['mediaProviders'],
  options?: { force?: boolean },
): boolean {
  return Boolean(options?.force) || hasAnyConfiguredProvider(mediaProviders);
}

function normalizeSavedComposioConfig(config: AppConfig['composio']): AppConfig['composio'] {
  const apiKey = config?.apiKey?.trim() ?? '';
  if (apiKey) {
    return {
      ...config,
      apiKey: '',
      apiKeyConfigured: true,
      apiKeyTail: apiKey.slice(-4),
    };
  }
  return { ...(config ?? {}) };
}

function amrProfileForConfig(config: AppConfig): string | null {
  const profile = config.agentCliEnv?.[AMR_AGENT_ID]?.[AMR_PROFILE_ENV_KEY];
  return typeof profile === 'string' && profile ? profile : null;
}

function mergeLinkedDirsIntoMetadata(
  metadata: ProjectMetadata | undefined,
  linkedDirs?: string[] | null,
): ProjectMetadata | undefined {
  const nextDirs = (linkedDirs ?? []).map((dir) => dir.trim()).filter(Boolean);
  if (nextDirs.length === 0) return metadata;
  const baseMetadata = metadata ?? { kind: 'other' };
  return {
    ...baseMetadata,
    linkedDirs: Array.from(new Set([...(baseMetadata.linkedDirs ?? []), ...nextDirs])),
  };
}

function sameAgentModelChoice(
  left: AgentModelChoice | undefined,
  right: AgentModelChoice | undefined,
): boolean {
  return (left?.model ?? null) === (right?.model ?? null)
    && (left?.reasoning ?? null) === (right?.reasoning ?? null)
    && (left?.serviceTier ?? null) === (right?.serviceTier ?? null);
}

export function mergeAgentModelChoice(
  previous: AgentModelChoice | undefined,
  next: { model?: string; reasoning?: string; serviceTier?: string },
): AgentModelChoice {
  const merged = { ...(previous ?? {}), ...next };
  if (
    Object.prototype.hasOwnProperty.call(next, 'serviceTier') &&
    next.serviceTier === undefined
  ) {
    delete merged.serviceTier;
  }
  return merged;
}

function clearStaleAmrModelChoiceOnProfileChange(
  previous: AppConfig,
  next: AppConfig,
): AppConfig {
  if (amrProfileForConfig(previous) === amrProfileForConfig(next)) return next;

  const previousChoice = previous.agentModels?.[AMR_AGENT_ID];
  const nextChoice = next.agentModels?.[AMR_AGENT_ID];
  if (!nextChoice || !sameAgentModelChoice(previousChoice, nextChoice)) return next;

  const nextAgentModels = { ...(next.agentModels ?? {}) };
  delete nextAgentModels[AMR_AGENT_ID];
  return { ...next, agentModels: nextAgentModels };
}

type ProjectListRequest = {
  generation: number;
  mutationVersion: number;
  scopeKey: string;
};

/**
 * The scope key for a caller with NO resolved workspace identity — either the
 * context has not landed yet (every fresh boot passes through this) or the
 * daemon has no workspace plane at all. It is deliberately NOT treated as "a
 * workspace you left": a boot that lists projects before the context resolves
 * did not read another workspace's data, so promoting `local` → `ws:member`
 * must not discard the list it just loaded.
 */
const UNRESOLVED_PROJECT_LIST_SCOPE = 'local';

function projectListScopeKey(context: WorkspaceCollabContext | null): string {
  return context
    ? `${context.workspaceId}:${context.workspaceMemberId}`
    : UNRESOLVED_PROJECT_LIST_SCOPE;
}

export function projectViewAuthorizationLifetimeKey(
  projectId: string,
  context: WorkspaceCollabContext | null,
): string {
  return `${projectListScopeKey(context)}:${projectId}`;
}

export async function persistComposioConfigChange(
  current: AppConfig,
  composio: AppConfig['composio'],
  sync: (config: AppConfig['composio']) => Promise<boolean> = syncComposioConfigToDaemon,
): Promise<AppConfig> {
  const saved = await sync(composio);
  if (!saved) throw new Error('Composio config save failed');
  return {
    ...current,
    composio: normalizeSavedComposioConfig(composio),
  };
}

export function buildPersistedConfig(next: AppConfig, current: AppConfig): AppConfig {
  const stalePrivacySnapshot =
    current.privacyDecisionAt != null && next.privacyDecisionAt == null;
  return {
    ...next,
    onboardingCompleted: current.onboardingCompleted ? true : next.onboardingCompleted,
    ...(stalePrivacySnapshot
      ? {
          installationId: current.installationId,
          privacyDecisionAt: current.privacyDecisionAt,
          telemetry: current.telemetry,
        }
      : {}),
    composio: next.composio
      ? {
          apiKey: '',
          apiKeyConfigured: Boolean(next.composio.apiKeyConfigured),
          apiKeyTail: next.composio.apiKeyTail ?? '',
        }
      : next.composio,
  };
}

/**
 * True when `next` and `last` produce an identical persisted shape —
 * i.e. the only diffs between them are fields that buildPersistedConfig
 * intentionally strips before disk/daemon writes (the Composio API key
 * draft today; any future save-on-explicit-confirm secrets later).
 *
 * The autosave loop in Settings uses this to skip the "All changes
 * saved" indicator transition when the user has only typed an unsaved
 * secret. Without it, autosave completes a no-op write and flashes
 * "Saved" — misleading users into trusting that a sensitive key has
 * been persisted when in fact only the section-local "Save key"
 * gesture commits it.
 */
export function isAutosaveDraftOnlyChange(next: AppConfig, last: AppConfig): boolean {
  return (
    JSON.stringify(buildPersistedConfig(next, next))
    === JSON.stringify(buildPersistedConfig(last, last))
  );
}

export function resolveSettingsCloseConfig(
  rendered: AppConfig,
  latestPersisted: AppConfig,
): AppConfig {
  const base = latestPersisted === rendered ? rendered : latestPersisted;
  return base.onboardingCompleted ? base : { ...base, onboardingCompleted: true };
}

function mergeAmrModelsIntoAgents(
  agents: AgentInfo[],
  amrModels: AmrModelsResponse | null,
): AgentInfo[] {
  if (!amrModels || amrModels.models.length === 0) return agents;
  return agents.map((agent) => {
    if (agent.id !== 'amr') return agent;
    const shouldPreferAgentModels =
      amrModels.source === 'preset' &&
      Array.isArray(agent.models) &&
      agent.models.length > 0;
    if (shouldPreferAgentModels) return agent;
    return { ...agent, models: amrModels.models, modelsSource: 'live' };
  });
}

const CANONICAL_AGENT_ORDER = [
  'amr',
  'claude',
  'codex',
  'devin',
  'gemini',
  'opencode',
  'hermes',
  'trae-cli',
  'grok-build',
  'kimi',
  'cursor-agent',
  'qwen',
  'qoder',
  'copilot',
  'pi',
  'kiro',
  'kilo',
  'vibe',
  'deepseek',
  'aider',
  'antigravity',
  'reasonix',
] as const;

const CANONICAL_AGENT_ORDER_INDEX = new Map<string, number>(
  CANONICAL_AGENT_ORDER.map((id, index) => [id, index]),
);

function orderAgentsByRegistry(agents: AgentInfo[]): AgentInfo[] {
  return agents
    .map((agent, index) => ({ agent, index }))
    .sort((left, right) => {
      const leftRank =
        CANONICAL_AGENT_ORDER_INDEX.get(left.agent.id) ??
        CANONICAL_AGENT_ORDER.length;
      const rightRank =
        CANONICAL_AGENT_ORDER_INDEX.get(right.agent.id) ??
        CANONICAL_AGENT_ORDER.length;
      if (leftRank !== rightRank) return leftRank - rightRank;
      return left.index - right.index;
    })
    .map(({ agent }) => agent);
}

function upsertAgent(agents: AgentInfo[], agent: AgentInfo): AgentInfo[] {
  const index = agents.findIndex((item) => item.id === agent.id);
  if (index === -1) return [...agents, agent];
  const next = agents.slice();
  next[index] = agent;
  return next;
}

function isAbortError(err: unknown): boolean {
  return (
    typeof err === 'object' &&
    err !== null &&
    'name' in err &&
    (err as { name?: unknown }).name === 'AbortError'
  );
}

/**
 * `isTeamShared` is the hub-backed truth: `/api/workspace/projects/team`
 * reads the team's resource-hub catalog directly (see
 * `apps/daemon/src/routes/collab-context.ts`), not this daemon's local
 * sqlite. It stays true the instant the hub confirms the project is shared
 * to the caller's team, well before the pull below has materialized a local
 * row. Callers that need to distinguish "not on the hub catalog" (genuinely
 * not shared / no access) from "on the catalog but the local mirror hasn't
 * landed yet" must branch on `isTeamShared`, not on `pulled` — a pull can
 * return `ok: true` with no bytes materialized yet (see collab-sync.ts's
 * `/collab/pull` handler, which only registers the local project once
 * `pullLatest` resolves a non-null version).
 */
type TeamSharedProjectPullOutcome = {
  isTeamShared: boolean;
  pulled: boolean;
};

type TeamProjectCatalogLookup =
  | { ok: true; project: TeamProject | null }
  | { ok: false };

async function fetchTeamProjectCatalogEntry(projectId: string): Promise<TeamProjectCatalogLookup> {
  try {
    const response = await fetch('/api/workspace/projects/team');
    if (!response.ok) return { ok: false };
    const body = (await response.json()) as WorkspaceTeamProjectsResponse;
    return {
      ok: true,
      project: (body.projects ?? []).find((project) => project.projectId === projectId) ?? null,
    };
  } catch {
    return { ok: false };
  }
}

async function pullTeamSharedProjectIfAvailable(projectId: string): Promise<TeamSharedProjectPullOutcome> {
  const lookup = await fetchTeamProjectCatalogEntry(projectId);
  if (!lookup.ok || !lookup.project) return { isTeamShared: false, pulled: false };
  try {
    const pullResponse = await fetch(`/api/projects/${encodeURIComponent(projectId)}/collab/pull`, {
      method: 'POST',
    });
    return { isTeamShared: true, pulled: pullResponse.ok };
  } catch {
    return { isTeamShared: false, pulled: false };
  }
}

// A member's first-ever open of a just-shared project races the daemon's
// local materialization (POST /collab/pull's registerPulledProject, or
// ProjectView's own /collab/status poll firing ensureSharedProjectPlaceholder
// — see collab-sync.ts) against the deep-link bootstrap effect below. Give
// that materialization a bounded window instead of trusting a single
// immediate miss.
//
// 21 attempts * 600ms = ~12s total. The original budget here was 4 * 600ms =
// ~2.4s, sized well under the real /collab/pull latency observed against a
// live vela-backed hub (up to ~10s for a fresh project's first pull) —
// exhausting the window and falling through to "not found" while the pull
// was still genuinely in flight is a false negative, not a correctness
// backstop. ~12s matches the budget ProjectView's own
// CONVERSATION_LOAD_RETRY_DELAYS_MS already established for the identical
// "team-shared project not yet materialized locally" race on the
// conversations-list read, so both retry loops now cover the same worst
// case instead of one giving up 5x sooner than the other. This is still a
// BOUNDED retry, not an unconditional hang: `everConfirmedTeamShared`
// already keeps the caller from navigating home the moment the hub confirms
// team membership even once (see `still-materializing` below), so widening
// this window only helps the case where the hub itself is slow to reflect a
// share, not a genuinely-missing/no-access project — that path still falls
// through to the not-found/navigate-home handling unchanged.
const DEEP_LINK_TEAM_SHARE_RETRY_ATTEMPTS = 21;
const DEEP_LINK_TEAM_SHARE_RETRY_DELAY_MS = 600;

function delay(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

export type DeepLinkedProjectResolution =
  | { kind: 'found'; project: Project }
  // The hub confirmed team membership at least once during the retry window:
  // the project exists and the caller has access. Local materialization is
  // still catching up — the caller must NOT treat this as "not found".
  | { kind: 'still-materializing' }
  // Never confirmed as team-shared within the retry window (or genuinely not
  // shared at all) — the caller's existing not-found handling applies.
  | { kind: 'not-found' };

/**
 * Resolves a project a member has just deep-linked to but has no local
 * record of yet. Bounded-retries `getProject` + `pullTeamSharedProjectIfAvailable`
 * so a first-ever open of a freshly team-shared project survives the local
 * materialization race instead of being misread as "doesn't exist" on the
 * first miss. Pulled out of the App.tsx bootstrap effect as a plain async
 * function (no React, no timers beyond the injected `delay`) so the retry
 * decision — when does "not found yet" become "still materializing" versus
 * "genuinely not found" — is unit-testable without mounting the component.
 */
export async function resolveDeepLinkedTeamSharedProject(
  projectId: string,
  deps: {
    getProject: (id: string) => Promise<Project | null>;
    pullTeamSharedProjectIfAvailable: (id: string) => Promise<TeamSharedProjectPullOutcome>;
    delay: (ms: number) => Promise<void>;
    retryAttempts?: number;
    retryDelayMs?: number;
    isCancelled?: () => boolean;
  },
): Promise<DeepLinkedProjectResolution> {
  const attempts = deps.retryAttempts ?? DEEP_LINK_TEAM_SHARE_RETRY_ATTEMPTS;
  const retryDelayMs = deps.retryDelayMs ?? DEEP_LINK_TEAM_SHARE_RETRY_DELAY_MS;
  const isCancelled = () => deps.isCancelled?.() ?? false;
  let everConfirmedTeamShared = false;
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    if (attempt > 0) {
      await deps.delay(retryDelayMs);
      if (isCancelled()) return { kind: 'still-materializing' };
    }
    const project = await deps.getProject(projectId).catch(() => null);
    if (isCancelled()) return { kind: 'still-materializing' };
    if (project) return { kind: 'found', project };
    const { isTeamShared, pulled } = await deps.pullTeamSharedProjectIfAvailable(projectId);
    if (isCancelled()) return { kind: 'still-materializing' };
    if (isTeamShared) everConfirmedTeamShared = true;
    if (pulled) {
      const pulledProject = await deps.getProject(projectId).catch(() => null);
      if (isCancelled()) return { kind: 'still-materializing' };
      if (pulledProject) return { kind: 'found', project: pulledProject };
    }
  }
  return everConfirmedTeamShared ? { kind: 'still-materializing' } : { kind: 'not-found' };
}

export async function hydrateReadyTeamProject(
  projectId: string,
  workspaceId: string,
  deps: {
    getWorkspaceContext: () => WorkspaceCollabContext | null;
    listWorkspaceProjects: (
      context: WorkspaceCollabContext,
    ) => Promise<WorkspaceProjectSummary[]>;
    applyProject: (project: Project) => void;
  },
): Promise<Project | null> {
  const initialContext = deps.getWorkspaceContext();
  if (
    !initialContext ||
    initialContext.workspaceType !== 'team' ||
    initialContext.workspaceId !== workspaceId ||
    initialContext.memberStatus !== 'active' ||
    initialContext.lifecycleState !== 'active'
  ) {
    return null;
  }
  const contextMatches = () => {
    const context = deps.getWorkspaceContext();
    return Boolean(
      context &&
      context.workspaceType === 'team' &&
      context.workspaceId === initialContext.workspaceId &&
      context.workspaceMemberId === initialContext.workspaceMemberId &&
      context.memberStatus === 'active' &&
      context.lifecycleState === 'active' &&
      (context.teamId ?? context.workspaceId) ===
        (initialContext.teamId ?? initialContext.workspaceId)
    );
  };
  const summaries = await deps.listWorkspaceProjects(initialContext).catch(() => []);
  if (!contextMatches()) return null;
  const summary = summaries.find((candidate) =>
    candidate.id === projectId &&
    candidate.project.id === projectId
  );
  const hasMaterializedTeamBinding = Boolean(
    summary &&
    summary.workspaceId === workspaceId &&
    summary.project.workspaceId === workspaceId &&
    summary.visibility === 'team' &&
    summary.resourceState === 'active' &&
    summary.cloudTombstonedAt == null &&
    summary.currentUserAccess.canOpen === true &&
    typeof summary.resourceHubResourceId === 'string' &&
    summary.resourceHubResourceId.trim() &&
    summary.syncState === 'synced'
  );
  if (!summary || !hasMaterializedTeamBinding) return null;
  deps.applyProject(summary.project);
  return summary.project;
}

export function App() {
  // `reducedMotion="user"` makes every motion/react component honor the OS
  // `prefers-reduced-motion` setting: transform/layout animations are zeroed
  // out while opacity-only changes are kept. The CSS `@media (prefers-reduced-
  // motion: reduce)` block covers the CSS-keyframe surfaces, but the dialogs,
  // toasts and popovers that moved to motion/react need this gate too — without
  // it they keep springing/sliding for users who asked us not to animate.
  return (
    <MotionConfig reducedMotion="user">
      <IframeKeepAliveProvider>
        <AppInner />
      </IframeKeepAliveProvider>
    </MotionConfig>
  );
}

function AppInner() {
  const { t } = useI18n();
  const iframeKeepAlivePool = useIframeKeepAlivePool();
  const clientType = useMemo(() => detectClientType(), []);
  const hostPlatform = useMemo(() => getOpenDesignHost()?.client.platform, []);
  useModalWindowDragGuard();
  const workspaceContextState = useWorkspaceContext();
  const {
    context: workspaceContext,
    loading: workspaceContextLoading,
  } = workspaceContextState;
  const currentWorkspaceIdentity = workspaceIdentityCacheKey(workspaceContext);
  const workspaceBilling = useWorkspaceBilling();
  const workspaceContextRef = useRef<WorkspaceCollabContext | null>(null);
  const workspaceContextStateRef = useRef(workspaceContextState);
  workspaceContextRef.current = workspaceContext;
  workspaceContextStateRef.current = workspaceContextState;
  const listCurrentWorkspaceProjects = useCallback(
    (options?: { throwOnError?: boolean; workspaceView?: WorkspaceProjectListView }) => {
      const context = workspaceContextRef.current;
      return listProjects({
        ...options,
        workspaceContext: context,
        workspaceView: context ? options?.workspaceView ?? 'recent' : undefined,
      });
    },
    [],
  );
  useEffect(() => {
    const onFirstPartyExternalLink = (event: MouseEvent) => openFirstPartyExternalLinkFromClick(
      event,
      (url) => { void openExternalUrl(url); },
    );
    // React handlers append AMR attribution while the event bubbles; bridge the final URL afterwards.
    document.addEventListener('click', onFirstPartyExternalLink);
    return () => document.removeEventListener('click', onFirstPartyExternalLink);
  }, []);
  // Icon fonts whose startup fetch lost a race stay tofu forever without
  // this — see runtime/font-recovery.ts.
  useEffect(() => installFontRecovery(), []);
  // Observability marker. `apps/web/src/observability/white-screen.ts`
  // keys its "app actually mounted" success condition on this attribute
  // because the dynamic-import loading shell (`<div class="od-loading-shell">
  // Loading Open Design…</div>`) is itself >MIN_VISIBLE_TEXT and would
  // otherwise be mistaken for a real mount. Survives subsequent render
  // crashes — once App has mounted at least once, it's no longer a white
  // screen (subsequent failures show up as `$exception`).
  useEffect(() => {
    if (typeof document !== 'undefined') {
      document.documentElement.setAttribute('data-od-app-mounted', '1');
      document.querySelectorAll('.od-loading-shell').forEach((node) => node.remove());
    }
  }, []);
  // Desktop vibrancy focus response: an unfocused window drops the cream
  // scrim to let the wallpaper show through more clearly; on focus the scrim
  // returns to full strength (app-wash.css keys off this class).
  useEffect(() => {
    if (
      clientType !== 'desktop'
      || hostPlatform !== 'darwin'
      || typeof window === 'undefined'
    ) return undefined;
    const root = document.documentElement;
    const sync = () => root.classList.toggle('is-window-blurred', !document.hasFocus());
    sync();
    window.addEventListener('focus', sync);
    window.addEventListener('blur', sync);
    return () => {
      window.removeEventListener('focus', sync);
      window.removeEventListener('blur', sync);
      root.classList.remove('is-window-blurred');
    };
  }, [clientType, hostPlatform]);
  const [config, setConfig] = useState<AppConfig>(() => loadConfig());
  const configRef = useRef(config);
  configRef.current = config;
  const latestPersistedConfigRef = useRef(config);
  latestPersistedConfigRef.current = config;
  const settingsDraftConfigRef = useRef<AppConfig | null>(null);
  const [settingsOpen, setSettingsOpen] = useState(false);
  const [amrArtifactUpgradeHomeMockConfig] = useState<AmrArtifactUpgradeHomeOffer | null>(
    () => process.env.NODE_ENV === 'development' && typeof window !== 'undefined'
      ? amrArtifactUpgradeHomeMockOffer(window.location.search)
      : null,
  );
  const amrArtifactUpgradeHomeMock = amrArtifactUpgradeHomeMockConfig !== null;
  const [amrArtifactUpgradeHomeOffer, setAmrArtifactUpgradeHomeOffer] =
    useState<AmrArtifactUpgradeHomeOffer | null>(() => amrArtifactUpgradeHomeMockConfig);
  // Surfaced when a Home-picked working dir could not be applied to a freshly
  // created project (expired/invalid desktop token, daemon rejection). Without
  // this the failure was swallowed and the user believed their folder was in
  // effect while the project actually stayed in the managed root.
  const [workingDirError, setWorkingDirError] = useState<string | null>(null);
  const [projectOpenError, setProjectOpenError] = useState<string | null>(null);
  const [settingsWelcome, setSettingsWelcome] = useState(false);
  const [settingsInitialSection, setSettingsInitialSection] = useState<SettingsSection>('execution');
  const [settingsHighlight, setSettingsHighlight] = useState<SettingsHighlight>(null);
  const [integrationInitialTab, setIntegrationInitialTab] = useState<IntegrationTab>('mcp');
  const [daemonLive, setDaemonLive] = useState(false);
  const [agents, setAgents] = useState<AgentInfo[]>([]);
  const amrModelsRef = useRef<AmrModelsResponse | null>(null);
  const amrPollGenerationRef = useRef(0);
  const agentStreamRequestSeqRef = useRef(0);
  const agentStreamAbortRef = useRef<AbortController | null>(null);
  const agentFocusRefreshLastRunRef = useRef(Date.now());
  const [amrPollRestartToken, setAmrPollRestartToken] = useState(0);
  const [providerModelsCache, setProviderModelsCache] = useState<
    Record<string, ProviderModelOption[]>
  >({});
  // Functional skills (capabilities the agent invokes mid-task) — stays
  // small and lives under the Settings → Skills surface.
  const [workspaceSkills, setWorkspaceSkills] = useState<{
    identity: string;
    items: SkillSummary[];
  }>(() => ({
    identity: currentWorkspaceIdentity,
    items: [],
  }));
  // A workspace-scoped response is safe to render only under the exact
  // identity it was fetched for. The replacement read starts in an effect, so
  // clearing in that effect would still paint one frame of A's skills under B.
  // Derive the visible catalog during render instead: an identity mismatch is
  // a fail-closed empty list until B's own response commits.
  const skills =
    workspaceSkills.identity === currentWorkspaceIdentity
      ? workspaceSkills.items
      : [];
  // Design templates (rendering catalogue: decks, prototypes, image/video/
  // audio templates) — sourced from /api/design-templates and shown in the
  // EntryView Templates tab. See specs/current/skills-and-design-templates.md.
  const [designTemplates, setDesignTemplates] = useState<SkillSummary[]>([]);
  const [designSystems, setDesignSystems] = useState<DesignSystemSummary[]>([]);
  const [pendingDesignSystemRevisionJobs, setPendingDesignSystemRevisionJobs] = useState<
    Record<string, DesignSystemGenerationJob>
  >({});
  const [projects, setProjects] = useState<Project[]>([]);
  const projectsRef = useRef<Project[]>(projects);
  useEffect(() => {
    projectsRef.current = projects;
  }, [projects]);
  // Project names from another member's team-catalog row are authoritative:
  // the local mirror can carry an older real name (not only "共享项目") with a
  // newer local timestamp. Scope keys prevent a project id observed in one
  // workspace/member context from leaking its title authority into another.
  const [authoritativeProjectNames, setAuthoritativeProjectNames] = useState<
    Record<string, string>
  >({});
  const authoritativeProjectNamesRef = useRef(authoritativeProjectNames);
  authoritativeProjectNamesRef.current = authoritativeProjectNames;
  const projectNameAuthorityRequestGenerationRef = useRef<Map<string, number>>(new Map());
  const [petTaskCenter, setPetTaskCenter] = useState<PetTaskCenter>({
    running: [],
    queued: [],
    recent: [],
  });
  const pendingLocalProjectIdsRef = useRef<Set<string>>(new Set());
  const pendingLocalProjectScopeRef = useRef(projectListScopeKey(workspaceContext));
  const currentProjectListScope = projectListScopeKey(workspaceContext);
  const projectAuthorizationScopeRef = useRef(currentProjectListScope);
  const projectAuthorizationGenerationRef = useRef(0);
  if (projectAuthorizationScopeRef.current !== currentProjectListScope) {
    projectAuthorizationScopeRef.current = currentProjectListScope;
    projectAuthorizationGenerationRef.current += 1;
  }
  if (pendingLocalProjectScopeRef.current !== currentProjectListScope) {
    pendingLocalProjectScopeRef.current = currentProjectListScope;
    pendingLocalProjectIdsRef.current.clear();
  }
  const locallyDeletedProjectIdsRef = useRef<Map<string, number>>(new Map());
  const projectListMutationVersionRef = useRef(0);
  const projectListRequestGenerationRef = useRef(0);
  const latestAppliedProjectListGenerationRef = useRef(0);
  const [templates, setTemplates] = useState<ProjectTemplate[]>([]);
  const [promptTemplates, setPromptTemplates] = useState<
    PromptTemplateSummary[]
  >([]);
  const [appVersionInfo, setAppVersionInfo] = useState<AppVersionInfo | null>(
    null,
  );
  const [daemonMediaProviders, setDaemonMediaProviders] = useState<
    AppConfig['mediaProviders'] | null
  >(null);
  const [daemonMediaProvidersFetchState, setDaemonMediaProvidersFetchState] = useState<
    'idle' | 'ok' | 'error'
  >('idle');
  const [mediaProvidersNotice, setMediaProvidersNotice] = useState<string | null>(null);
  // Per-resource loading flags. Each goes false the moment its own fetch
  // resolves so each entry-view tab can render as its data lands instead of
  // every tab waiting on the slowest endpoint (typically `/api/agents`,
  // which probes CLI versions and can take seconds on cold start). The entry
  // view picks the right flag for whichever tab the user is currently on.
  const [agentsLoading, setAgentsLoading] = useState(true);
  const [skillsLoading, setSkillsLoading] = useState(true);
  // Functional skills and design templates are two independent registry reads
  // that gate ONE loader: the EntryView must not stop spinning until both have
  // answered, or whichever tab the user is on renders an incomplete catalog as
  // if it were final. They are now read from two different places (the boot pass
  // reads templates; the workspace-keyed effect reads skills once the caller's
  // identity is known), so the pair of flags lives here rather than inside one
  // effect's closure.
  const skillRegistriesReadyRef = useRef({ functional: false, templates: false });
  const markSkillRegistryReady = useCallback((half: 'functional' | 'templates') => {
    skillRegistriesReadyRef.current[half] = true;
    const { functional, templates } = skillRegistriesReadyRef.current;
    if (functional && templates) setSkillsLoading(false);
  }, []);
  const [dsLoading, setDsLoading] = useState(true);
  const [projectsLoading, setProjectsLoading] = useState(true);
  // A loaded project list describes exactly ONE workspace identity, so leaving
  // that workspace INVALIDATES it — it does not merely make it stale.
  //
  // Everything downstream of `projects` (the home 最近项目 strip, the 全部项目 and
  // 草稿 grids) renders whatever this array holds, and the re-list on switch is
  // an effect: effects run after the commit, so the browser paints the previous
  // workspace's cards under the new workspace's identity first and only swaps
  // them when the new list lands. That is the reported 「总是要慢一拍」 — the
  // strip presenting one workspace's projects as another's, which is worse than
  // showing nothing. Dropping the list here, during the render that first
  // observes the new scope, means no frame ever shows the wrong workspace's
  // data. (`reconcileFetchedProjects` already refuses to APPLY a response whose
  // scope has moved on; the missing half was discarding what is already on
  // screen.)
  //
  // Nothing is refetched: the switch effect below owns that, and its request is
  // already keyed on the resolved workspace, so this is not a backend problem
  // and needs no extra round-trip.
  const projectListScopeRef = useRef(currentProjectListScope);
  if (projectListScopeRef.current !== currentProjectListScope) {
    const leftAResolvedWorkspace =
      projectListScopeRef.current !== UNRESOLVED_PROJECT_LIST_SCOPE;
    projectListScopeRef.current = currentProjectListScope;
    if (leftAResolvedWorkspace) {
      setProjects([]);
      setProjectsLoading(true);
    }
  }
  const [promptTemplatesLoading, setPromptTemplatesLoading] = useState(true);
  // Goes true once the daemon-persisted config (agentId/designSystemId/etc.)
  // has merged into local state. Auto-selection effects below wait on this
  // so they don't race ahead of the daemon-stored choice and overwrite it
  // with a freshly picked first-available agent.
  const [daemonConfigLoaded, setDaemonConfigLoaded] = useState(false);
  // Narrower flag dedicated to the Composio API key hydration. The key is
  // persisted by the daemon (and only reflected back via apiKeyConfigured
  // + apiKeyTail), so after a dev-server restart there is a window where
  // the dialog can render an empty Composio input even though a saved key
  // exists. Settings → Connectors uses this to render a skeleton over the
  // input + buttons instead of an empty input that the user might
  // mistake for "no key saved" — and to disable Save/Clear so a misclick
  // can't overwrite the saved state with `''` before hydration lands.
  const [composioConfigLoading, setComposioConfigLoading] = useState(true);
  const route = useRoute();
  const workspaceProjectView = workspaceProjectListViewForRoute(route);
  // Read-only mirror for the boot effect. The boot pass needs to know which
  // project list to seed, but it must NOT restart when that answer changes:
  // see the "boot is a one-shot" note on the bootstrap effect below. A
  // dedicated effect already re-lists projects whenever the view or the
  // workspace changes, so nothing is lost by the boot pass not reacting.
  const workspaceProjectViewRef = useRef(workspaceProjectView);
  workspaceProjectViewRef.current = workspaceProjectView;
  // `listCurrentWorkspaceProjects` already collapses `workspaceView` to
  // `undefined` when there is no resolved `workspaceContext` (see its
  // `context ? options?.workspaceView ?? 'recent' : undefined` above), so the
  // request it sends never actually varies by home tab outside a workspace.
  // But the raw route-derived `workspaceProjectView` still changes string
  // value on every 最近/全部/草稿 tab switch, and that alone is enough to
  // re-run the effect below (dependency arrays compare the value passed in,
  // not what the callback does with it) — re-fetching the identical list on
  // every click. Mirror the callback's own collapse here so the effect's
  // dependency is stable outside a workspace, matching the fetch it triggers.
  const effectiveWorkspaceProjectView = workspaceContext ? workspaceProjectView : undefined;
  const projectScopeRefreshMountedRef = useRef(false);
  const analytics = useAnalytics();

  // Single-flight guard for `/api/agents?stream=1`: beginning a new request
  // physically aborts the previous stream, not just invalidates its
  // callbacks. Stacked live streams are what deadlocked the packaged app —
  // each navigation/focus refresh opened another slow cold-probe stream,
  // and once they pinned every upstream connection slot the whole od://
  // proxy starved (see apps/packaged/src/index.ts ignore-connections-limit
  // note for the other half of that fix).
  const beginAgentStreamRequest = useCallback(() => {
    agentStreamAbortRef.current?.abort();
    agentStreamAbortRef.current = new AbortController();
    agentStreamRequestSeqRef.current += 1;
    return agentStreamRequestSeqRef.current;
  }, []);

  const isCurrentAgentStreamRequest = useCallback((requestId: number) => {
    return agentStreamRequestSeqRef.current === requestId;
  }, []);

  const restartAmrPolling = useCallback(() => {
    amrPollGenerationRef.current += 1;
    setAmrPollRestartToken((current) => current + 1);
  }, []);

  // v2 schema removed the standalone `app_launch` event; the initial
  // page_view fires from each top-level page surface (home / projects /
  // automations / plugins / design_systems / integrations) instead.
  // `detectClientType` still feeds analytics identity via the provider.
  void detectClientType;

  const rememberLocalProject = useCallback((projectId: string) => {
    pendingLocalProjectIdsRef.current.add(projectId);
    locallyDeletedProjectIdsRef.current.delete(projectId);
    projectListMutationVersionRef.current += 1;
  }, []);

  const handleTeamProjectContentReady = useCallback(async (
    projectId: string,
    workspaceId: string,
    workspaceMemberId: string,
  ): Promise<boolean> => {
    if (workspaceContextRef.current?.workspaceMemberId !== workspaceMemberId) {
      return false;
    }
    const project = await hydrateReadyTeamProject(projectId, workspaceId, {
      getWorkspaceContext: () => workspaceContextRef.current,
      listWorkspaceProjects: (context) =>
        listWorkspaceProjectSummaries({
          context,
          workspaceView: 'team',
          throwOnError: true,
        }),
      applyProject: (project) => {
        rememberLocalProject(projectId);
        setProjects((current) => [
          project,
          ...current.filter((candidate) => candidate.id !== projectId),
        ]);
      },
    });
    return project != null;
  }, [rememberLocalProject]);

  const clearLocalProject = useCallback((projectId: string, options?: { deleted?: boolean }) => {
    pendingLocalProjectIdsRef.current.delete(projectId);
    projectListMutationVersionRef.current += 1;
    if (options?.deleted) {
      locallyDeletedProjectIdsRef.current.set(
        projectId,
        projectListMutationVersionRef.current,
      );
    }
  }, []);

  const beginProjectListRequest = useCallback((): ProjectListRequest => {
    projectListRequestGenerationRef.current += 1;
    return {
      generation: projectListRequestGenerationRef.current,
      mutationVersion: projectListMutationVersionRef.current,
      scopeKey: projectListScopeKey(workspaceContextRef.current),
    };
  }, []);

  const reconcileFetchedProjects = useCallback((list: Project[], request: ProjectListRequest) => {
    if (request.scopeKey !== projectListScopeKey(workspaceContextRef.current)) {
      return false;
    }
    const pendingLocalProjectIds = pendingLocalProjectIdsRef.current;
    const locallyDeletedProjectIds = locallyDeletedProjectIdsRef.current;
    const fetchedIds = new Set(list.map((project) => project.id));
    if (request.generation < latestAppliedProjectListGenerationRef.current) {
      const visibleList =
        locallyDeletedProjectIds.size > 0
          ? list.filter((project) => !locallyDeletedProjectIds.has(project.id))
          : list;
      if (visibleList.length === 0) return false;
      const hydratableProjects = visibleList.filter(
        (project) =>
          pendingLocalProjectIds.has(project.id),
      );
      if (hydratableProjects.length === 0) return false;
      const hydratableById = new Map(
        hydratableProjects.map((project) => [project.id, project]),
      );
      for (const project of hydratableProjects) {
        pendingLocalProjectIds.delete(project.id);
      }
      setProjects((current) => {
        let changed = false;
        const currentIds = new Set<string>();
        const next = current.map((project) => {
          currentIds.add(project.id);
          const hydrated = hydratableById.get(project.id);
          if (!hydrated) return project;
          changed = true;
          hydratableById.delete(project.id);
          return hydrated;
        });
        for (const project of hydratableById.values()) {
          if (currentIds.has(project.id)) continue;
          changed = true;
          next.push(project);
        }
        return changed ? next : current;
      });
      return true;
    }
    latestAppliedProjectListGenerationRef.current = request.generation;
    for (const id of fetchedIds) pendingLocalProjectIds.delete(id);
    for (const [id, deletedAtMutationVersion] of locallyDeletedProjectIds) {
      if (
        request.mutationVersion >= deletedAtMutationVersion
        && !fetchedIds.has(id)
      ) {
        locallyDeletedProjectIds.delete(id);
      }
    }
    const activeDeletedProjectIds = new Set(locallyDeletedProjectIds.keys());
    const visibleList =
      activeDeletedProjectIds.size > 0
        ? list.filter((project) => !activeDeletedProjectIds.has(project.id))
        : list;
    const visibleFetchedIds =
      activeDeletedProjectIds.size > 0
        ? new Set(visibleList.map((project) => project.id))
        : fetchedIds;
    setProjects((current) => {
      const preserved = current.filter(
        (project) =>
          pendingLocalProjectIds.has(project.id) &&
          !visibleFetchedIds.has(project.id) &&
          !activeDeletedProjectIds.has(project.id),
      );
      return preserved.length > 0 ? [...preserved, ...visibleList] : visibleList;
    });
    return true;
  }, []);

  // Propagate the Privacy toggle through to PostHog without a reload —
  // posthog-js's opt_out_capturing flips a localStorage flag that makes
  // every subsequent capture() a no-op. When the user opts back in we
  // call opt_in_capturing to resume.
  useEffect(() => {
    analytics.setConsent(config.telemetry?.metrics === true);
  }, [analytics.setConsent, config.telemetry?.metrics]);

  // Sync PostHog's distinct_id with the anonymous installationId, both on
  // first opt-in (when the daemon stamps a fresh id) and on Delete-my-data
  // rotation (when PrivacySection.tsx generates a new one). posthog-js
  // caches the previous id in localStorage; identify() alone would stitch
  // the two ids together, so applyIdentity() does reset() first to
  // guarantee the new session is fully decoupled from the deleted one.
  useEffect(() => {
    if (config.telemetry?.metrics !== true) return;
    analytics.setIdentity(config.installationId ?? null);
  }, [analytics.setIdentity, config.installationId, config.telemetry?.metrics]);

  // App-level AMR sign-in state — declared here because the configure
  // globals effect below reads it; the sync effects live next to the
  // other AMR plumbing further down.
  const [amrLoginStatus, setAmrLoginStatus] = useState<VelaLoginStatus | null>(null);
  // The plan that gates free-tier surfaces (today: the post-generation artifact
  // upsell). vela's login status is ACCOUNT-scoped, so a member whose plan is
  // held by the team workspace reads `free` there and used to be shown the
  // free-user banner; the workspace context's plan id is authoritative and
  // wins. See resolvePlanTier for the full precedence rule.
  const resolvedAmrPlan = resolvePlanTier({
    billing: workspaceBilling,
    context: workspaceContext,
    accountPlan:
      workspaceContextLoading || workspaceContext?.workspaceType === 'team'
        ? null
        : amrLoginStatus?.account?.plan?.trim()
          || amrLoginStatus?.user?.plan?.trim()
          || null,
  });
  // Child surfaces report status snapshots, not login events. Deduplicate the
  // signed-in transition here: restarting the model poll for every Settings
  // snapshot updates `agents`, which makes Settings fetch status again and
  // creates a status -> models -> agents request loop.
  const amrLoginStatusRef = useRef<VelaLoginStatus | null>(null);
  const applyAmrLoginStatus = useCallback((
    status: VelaLoginStatus,
    options: { forceModelRefresh?: boolean; restartOnSignIn?: boolean } = {},
  ) => {
    const wasLoggedIn = amrLoginStatusRef.current?.loggedIn === true;
    amrLoginStatusRef.current = status;
    setAmrLoginStatus(status);
    if (
      status.loggedIn === true
      && (
        options.forceModelRefresh === true
        || (options.restartOnSignIn === true && !wasLoggedIn)
      )
    ) {
      restartAmrPolling();
    }
  }, [restartAmrPolling]);

  // Tab-scope identity key, fed to WorkspaceTabsBar so it can close every open
  // tab down to a single fresh Home tab whenever the caller's identity
  // changes — signing out, signing in as a different account, switching
  // workspace, or simply never having signed into AMR at all are each their
  // own scope, and a tab opened under one must not silently keep pointing at
  // a project/section the next identity has no standing to see (see
  // WorkspaceTabsBar's own doc, and deriveTabIdentityScope's, for the full
  // design rationale — notably why the workspace half of the key LATCHES
  // across a null `workspaceContext` instead of reacting to it directly, and
  // why `workspaceContextLoading` must ride along: on every fresh boot
  // (first load OR a plain refresh) `amrLoginStatus` and `workspaceContext`
  // resolve on independent timers, and without the loading flag the
  // in-between "logged in, workspace context not landed yet" tick reads as a
  // confirmed no-workspace baseline — so the real workspace context landing a
  // beat later looks exactly like a workspace switch and bounces a team
  // member's own deep-linked/refreshed project back to Home).
  const tabScopeWorkspaceIdRef = useRef<string>('none');
  const tabScopeAccountIdRef = useRef<string>(UNSET_ACCOUNT_BUCKET);
  const {
    scopeKey: identityScopeKey,
    nextWorkspaceBucket: nextTabScopeWorkspaceId,
    nextAccountBucket: nextTabScopeAccountId,
  } = deriveTabIdentityScope({
    amrLoginStatus,
    workspaceContext,
    workspaceContextLoading,
    previousWorkspaceBucket: tabScopeWorkspaceIdRef.current,
    previousAccountBucket: tabScopeAccountIdRef.current,
  });
  tabScopeWorkspaceIdRef.current = nextTabScopeWorkspaceId;
  tabScopeAccountIdRef.current = nextTabScopeAccountId;

  // v2 analytics requires every event to carry the configure-state
  // triplet (has_available_configure_cli / configure_type /
  // configure_availability). We push it into the PostHog global register
  // whenever the user's execution-mode config or the detected agent list
  // changes; the next capture inherits the fresh values, so dashboards
  // can segment by execution setup without per-helper boilerplate.
  //
  // Gated on `agentsLoading` so the cold-start probe (`fetchAgentsStream()`
  // lands asynchronously after this effect's first run) does not stamp
  // the first home/projects/plugins page_view with
  // has_available_configure_cli=false / configure_availability=unavailable
  // on machines that DO have an installed CLI. While the probe is in
  // flight we leave the boot defaults ('unknown'/'unknown') in place,
  // matching what the helper would return for an empty agent list with
  // no mode pinned.
  useEffect(() => {
    if (agentsLoading) return;
    const byokConfigured = (() => {
      const protocols = config.apiProtocolConfigs;
      if (!protocols) return Boolean(config.apiKey?.trim());
      return Object.values(protocols).some(
        (cfg) => Boolean(cfg?.apiKey?.trim()),
      );
    })();
    const globals = deriveConfigureGlobals({
      mode: config.mode,
      agentId: config.agentId,
      agents: agents.map((a) => ({ id: a.id, available: a.available })),
      byokConfigured,
      amrAuthorized: amrLoginStatus?.loggedIn === true,
    });
    analytics.setConfigureGlobals(globals);
  }, [
    analytics.setConfigureGlobals,
    agentsLoading,
    amrLoginStatus,
    config.mode,
    config.agentId,
    config.apiKey,
    config.apiProtocolConfigs,
    agents,
  ]);

  // Stamp the app appearance onto the <html> element so CSS variables pick it
  // up. The theme itself is a constant (light-only), but the accent still comes
  // from config, and the stamp must be re-applied whenever that changes.
  // useLayoutEffect (vs useEffect) fires before the browser paints, so no
  // 1-frame flash. Safe here because the component tree is ssr:false.
  useLayoutEffect(() => {
    applyAppearanceToDocument({ accentColor: config.accentColor });
  }, [config.accentColor]);

  // Tell the daemon what the user is currently looking at, so the MCP
  // server can surface it as `get_active_context` to a coding agent in
  // another repo. Best-effort fire-and-forget; the daemon holds it in
  // memory with a short TTL and the MCP layer falls back to
  // {active:false} if this hasn't run.
  const activeProjectId = route.kind === 'project' ? route.projectId : null;
  const activeFileName = route.kind === 'project' ? route.fileName : null;
  // While a project route is active, background home-surface thumbnail
  // documents must not compete with the project's own foreground reads; the
  // card-click handler suspends the gate synchronously and this effect keeps
  // it authoritative for every other entry path (deep links, quick switcher)
  // and resumes it when the user returns home (Batch A §4.2).
  useEffect(() => {
    if (route.kind === 'project') suspendThumbnailLoads();
    else resumeThumbnailLoads();
  }, [route.kind]);
  // Gate the privacy banner on three things:
  //   1. Daemon config has hydrated (privacyDecisionAt is daemon-owned).
  //   2. The user has not yet made a privacy decision.
  //   3. Onboarding is complete (Skip and design-system creation both flip
  //      onboardingCompleted to true; see handleCompleteOnboarding wiring).
  // Once onboarding is done the banner is allowed on any route — including
  // the project view the design-system finish path drops the user into, so
  // they can read and acknowledge the disclosure while the first generation
  // is running. Settings is irrelevant to visibility; the banner sits above
  // the modal-backdrop layer in index.css so opening Settings does not hide
  // it.
  const showPrivacyConsent =
    daemonConfigLoaded &&
    config.privacyDecisionAt == null &&
    config.onboardingCompleted === true;
  useEffect(() => {
    const body = activeProjectId
      ? { projectId: activeProjectId, fileName: activeFileName }
      : { active: false };
    fetch('/api/active', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    }).catch(() => {
      // Daemon down or transient network — not worth surfacing.
    });
  }, [activeProjectId, activeFileName]);

  useEffect(() => {
    if (!daemonLive) return;
    let cancelled = false;
    let timer: number | null = null;
    const pollGeneration = amrPollGenerationRef.current + 1;
    amrPollGenerationRef.current = pollGeneration;
    const pollDelayMs = 1_000;
    const maxPresetPolls = 10;
    let presetPolls = 0;

    const applyAmrModels = async () => {
      const result = await fetchAmrModels();
      if (
        cancelled ||
        amrPollGenerationRef.current !== pollGeneration ||
        !result ||
        !Array.isArray(result.models) ||
        result.models.length === 0
      ) {
        return;
      }
      amrModelsRef.current = result;
      setAgents((current) => mergeAmrModelsIntoAgents(current, result));
      const shouldPollPreset =
        result.source === 'preset' &&
        !result.remoteError &&
        presetPolls < maxPresetPolls;
      if (shouldPollPreset) {
        presetPolls += 1;
        timer = window.setTimeout(() => {
          void applyAmrModels();
        }, pollDelayMs);
      }
    };

    void applyAmrModels();
    return () => {
      cancelled = true;
      if (timer !== null) window.clearTimeout(timer);
    };
  }, [amrPollRestartToken, daemonLive]);

  // App-level AMR sign-in state. Feeds two analytics globals: the
  // `amr` configure_type bucket (deriveConfigureGlobals below) and the
  // `user_id` public param (the AMR account id is the only join key
  // between this PostHog project and the AMR-side one). Child surfaces
  // push status changes up via onAmrLoginStatusChange; the global
  // AMR_LOGIN_STATUS_EVENT covers logins finishing in surfaces that
  // unmounted before their poll settled.
  useEffect(() => {
    let cancelled = false;
    const sync = async (
      options: { refresh?: boolean } = {},
      restartOnSignIn = false,
    ) => {
      const status = await fetchVelaLoginStatus(options);
      if (!cancelled && status) {
        applyAmrLoginStatus(status, {
          forceModelRefresh: options.refresh === true,
          restartOnSignIn,
        });
      }
    };
    void sync();
    const onStatusEvent = () => {
      void sync({}, true);
    };
    const onReturnToApp = () => {
      if (document.visibilityState === 'hidden') return;
      void sync({ refresh: true });
    };
    window.addEventListener(AMR_LOGIN_STATUS_EVENT, onStatusEvent);
    window.addEventListener('focus', onReturnToApp);
    document.addEventListener('visibilitychange', onReturnToApp);
    return () => {
      cancelled = true;
      window.removeEventListener(AMR_LOGIN_STATUS_EVENT, onStatusEvent);
      window.removeEventListener('focus', onReturnToApp);
      document.removeEventListener('visibilitychange', onReturnToApp);
    };
  }, [applyAmrLoginStatus, daemonLive]);

  useEffect(() => {
    analytics.setUserId(
      amrLoginStatus?.loggedIn === true ? amrLoginStatus.user?.id ?? null : null,
    );
  }, [analytics.setUserId, amrLoginStatus]);

  const handleAmrLoginStatusChange = useCallback((status: VelaLoginStatus | null) => {
    if (status) applyAmrLoginStatus(status, { restartOnSignIn: true });
  }, [applyAmrLoginStatus]);

  // Bootstrap — detect daemon, then fan out independent fetches so each
  // entry-view tab can render the moment its own data lands. Earlier this
  // was one Promise.all behind a global "Loading workspace…" placeholder,
  // which made the slowest endpoint (typically `/api/agents` on cold start)
  // gate every tab including the ones that don't need agents at all.
  //
  // Boot is a ONE-SHOT: every dependency below is a stable callback, so this
  // runs once per app launch and never again. That is load-bearing, not
  // incidental — this pass owns the first-run onboarding routing decision and
  // rewrites the merged config back to localStorage + the daemon. Re-running it
  // on navigation replays both: a user is re-judged against a config read that
  // may lag their own completion, and gets bounced into the first-run flow they
  // already finished. Anything route- or workspace-derived that boot needs must
  // be read through a ref (see `workspaceProjectViewRef`), and anything that
  // must react to those changes belongs in its own effect.
  useEffect(() => {
    let cancelled = false;
    let effectAgentStreamAbort: AbortController | null = null;
    (async () => {
      const alive = await daemonIsLive();
      if (cancelled) return;
      setDaemonLive(alive);
      if (!alive) {
        // No daemon — clear every loading flag so empty states render
        // instead of the entry view sitting on indefinite spinners.
        setAgentsLoading(false);
        setSkillsLoading(false);
        setDsLoading(false);
        setProjectsLoading(false);
        setPromptTemplatesLoading(false);
        setDaemonConfigLoaded(true);
        // Composio hydration also depends on the daemon. With no daemon
        // we just keep whatever localStorage already held; drop the
        // skeleton so the Settings → Connectors input reflects state.
        setComposioConfigLoading(false);
        return;
      }

      const agentRequestId = beginAgentStreamRequest();
      effectAgentStreamAbort = agentStreamAbortRef.current;
      void fetchAgentsStream({
        signal: effectAgentStreamAbort?.signal,
        onAgent: (agent) => {
          if (cancelled || !isCurrentAgentStreamRequest(agentRequestId)) return;
          setAgents((current) =>
            mergeAmrModelsIntoAgents(
              upsertAgent(current, agent),
              amrModelsRef.current,
            ),
          );
        },
      })
        .then((list) => {
          if (cancelled || !isCurrentAgentStreamRequest(agentRequestId)) return;
          setAgents(
            mergeAmrModelsIntoAgents(
              orderAgentsByRegistry(list),
              amrModelsRef.current,
            ),
          );
        })
        .catch((err) => {
          if (
            cancelled ||
            isAbortError(err) ||
            !isCurrentAgentStreamRequest(agentRequestId)
          ) {
            return;
          }
          setAgents([]);
        })
        .finally(() => {
          if (cancelled || !isCurrentAgentStreamRequest(agentRequestId)) return;
          setAgentsLoading(false);
        });

      // Functional skills + design templates land independently. Both
      // gate `skillsLoading` together so the EntryView stops rendering
      // its loader once both registries respond — neither tab would have
      // a complete picture if we cleared the flag on the first reply.
      //
      // Only the TEMPLATE half is read here. Functional skills are
      // workspace-scoped on the daemon and must carry the caller's identity
      // headers, which do not exist until `/api/workspace/context` settles —
      // so that read belongs to the workspace-keyed effect below, which owns
      // the `functional` half of this gate. Reading it here as well would
      // spend a second `/api/skills` request per launch, and the first one
      // would be the headerless (fail-closed) answer.
      void fetchDesignTemplates().then((list) => {
        if (cancelled) return;
        setDesignTemplates(list);
        markSkillRegistryReady('templates');
      });

      const designSystemsWorkspaceId = workspaceContextRef.current?.workspaceId ?? null;
      void fetchDesignSystems().then((list) => {
        if (
          cancelled ||
          (workspaceContextRef.current?.workspaceId ?? null) !== designSystemsWorkspaceId
        ) return;
        setDesignSystems(list);
        setDsLoading(false);
      });

      const request = beginProjectListRequest();
      void listCurrentWorkspaceProjects({
        workspaceView: workspaceProjectViewRef.current,
      }).then((list) => {
        if (cancelled) return;
        reconcileFetchedProjects(list, request);
        setProjectsLoading(false);
      });

      void listTemplates().then((list) => {
        if (cancelled) return;
        setTemplates(list);
      });

      void fetchPromptTemplates().then((list) => {
        if (cancelled) return;
        setPromptTemplates(list);
        setPromptTemplatesLoading(false);
      });

      void fetchAppVersionInfo().then((info) => {
        if (cancelled) return;
        setAppVersionInfo(info);
      });

      // Daemon-persisted config + composio config + media provider config land
      // together so the welcome-modal decision and daemon-backed settings
      // apply in one merge, avoiding a flash where local-only state is shown
      // before daemon overrides it.
      void Promise.all([
        fetchDaemonConfig(),
        fetchComposioConfigFromDaemon(),
        fetchMediaProvidersFromDaemon(),
      ]).then(([
        daemonConfig,
        daemonComposioConfig,
        daemonMediaProvidersResult,
      ]) => {
        if (cancelled) return;
        const daemonMediaProvidersLoaded =
          daemonMediaProvidersResult.status === 'ok'
            ? daemonMediaProvidersResult.providers
            : null;
        setDaemonMediaProviders(daemonMediaProvidersLoaded);
        setDaemonMediaProvidersFetchState(daemonMediaProvidersResult.status);
        setMediaProvidersNotice(
          daemonMediaProvidersResult.status === 'error'
            ? t('settings.mediaProviderLoadError')
            : null,
        );
        // Compute the next config outside the setConfig updater so we can
        // both (a) call navigate() after setConfig returns — calling it
        // inside the updater would trigger a Router setState during React's
        // render phase — and (b) read next.onboardingCompleted synchronously,
        // since React batches setConfig and the updater doesn't run until
        // the next render. latestPersistedConfigRef is kept in sync with
        // the rendered config and is safe to read here.
        const baseConfig = latestPersistedConfigRef.current;
        const migratedLocalMediaProviders = shouldSyncLocalMediaProvidersToDaemon(
          baseConfig.mediaProviders,
          daemonMediaProvidersLoaded,
        );
        const next = mergeDaemonMediaProviders(
          clearStaleAmrModelChoiceOnProfileChange(
            baseConfig,
            mergeDaemonConfig(baseConfig, daemonConfig),
          ),
          daemonMediaProvidersLoaded,
        );
        const hasLocalComposioKey = Boolean(next.composio?.apiKey?.trim());
        if (!hasLocalComposioKey && daemonComposioConfig) {
          next.composio = daemonComposioConfig;
        }
        saveConfig(next);
        if (
          daemonMediaProvidersResult.status === 'ok' &&
          migratedLocalMediaProviders &&
          hasAnyConfiguredProvider(next.mediaProviders)
        ) {
          void syncMediaProvidersToDaemon(next.mediaProviders, {
            daemonProviders: daemonMediaProvidersLoaded,
          });
        }
        // Migrate localStorage prefs to daemon on first boot with the new
        // endpoint. If daemon already had values the merge above used them;
        // writing back is idempotent and keeps both sides in sync.
        void syncConfigToDaemon(next);
        void syncComposioConfigToDaemon(next.composio);
        latestPersistedConfigRef.current = next;
        setConfig(next);

        // Route first-run users through the global onboarding panel.
        // The onboarding panel and the privacy banner have independent
        // lifecycles: onboarding keys off `onboardingCompleted`, the
        // banner keys off `privacyDecisionAt`. They may coexist on the
        // first launch; the banner sits above the modal layer so it
        // stays actionable regardless of the active view.
        if (shouldRouteToFirstRunOnboarding(next, window.location.pathname)) {
          navigate({ kind: 'home', view: 'onboarding' }, { replace: true });
        }
        setDaemonConfigLoaded(true);
        // Composio key hydration is part of this same daemon-config
        // fetch — by the time we land here the daemon has either
        // returned the saved-key shape (apiKeyConfigured + tail) or
        // it errored and we kept whatever localStorage held. Either
        // way it is safe to drop the skeleton.
        setComposioConfigLoading(false);
      });
    })();
    return () => {
      cancelled = true;
      effectAgentStreamAbort?.abort();
    };
    // `workspaceProjectView` is intentionally absent: it is route-derived, and
    // depending on it would turn this one-shot boot pass into a per-navigation
    // one. It is read through `workspaceProjectViewRef` instead.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [
    beginAgentStreamRequest,
    beginProjectListRequest,
    isCurrentAgentStreamRequest,
    listCurrentWorkspaceProjects,
    reconcileFetchedProjects,
  ]);

  // Auto-pick the first available agent once both the daemon-stored config
  // and the agents listing have landed. Splitting this out of bootstrap
  // avoids racing the local-config initial value against a slow agents
  // probe — by the time this runs, daemonConfig has already overlaid the
  // user's previous choice, so we only fill an empty slot.
  //
  // First-run onboarding is the one time we must NOT do this: the onboarding
  // flow is the sole authority for the initial agent pick (AMR is the
  // recommended default there), and AMR (vela) detection is asynchronous. If
  // this fallback fires during onboarding while AMR is still being detected it
  // snaps the slot to the registry-first *detected* agent (Claude) and
  // persists it to the daemon, which then races and clobbers the user's AMR
  // selection on the next launch. Gate on onboardingCompleted so this only
  // backfills an empty slot for returning users.
  useEffect(() => {
    if (!daemonConfigLoaded || agentsLoading) return;
    if (config.onboardingCompleted !== true) return;
    if (config.agentId) return;
    const firstAvailable = agents.find((a) => a.available);
    if (!firstAvailable) return;
    setConfig((prev) => {
      if (prev.agentId) return prev;
      const next: AppConfig = { ...prev, agentId: firstAvailable.id };
      saveConfig(next);
      void syncConfigToDaemon(next);
      return next;
    });
  }, [
    daemonConfigLoaded,
    agentsLoading,
    agents,
    config.agentId,
    config.onboardingCompleted,
  ]);

  // Auto-pick the default design system the same way — only after daemon
  // config has merged so we never overwrite a daemon-stored selection.
  useEffect(() => {
    if (!daemonConfigLoaded || dsLoading) return;
    if (config.designSystemId) return;
    if (designSystems.length === 0) return;
    const id =
      designSystems.find((d) => d.id === 'default')?.id ?? designSystems[0]!.id;
    setConfig((prev) => {
      if (prev.designSystemId) return prev;
      const next: AppConfig = { ...prev, designSystemId: id };
      saveConfig(next);
      void syncConfigToDaemon(next);
      return next;
    });
  }, [daemonConfigLoaded, dsLoading, designSystems, config.designSystemId]);

  // One-shot self-healing migration for pets adopted before the
  // overlay learned atlas-row switching. If the stored pet is a
  // custom / codex pet whose imageUrl is a single-row strip
  // (no atlas), we silently re-download the full spritesheet so
  // hover, drag, and idle-ambient variety all light up on next render.
  useEffect(() => {
    let cancelled = false;
    void (async () => {
      const upgraded = await migrateCustomPetAtlas(config);
      if (!upgraded || cancelled) return;
      setConfig((prev) => {
        if (!prev.pet) return prev;
        const next: AppConfig = {
          ...prev,
          pet: { ...prev.pet, custom: upgraded },
        };
        saveConfig(next);
        return next;
      });
    })();
    return () => {
      cancelled = true;
    };
    // Snapshot the config at mount; migration is one-shot per session
    // and should not re-run every time config changes.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  const refreshProjects = useCallback(async () => {
    const request = beginProjectListRequest();
    const list = await listCurrentWorkspaceProjects({ workspaceView: workspaceProjectView });
    reconcileFetchedProjects(list, request);
  }, [beginProjectListRequest, listCurrentWorkspaceProjects, reconcileFetchedProjects, workspaceProjectView]);

  const refreshProjectsStrict = useCallback(async () => {
    const request = beginProjectListRequest();
    const list = await listCurrentWorkspaceProjects({
      throwOnError: true,
      workspaceView: workspaceProjectView,
    });
    reconcileFetchedProjects(list, request);
  }, [beginProjectListRequest, listCurrentWorkspaceProjects, reconcileFetchedProjects, workspaceProjectView]);

  useEffect(() => {
    // Bootstrap already reads this exact scope on mount. Only re-list after
    // the resolved workspace identity or a workspace-specific route changes;
    // local navigation does not alter the unscoped project catalogue.
    if (!projectScopeRefreshMountedRef.current) {
      projectScopeRefreshMountedRef.current = true;
      return;
    }
    let cancelled = false;
    const request = beginProjectListRequest();
    setProjectsLoading(true);
    (async () => {
      for (let attempt = 0; attempt < 2; attempt++) {
        try {
          const list = await listCurrentWorkspaceProjects({
            throwOnError: true,
            workspaceView: effectiveWorkspaceProjectView,
          });
          if (!cancelled) reconcileFetchedProjects(list, request);
          return;
        } catch (err) {
          if (cancelled) return;
          if (attempt === 0) {
            // Switching into a team workspace can race the daemon's remote
            // team-project-catalog session warming up for it (recvqaeREM6pdv:
            // a transient 502 here used to be silently downgraded to an empty
            // list, which HomeView cannot tell apart from a genuinely empty
            // workspace and renders as the first-run empty state). Retry once
            // before giving up instead of reconciling a failure as "no
            // projects".
            await new Promise((resolve) => setTimeout(resolve, 1200));
            continue;
          }
          console.error('[projects] failed to refresh after workspace switch', err);
        }
      }
    })().finally(() => {
      if (!cancelled) setProjectsLoading(false);
    });
    return () => {
      cancelled = true;
    };
  }, [
    workspaceContext?.workspaceId,
    beginProjectListRequest,
    effectiveWorkspaceProjectView,
    listCurrentWorkspaceProjects,
    reconcileFetchedProjects,
  ]);

  const refreshDesignSystems = useCallback(async () => {
    // `fetchDesignSystems()` takes no context — the daemon resolves the scope
    // from its OWN vela session (`resolveWorkspaceScope`), not from request
    // headers. The catalog itself is keyed only by workspaceId, so the commit
    // guard deliberately uses that SAME scope: role/member/permission changes
    // must not discard a still-valid response without scheduling a successor.
    // A slow read for a different workspace still cannot restore its library.
    const issuedWorkspaceId = workspaceContextRef.current?.workspaceId ?? null;
    const list = await fetchDesignSystems();
    if ((workspaceContextRef.current?.workspaceId ?? null) !== issuedWorkspaceId) return;
    setDesignSystems(list);
    // Bootstrap and this workspace-scoped refresh can overlap on launch.
    // Either response is a complete catalog for the active daemon identity,
    // so do not leave a successful refresh hidden behind bootstrap's loader
    // when that duplicate request is cancelled or stalls.
    setDsLoading(false);
  }, []);

  // The design-system catalog is workspace-scoped on the daemon (#145), so it
  // is stale the moment the active workspace changes. Only the boot pass and a
  // route change into home refetched it, and switching workspaces does neither
  // — the switcher lives ON the home view, so `route.kind` stays 'home' — which
  // left the previous workspace's library on screen until a reload.
  useEffect(() => {
    void refreshDesignSystems();
  }, [workspaceContext?.workspaceId, refreshDesignSystems]);

  const refreshSkills = useCallback(async () => {
    // Always scoped. `GET /api/skills` is fail-closed on a missing
    // `x-od-workspace-id` (`skills.ts`: `if (!scopeId) return !ownerId;`), so a
    // headerless read is not the "unfiltered" list — it is the list with every
    // workspace-claimed skill removed, including the ones claimed by the
    // workspace the user is actually in.
    const read = beginWorkspaceScopedRead(workspaceContextRef.current);
    const list = await fetchSkills(read.context);
    // A read for the workspace the user has since LEFT must not restore that
    // workspace's catalog over the current one — see `beginWorkspaceScopedRead`.
    // Skipping the gate too is deliberate: this response is not an answer about
    // the current identity, and the newer read that replaced it will mark it.
    if (!read.isStillCurrent(workspaceContextRef.current)) return;
    setWorkspaceSkills({
      identity: workspaceIdentityCacheKey(read.context),
      items: list,
    });
    markSkillRegistryReady('functional');
  }, [markSkillRegistryReady]);

  // The skills catalog is workspace-scoped on the daemon exactly like the
  // design-system catalog above, and needs the same workspace-keyed refresh for
  // the same reason: the switcher lives ON the home view, so `route.kind` stays
  // 'home' and no route change fires.
  //
  // It additionally waits for `workspaceContextLoading` to settle, because
  // unlike design systems (whose scope the daemon resolves from its own vela
  // session) this read carries the identity in REQUEST HEADERS — there is
  // nothing correct to send until the context has resolved. Gating on it also
  // keeps launch at exactly one `/api/skills` request: the boot pass no longer
  // reads skills, this effect performs the first read, and a switch performs
  // one more.
  // Keyed on the SAME digest the commit guard compares, not just `workspaceId`.
  // The guard discards a response whenever `workspaceIdentityCacheKey` moves —
  // which includes member id, role, status, lifecycle and the two permission
  // bits. A trigger that only watched `workspaceId` would therefore discard a
  // response without starting its successor: two accounts active in the same
  // shared team workspace differ only by membership, so A's pending read would
  // be dropped for B while the workspace id, being unchanged, suppressed B's
  // replacement read — leaving the functional registry loading forever on
  // startup, or holding A's list later. "Discarded and never replaced" is a
  // worse outcome than the staleness it replaced, so every transition that
  // invalidates a response must also start its successor.
  const skillsReadIdentity = currentWorkspaceIdentity;
  const skillsReadIdentityRef = useRef<string | null>(null);
  useEffect(() => {
    if (workspaceContextLoading) return;
    if (skillsReadIdentityRef.current === skillsReadIdentity) return;
    skillsReadIdentityRef.current = skillsReadIdentity;
    void refreshSkills();
  }, [workspaceContextLoading, skillsReadIdentity, refreshSkills]);

  const refreshTemplates = useCallback(async () => {
    const list = await listTemplates();
    setTemplates(list);
  }, []);

  const handleDeleteTemplate = useCallback(async (id: string) => {
    const ok = await deleteTemplate(id);
    if (ok) await refreshTemplates();
    return ok;
  }, [refreshTemplates]);

  const reloadMediaProvidersFromDaemon = useCallback(async () => {
    const result = await fetchMediaProvidersFromDaemon();
    if (result.status !== 'ok') {
      setDaemonMediaProvidersFetchState('error');
      setMediaProvidersNotice(
        t('settings.mediaProviderLoadError'),
      );
      return null;
    }
    setDaemonMediaProviders(result.providers);
    setDaemonMediaProvidersFetchState('ok');
    setMediaProvidersNotice(null);
    setConfig((prev) => {
      const merged = mergeDaemonMediaProviders(prev, result.providers);
      saveConfig(merged);
      return merged;
    });
    return result.providers;
  }, []);

  /**
   * Autosave-driven persistence path. The settings dialog calls this on
   * every committed edit (via a debounced effect) so localStorage and
   * the daemon stay in lock-step with the user's draft. We deliberately
   * do NOT touch the Composio secret here — it has its own gesture
   * (handleConfigPersistComposioKey) so partial keys never leave the
   * browser. Onboarding is also left alone; the dialog's close path
   * is the canonical "I'm done" signal.
   */
  const handleConfigPersist = useCallback(async (
    next: AppConfig,
    options?: { forceMediaProviderSync?: boolean },
  ) => {
    // Strip the in-flight Composio secret before anything hits disk so
    // a half-typed key can't survive in localStorage. If the dialog is
    // closing, preserve any onboarding completion that the close gesture
    // already committed so an unmount autosave cannot re-open the welcome flow.
    const persisted = buildPersistedConfig(next, configRef.current);
    latestPersistedConfigRef.current = persisted;
    saveConfig(persisted);
    setConfig(persisted);
    const shouldSyncMediaProviders =
      daemonMediaProvidersFetchState === 'ok'
      && shouldSyncMediaProvidersOnSave(persisted.mediaProviders, {
        force: options?.forceMediaProviderSync,
      });
    await Promise.all([
      shouldSyncMediaProviders
        ? syncMediaProvidersToDaemon(persisted.mediaProviders, {
            force: options?.forceMediaProviderSync,
            daemonProviders: daemonMediaProviders,
            throwOnError: options?.forceMediaProviderSync,
          })
        : Promise.resolve(),
      syncConfigToDaemon(persisted, { throwOnError: true }),
    ]);
  }, [daemonMediaProviders, daemonMediaProvidersFetchState]);

  const handleSettingsDraftChange = useCallback((draft: AppConfig) => {
    settingsDraftConfigRef.current = draft;
  }, []);

  const handlePrivacyConsentChoice = useCallback((share: boolean) => {
    const base = settingsDraftConfigRef.current ?? latestPersistedConfigRef.current;
    const installationId = share
      ? base.installationId ?? generateInstallationIdSafe()
      : null;
    void handleConfigPersist({
      ...base,
      installationId,
      privacyDecisionAt: Date.now(),
      telemetry: {
        ...(base.telemetry ?? {}),
        metrics: share,
        content: share,
      },
    });
  }, [handleConfigPersist]);

  /**
   * Explicit Composio API-key save. Called from the section-local
   * "Save key" button so secrets never ride the autosave keystroke
   * loop. Once the daemon confirms, we normalize the saved config
   * (strip the secret, store apiKeyConfigured + apiKeyTail) and feed
   * it back into local state so the saved-key badge appears.
   */
  const handleConfigPersistComposioKey = useCallback(
    async (composio: AppConfig['composio']) => {
      const next = await persistComposioConfigChange(config, composio);
      setConfig((curr) => {
        const merged: AppConfig = { ...curr, composio: next.composio };
        saveConfig(merged);
        return merged;
      });
    },
    [config],
  );

  const handleModeChange = useCallback(
    (mode: AppConfig['mode']) => {
      const next = { ...latestPersistedConfigRef.current, mode };
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      setConfig(next);
    },
    [],
  );

  const handleAgentChange = useCallback(
    (agentId: string) => {
      const next = { ...latestPersistedConfigRef.current, agentId };
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    },
    [],
  );

  const handleAgentModelChange = useCallback(
    (agentId: string, choice: { model?: string; reasoning?: string; serviceTier?: string }) => {
      const current = latestPersistedConfigRef.current;
      const prev = current.agentModels?.[agentId] ?? {};
      const merged = mergeAgentModelChoice(prev, choice);
      const nextAgentModels = {
        ...(current.agentModels ?? {}),
        [agentId]: merged,
      };
      const next = { ...current, agentModels: nextAgentModels };
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    },
    [],
  );

  // BYOK protocol switch — also flips `mode` to 'api' so the user does
  // not have to take a second step after picking a provider from the
  // inline switcher. The helper preserves any per-protocol fields the
  // user had previously configured for the target protocol.
  const handleApiProtocolChange = useCallback(
    (protocol: ApiProtocol) => {
      const next = switchApiProtocolConfig(
        latestPersistedConfigRef.current,
        protocol,
      );
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    },
    [],
  );

  // BYOK model picker — patches `model` (and the per-protocol shadow
  // copy) without touching apiKey/baseUrl so the user can swap models
  // mid-session without retyping their key.
  const handleApiModelChange = useCallback(
    (model: string) => {
      const next = updateCurrentApiProtocolConfig(
        latestPersistedConfigRef.current,
        { model },
      );
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    },
    [],
  );

  const handleChangeDefaultDesignSystem = useCallback(
    (designSystemId: string | null) => {
      const next = {
        ...latestPersistedConfigRef.current,
        designSystemId,
      };
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    },
    [],
  );

  const refreshAgents = useCallback(
    async (options?: { throwOnError?: boolean; agentCliEnv?: AppConfig['agentCliEnv'] }) => {
      if (options && Object.prototype.hasOwnProperty.call(options, 'agentCliEnv')) {
        const current = latestPersistedConfigRef.current;
        const nextConfig = clearStaleAmrModelChoiceOnProfileChange(current, {
          ...current,
          agentCliEnv: options.agentCliEnv ?? {},
        });
        latestPersistedConfigRef.current = nextConfig;
        amrModelsRef.current = null;
        saveConfig(nextConfig);
        setConfig(nextConfig);
        await syncConfigToDaemon(nextConfig);
      }
      const agentRequestId = beginAgentStreamRequest();
      setAgentsLoading(true);
      try {
        const next = await fetchAgentsStream({
          signal: agentStreamAbortRef.current?.signal,
          onAgent: (agent) => {
            if (!isCurrentAgentStreamRequest(agentRequestId)) return;
            setAgents((current) =>
              mergeAmrModelsIntoAgents(
                upsertAgent(current, agent),
                amrModelsRef.current,
              ),
            );
          },
        });
        const ordered = orderAgentsByRegistry(next);
        if (isCurrentAgentStreamRequest(agentRequestId)) {
          setAgents(mergeAmrModelsIntoAgents(ordered, amrModelsRef.current));
          setAgentsLoading(false);
        }
        return ordered;
      } catch (err) {
        if (!isCurrentAgentStreamRequest(agentRequestId)) return [];
        setAgentsLoading(false);
        if (options?.throwOnError) throw err;
        setAgents([]);
        return [];
      }
    },
    [beginAgentStreamRequest, isCurrentAgentStreamRequest],
  );

  useEffect(() => {
    if (!daemonLive || agentsLoading) return;

    const refreshIfDue = () => {
      if (document.visibilityState === 'hidden') return;
      const now = Date.now();
      if (now - agentFocusRefreshLastRunRef.current < AGENT_FOCUS_REFRESH_THROTTLE_MS) return;
      agentFocusRefreshLastRunRef.current = now;
      void refreshAgents();
    };

    const handleVisibilityChange = () => {
      if (document.visibilityState === 'visible') refreshIfDue();
    };

    window.addEventListener('focus', refreshIfDue);
    document.addEventListener('visibilitychange', handleVisibilityChange);
    return () => {
      window.removeEventListener('focus', refreshIfDue);
      document.removeEventListener('visibilitychange', handleVisibilityChange);
    };
  }, [agentsLoading, daemonLive, refreshAgents]);

  useEffect(() => {
    const handleAppConfigChanged = () => {
      void fetchDaemonConfig().then((daemonConfig) => {
        const next = clearStaleAmrModelChoiceOnProfileChange(
          latestPersistedConfigRef.current,
          mergeDaemonConfig(latestPersistedConfigRef.current, daemonConfig),
        );
        latestPersistedConfigRef.current = next;
        saveConfig(next);
        setConfig(next);
        amrModelsRef.current = null;
        restartAmrPolling();
        void refreshAgents();
      });
    };
    window.addEventListener(APP_CONFIG_CHANGED_EVENT, handleAppConfigChanged);
    return () => window.removeEventListener(APP_CONFIG_CHANGED_EVENT, handleAppConfigChanged);
  }, [refreshAgents, restartAmrPolling]);

  const handleCreateProject = useCallback(
    async (
      input: AppCreateProjectInput,
    ): Promise<boolean> => {
      // Honor an explicit `null` design system — the create panel defaults
      // to "None" for every kind now, and the user expects that to land
      // as a no-design-system project rather than silently inheriting the
      // workspace default.
      const derivedPendingPrompt =
      input.pendingPrompt ??
      (input.metadata?.promptTemplate?.prompt?.trim() || undefined);

      const metadata = mergeLinkedDirsIntoMetadata(input.metadata, input.linkedDirs);
      const kind = metadata?.kind ?? null;
      const fidelity = fidelityToTracking(metadata?.fidelity ?? null);
      const creationSource: 'blank' | 'template' | 'zip' | 'folder' =
        kind === 'template' ? 'template' : 'blank';
      let result;
      try {
        const createWorkspaceContext = resolvedWorkspaceContextForWrite(
          workspaceContextStateRef.current,
        );
        if (
          input.amrGatePrecheckWitness &&
          !amrBalanceGateScopesMatch(
            input.amrGatePrecheckWitness,
            amrBalanceGateScopeForWorkspaceContext(createWorkspaceContext),
          )
        ) {
          throw new Error('AMR_WORKSPACE_GATE_STALE');
        }
        result = await createProject({
          name: input.name,
          skillId: input.skillId,
          designSystemId: input.designSystemId,
          pendingPrompt: derivedPendingPrompt,
          metadata,
          ...(input.conversationMode ? { conversationMode: input.conversationMode } : {}),
          ...(input.pluginId ? { pluginId: input.pluginId } : {}),
          ...(input.appliedPluginSnapshotId
            ? { appliedPluginSnapshotId: input.appliedPluginSnapshotId }
            : {}),
          ...(input.pluginInputs ? { pluginInputs: input.pluginInputs } : {}),
          workspaceContext: createWorkspaceContext,
        });
      } catch (err) {
        const errorCode =
          err instanceof Error && err.message.trim()
            ? err.message
            : 'CREATE_REQUEST_FAILED';
        trackProjectCreateResult(
          analytics.track,
          {
            page_name: 'home',
            area: 'new_project',
            project_source: 'create_button',
            project_id: null,
            project_kind: projectKindFromMetadataToTracking(metadata),
            fidelity,
            result: 'failed',
            error_code: errorCode,
          },
          { requestId: input.requestId },
        );
        throw err;
      }
      if (!result) {
        trackProjectCreateResult(
          analytics.track,
          {
            page_name: 'home',
            area: 'new_project',
            project_source: 'create_button',
            project_id: null,
            project_kind: projectKindFromMetadataToTracking(metadata),
            fidelity,
            ...(input.pluginId ? { plugin_id: input.pluginId } : {}),
            ...(input.pluginType ? { plugin_type: input.pluginType } : {}),
            result: 'failed',
            error_code: 'CREATE_REQUEST_FAILED',
          },
          { requestId: input.requestId },
        );
        return false;
      }
      const pendingFiles = Array.isArray(input.pendingFiles)
        ? input.pendingFiles.filter((file): file is File => file instanceof File)
        : [];
      // Flip the project onto the user-picked working directory BEFORE
      // uploading staged Home attachments. `replaceProjectWorkingDir` changes
      // `metadata.baseDir`, so the project starts reading from the external
      // folder. If we uploaded first, the staged files would land in the
      // temporary managed `.od/projects/<id>` root and then silently vanish
      // from Design Files and the first auto-send context once the working
      // dir flips. Doing the handoff first means the initial upload lands in
      // the final tree.
      const userWorkingDir = metadata?.userWorkingDir;
      let workingDirHandoffFailed = false;
      if (userWorkingDir) {
        try {
          await replaceProjectWorkingDir(
            result.project.id,
            userWorkingDir,
            input.userWorkingDirToken,
          );
        } catch (err) {
          // The desktop working-dir token is short-lived (~60s TTL); if the
          // user lingered on Home or the POST was otherwise rejected, the
          // handoff fails AFTER the project already exists. Do NOT swallow
          // this and do NOT proceed: uploading staged attachments or
          // auto-sending the first message would target the managed
          // `.od/projects/<id>` root the user did not choose. Mark the
          // handoff as failed so the upload + auto-send branches below are
          // skipped, then surface a create-time error so the user can
          // re-pick the working directory from inside the project.
          console.warn('Failed to set working directory for new project', userWorkingDir, err);
          workingDirHandoffFailed = true;
          setWorkingDirError(
            `Couldn't apply the chosen folder "${userWorkingDir}". The project was created in the default location — re-pick the working directory from the project before uploading files or sending a message.`,
          );
        }
      }
      let firstMessageAttachments: ChatAttachment[] = [];
      if (!workingDirHandoffFailed && pendingFiles.length > 0) {
        // Home composer attaches stay client-side until submit lands a
        // project; the actual upload happens here. v2 doc wants one
        // file_upload_result per surface — `page_name='home'` /
        // `area='chat_composer'` so it's distinguishable from the
        // file_manager Upload button and the chat_panel composer.
        const cohort = deriveUploadCohort(pendingFiles);
        const uploadResult = await uploadProjectFiles(
          result.project.id,
          pendingFiles,
          undefined,
          workspaceContextRef.current,
        );
        firstMessageAttachments = uploadResult.uploaded;
        const partial = uploadResult.failed.length > 0;
        if (partial) {
          console.warn('Some Home attachments failed to upload', uploadResult.failed);
        }
        trackFileUploadResult(analytics.track, {
          page_name: 'home',
          area: 'chat_composer',
          project_id: result.project.id,
          ...cohort,
          result: partial ? 'failed' : 'success',
          ...(partial && uploadResult.error
            ? { error_code: uploadResult.error }
            : {}),
        });
      }
      trackProjectCreateResult(
        analytics.track,
        {
          page_name: 'home',
          area: 'new_project',
          project_source: 'create_button',
          project_id: result.project.id,
          project_kind: projectKindFromMetadataToTracking(metadata),
          fidelity,
          ...(input.pluginId ? { plugin_id: input.pluginId } : {}),
          ...(input.pluginType ? { plugin_type: input.pluginType } : {}),
          result: 'success',
        },
        { requestId: input.requestId },
      );
      // PluginLoopHome flow: the user already typed (or accepted) the
      // first message on Home. Mark this project so ProjectView fires
      // sendMessage(pendingPrompt) once on mount instead of just
      // pre-filling the composer. Scoped to sessionStorage so a page
      // reload after the run has started does not refire.
      if (
        !workingDirHandoffFailed &&
        input.autoSendFirstMessage &&
        (derivedPendingPrompt !== undefined || firstMessageAttachments.length > 0)
      ) {
        try {
          window.sessionStorage.setItem(
            `od:auto-send-first:${result.project.id}`,
            '1',
          );
          if (input.amrGatePrecheckWitness) {
            window.sessionStorage.setItem(
              `od:auto-send-amr-gate-witness:${result.project.id}`,
              JSON.stringify(input.amrGatePrecheckWitness),
            );
          } else {
            window.sessionStorage.removeItem(
              `od:auto-send-amr-gate-witness:${result.project.id}`,
            );
          }
          window.sessionStorage.removeItem(
            `od:auto-send-amr-gate-ok:${result.project.id}`,
          );
          if (firstMessageAttachments.length > 0) {
            window.sessionStorage.setItem(
              `od:auto-send-attachments:${result.project.id}`,
              JSON.stringify(firstMessageAttachments),
            );
          } else {
            window.sessionStorage.removeItem(
              `od:auto-send-attachments:${result.project.id}`,
            );
          }
          if (input.initialRunContext && Object.keys(input.initialRunContext).length > 0) {
            window.sessionStorage.setItem(
              `od:auto-send-context:${result.project.id}`,
              JSON.stringify(input.initialRunContext),
            );
          } else {
            window.sessionStorage.removeItem(
              `od:auto-send-context:${result.project.id}`,
            );
          }
        } catch {
          /* sessionStorage may be unavailable (e.g. SSR / private mode); fall
             back to manual send. */
        }
      }
      // Home recommendation handoff: now that the project exists and its id is
      // known, stash the onboarding entry keyed by that id. Studio consumes it
      // by the same id on mount. Keying by id (instead of a single global slot
      // written before create) removes the race where opening an unrelated
      // project mid-create could steal the personalized funnel context, and
      // means a failed/aborted create leaves nothing behind.
      if (input.onboardingEntry) {
        // Cache the prefilled seed prompt WITH the entry so the first-prompt
        // funnel's `has_prefilled_prompt` comparison base survives a
        // reopen-before-send (project.pendingPrompt is wiped on first mount).
        stashOnboardingEntryForProject(result.project.id, {
          ...input.onboardingEntry,
          ...(derivedPendingPrompt
            ? { seedPrompt: derivedPendingPrompt.trim() }
            : {}),
        });
      }
      const project = result.appliedPluginSnapshotId
        ? {
            ...result.project,
            appliedPluginSnapshotId: result.appliedPluginSnapshotId,
          }
        : result.project;
      rememberLocalProject(project.id);
      flushSync(() => {
        setProjects((curr) => [
          project,
          ...curr.filter((p) => p.id !== project.id),
        ]);
      });
      const projectRoute = {
        kind: 'project',
        projectId: project.id,
        fileName: null,
      } as const;
      openWorkspaceTab(projectRoute);
      navigate(projectRoute);
      return true;
    },
    [analytics.track, rememberLocalProject],
  );

  const handleCreateProjectFromDesignSystem = useCallback(
    async (designSystemId: string, designSystemTitle: string) => {
      // "Create with this design system" must NOT assume a prototype. Route
      // the click through the hidden default design router (od-default) —
      // exactly like a free-form Home prompt — so the agent first asks (via
      // the task-type question-form) what to build with this system instead
      // of silently binding the web-prototype scenario + high-fidelity
      // metadata. The preset prompt seeds the conversation and is auto-sent
      // so the router surfaces the confirmation form immediately; `kind`
      // stays the neutral 'other' so no surface-specific default leaks back
      // in on the daemon side.
      const presetPrompt = t('nextStep.brandCreateDesignPrompt', {
        designSystem: designSystemTitle,
      });
      await handleCreateProject({
        name: t('common.untitled'),
        skillId: null,
        designSystemId,
        pluginId: DEFAULT_UNSELECTED_SCENARIO_PLUGIN_ID,
        pluginInputs: { prompt: presetPrompt },
        pendingPrompt: presetPrompt,
        autoSendFirstMessage: true,
        conversationMode: 'design',
        metadata: {
          kind: 'other',
          nameSource: 'generated',
        },
      });
    },
    [handleCreateProject, t],
  );

  const handleCreateDesignSystemFromProject = useCallback(
    async (
      sourceProjectId: string,
      input: { name?: string; pendingPrompt?: string },
    ) => {
      // Carry the active workspace identity — same reasoning as
      // handleDeleteProject: without it enforceWorkspaceProjectMutation
      // treats the request as a legacy pre-workspace caller and skips its
      // ownership check entirely.
      const result = await createDesignSystemProjectFromProject(
        sourceProjectId,
        input,
        workspaceContextRef.current,
      );
      try {
        window.sessionStorage.setItem(`od:auto-send-first:${result.project.id}`, '1');
      } catch {
        // If sessionStorage is unavailable, the project still opens with the
        // pending prompt ready for the user to send manually.
      }
      rememberLocalProject(result.project.id);
      setProjects((curr) => [
        result.project,
        ...curr.filter((p) => p.id !== result.project.id),
      ]);
      void refreshDesignSystems();
      navigate({
        kind: 'project',
        projectId: result.project.id,
        conversationId: result.conversationId,
        fileName: null,
      });
    },
    [refreshDesignSystems, rememberLocalProject],
  );

  const handleDuplicateProject = useCallback(
    async (sourceProjectId: string, input: { name?: string } = {}) => {
      // Same reasoning as handleDeleteProject / handleCreateDesignSystemFromProject.
      const result = await duplicateProject(sourceProjectId, input, workspaceContextRef.current);
      rememberLocalProject(result.project.id);
      setProjects((curr) => [
        result.project,
        ...curr.filter((p) => p.id !== result.project.id),
      ]);
      navigate({
        kind: 'project',
        projectId: result.project.id,
        conversationId: result.conversationId,
        fileName: null,
      });
    },
    [rememberLocalProject],
  );

  const handleCreatePluginShareProject = useCallback(
    async (
      pluginId: string,
      action: PluginShareAction,
      locale?: string,
    ): Promise<PluginShareProjectOutcome> => {
      // Best-effort, NOT `resolvedWorkspaceContextForWrite`: that helper throws
      // while the identity read is in flight, and refusing this create would be
      // a new block on a path that works today. Sending the context whenever it
      // is known is a strict improvement — this call used to send none, ever —
      // and the daemon binds a headerless create to its own signed-in workspace
      // (`createdProjectWorkspaceHome`), so the loading window no longer
      // produces an orphan either way.
      const outcome = await createPluginShareProject(
        pluginId,
        action,
        locale,
        workspaceContextStateRef.current.context,
      );
      if (!outcome.ok) return outcome;
      try {
        window.sessionStorage.setItem(
          `od:auto-send-first:${outcome.project.id}`,
          '1',
        );
      } catch {
        // If sessionStorage is unavailable, the project still opens with
        // the prepared prompt in the composer.
      }
      const project = outcome.appliedPluginSnapshotId
        ? {
            ...outcome.project,
            appliedPluginSnapshotId: outcome.appliedPluginSnapshotId,
          }
        : outcome.project;
      rememberLocalProject(project.id);
      setProjects((curr) => [
        project,
        ...curr.filter((p) => p.id !== project.id),
      ]);
      navigate({
        kind: 'project',
        projectId: project.id,
        fileName: null,
      });
      return outcome;
    },
    [rememberLocalProject],
  );

  const handleImportClaudeDesign = useCallback(async (
    file: File,
  ): Promise<ImportClaudeDesignOutcome> => {
    try {
      const result = await importClaudeDesignZip(
        file,
        resolvedWorkspaceContextForWrite(workspaceContextStateRef.current),
      );
      rememberLocalProject(result.project.id);
      setProjects((curr) => [
        result.project,
        ...curr.filter((p) => p.id !== result.project.id),
      ]);
      navigate({
        kind: 'project',
        projectId: result.project.id,
        fileName: result.entryFile,
      });
      return { ok: true };
    } catch (err) {
      return {
        ok: false,
        message: err instanceof Error ? err.message : 'The ZIP could not be imported.',
      };
    }
  }, [rememberLocalProject]);

  const handleImportFolder = useCallback(async (baseDir: string) => {
    const result = await importFolderProject(
      { baseDir },
      resolvedWorkspaceContextForWrite(workspaceContextStateRef.current),
    );
    rememberLocalProject(result.project.id);
    setProjects((curr) => [result.project, ...curr.filter((p) => p.id !== result.project.id)]);
    navigate({
      kind: 'project',
      projectId: result.project.id,
      fileName: null,
    });
  }, [rememberLocalProject]);

  // PR #974: on desktop, the host bridge owns the picker and import POST
  // atomically. The renderer never sees the path, token, or daemon DTO;
  // it receives host-owned project identifiers and refreshes project state
  // through the normal daemon API.
  const handleImportFolderResponse = useCallback(async (result: OpenDesignHostProjectImportSuccess) => {
    rememberLocalProject(result.projectId);
    const project = await getProject(result.projectId);
    if (project != null) {
      setProjects((curr) => [project, ...curr.filter((p) => p.id !== project.id)]);
    } else {
      // Daemon hasn't materialized the full record yet (race between the
      // host's import POST and our /api/projects read). Seed a minimal
      // placeholder so the route stays alive and ProjectView mounts; the
      // pending-local id keeps reconcileFetchedProjects from evicting the
      // stub until a project-list snapshot actually includes it, and the
      // next refresh swaps it for the real Project record. Without the
      // stub, a stale `[]` list response would replace `projects` with `[]`
      // and the route-guard effect would bounce the user back to Home.
      const stub: Project = {
        id: result.projectId,
        name: '',
        skillId: null,
        designSystemId: null,
        createdAt: Date.now(),
        updatedAt: Date.now(),
      };
      setProjects((curr) => [stub, ...curr.filter((p) => p.id !== stub.id)]);
      const request = beginProjectListRequest();
      const list = await listCurrentWorkspaceProjects({ workspaceView: workspaceProjectView });
      reconcileFetchedProjects(list, request);
    }
    navigate({
      kind: 'project',
      projectId: result.projectId,
      fileName: null,
    });
  }, [beginProjectListRequest, listCurrentWorkspaceProjects, rememberLocalProject, reconcileFetchedProjects, workspaceProjectView]);

  const rememberAuthoritativeProjectName = useCallback((
    key: string,
    name: string | null,
    isCurrent: () => boolean = () => true,
  ) => {
    setAuthoritativeProjectNames((current) => {
      if (!isCurrent()) return current;
      if (name) {
        if (current[key] === name) return current;
        return { ...current, [key]: name };
      }
      if (!(key in current)) return current;
      const next = { ...current };
      delete next[key];
      return next;
    });
  }, []);

  const resolveAuthoritativeProjectName = useCallback(async (
    projectId: string,
    expectedAuthorizationKey: string,
  ): Promise<ProjectNameAuthorityResolution> => {
    const context = workspaceContextRef.current;
    const key = projectViewAuthorizationLifetimeKey(projectId, context);
    if (key !== expectedAuthorizationKey) return { kind: 'stale' };
    const authorizationGeneration = projectAuthorizationGenerationRef.current;
    const requestGeneration =
      (projectNameAuthorityRequestGenerationRef.current.get(key) ?? 0) + 1;
    projectNameAuthorityRequestGenerationRef.current.set(key, requestGeneration);
    const authorityRequestIsCurrent = () =>
      projectAuthorizationGenerationRef.current === authorizationGeneration
      && projectNameAuthorityRequestGenerationRef.current.get(key) === requestGeneration
      && projectViewAuthorizationLifetimeKey(projectId, workspaceContextRef.current) === key;
    const lookup = await fetchTeamProjectCatalogEntry(projectId);
    if (!authorityRequestIsCurrent()) {
      // Workspace/member changed while the catalog request was in flight.
      // A newer same-key request also supersedes this response, so an older
      // catalog snapshot cannot roll back a rename that resolved first.
      return { kind: 'stale' };
    }
    if (!lookup.ok) {
      // A transport failure is not evidence that ownership/title authority
      // changed. Keep the last catalog title until a successful read says so.
      return {
        kind: 'resolved',
        name: authoritativeProjectNamesRef.current[key] ?? null,
      };
    }
    const catalogProject = lookup.project;
    const catalogName = catalogProject?.name?.trim() || null;
    const belongsToAnotherMember = Boolean(
      catalogProject
      && catalogProject.ownerMemberId !== context?.workspaceMemberId,
    );
    const authoritativeName = belongsToAnotherMember ? catalogName : null;
    rememberAuthoritativeProjectName(key, authoritativeName, authorityRequestIsCurrent);
    if (authoritativeName) {
      // Merge title only into the already-authorized local row; never construct
      // a catalog-shaped Project because catalog rows do not carry workspace
      // binding or the full project metadata.
      setProjects((current) => {
        if (!authorityRequestIsCurrent()) return current;
        return current.map((project) =>
          project.id === projectId
            && project.workspaceId
            && (!context?.workspaceId || project.workspaceId === context.workspaceId)
            ? { ...project, name: authoritativeName }
            : project);
      });
    }
    return { kind: 'resolved', name: authoritativeName };
  }, [rememberAuthoritativeProjectName]);

  const handleOpenProject = useCallback(async (
    id: string,
    fileName?: string,
    projectTitleHint?: ProjectTitleHint,
  ): Promise<boolean> => {
    const routeFileName = fileName ?? null;
    const hintedProjectName = projectTitleHint?.name.trim() || null;
    const requiresBoundCatalogProject = projectTitleHint?.authoritative === true;
    const openingContext = workspaceContextRef.current;
    const openingAuthorizationGeneration = projectAuthorizationGenerationRef.current;
    const openingScopeKey = projectListScopeKey(openingContext);
    const expectedWorkspaceId = openingContext?.workspaceId ?? null;
    const hintMatchesOpeningScope =
      !projectTitleHint
      || Boolean(
        expectedWorkspaceId
        && openingContext?.workspaceMemberId
        && projectTitleHint.workspaceId === expectedWorkspaceId
        && projectTitleHint.workspaceMemberId === openingContext.workspaceMemberId,
      );
    if (requiresBoundCatalogProject && !hintMatchesOpeningScope) return false;
    // A stale non-authoritative card may still open the current local row, but
    // its old-workspace title must never overwrite that row. Authoritative
    // catalog cards fail closed above; own/local cards simply drop the hint.
    const catalogName = hintMatchesOpeningScope ? hintedProjectName : null;
    const titleAuthorityKey = projectViewAuthorizationLifetimeKey(
      id,
      openingContext,
    );
    const openingScopeIsCurrent = () =>
      projectAuthorizationGenerationRef.current === openingAuthorizationGeneration
      && projectListScopeKey(workspaceContextRef.current) === openingScopeKey;
    const canUseLocalProject = (project: Project) => {
      if (project.workspaceId) return project.workspaceId === expectedWorkspaceId;
      return !requiresBoundCatalogProject;
    };
    const rememberHintAuthority = () => {
      if (projectTitleHint?.authoritative && catalogName && openingScopeIsCurrent()) {
        // A catalog card is an authority response too. Invalidate any older
        // deep-link/metadata lookup that started before this newer UI snapshot
        // was accepted, otherwise its late response could roll the title back.
        const nextRequestGeneration =
          (projectNameAuthorityRequestGenerationRef.current.get(titleAuthorityKey) ?? 0) + 1;
        projectNameAuthorityRequestGenerationRef.current.set(
          titleAuthorityKey,
          nextRequestGeneration,
        );
        rememberAuthoritativeProjectName(
          titleAuthorityKey,
          catalogName,
          openingScopeIsCurrent,
        );
      }
    };
    // EntryShell's shared-project grid has already reconciled local SQLite with
    // the workspace catalog. Preserve its authoritative display name during the
    // route transition instead of reopening the stale local placeholder by id.
    //
    // The catalog row is NOT a local project record: it may omit workspaceId
    // and other binding fields. Treat it as a name hint only, and merge it into
    // an already-bound local row. If App has not observed that row yet, keep
    // loading through GET/pull/list below instead of inserting an unbound
    // catalog-shaped Project into local state.
    if (
      catalogName
      && projectsRef.current.some((project) => project.id === id && canUseLocalProject(project))
    ) {
      setProjects((current) => {
        if (!openingScopeIsCurrent()) return current;
        const existingIndex = current.findIndex(
          (project) => project.id === id && canUseLocalProject(project),
        );
        if (existingIndex < 0) return current;
        const existing = current[existingIndex]!;
        if (existing.name === catalogName) return current;
        const next = [...current];
        next[existingIndex] = {
          ...existing,
          name: catalogName,
        };
        return next;
      });
      rememberHintAuthority();
      navigate({ kind: 'project', projectId: id, fileName: routeFileName });
      return true;
    }
    if (
      !catalogName
      && projectsRef.current.some(
        (project) => project.id === id && canUseLocalProject(project),
      )
    ) {
      navigate({ kind: 'project', projectId: id, fileName: routeFileName });
      return true;
    }
    try {
      const project = await getProject(id);
      if (!openingScopeIsCurrent()) return false;
      if (project && canUseLocalProject(project)) {
        const openedProject = catalogName ? { ...project, name: catalogName } : project;
        setProjects((curr) => openingScopeIsCurrent()
          ? [
              openedProject,
              ...curr.filter((candidate) => candidate.id !== openedProject.id),
            ]
          : curr);
        rememberHintAuthority();
        navigate({ kind: 'project', projectId: id, fileName: routeFileName });
        return true;
      }
      const { pulled } = await pullTeamSharedProjectIfAvailable(id);
      if (!openingScopeIsCurrent()) return false;
      if (pulled) {
        const pulledProject = await getProject(id);
        if (!openingScopeIsCurrent()) return false;
        if (pulledProject && canUseLocalProject(pulledProject)) {
          const openedProject = catalogName
            ? { ...pulledProject, name: catalogName }
            : pulledProject;
          setProjects((curr) => openingScopeIsCurrent()
            ? [
                openedProject,
                ...curr.filter((candidate) => candidate.id !== openedProject.id),
              ]
            : curr);
          rememberHintAuthority();
          navigate({ kind: 'project', projectId: id, fileName: routeFileName });
          return true;
        }
      }
      const request = beginProjectListRequest();
      const list = await listCurrentWorkspaceProjects({ workspaceView: 'all' });
      if (!openingScopeIsCurrent()) return false;
      const reconciledList = catalogName
        ? list.map((candidate) =>
            candidate.id === id && canUseLocalProject(candidate)
              ? { ...candidate, name: catalogName }
              : candidate)
        : list;
      reconcileFetchedProjects(reconciledList, request);
      const fetchedProject = locallyDeletedProjectIdsRef.current.has(id)
        ? undefined
        : reconciledList.find(
            (candidate) => candidate.id === id && canUseLocalProject(candidate),
          );
      if (fetchedProject) {
        rememberHintAuthority();
        navigate({ kind: 'project', projectId: id, fileName: routeFileName });
        return true;
      }
    } catch {
      // Fall through to the same visible missing-project state. The daemon can
      // return 404 or transiently fail while reconciling a deleted backing
      // project; either way the user needs feedback instead of a silent bounce.
    }
    if (!openingScopeIsCurrent()) return false;
    setProjectOpenError(t('project.missing'));
    return false;
  }, [
    beginProjectListRequest,
    listCurrentWorkspaceProjects,
    reconcileFetchedProjects,
    rememberAuthoritativeProjectName,
    t,
  ]);

  useEffect(() => {
    if (!config.pet?.enabled || !daemonLive) {
      setPetTaskCenter({ running: [], queued: [], recent: [] });
      return;
    }

    let cancelled = false;
    const refresh = async () => {
      const runs = await listProjectRuns();
      if (cancelled) return;
      setPetTaskCenter(buildPetTaskCenter(projects, runs));
    };
    const handleRunsChanged = () => {
      void refresh();
    };

    void refresh();
    window.addEventListener(RUNS_CHANGED_EVENT, handleRunsChanged);
    const id = window.setInterval(refresh, 2000);
    return () => {
      cancelled = true;
      window.removeEventListener(RUNS_CHANGED_EVENT, handleRunsChanged);
      window.clearInterval(id);
    };
  }, [config.pet?.enabled, daemonLive, projects]);

  const handleOpenLiveArtifact = useCallback((projectId: string, artifactId: string) => {
    navigate({ kind: 'project', projectId, fileName: liveArtifactTabId(artifactId) });
  }, []);

  const handleDeleteProject = useCallback(async (id: string) => {
    // Carry the active workspace identity so the daemon's cross-workspace
    // ownership check actually runs — see deleteProject's docblock
    // (recvq5ecTkar91: a leaked-in project was really deletable, not just
    // visible, because this call sent no workspace headers at all).
    const ok = await deleteProjectApi(id, workspaceContextRef.current);
    if (!ok) return false;
    clearLocalProject(id, { deleted: true });
    iframeKeepAlivePool.evictProject(id, { includeActive: true });
    setProjects((curr) => curr.filter((p) => p.id !== id));
    if (route.kind === 'project' && route.projectId === id) {
      navigate({ kind: 'home', view: 'home' });
    }
    return true;
  }, [clearLocalProject, iframeKeepAlivePool, route]);

  const handleRenameProject = useCallback(async (id: string, name: string) => {
    const trimmed = name.trim();
    if (!trimmed) return;
    setProjects((curr) =>
      curr.map((p) => (p.id === id ? { ...p, name: trimmed } : p)),
    );
    void patchProject(id, { name: trimmed }, workspaceContextRef.current);
  }, []);

  // The project header back button is an escape hatch back to Home. Avoid
  // depending on browser history here: tab restores and template-create flows
  // can leave an in-app history entry that points back to the same project.
  const handleBack = useCallback(() => {
    const currentProjectId = route.kind === 'project' ? route.projectId : null;
    navigate({ kind: 'home', view: 'home' });
    if (currentProjectId && typeof window !== 'undefined') {
      window.setTimeout(() => {
        iframeKeepAlivePool.evictProject(currentProjectId, { includeActive: true });
      }, 0);
    }
  }, [iframeKeepAlivePool, route]);

  const handleClearPendingPrompt = useCallback(() => {
    const projectId = route.kind === 'project' ? route.projectId : null;
    if (!projectId) return;
    setProjects((curr) =>
      curr.map((p) =>
        p.id === projectId ? { ...p, pendingPrompt: undefined } : p,
      ),
    );
    void patchProject(projectId, { pendingPrompt: null }, workspaceContextRef.current);
  }, [route]);

  const handleTouchProject = useCallback(() => {
    const projectId = route.kind === 'project' ? route.projectId : null;
    if (!projectId) return;
    const updatedAt = Date.now();
    setProjects((curr) =>
      curr.map((p) => (p.id === projectId ? { ...p, updatedAt } : p)),
    );
    void patchProject(projectId, { updatedAt }, workspaceContextRef.current);
  }, [route]);

  const handleProjectChange = useCallback((updated: Project) => {
    setProjects((curr) => {
      const previous = curr.find((p) => p.id === updated.id);
      if (
        previous
        && (
          previous.skillId !== updated.skillId
          || previous.designSystemId !== updated.designSystemId
          || previous.customInstructions !== updated.customInstructions
        )
      ) {
        iframeKeepAlivePool.evictProject(updated.id, { includeActive: true });
      }
      return curr.map((p) => (p.id === updated.id ? updated : p));
    });
  }, [iframeKeepAlivePool]);

  // ProjectView's prompt-context signature derives from SkillSummary /
  // DesignSystemSummary fields, so a body-only registry edit (same name,
  // description, etc.) leaves every signature unchanged and the active
  // preview keeps serving stale prompt context. Settings → Skills /
  // Settings → Design Systems call back through these handlers after
  // every successful mutation; we drop any pool entry whose project
  // depends on the affected id — active or parked — so the next mount
  // recomposes the system prompt with the new body.

  const handleSkillsChanged = useCallback(
    (affectedSkillId?: string) => {
      // Scoped AND guarded on commit, like every other app-level skills read —
      // see `refreshSkills` and `beginWorkspaceScopedRead`.
      const skillsRead = beginWorkspaceScopedRead(workspaceContextRef.current);
      void fetchSkills(skillsRead.context).then((list) => {
        if (!skillsRead.isStillCurrent(workspaceContextRef.current)) return;
        setWorkspaceSkills({
          identity: workspaceIdentityCacheKey(skillsRead.context),
          items: list,
        });
      });
      void fetchDesignTemplates().then((list) => setDesignTemplates(list));
      iframeKeepAlivePool.evictMatching(
        (entry) => {
          const proj = projectsRef.current.find((p) => p.id === entry.projectId);
          if (!proj) return false;
          if (affectedSkillId) return proj.skillId === affectedSkillId;
          return proj.skillId != null;
        },
        { includeActive: true },
      );
    },
    [iframeKeepAlivePool],
  );

  const handleDesignSystemsChanged = useCallback(
    (affectedDesignSystemId?: string) => {
      void refreshDesignSystems();
      iframeKeepAlivePool.evictMatching(
        (entry) => {
          const proj = projectsRef.current.find((p) => p.id === entry.projectId);
          if (!proj) return false;
          if (affectedDesignSystemId) {
            return proj.designSystemId === affectedDesignSystemId;
          }
          return proj.designSystemId != null;
        },
        { includeActive: true },
      );
    },
    [iframeKeepAlivePool, refreshDesignSystems],
  );
  const handleDesignSystemImportRebuildJob = useCallback(
    (designSystemId: string, job: DesignSystemGenerationJob) => {
      setPendingDesignSystemRevisionJobs((current) => ({
        ...current,
        [designSystemId]: job,
      }));
    },
    [],
  );
  const handleDesignSystemRevisionJobConsumed = useCallback((designSystemId: string, jobId: string) => {
    setPendingDesignSystemRevisionJobs((current) => {
      if (current[designSystemId]?.id !== jobId) return current;
      const next = { ...current };
      delete next[designSystemId];
      return next;
    });
  }, []);

  const loadedActiveProject =
    route.kind === 'project'
      ? (projects.find((p) => p.id === route.projectId) ?? null)
      : null;
  const routeProjectPlaceholder = useMemo<Project | null>(() => {
    if (route.kind !== 'project') return null;
    const now = Date.now();
    return {
      id: route.projectId,
      name: 'Untitled',
      skillId: null,
      designSystemId: null,
      createdAt: now,
      updatedAt: now,
    };
  }, [route]);
  const activeProject = loadedActiveProject ?? routeProjectPlaceholder;
  const activeAuthoritativeProjectName =
    route.kind === 'project'
      ? authoritativeProjectNames[
          projectViewAuthorizationLifetimeKey(route.projectId, workspaceContext)
        ]
      : undefined;
  const activeProjectAuthorizationKey =
    route.kind === 'project'
      ? projectViewAuthorizationLifetimeKey(route.projectId, workspaceContext)
      : null;

  // A full-page refresh/deep link does not pass through EntryShell's card
  // click, and the local list may already contain a stale shared-project row.
  // Calibrate that bound row from the hub catalog as soon as both the route and
  // workspace identity have settled. This closes the path where the effect
  // below skipped resolution merely because SQLite returned "some" row.
  useEffect(() => {
    if (route.kind !== 'project') return;
    if (workspaceContextLoading) return;
    if (!loadedActiveProject?.workspaceId) return;
    if (!activeProjectAuthorizationKey || activeAuthoritativeProjectName) return;
    void resolveAuthoritativeProjectName(route.projectId, activeProjectAuthorizationKey);
  }, [
    route.kind,
    route.kind === 'project' ? route.projectId : null,
    loadedActiveProject?.id,
    loadedActiveProject?.workspaceId,
    activeAuthoritativeProjectName,
    activeProjectAuthorizationKey,
    workspaceContextLoading,
    workspaceContext?.workspaceId,
    workspaceContext?.workspaceMemberId,
    resolveAuthoritativeProjectName,
  ]);

  // Deep-linked route to a project we don't have yet (e.g. after a refresh
  // that finishes after the project list comes back, OR a member's first-ever
  // open of a project their team just shared with them). Fetch it in the
  // background so the view can render rather than bouncing to home.
  //
  // A member's first open of a freshly-shared project is a genuine race: the
  // hub already confirms the project belongs to their team, but the local
  // sqlite mirror (materialized by POST /collab/pull's registerPulledProject,
  // or by ProjectView's own /collab/status poll firing
  // ensureSharedProjectPlaceholder — see collab-sync.ts) hasn't landed yet. A
  // single immediate miss used to be indistinguishable from "this project
  // doesn't exist / I have no access", and navigated the member straight back
  // to Home mid-sync. `pullTeamSharedProjectIfAvailable`'s
  // `isTeamShared` is the reliable signal here: it comes from the hub-backed
  // `/api/workspace/projects/team` catalog, not from local sqlite state that
  // can simply be running behind. Retry on that signal for a short bounded
  // window, and once the hub has confirmed team membership even once, never
  // fall through to the not-found/navigate-home path for this project — only
  // a hub-confirmed absence does.
  useEffect(() => {
    if (route.kind !== 'project') return;
    if (loadedActiveProject) return;
    if (!projects.length && !daemonLive) return;
    if (projects.some((p) => p.id === route.projectId)) return;
    let cancelled = false;
    const projectId = route.projectId;
    (async () => {
      const resolution = await resolveDeepLinkedTeamSharedProject(projectId, {
        getProject,
        pullTeamSharedProjectIfAvailable,
        delay,
        isCancelled: () => cancelled,
      });
      if (cancelled) return;
      if (resolution.kind === 'found') {
        const fetched = resolution.project;
        setProjects((curr) => {
          const existingIndex = curr.findIndex((candidate) => candidate.id === fetched.id);
          if (existingIndex < 0) {
            return [...curr, fetched];
          }
          return curr.map((candidate) => (candidate.id === fetched.id ? fetched : candidate));
        });
        return;
      }
      // The hub confirmed at least once during the retry window that this
      // project belongs to the caller's team: it exists and they have access.
      // Local materialization is just still catching up — leave the route
      // alone instead of bouncing the member off a project they can see.
      if (resolution.kind === 'still-materializing') return;
      const request = beginProjectListRequest();
      const list = await listCurrentWorkspaceProjects({ workspaceView: 'all' }).catch(() => []);
      if (cancelled) return;
      const applied = reconcileFetchedProjects(list, request);
      if (!applied) return;
      const fetchedProject = locallyDeletedProjectIdsRef.current.has(projectId)
        ? undefined
        : list.find((p) => p.id === projectId);
      const staleRequest = request.mutationVersion < projectListMutationVersionRef.current;
      const knownLocalProject =
        staleRequest && pendingLocalProjectIdsRef.current.has(projectId);
      if (!fetchedProject && !knownLocalProject) {
        setProjectOpenError(t('project.missing'));
        navigate({ kind: 'home', view: 'home' }, { replace: true });
      }
    })();
    return () => {
      cancelled = true;
    };
  }, [route, loadedActiveProject, projects, daemonLive, beginProjectListRequest, listCurrentWorkspaceProjects, reconcileFetchedProjects, t]);

  const openSettings = useCallback((
    section: SettingsSection = 'execution',
    opts?: { highlight?: SettingsHighlight },
  ) => {
    if (section === 'composio' || section === 'mcpClient' || section === 'integrations') {
      setIntegrationInitialTab(
        section === 'composio'
          ? 'connectors'
          : section === 'mcpClient'
            ? 'mcp'
            : 'use-everywhere',
      );
      navigate({ kind: 'home', view: 'integrations' });
      return;
    }
    setSettingsWelcome(false);
    setSettingsInitialSection(section);
    setSettingsHighlight(opts?.highlight ?? null);
    navigate({ kind: 'home', view: 'settings' });
  }, []);

  // Entry point from the failed-run AMR nudge: open Settings on the execution
  // section and flag the AMR agent card for a one-shot scroll-into-view +
  // highlight (and a sign-in coachmark when not yet authorized).
  const openAmrSettings = useCallback(() => {
    openSettings('execution', { highlight: 'amr' });
  }, [openSettings]);

  const openPetSettings = useCallback(() => {
    setSettingsWelcome(false);
    setSettingsInitialSection('pet');
    setSettingsHighlight(null);
    navigate({ kind: 'home', view: 'settings' });
  }, []);

  const openMcpSettings = useCallback(() => {
    setIntegrationInitialTab('mcp');
    navigate({ kind: 'home', view: 'integrations' });
  }, []);

  // The composer "+" menu's "add plugin" / "add connector" rows route to the
  // home plugin-registry / connector-integration surfaces.
  const openPluginRegistry = useCallback(() => {
    navigate({ kind: 'home', view: 'plugins' });
  }, []);

  const openConnectorIntegrations = useCallback(() => {
    setIntegrationInitialTab('connectors');
    navigate({ kind: 'home', view: 'integrations' });
  }, []);

  const handleCompleteOnboarding = useCallback(() => {
    const current = latestPersistedConfigRef.current;
    if (current.onboardingCompleted) return;
    const next: AppConfig = { ...current, onboardingCompleted: true };
    latestPersistedConfigRef.current = next;
    saveConfig(next);
    void syncConfigToDaemon(next);
    setConfig(next);
  }, []);

  // Cmd+, (mac) / Ctrl+, (win/linux) opens Settings. Capture phase so we
  // beat the browser's default Preferences dialog. Platform-gated so
  // meta/ctrl don't conflict across OS.
  useEffect(() => {
    const onKeyDown = (e: KeyboardEvent) => {
      const primary = isMacPlatform() ? e.metaKey && !e.ctrlKey : e.ctrlKey && !e.metaKey;
      if (primary && !e.shiftKey && !e.altKey && e.key === ',') {
        if (e.isComposing) return;
        e.preventDefault();
        openSettings();
      }
    };
    window.addEventListener('keydown', onKeyDown, { capture: true });
    return () => window.removeEventListener('keydown', onKeyDown, { capture: true });
  }, [openSettings]);

  // Explicit enabled toggle — true = wake, false = tuck. Persists to
  // localStorage so the overlay state survives across reloads. We keep
  // `adopted` untouched so the entry-view CTA does not regress to
  // "adopt me" once the user has already chosen.
  const handleSetPetEnabled = useCallback((enabled: boolean) => {
    setConfig((curr) => {
      const prev = curr.pet ?? DEFAULT_PET;
      const next: AppConfig = { ...curr, pet: { ...prev, enabled } };
      saveConfig(next);
      return next;
    });
  }, []);

  const handleTuckPet = useCallback(
    () => handleSetPetEnabled(false),
    [handleSetPetEnabled],
  );

  // Toggle wake/tuck — used by the pet rail and the composer button.
  const handleTogglePet = useCallback(() => {
    setConfig((curr) => {
      const prev = curr.pet ?? DEFAULT_PET;
      const next: AppConfig = {
        ...curr,
        pet: { ...prev, enabled: !prev.enabled },
      };
      saveConfig(next);
      return next;
    });
  }, []);

  // Inline adopt — the right-hand pet rail and the composer's pet menu
  // both call this to switch pets without bouncing the user into
  // Settings. It always wakes the overlay so the change is visible.
  const handleAdoptPet = useCallback((petId: string) => {
    setConfig((curr) => {
      const prev = curr.pet ?? DEFAULT_PET;
      const next: AppConfig = {
        ...curr,
        pet: { ...prev, adopted: true, enabled: true, petId },
      };
      saveConfig(next);
      return next;
    });
  }, []);

  // When the user lands on the entry view (route.kind === 'home'), pull
  // a fresh template list. The template store is global — if they just
  // saved a template inside a project, returning home should reflect it
  // immediately in the From-template tab without forcing a page reload.
  // Same rationale for design systems: a brand extraction (or any in-project
  // design-system creation) registers a `user:<id>` system out of band, so the
  // Design systems tab must re-fetch to show it — and the brand-ready prompt
  // relies on the new system being present so it can preselect it.
  useEffect(() => {
    if (route.kind !== 'home') return;
    void refreshTemplates();
    void refreshDesignSystems();
  }, [route.kind, refreshTemplates, refreshDesignSystems]);

  // Existing card grids (DesignsTab, ProjectView), pickers (NewProjectPanel,
  // ChatComposer mention) all look skills up by id without caring whether
  // the id resolves to a functional skill or a design template. Pass them
  // the union so the post-split refactor stays invisible to those callers.
  const allSkillSummaries = useMemo(
    () => [...skills, ...designTemplates],
    [skills, designTemplates],
  );
  const enabledSkills = useMemo(
    () =>
      allSkillSummaries.filter(
        (s) => !(config.disabledSkills ?? []).includes(s.id),
      ),
    [allSkillSummaries, config.disabledSkills],
  );
  // Functional-skills-only enabled subset — what ProjectView's chat
  // composer @-picker should see. Without this, a skill the user has
  // disabled in Settings still appears in an existing project's @-mention
  // popover and can ride along to the daemon via skillIds, breaking the
  // Library toggle for projects opened on the post-split branch.
  const enabledFunctionalSkills = useMemo(
    () =>
      skills.filter(
        (s) => !(config.disabledSkills ?? []).includes(s.id),
      ),
    [skills, config.disabledSkills],
  );
  // Templates-only enabled subset — what the EntryView Templates gallery
  // actually renders. Filtering in App keeps the EntryView prop surface
  // narrow ("here are the templates the user has not disabled").
  const enabledDesignTemplates = useMemo(
    () =>
      designTemplates.filter(
        (s) => !(config.disabledSkills ?? []).includes(s.id),
      ),
    [designTemplates, config.disabledSkills],
  );
  const enabledDS = useMemo(
    () =>
      designSystems.filter(
        (d) => !(config.disabledDesignSystems ?? []).includes(d.id),
      ),
    [designSystems, config.disabledDesignSystems],
  );

  const handleCloseSettings = () => {
    // Closing Settings is still the canonical "I'm done" gesture now that
    // there is no global Save button. The same close path is shared by the
    // legacy modal and the full-page route. We mark onboardingCompleted on
    // close so the welcome modal stops re-prompting on every refresh,
    // regardless of whether the user changed anything during the session.
    const next = resolveSettingsCloseConfig(config, latestPersistedConfigRef.current);
    if (!next.onboardingCompleted || !config.onboardingCompleted) {
      latestPersistedConfigRef.current = next;
      saveConfig(next);
      void syncConfigToDaemon(next);
      setConfig(next);
    }
    setSettingsOpen(false);
    settingsDraftConfigRef.current = null;
    setSettingsHighlight(null);
    if (route.kind === 'home' && route.view === 'settings') {
      navigate({ kind: 'home', view: 'home' });
    }
  };

  const handleResetOnboarding = useCallback((next: AppConfig) => {
    latestPersistedConfigRef.current = next;
    saveConfig(next);
    void syncConfigToDaemon(next, { allowOnboardingReset: true });
    setConfig(next);
    setSettingsOpen(false);
    settingsDraftConfigRef.current = null;
    setSettingsHighlight(null);
    navigate({ kind: 'home', view: 'onboarding' });
  }, []);

  const renderSettingsSurface = (presentation: 'modal' | 'page') => (
    <SettingsDialog
      presentation={presentation}
      initial={config}
      agents={agents}
      agentsLoading={agentsLoading}
      daemonLive={daemonLive}
      appVersionInfo={appVersionInfo}
      welcome={presentation === 'modal' ? settingsWelcome : false}
      initialSection={settingsInitialSection}
      initialHighlight={settingsHighlight}
      composioConfigLoading={composioConfigLoading}
      onPersist={handleConfigPersist}
      onDraftChange={handleSettingsDraftChange}
      onPersistComposioKey={handleConfigPersistComposioKey}
      onClose={handleCloseSettings}
      onResetOnboarding={handleResetOnboarding}
      onRefreshAgents={refreshAgents}
      onAmrLoginStatusChange={handleAmrLoginStatusChange}
      daemonMediaProviders={daemonMediaProviders}
      daemonMediaProvidersFetchState={daemonMediaProvidersFetchState}
      mediaProvidersNotice={mediaProvidersNotice}
      onReloadMediaProviders={reloadMediaProvidersFromDaemon}
      onProjectsRefresh={refreshProjects}
      onSkillsChanged={handleSkillsChanged}
      onDesignSystemsChanged={handleDesignSystemsChanged}
      onDesignSystemImportRebuildJob={handleDesignSystemImportRebuildJob}
      providerModelsCache={providerModelsCache}
      onProviderModelsCacheChange={setProviderModelsCache}
    />
  );

  // Phase 2B / spec §11.6 — marketplace deep UI dispatch. The
  // /marketplace and /marketplace/:id routes render outside the
  // EntryView / ProjectView split so the discovery surface stays
  // independent of any active project.
  let appMain: ReactNode;
  const pendingFirstRunOnboardingRoute =
    route.kind === 'home' &&
    route.view === 'home' &&
    config.onboardingCompleted !== true &&
    !daemonConfigLoaded;
  if (pendingFirstRunOnboardingRoute) {
    appMain = (
      <div className="entry-shell entry-shell--no-header">
        <CenteredLoader label={t('entry.loadingWorkspace')} />
      </div>
    );
  } else if (route.kind === 'marketplace') {
    appMain = <MarketplaceView />;
  } else if (route.kind === 'marketplace-detail') {
    appMain = <PluginDetailView pluginId={route.pluginId} />;
  } else if (route.kind === 'collab-demo') {
    appMain = <CollabDemoView projectId={route.projectId} />;
  } else if (route.kind === 'community') {
    appMain = (
      <CommunityView
        onRemixTemplate={({ templateId, prompt }) => {
          // Remix carries the template's PROJECT along, not just its prompt:
          // duplicate the plugin's example artifact into a fresh project,
          // seed the composer with the template prompt, then open it on the
          // copied entry file (keep in sync with the EntryShell-embedded
          // community tab). Templates without a duplicable artifact fall
          // back to the old prompt-only project.
          void (async () => {
            const name = summarizeProjectNameFromPrompt(prompt) || t('common.untitled');
            try {
              // One resolved authority for BOTH requests: the create binds the
              // copied project to this workspace, and the seed patch is then
              // authorized against that same binding. A headerless create is
              // read by the daemon as a legacy caller and leaves the project
              // bound to no workspace at all, which is what kept remixed
              // projects out of the member's own 草稿 list.
              const writeContext = resolvedWorkspaceContextForWrite(workspaceContextState);
              const result = await duplicatePluginAsProject(templateId, { name }, writeContext);
              const seeded = await patchProject(
                result.projectId,
                { pendingPrompt: prompt },
                writeContext,
              );
              if (!seeded) {
                // The project itself exists and is bound — only the prompt seed
                // was refused. Keep the user on it (retrying through the catch
                // below would leave the copy orphaned and create a second,
                // empty project) and surface the dropped seed instead of
                // discarding it silently.
                console.error('Community remix: could not seed the template prompt.');
              }
              navigate({
                kind: 'project',
                projectId: result.projectId,
                conversationId: result.conversationId,
                fileName: result.relPath,
              });
            } catch {
              await handleCreateProject({
                name,
                skillId: null,
                designSystemId: null,
                metadata: { kind: 'other', nameSource: 'prompt' },
                pendingPrompt: prompt,
              });
            }
          })();
        }}
        onUsePrompt={(prompt) => {
          // Seed the Home composer with the template's starting prompt, then hand
          // the user into Home to review + send it (instead of dropping the pick).
          seedHomeComposerPrompt(prompt);
          navigate({ kind: 'home', view: 'home' });
        }}
      />
    );
  } else if (route.kind === 'design-system-create') {
    appMain = (
      <DesignSystemCreationFlow
        onBack={() => navigate({ kind: 'home', view: 'design-systems' })}
        designSystems={enabledDS}
        onCreated={(projectId, project, conversationId) => {
          if (project) {
            setProjects((curr) => [
              project,
              ...curr.filter((p) => p.id !== project.id),
            ]);
          }
          navigate({ kind: 'project', projectId, conversationId: conversationId ?? null, fileName: null });
        }}
        onProjectPrepared={(project) => {
          setProjects((curr) => [
            project,
            ...curr.filter((p) => p.id !== project.id),
          ]);
        }}
        onSystemsRefresh={refreshDesignSystems}
        config={config}
        onOpenConnectorsTab={() => openSettings('composio')}
      />
    );
  } else if (route.kind === 'design-system-detail') {
    appMain = (
      <DesignSystemDetailView
        id={route.designSystemId}
        selectedId={config.designSystemId}
        config={config}
        agents={agents}
        onBack={() => navigate({ kind: 'home', view: 'design-systems' })}
        onOpenProject={(projectId) => void handleOpenProject(projectId)}
        onSetDefault={handleChangeDefaultDesignSystem}
        onSystemsRefresh={refreshDesignSystems}
        onProjectsRefresh={refreshProjects}
        initialRevisionJob={pendingDesignSystemRevisionJobs[route.designSystemId] ?? null}
        onInitialRevisionJobConsumed={(jobId) =>
          handleDesignSystemRevisionJobConsumed(route.designSystemId, jobId)
        }
      />
    );
  } else if (route.kind === 'home' && route.view === 'settings') {
    appMain = renderSettingsSurface('page');
  } else if (activeProject) {
    appMain = (
      <ProjectView
        key={projectViewAuthorizationLifetimeKey(activeProject.id, workspaceContext)}
        project={activeProject}
        projectAuthorizationKey={
          activeProjectAuthorizationKey ?? activeProject.id
        }
        authoritativeProjectName={activeAuthoritativeProjectName}
        resolveAuthoritativeProjectName={resolveAuthoritativeProjectName}
        routeFileName={route.kind === 'project' ? route.fileName : null}
        routeConversationId={route.kind === 'project' ? route.conversationId : null}
        config={config}
        agents={agents}
        skills={enabledFunctionalSkills}
        designTemplates={designTemplates}
        designSystems={designSystems}
        daemonLive={daemonLive}
        onModeChange={handleModeChange}
        onAgentChange={handleAgentChange}
        onAgentModelChange={handleAgentModelChange}
        onApiModelChange={handleApiModelChange}
        onRefreshAgents={refreshAgents}
        onOpenSettings={openSettings}
        onOpenAmrSettings={openAmrSettings}
        onOpenMcpSettings={openMcpSettings}
        onBrowsePlugins={openPluginRegistry}
        onOpenConnectors={openConnectorIntegrations}
        onAdoptPetInline={handleAdoptPet}
        onTogglePet={handleTogglePet}
        onOpenPetSettings={openPetSettings}
        onBack={handleBack}
        onClearPendingPrompt={handleClearPendingPrompt}
        onTouchProject={handleTouchProject}
        onProjectChange={handleProjectChange}
        onProjectsRefresh={refreshProjects}
        onDeleteProject={handleDeleteProject}
        onChangeDefaultDesignSystem={handleChangeDefaultDesignSystem}
        onDesignSystemsRefresh={refreshDesignSystems}
        onCreateProjectFromDesignSystem={handleCreateProjectFromDesignSystem}
        onCreateDesignSystemFromProject={handleCreateDesignSystemFromProject}
        onDuplicateProject={handleDuplicateProject}
      />
    );
  } else {
    appMain = (
      <EntryView
        skills={enabledSkills}
        designTemplates={enabledDesignTemplates}
        designSystems={enabledDS}
        projects={projects}
        templates={templates}
        onDeleteTemplate={handleDeleteTemplate}
        promptTemplates={promptTemplates}
        defaultDesignSystemId={config.designSystemId}
        agents={agents}
        agentsLoading={agentsLoading}
        amrLoggedIn={amrLoginStatus?.loggedIn ?? null}
        config={config}
        providerModelsCache={providerModelsCache}
        onProviderModelsCacheChange={setProviderModelsCache}
        integrationInitialTab={integrationInitialTab}
        composioConfigLoading={composioConfigLoading}
        daemonLive={daemonLive}
        onModeChange={handleModeChange}
        onAgentChange={handleAgentChange}
        onAgentModelChange={handleAgentModelChange}
        onApiProtocolChange={handleApiProtocolChange}
        onApiModelChange={handleApiModelChange}
        onConfigPersist={handleConfigPersist}
        onSkillsRefresh={refreshSkills}
        onSkillsChanged={handleSkillsChanged}
        onRefreshAgents={refreshAgents}
        skillsLoading={
          workspaceSkills.identity !== currentWorkspaceIdentity || skillsLoading
        }
        designSystemsLoading={dsLoading}
        projectsLoading={projectsLoading}
        promptTemplatesLoading={promptTemplatesLoading}
        onCreateProject={handleCreateProject}
        onCreatePluginShareProject={handleCreatePluginShareProject}
        onImportClaudeDesign={handleImportClaudeDesign}
        onImportFolder={handleImportFolder}
        onImportFolderResponse={handleImportFolderResponse}
        onOpenProject={handleOpenProject}
        onOpenLiveArtifact={handleOpenLiveArtifact}
        onDeleteProject={handleDeleteProject}
        onDuplicateProject={handleDuplicateProject}
        onRenameProject={handleRenameProject}
        onProjectsRefresh={refreshProjectsStrict}
        onTeamProjectContentReady={handleTeamProjectContentReady}
        onChangeDefaultDesignSystem={handleChangeDefaultDesignSystem}
        onCreateDesignSystem={() => {
          setPendingDesignSystemCreateEntry('design_systems_page');
          navigate({ kind: 'design-system-create' });
        }}
        onOpenDesignSystem={(id: string) => navigate({ kind: 'design-system-detail', designSystemId: id })}
        onDesignSystemsRefresh={refreshDesignSystems}
        onPersistComposioKey={handleConfigPersistComposioKey}
        onOpenSettings={openSettings}
        onCompleteOnboarding={handleCompleteOnboarding}
        artifactUpgradeSlot={
          amrArtifactUpgradeHomeOffer ? (
            <AmrArtifactUpgradeHomeCard
              key={amrArtifactUpgradeHomeOffer.sessionKey}
              profile={amrLoginStatus?.profile ?? null}
              metricsConsent={config.telemetry?.metrics === true}
              installationId={config.installationId}
              onViewArtifact={() => {
                if (
                  !amrArtifactUpgradeHomeOffer.projectId
                  || !amrArtifactUpgradeHomeOffer.conversationId
                ) {
                  navigate({ kind: 'home', view: 'projects' });
                  return;
                }
                navigate({
                  kind: 'project',
                  projectId: amrArtifactUpgradeHomeOffer.projectId,
                  conversationId: amrArtifactUpgradeHomeOffer.conversationId,
                  fileName: amrArtifactUpgradeHomeOffer.fileName,
                });
              }}
              onDismiss={() => {
                if (amrArtifactUpgradeHomeMock) return;
                setAmrArtifactUpgradeHomeOffer((current) =>
                  current?.sessionKey === amrArtifactUpgradeHomeOffer.sessionKey
                    ? null
                    : current,
                );
              }}
            />
          ) : undefined
        }
      />
    );
  }
  return (
    <>
      <div
        className={`workspace-shell workspace-shell--${clientType}`}
        data-client-type={clientType}
        data-host-platform={hostPlatform}
      >
        <WorkspaceTabsBar
          route={route}
          projects={projects}
          onboardingCompleted={config.onboardingCompleted === true}
          identityScopeKey={identityScopeKey}
        />
        <div className="workspace-shell__body">
          {appMain}
        </div>
      </div>
      {clientType === 'desktop' ? null : (
        <PetOverlay
          pet={config.pet?.enabled ? config.pet : undefined}
          taskCenter={petTaskCenter}
          onOpenProject={handleOpenProject}
          dockLine
        />
      )}
      <TooltipLayer />
      <UpdateDialog />
      <AmrArtifactUpgradeGate
        homeVisible={route.kind === 'home' && route.view === 'home'}
        activeProjectId={route.kind === 'project' ? route.projectId : null}
        activeConversationId={
          route.kind === 'project' ? route.conversationId ?? null : null
        }
        activeFileName={route.kind === 'project' ? route.fileName : null}
        plan={resolvedAmrPlan}
        planResolved={
          amrLoginStatus !== null
          && (amrLoginStatus.loggedIn === false || resolvedAmrPlan !== null)
        }
        profile={amrLoginStatus?.profile ?? null}
        metricsConsent={config.telemetry?.metrics === true}
        installationId={config.installationId}
        onHomeOfferChange={
          amrArtifactUpgradeHomeMock
            ? undefined
            : setAmrArtifactUpgradeHomeOffer
        }
      />
      <AnimatePresence>
      {settingsOpen ? (
        renderSettingsSurface('modal')
      ) : null}
      </AnimatePresence>
      <MemoryToast onOpenMemory={() => openSettings('memory')} />
      {workingDirError ? (
        <Toast
          message={workingDirError}
          role="alert"
          onDismiss={() => setWorkingDirError(null)}
        />
      ) : null}
      {projectOpenError ? (
        <Toast
          message={projectOpenError}
          role="alert"
          tone="error"
          onDismiss={() => setProjectOpenError(null)}
        />
      ) : null}
      {/* First-run privacy consent banner. It waits for daemon config
          hydration because privacyDecisionAt is daemon-owned and stripped
          from localStorage. It waits for `onboardingCompleted` so first-run
          users see the welcome panel before the disclosure (Skip and
          finish both flip the flag). Independent of Settings: z-index in
          index.css sits above modal backdrops so opening Settings does
          not hide the banner. */}
      <AnimatePresence>
      {showPrivacyConsent ? (
        <motion.div
          initial={{ opacity: 0, y: 20, scale: 0.97 }}
          animate={{ opacity: 1, y: 0, scale: 1 }}
          exit={{ opacity: 0, y: 10, scale: 0.97 }}
          transition={{ type: 'spring', stiffness: 400, damping: 28 }}
        >
        <PrivacyConsentModal
          onShare={() => {
            // The banner owns only the privacy decision; it does not drive
            // navigation. Choosing Share keeps the current anonymous identity
            // when one already exists and enables the telemetry surface.
            handlePrivacyConsentChoice(true);
          }}
          onDecline={() => {
            handlePrivacyConsentChoice(false);
          }}
        />
      </motion.div>
      ) : null}
      </AnimatePresence>
    </>
  );
}

function generateInstallationIdSafe(): string {
  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
    return crypto.randomUUID();
  }
  return `inst-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
}