Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

45.1 KB
Raw Blame
// @vitest-environment-options {"settings":{"navigation":{"disableChildFrameNavigation":true}}}
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { MemoryRouter } from 'react-router';
import { awaitEnabled, findEnabledByRole } from '../test/enabledBarrier.js';
import { mockFrameWindows } from '../test/mockFrameWindows.js';

vi.mock('../services/api', () => ({
  getApp: vi.fn(),
  getAppRepositorySources: vi.fn(),
  getEidoverseWorldProjectionStatus: vi.fn(),
  getEidoverseWorldStatus: vi.fn(),
  getEidoverseDestinations: vi.fn(async () => ({ destinations: [] })),
  departEidoverse: vi.fn(),
  getInstanceFeatures: vi.fn(),
  projectEidoverseWorld: vi.fn(),
  startApp: vi.fn(),
  startEidoverseHost: vi.fn(),
  updateEidoverseWorldConfig: vi.fn(),
}));

vi.mock('../services/socket', async () => {
  const { EventEmitter } = await import('node:events');
  return { default: new EventEmitter() };
});
import socket from '../services/socket';
afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });

vi.mock('../components/BrailleSpinner', () => ({
  default: ({ text }) => <span>{text}</span>,
}));

import * as api from '../services/api';
import Eidoverse, { hostUrlFor } from './Eidoverse';

const setup = { installed: true, appId: 'app-eidoverse', uiPort: 8940, runtimeStatus: 'online' };
const featureResponse = (overrides = {}) => ({
  features: [{ id: 'eidoverse', enabled: false, setup: { ...setup, ...overrides } }],
});

const includes = {
  apps: true, agents: true, tasks: true, features: true, peers: true, health: true,
  productivity: true, activity: true, goals: true, memory: true, storage: true, jira: true, operations: true,
};
const limits = {
  apps: 8, agents: 6, tasks: 6, features: 4, peers: 4, health: 1,
  productivity: 1, activity: 3, goals: 4, memory: 3, storage: 4, jira: 3, operations: 1,
};
const scale = Object.fromEntries([
  'app', 'agent', 'task', 'feature', 'peer', 'health', 'productivity',
  'activity', 'goal', 'memory', 'storage', 'jira', 'operations',
].map((kind) => [kind, 1]));
const slot = (name) => ({
  preferredPaths: [`eidoverse/assets/models/${name}.glb`],
  fallbackQueries: [`example ${name}`],
  requiredTokens: [name],
  excludedTokens: ['car'],
  maxBytes: 20_000_000,
  format: 'glb',
  animation: 'optional',
  sourcePolicy: 'library-only',
  fallback: 'eidoverse/assets/models/orb.glb',
});
const assetSlots = Object.fromEntries([
  'nexus', 'app', 'agent', 'task', 'goal', 'memory', 'storage', 'peer', 'activity', 'district',
].map((name) => [name, slot(name)]));

const recipe = {
  version: 2,
  name: 'Luminous Systems Garden',
  maxEntities: 48,
  includes,
  limits,
  scale,
  districts: [
    { id: 'nexus', label: 'PortOS Nexus', anchor: [0, 0, 0], sources: ['health', 'operations', 'features'], accent: '#ffb86b' },
    { id: 'apps', label: 'App Terraces', anchor: [-30, 0, -18], sources: ['apps'], accent: '#65d9ff' },
    { id: 'agents', label: 'Agent Foundry', anchor: [0, 0, -34], sources: ['agents', 'tasks'], accent: '#a78bfa' },
  ],
  environment: {
    terrain: { seed: 'example', size: 180, segments: 96, amplitude: 1.4, flatRadius: 48, layers: [{ color: '#0d1629', repeat: 22 }] },
    sky: { system: 'skymesh', hours: 7.2, azimuth: 145, sun: 1.35, ambient: 1.2, fill: 1.1, exposure: 1.08, fog: 0.42, clouds: 'cirrus', weather: 'clear' },
    grass: { species: 'grass', width: 154, depth: 144, center: [0, 0], height: 0.22, color: 'gray-green', density: 0.45 },
    lights: [],
  },
  assetRecipe: { version: 2, slots: assetSlots },
  assets: { app: 'eidoverse/assets/models/app.glb' },
};

const design = {
  name: recipe.name,
  selectedVersion: 2,
  lastAppliedVersion: 1,
  pendingVersion: 2,
  assetRecipeVersion: 2,
  maxEntities: 48,
  districts: recipe.districts,
  assetResolutions: {
    app: { path: 'eidoverse/assets/models/app.glb', source: 'preferred', bytes: 4_000_000, catalogFingerprint: 'example' },
  },
  migrationReport: { status: 'ready', fromDesignVersion: 1, toDesignVersion: 2, preservedOverrides: ['limits.apps'] },
  reconciliation: { status: 'pending', checkpoint: 'migration-complete', error: null },
};

const worldResponse = {
  world: 'portos',
  identity: { name: 'example-portos-user' },
  human: { name: 'example-portos-user' },
  cos: { id: 'portos-cos', enabled: true },
  recipe,
  design,
  projection: {
    lastSummary: {
      liveEntityCount: 12,
      sourceAvailability: { apps: true, agents: false },
      sourceCounts: { apps: 3, agents: null },
    },
  },
  presence: { connected: false },
};

const renderPage = (entry = '/eidoverse') => render(
  <MemoryRouter initialEntries={[entry]}>
    <Eidoverse />
  </MemoryRouter>,
);

describe('Eidoverse hosted page', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    mockFrameWindows();
    api.getInstanceFeatures.mockResolvedValue(featureResponse());
    api.getApp.mockResolvedValue({ id: setup.appId, overallStatus: 'online' });
    api.getAppRepositorySources.mockResolvedValue({ updateAvailable: false, sources: [] });
    api.startApp.mockResolvedValue({ success: true, results: {} });
    api.startEidoverseHost.mockResolvedValue({ running: true, protocol: 'http', port: 5563 });
    api.getEidoverseWorldStatus.mockResolvedValue(worldResponse);
    api.getEidoverseWorldProjectionStatus.mockResolvedValue({
      design: {
        lastAppliedVersion: design.lastAppliedVersion,
        pendingVersion: design.pendingVersion,
        reconciliation: design.reconciliation,
      },
      projection: worldResponse.projection,
    });
    api.projectEidoverseWorld.mockResolvedValue({
      success: true,
      projection: { lastSuccessAt: '2026-01-01T00:00:00.000Z', lastSummary: worldResponse.projection.lastSummary },
      presence: { connected: true, role: 'owner' },
      design: { ...design, lastAppliedVersion: 2, pendingVersion: null, reconciliation: { status: 'complete', checkpoint: 'projection-committed' } },
      recipe,
    });
    api.updateEidoverseWorldConfig.mockResolvedValue({ ...worldResponse, human: worldResponse.identity });
  });

  it('loads the installed managed app without covering Eidoverse controls', async () => {
    const user = userEvent.setup();
    renderPage();

    const frame = await screen.findByTitle('Eidoverse Worlds');
    expect(frame).toHaveAttribute('src', `${window.location.protocol}//${window.location.host}/eidoverse-host/?world=portos&name=example-portos-user`);
    expect(screen.getByRole('button', { name: 'Refresh world' }))
      .toHaveAttribute('aria-label', 'Refresh world');
    expect(screen.getByRole('button', { name: 'Refresh world' })).not.toHaveClass('port-media-overlay');
    const labels = screen.getByRole('button', { name: 'Show object labels' });
    expect(labels).toHaveAttribute('aria-pressed', 'false');
    await user.click(labels);
    expect(labels).toHaveAttribute('aria-pressed', 'true');
    await user.click(labels);
    expect(labels).toHaveAttribute('aria-pressed', 'false');
    expect(screen.queryByText('Your PortOS, made spatial')).not.toBeInTheDocument();
    expect(screen.queryByRole('region', { name: 'PortOS district legend' })).not.toBeInTheDocument();
    expect(screen.queryByText('12/48 live signals')).not.toBeInTheDocument();
    expect(screen.getByRole('link', { name: 'Open Eidoverse without PortOS controls' }))
      .toHaveAttribute('href', '/eidoverse/solo');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledWith({ silent: true }));
    expect(screen.getByRole('link', { name: 'Manage Eidoverse app' })).toHaveAttribute('href', '/apps/app-eidoverse/overview');

    await user.click(screen.getByRole('button', { name: 'World controls' }));
    expect(screen.getByText('12 shown')).toBeInTheDocument();
    expect(screen.getByText(/Up to 48 can be displayed at once\. This is scene capacity, not a health score\./)).toBeInTheDocument();
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    expect(screen.getByText(/12 are shown now; the 48-indicator limit keeps the scene legible/)).toBeInTheDocument();
    expect(screen.getByText('App Terraces')).toBeInTheDocument();
  });

  it('keeps label visibility browser-only and saves or clears explicit aliases from the object legend', async () => {
    const user = userEvent.setup();
    const key = 'app-0123456789ab';
    const object = {
      id: 'portos-design-v2-signal-app-example', kind: 'app', resourceKey: key,
      districtId: 'apps', name: 'Managed app 012345', description: 'An app this install manages. Data is current.',
      visibility: 'nearby', route: '/apps',
      asset: { slot: 'app', path: 'eidoverse/assets/models/orb.glb', reason: 'catalog-fallback' },
    };
    const summary = { ...worldResponse.projection.lastSummary, objects: [object] };
    api.projectEidoverseWorld.mockResolvedValue({
      success: true, recipe, design, projection: { lastSummary: summary },
    });
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledTimes(1));
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    api.projectEidoverseWorld.mockClear();
    await user.selectOptions(screen.getByLabelText('Floating labels'), 'off');
    expect(api.updateEidoverseWorldConfig).not.toHaveBeenCalled();
    expect(api.projectEidoverseWorld).not.toHaveBeenCalled();
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    const legend = screen.getByRole('region', { name: 'Projected object labels' });
    expect(within(legend).getByText('Managed app 012345')).toBeInTheDocument();
    expect(within(legend).getByText('Fallback — available library asset')).toBeInTheDocument();
    const alias = screen.getByLabelText('Display alias for app 0123456789ab');
    expect(alias).toHaveValue('');
    await user.type(alias, 'Example tower');
    api.updateEidoverseWorldConfig.mockRejectedValueOnce(new Error('Example save failure'));
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    expect(await screen.findByText('Example save failure')).toBeInTheDocument();
    expect(alias).toHaveValue('Example tower');
    expect(api.updateEidoverseWorldConfig).toHaveBeenLastCalledWith(
      expect.objectContaining({ labelAliases: { [key]: 'Example tower' } }), { silent: true },
    );
    expect(api.projectEidoverseWorld).not.toHaveBeenCalled();
    await user.clear(alias);
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenLastCalledWith(
      expect.objectContaining({ labelAliases: {} }), { silent: true },
    ));
  });

  it('clears aliases for absent objects without resetting and distinguishes identical display names', async () => {
    const user = userEvent.setup();
    const keys = ['app-0123456789ab', 'app-abcdef012345'];
    const absentKey = 'agent-0123456789ab';
    const labelAliases = { [keys[0]]: 'Example tower', [keys[1]]: 'Example tower', [absentKey]: 'Example retired beacon' };
    const objects = keys.map((resourceKey) => ({
      id: `example-${resourceKey}`, resourceKey, kind: 'app', districtId: 'apps',
      name: 'Example tower', description: 'An app this install manages.', visibility: 'nearby',
    }));
    const saved = { ...worldResponse, design: { ...design, labelAliases }, projection: { lastSummary: { objects } } };
    api.getEidoverseWorldStatus.mockResolvedValueOnce(saved);
    api.projectEidoverseWorld.mockResolvedValueOnce({ success: true, ...saved });
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    expect(screen.getByLabelText('Display alias for app 0123456789ab')).toHaveValue('Example tower');
    expect(screen.getByLabelText('Display alias for app abcdef012345')).toHaveValue('Example tower');
    const savedAliases = screen.getByRole('region', { name: 'Saved aliases without a current object' });
    const absentAlias = within(savedAliases).getByLabelText('Display alias for agent 0123456789ab');
    await user.clear(absentAlias);
    expect(absentAlias).toHaveFocus();
    expect(absentAlias).toBeInTheDocument();
    await user.type(absentAlias, 'Example renamed beacon');
    expect(absentAlias).toHaveValue('Example renamed beacon');
    await user.clear(absentAlias);
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalled());
    const patch = api.updateEidoverseWorldConfig.mock.calls.at(-1)[0];
    expect(patch.labelAliases).toEqual({ [keys[0]]: 'Example tower', [keys[1]]: 'Example tower' });
    expect(patch).not.toHaveProperty('reset');
  });

  it('preserves saved aliases when the initial projection fails and another setting is saved', async () => {
    const user = userEvent.setup();
    const labelAliases = { 'app-0123456789ab': 'Example saved tower' };
    api.getEidoverseWorldStatus.mockResolvedValueOnce({
      ...worldResponse, design: { ...design, labelAliases },
    });
    api.projectEidoverseWorld.mockRejectedValueOnce(new Error('Example initial projection failure'));
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    expect(await screen.findByText('Example initial projection failure')).toBeInTheDocument();
    await user.type(screen.getByLabelText('My Eidoverse name'), '-edited');
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledWith(
      expect.objectContaining({
        labelAliases,
        humanName: 'example-portos-user-edited',
      }), { silent: true },
    ));
  });

  it('saves a username during projection without a recipe and displays the automatic mind name', async () => {
    const user = userEvent.setup();
    api.getEidoverseWorldStatus.mockResolvedValueOnce({ ...worldResponse, recipe: null, cos: { id: 'Helm' } });
    let finishProjection;
    api.projectEidoverseWorld.mockReturnValueOnce(new Promise((resolve) => { finishProjection = resolve; }));
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    expect(screen.getByLabelText('CoS / Persistent Mind name')).toHaveValue('Helm');
    expect(screen.getByLabelText('CoS / Persistent Mind name')).toHaveAttribute('readonly');
    await user.clear(screen.getByLabelText('My Eidoverse name'));
    await user.type(screen.getByLabelText('My Eidoverse name'), 'Example User');
    const save = screen.getByRole('button', { name: 'Save and project' });
    expect(save).toBeEnabled();
    await user.click(save);
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledWith(
      expect.objectContaining({ humanName: 'Example User' }), { silent: true },
    ));
    expect(api.updateEidoverseWorldConfig.mock.calls[0][0]).not.toHaveProperty('cosId');
    expect(api.updateEidoverseWorldConfig.mock.calls[0][0]).not.toHaveProperty('recipe');
    await act(async () => finishProjection({ success: true }));
  });

  it('shows a renderer update link while preserving the saved recipe on older clients', async () => {
    const user = userEvent.setup();
    const oldDesign = { ...design, reconciliation: { ...design.reconciliation,
      runtimeVersion: { sha: 'example-old-build', capabilities: { objectLabels: null } } } };
    api.projectEidoverseWorld.mockResolvedValue({ success: true, recipe, design: oldDesign });
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    expect(await screen.findByText(/does not report object-label support/)).toBeInTheDocument();
    expect(screen.getByRole('link', { name: 'Manage renderer updates' })).toHaveAttribute('href', '/apps/app-eidoverse/overview');
    expect(screen.getByText('Luminous Systems Garden')).toBeInTheDocument();
  });

  it('keeps an unknown indicator count distinct from a projected empty world', async () => {
    const user = userEvent.setup();
    api.getEidoverseWorldStatus.mockResolvedValueOnce({
      ...worldResponse,
      projection: { lastSummary: null },
    });
    api.projectEidoverseWorld.mockResolvedValueOnce({
      success: true,
      projection: { lastSummary: null },
      presence: { connected: true, role: 'owner' },
      design,
      recipe,
    });
    renderPage();

    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    expect(screen.getByText('Waiting for projection')).toBeInTheDocument();
    expect(screen.queryByText('0 shown')).not.toBeInTheDocument();
  });

  it('starts a stopped managed app before connecting', async () => {
    api.getApp.mockResolvedValue({ id: setup.appId, overallStatus: 'stopped' });
    renderPage();

    await screen.findByTitle('Eidoverse Worlds');
    expect(api.startApp).toHaveBeenCalledWith('app-eidoverse', { silent: true });
    expect(api.startEidoverseHost).toHaveBeenCalledAfter(api.startApp);
  });

  it('raises the out-of-date advisory here, where a user living in the world will see it', async () => {
    api.getAppRepositorySources.mockResolvedValue({
      updateAvailable: true,
      sources: [{
        id: 'primary',
        label: 'Eidoverse Worlds',
        origin: { hasOrigin: true, isFork: false, isUpstream: true, head: 'a'.repeat(40) },
        localVsOrigin: { ahead: 0, behind: 2, state: 'behind' },
      }],
    });
    api.getInstanceFeatures.mockImplementation(async () => {
      await new Promise((resolve) => setTimeout(resolve, 0));
      return featureResponse();
    });
    renderPage();

    await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() =>
      expect(api.getAppRepositorySources).toHaveBeenCalledWith('app-eidoverse', { silent: true })
    );
    expect(await screen.findByText(/Eidoverse Worlds is 2 commits behind its origin/)).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /Update Eidoverse/ })).toBeInTheDocument();
  });

  it('never checks freshness for an install that has no Eidoverse yet', async () => {
    api.getInstanceFeatures.mockResolvedValue(featureResponse({ installed: false, appId: 'app-eidoverse' }));
    renderPage();

    await screen.findByRole('link', { name: 'Open Features' });
    expect(api.getAppRepositorySources).not.toHaveBeenCalled();
  });

  it('sends an uninstalled user to Features', async () => {
    api.getInstanceFeatures.mockResolvedValue(featureResponse({ installed: false, appId: null }));
    renderPage();

    expect(await screen.findByRole('link', { name: 'Open Features' })).toHaveAttribute('href', '/settings/features');
    expect(api.getApp).not.toHaveBeenCalled();
  });

  it('surfaces a managed-app start failure and retries', async () => {
    api.getApp.mockResolvedValue({ id: setup.appId, overallStatus: 'stopped' });
    api.startApp
      .mockResolvedValueOnce({ success: true, results: { eidoverse: { success: false, error: 'Example startup failure' } } })
      .mockResolvedValueOnce({ success: true, results: { eidoverse: { success: true } } });
    const user = userEvent.setup();
    renderPage();

    expect(await screen.findByRole('alert')).toHaveTextContent('Example startup failure');
    await user.click(screen.getByRole('button', { name: 'Retry' }));
    await screen.findByTitle('Eidoverse Worlds');
    expect(api.startApp).toHaveBeenCalledTimes(2);
  });

  it('uses the same-origin /eidoverse-host path for an HTTPS MagicDNS page', () => {
    expect(hostUrlFor(
      { running: true, protocol: 'https', port: 5563 },
      setup,
      { protocol: 'https:', hostname: 'host-alpha.example-tailnet.ts.net', host: 'host-alpha.example-tailnet.ts.net' },
    )).toBe('https://host-alpha.example-tailnet.ts.net/eidoverse-host/');
    expect(() => hostUrlFor(
      { running: true, protocol: 'http', port: 5563 },
      setup,
      { protocol: 'https:', hostname: 'host-alpha.example-tailnet.ts.net', host: 'host-alpha.example-tailnet.ts.net' },
    )).toThrow(/shared certificate/);
  });

  // Same-origin path keeps a single-port tailcat forward working (UI host+port
  // only). The one escape is an HTTP page in front of an HTTPS-only host
  // certificate that does not cover the hostname — loopback mirror / some Vite
  // setups — where we still fall back to the direct :uiPort load.
  it('routes through /eidoverse-host on the UI origin, with a direct-uiPort escape for HTTP+HTTPS-cert', () => {
    expect(hostUrlFor(
      { running: true, protocol: 'http', port: 5563 },
      setup,
      { protocol: 'http:', hostname: 'host-alpha.example-tailnet.ts.net', host: 'host-alpha.example-tailnet.ts.net:5555' },
    )).toBe('http://host-alpha.example-tailnet.ts.net:5555/eidoverse-host/');
    expect(hostUrlFor(
      { running: true, protocol: 'http', port: 5563 },
      setup,
      { protocol: 'http:', hostname: '127.0.0.1', host: '127.0.0.1:15555' },
    )).toBe('http://127.0.0.1:15555/eidoverse-host/');
    expect(hostUrlFor(
      { running: true, protocol: 'https', port: 5563 },
      setup,
      { protocol: 'http:', hostname: 'localhost', host: 'localhost:5553' },
    )).toBe(`http://localhost:${setup.uiPort}/`);
  });

  it('opens World only as an in-app chromeless route that reuses the same host iframe', async () => {
    renderPage('/eidoverse/solo');

    const frame = await screen.findByTitle('Eidoverse Worlds');
    expect(frame).toHaveAttribute(
      'src',
      `${window.location.protocol}//${window.location.host}/eidoverse-host/?world=portos&name=example-portos-user`,
    );
    expect(screen.getByRole('heading', { name: 'Eidoverse · world only' })).toBeInTheDocument();
    expect(screen.getByRole('link', { name: 'Back to Eidoverse controls' })).toHaveAttribute('href', '/eidoverse');
    expect(screen.queryByRole('link', { name: 'Open Eidoverse without PortOS controls' })).not.toBeInTheDocument();
    expect(screen.queryByRole('button', { name: 'World controls' })).not.toBeInTheDocument();
    expect(screen.queryByText('Your PortOS, made spatial')).not.toBeInTheDocument();

    const source = frame.contentWindow;
    const post = vi.spyOn(source, 'postMessage').mockImplementation(() => {});
    fireEvent.load(frame);
    const [hello] = post.mock.calls.at(-1);
    act(() => window.dispatchEvent(new MessageEvent('message', {
      source, origin: new URL(frame.src).origin,
      data: { type: 'eidoverse:ready', version: 1, nonce: hello.nonce,
        capabilities: { identityRenameRequest: 1 } },
    })));
    act(() => window.dispatchEvent(new MessageEvent('message', {
      source, origin: new URL(frame.src).origin,
      data: { type: 'eidoverse:identity-rename', version: 1, nonce: hello.nonce,
        name: 'Example Solo Visitor' },
    })));
    expect(await screen.findByLabelText('My Eidoverse name')).toHaveValue('Example Solo Visitor');
    expect(screen.getByRole('heading', { name: 'Eidoverse · world only' })).toBeInTheDocument();
  });

  it('keeps a successful local save visible when projection fails', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledTimes(1));
    api.projectEidoverseWorld.mockRejectedValueOnce(new Error('Example projection failure'));

    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('button', { name: 'Save and project' }));

    expect(await screen.findByText('Saved locally and queued for projection.')).toBeInTheDocument();
    expect(await screen.findByText('Example projection failure')).toBeInTheDocument();
    expect(screen.getByRole('link', { name: 'Check the Eidoverse runtime' })).toHaveAttribute('href', '/apps/app-eidoverse/overview');
  });

  it('stages a renderer name request in World Design and retains it when save fails', async () => {
    const user = userEvent.setup();
    renderPage();
    const frame = await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    const worldInput = screen.getByLabelText('World name');
    await user.type(worldInput, '-draft');
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    await user.click(screen.getByRole('button', { name: 'Close' }));
    const source = frame.contentWindow;
    const post = vi.spyOn(source, 'postMessage').mockImplementation(() => {});
    fireEvent.load(frame);
    const [hello] = post.mock.calls.at(-1);
    expect(hello.capabilities.identityRenameRequest).toBe(1);
    act(() => window.dispatchEvent(new MessageEvent('message', {
      source, origin: new URL(frame.src).origin,
      data: { type: 'eidoverse:ready', version: 1, nonce: hello.nonce,
        capabilities: { identityRenameRequest: 1 } },
    })));
    act(() => window.dispatchEvent(new MessageEvent('message', {
      source, origin: new URL(frame.src).origin,
      data: { type: 'eidoverse:identity-rename', version: 1, nonce: hello.nonce,
        name: 'Example Visitor' },
    })));

    const nameInput = await screen.findByLabelText('My Eidoverse name');
    expect(screen.getByRole('tab', { name: 'Experience' })).toHaveAttribute('aria-selected', 'true');
    expect(nameInput).toHaveValue('Example Visitor');
    expect(screen.getByLabelText('World name')).toHaveValue('portos-draft');
    expect(screen.getByText(/Save and project leaves the current session and re-enters/)).toBeInTheDocument();

    api.updateEidoverseWorldConfig.mockRejectedValueOnce(new Error('Example identity save failure'));
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    expect(await screen.findByText('Example identity save failure')).toBeInTheDocument();
    expect(nameInput).toHaveValue('Example Visitor');
    expect(screen.getByLabelText('World name')).toHaveValue('portos-draft');
    expect(api.updateEidoverseWorldConfig).toHaveBeenLastCalledWith(
      expect.objectContaining({ world: 'portos-draft', humanName: 'Example Visitor' }),
      { silent: true },
    );
    expect(frame).toHaveAttribute('src', `${window.location.protocol}//${window.location.host}/eidoverse-host/?world=portos&name=example-portos-user`);

    api.updateEidoverseWorldConfig.mockResolvedValueOnce({
      ...worldResponse,
      world: 'portos-draft',
      identity: { name: 'Example Visitor' },
      human: { name: 'Example Visitor' },
    });
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    await waitFor(() => expect(frame).toHaveAttribute(
      'src',
      `${window.location.protocol}//${window.location.host}/eidoverse-host/?world=portos-draft&name=Example+Visitor`,
    ));
  });

  it('keeps newer edits intact while an earlier save is in flight', async () => {
    let resolveSave;
    api.updateEidoverseWorldConfig.mockReturnValueOnce(new Promise((resolve) => { resolveSave = resolve; }));
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));

    const nameInput = screen.getByLabelText('My Eidoverse name');
    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    expect(screen.getByRole('button', { name: 'Saving…' })).toBeDisabled();
    await user.type(nameInput, '-edited');
    resolveSave({ ...worldResponse, human: worldResponse.identity });

    await findEnabledByRole('button', { name: 'Save and project' });
    expect(nameInput).toHaveValue('example-portos-user-edited');
    expect(screen.queryByText('Saved locally and queued for projection.')).not.toBeInTheDocument();
  });

  it('reloads the durable browser identity after a world rename', async () => {
    const user = userEvent.setup();
    const renamed = { ...worldResponse, world: 'portos-two', human: worldResponse.identity };
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    api.updateEidoverseWorldConfig.mockResolvedValueOnce(renamed);

    await user.click(screen.getByRole('button', { name: 'World controls' }));
    const worldInput = screen.getByLabelText('World name');
    await user.clear(worldInput);
    await user.type(worldInput, 'portos-two');
    await user.click(screen.getByRole('button', { name: 'Save and project' }));

    await waitFor(() => expect(screen.getByTitle('Eidoverse Worlds')).toHaveAttribute(
      'src',
      `${window.location.protocol}//${window.location.host}/eidoverse-host/?world=portos-two&name=example-portos-user`,
    ));
  });

  it('groups data, assets, and upgrade state in a deep-linkable tabbed drawer', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));

    expect(screen.getByLabelText('World name')).toHaveAttribute('pattern', '[A-Za-z0-9_-]+');
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    expect(screen.getByText(/bounded summary indicators, never raw records/i)).toBeInTheDocument();
    expect(screen.getByLabelText('Apps')).toBeChecked();
    expect(screen.getByText('3')).toBeInTheDocument();
    expect(screen.getAllByRole('link', { name: 'Open in PortOS' })
      .some((link) => link.getAttribute('href') === '/apps')).toBe(true);

    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));
    expect(screen.getByText('Portable asset recipe')).toBeInTheDocument();
    expect(screen.getByText('eidoverse/assets/models/app.glb')).toBeInTheDocument();
    expect(screen.getByLabelText('Sun hour')).toHaveValue(7.2);

    await user.click(screen.getByRole('tab', { name: 'Updates & Advanced' }));
    expect(screen.getByText('projection-committed')).toBeInTheDocument();
    expect(screen.getByText('1', { selector: 'dd' })).toBeInTheDocument();
    expect(screen.getByText('limits.apps')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: 'Apply world update' })).toBeInTheDocument();
  });

  it('surfaces per-source omissions when the shared live-signal cap is saturated', async () => {
    const user = userEvent.setup();
    const truncatedSummary = {
      ...worldResponse.projection.lastSummary,
      liveEntityCount: 48,
      maxLiveEntities: 48,
      truncated: true,
      droppedBySource: { apps: 2, agents: 1 },
    };
    api.getEidoverseWorldStatus.mockResolvedValueOnce({
      ...worldResponse,
      projection: { lastSummary: truncatedSummary },
    });
    api.projectEidoverseWorld.mockResolvedValueOnce({
      success: true,
      projection: { lastSummary: truncatedSummary },
      presence: { connected: true, role: 'owner' },
      design: { ...design, lastAppliedVersion: 2, pendingVersion: null },
      recipe,
    });
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));

    expect(screen.getByText(/shared world cap omitted 2 Apps, 1 Agents signal/i)).toBeInTheDocument();
    expect(screen.getByText(/2 omitted by cap/)).toBeInTheDocument();
  });

  it('shows exact staged reconciliation progress while a projection is running', async () => {
    const user = userEvent.setup();
    let resolveProjection;
    api.getEidoverseWorldStatus.mockResolvedValueOnce({
      ...worldResponse,
      design: {
        ...design,
        reconciliation: {
          status: 'applying', checkpoint: 'applying-infrastructure', operationCount: 20, appliedOperations: 5,
        },
      },
    });
    api.projectEidoverseWorld.mockReturnValueOnce(new Promise((resolve) => { resolveProjection = resolve; }));
    renderPage();

    const refresh = await screen.findByRole('button', { name: 'Refresh world' });
    await waitFor(() => expect(refresh).toBeDisabled());
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Updates & Advanced' }));
    expect(screen.getByRole('progressbar', { name: 'World reconciliation progress' })).toHaveAttribute('aria-valuenow', '5');
    resolveProjection({
      success: true,
      projection: worldResponse.projection,
      presence: { connected: true },
      design: { ...design, reconciliation: { status: 'complete', checkpoint: 'projection-committed' } },
      recipe,
    });
    await awaitEnabled(refresh);
  });

  it('pushes projection progress without polling and reconciles once on reconnect and tab show', async () => {
    let resolveProjection;
    api.getEidoverseWorldStatus.mockResolvedValueOnce({
      ...worldResponse,
      design: {
        ...design,
        lastAppliedVersion: null,
        reconciliation: { status: 'applying', checkpoint: 'asset-preflight-complete' },
      },
    });
    api.projectEidoverseWorld.mockReturnValueOnce(new Promise((resolve) => { resolveProjection = resolve; }));
    renderPage();
    const frame = await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledOnce());
    fireEvent.load(frame);

    expect(screen.getByText(/Preparing the PortOS systems garden/)).toBeInTheDocument();
    vi.useFakeTimers();
    const visibility = vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
    await act(async () => { await vi.advanceTimersByTimeAsync(3000); });
    expect(api.getEidoverseWorldProjectionStatus).not.toHaveBeenCalled();
    api.getEidoverseWorldProjectionStatus.mockResolvedValue({
      projection: worldResponse.projection,
      design: {
        lastAppliedVersion: null,
        reconciliation: { status: 'applying', checkpoint: 'environment-complete' },
      },
    });
    await act(async () => { socket.emit('eidoverse:projection', {}); });
    expect(screen.queryByText(/Preparing the PortOS systems garden/)).not.toBeInTheDocument();
    expect(api.getEidoverseWorldStatus).toHaveBeenCalledOnce();
    expect(api.getEidoverseWorldProjectionStatus).toHaveBeenCalledTimes(1);
    await act(async () => { socket.emit('connect'); });
    expect(api.getEidoverseWorldProjectionStatus).toHaveBeenCalledTimes(2);
    visibility.mockReturnValue('hidden');
    fireEvent(document, new Event('visibilitychange'));
    await act(async () => { socket.emit('eidoverse:projection', {}); });
    expect(api.getEidoverseWorldProjectionStatus).toHaveBeenCalledTimes(2);
    visibility.mockReturnValue('visible');
    await act(async () => { fireEvent(document, new Event('visibilitychange')); });
    expect(api.getEidoverseWorldProjectionStatus).toHaveBeenCalledTimes(3);

    // A read already in flight cannot overwrite the completed mutation response.
    let finishOldRead;
    api.getEidoverseWorldProjectionStatus.mockReturnValueOnce(new Promise(resolve => { finishOldRead = resolve; }));
    await act(async () => { socket.emit('eidoverse:projection', {}); });

    await act(async () => {
      resolveProjection({
        success: true,
        projection: worldResponse.projection,
        presence: { connected: true },
        design: { ...design, reconciliation: { status: 'complete', checkpoint: 'projection-committed' } },
        recipe,
      });
    });
    await act(async () => {
      finishOldRead({
        projection: { lastSummary: null },
        design: { lastAppliedVersion: null, reconciliation: { status: 'applying', checkpoint: 'plan-ready' } },
      });
    });
    expect(screen.getByRole('button', { name: 'Refresh world' })).toBeEnabled();
    expect(screen.queryByText(/Preparing the PortOS systems garden/)).not.toBeInTheDocument();
    fireEvent.click(screen.getByRole('button', { name: 'World controls' }));
    fireEvent.click(screen.getByRole('tab', { name: 'Updates & Advanced' }));
    expect(screen.getByText('projection-committed')).toBeInTheDocument();
  });

  it('resets one semantic district without clearing the full world design', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    await user.click(screen.getByRole('button', { name: 'Reset App Terraces' }));

    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledWith(
      { reset: { scope: 'district', districtId: 'apps' } },
      { silent: true },
    ));
  });

  it('keeps newer edits intact while a scoped reset is in flight', async () => {
    let resolveReset;
    api.updateEidoverseWorldConfig.mockReturnValueOnce(new Promise((resolve) => { resolveReset = resolve; }));
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    await user.click(screen.getByRole('button', { name: 'Reset App Terraces' }));
    await user.click(screen.getByRole('tab', { name: 'Experience' }));

    const nameInput = screen.getByLabelText('My Eidoverse name');
    await user.type(nameInput, '-edited');
    resolveReset({ ...worldResponse, human: worldResponse.identity });

    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledTimes(2));
    expect(nameInput).toHaveValue('example-portos-user-edited');
  });

  it('merges a scoped reset into the draft without discarding unrelated unsaved edits', async () => {
    const user = userEvent.setup();
    const objects = ['app', 'agent'].map((kind) => ({
      id: `portos-design-v2-signal-${kind}-example`, kind, resourceKey: `${kind}-0123456789ab`,
      districtId: `${kind}s`, name: `Example ${kind} signal`, visibility: 'nearby',
      description: 'An example aggregate signal.', asset: { path: 'store/example', reason: 'user-override' },
    }));
    api.projectEidoverseWorld.mockResolvedValue({ success: true, recipe, design,
      projection: { lastSummary: { ...worldResponse.projection.lastSummary, objects } } });
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledOnce());
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));

    const sunHour = screen.getByLabelText('Sun hour');
    await user.clear(sunHour);
    await user.type(sunHour, '8.4');
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));
    await user.type(screen.getByLabelText('Display alias for app 0123456789ab'), 'Unsaved app alias');
    await user.type(screen.getByLabelText('Display alias for agent 0123456789ab'), 'Keep agent alias');
    const appsSection = screen.getByRole('heading', { name: 'App Terraces' }).closest('section');
    const appsLimit = within(appsSection).getByRole('spinbutton', { name: 'Cap' });
    await user.clear(appsLimit);
    await user.type(appsLimit, '5');
    await user.click(within(appsSection).getByRole('button', { name: 'Reset App Terraces' }));

    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledWith(
      { reset: { scope: 'district', districtId: 'apps' } },
      { silent: true },
    ));
    await waitFor(() => expect(appsLimit).toHaveValue(8));
    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));
    expect(screen.getByLabelText('Sun hour')).toHaveValue(8.4);

    const save = screen.getByRole('button', { name: 'Save and project' });
    await awaitEnabled(save);
    expect([...save.closest('form').elements]
      .filter((element) => typeof element.checkValidity === 'function' && !element.checkValidity())
      .map((element) => ({ id: element.id, value: element.value, validationMessage: element.validationMessage })))
      .toEqual([]);
    await user.click(save);
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledTimes(2));
    const saved = api.updateEidoverseWorldConfig.mock.calls.at(-1)[0];
    expect(saved.labelAliases).toEqual({ 'agent-0123456789ab': 'Keep agent alias' });
    expect(saved.recipe.environment.sky.hours).toBe(8.4);
    expect(saved.recipe.limits.apps).toBe(8);
  });

  it('gates projection and asset actions until the visible draft is saved', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledOnce());
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));

    const sunHour = screen.getByLabelText('Sun hour');
    await user.clear(sunHour);
    await user.type(sunHour, '8.4');
    const appearanceRefresh = screen.getByRole('button', { name: 'Refresh asset matches' });
    expect(appearanceRefresh).toBeDisabled();
    expect(screen.getByText('Save changes before refreshing asset matches.')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: 'Refresh world' })).toBeDisabled();

    await user.click(screen.getByRole('tab', { name: 'Updates & Advanced' }));
    const apply = screen.getByRole('button', { name: 'Apply world update' });
    const refresh = screen.getByRole('button', { name: 'Refresh asset matches' });
    expect(apply).toBeDisabled();
    expect(refresh).toBeDisabled();
    expect(screen.getByText(/Save your world changes before applying an update/)).toBeInTheDocument();
    await user.click(apply);
    await user.click(refresh);
    expect(api.updateEidoverseWorldConfig).not.toHaveBeenCalled();
    expect(api.projectEidoverseWorld).toHaveBeenCalledOnce();

    await user.click(screen.getByRole('button', { name: 'Save and project' }));
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledOnce());
    await waitFor(() => expect(api.projectEidoverseWorld).toHaveBeenCalledTimes(2));
    await awaitEnabled(apply);
    expect(refresh).toBeEnabled();
    expect(screen.getByRole('button', { name: 'Refresh world' })).toBeEnabled();
  });

  it('does not coerce temporarily cleared appearance numbers to invalid zeroes', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));

    await user.clear(screen.getByLabelText('Exposure'));
    await user.clear(screen.getByLabelText('Grass density'));
    const save = screen.getByRole('button', { name: 'Save and project' });
    await awaitEnabled(save);
    fireEvent.submit(save.closest('form'));

    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledOnce());
    const saved = api.updateEidoverseWorldConfig.mock.calls[0][0];
    expect(saved.recipe.environment.sky.exposure).toBe(1.08);
    expect(saved.recipe.environment.grass.density).toBe(0.45);
  });

  it('does not coerce a temporarily cleared source cap to zero', async () => {
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Districts & Data' }));

    const appsSection = screen.getByRole('heading', { name: 'App Terraces' }).closest('section');
    const appsLimit = within(appsSection).getByRole('spinbutton', { name: 'Cap' });
    await user.clear(appsLimit);
    expect(appsLimit).toHaveValue(null);
    const save = screen.getByRole('button', { name: 'Save and project' });
    fireEvent.submit(save.closest('form'));

    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledOnce());
    expect(api.updateEidoverseWorldConfig.mock.calls[0][0].recipe.limits.apps).toBe(8);
  });

  it('surfaces a preserved legacy asset override and lets the user clear it', async () => {
    const legacyPath = 'store/example-legacy-feature';
    const legacyDesign = {
      ...design,
      userOverrides: { assets: { feature: legacyPath } },
    };
    api.getEidoverseWorldStatus.mockResolvedValue({ ...worldResponse, design: legacyDesign });
    api.projectEidoverseWorld.mockResolvedValue({
      success: true,
      projection: worldResponse.projection,
      presence: { connected: true },
      design: legacyDesign,
      recipe,
    });
    const user = userEvent.setup();
    renderPage();
    await screen.findByTitle('Eidoverse Worlds');
    await user.click(screen.getByRole('button', { name: 'World controls' }));
    await user.click(screen.getByRole('tab', { name: 'Appearance & Assets' }));

    expect(screen.getByText(legacyPath)).toBeInTheDocument();
    const clear = screen.getByRole('button', { name: 'Clear legacy Feature override' });
    await awaitEnabled(clear);
    await user.click(clear);
    expect(screen.queryByRole('button', { name: 'Clear legacy Feature override' })).not.toBeInTheDocument();

    const save = screen.getByRole('button', { name: 'Save and project' });
    expect(save).toBeEnabled();
    fireEvent.submit(save.closest('form'));
    await waitFor(() => expect(api.updateEidoverseWorldConfig).toHaveBeenCalledOnce());
    expect(api.updateEidoverseWorldConfig.mock.calls[0][0].assetOverrides).toEqual({});
  });
});