#137: Persist visualization mode in query string parameter

packages/factory/src/client/components/VisualizationSwitcher.tsx

@@ -1,17 +1,16 @@
-import React, { useState } from 'react';
+import React from 'react';
 
 import type { CanonicalRunStatus } from '../../shared/types/canonical.js';
+import { useVisualizationParam } from '../hooks/useVisualizationParam.js';
 import { FlowDiagram } from './FlowDiagram/FlowDiagram.js';
 import { GameCanvas } from './GameCanvas.js';
 
-type ActiveView = 'factory' | 'flow';
-
 interface VisualizationSwitcherProps {
   status: CanonicalRunStatus;
 }
 
 export function VisualizationSwitcher({ status }: VisualizationSwitcherProps): React.JSX.Element {
-  const [activeView, setActiveView] = useState<ActiveView>('factory');
+  const [activeView, setActiveView] = useVisualizationParam();
 
   return (
     <>

packages/factory/src/client/components/__tests__/VisualizationSwitcher.test.tsx

@@ -1,5 +1,5 @@
 import { cleanup, fireEvent, render, screen } from '@testing-library/react';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createMockRunStatus } from '../../../__test-helpers__/fixtures.js';
 
@@ -18,6 +18,13 @@ vi.mock('../FlowDiagram/FlowDiagram.js', () => ({
 const { VisualizationSwitcher } = await import('../VisualizationSwitcher.js');
 
 describe('VisualizationSwitcher', () => {
+  const replaceStateSpy = vi.spyOn(globalThis.history, 'replaceState');
+
+  beforeEach(() => {
+    globalThis.history.replaceState(null, '', '/');
+    replaceStateSpy.mockClear();
+  });
+
   afterEach(() => {
     cleanup();
   });
@@ -76,4 +83,37 @@ describe('VisualizationSwitcher', () => {
     expect(flowButton.className).toContain('active');
     expect(factoryButton.className).not.toContain('active');
   });
+
+  it('renders in flow view when URL has visualization=flow', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=flow');
+
+    const status = createMockRunStatus();
+    const { container } = render(<VisualizationSwitcher status={status} />);
+
+    const canvasContainer = container.querySelector<HTMLDivElement>('.canvas-container');
+    expect(canvasContainer?.dataset.view).toBe('flow');
+    expect(screen.getByTestId('flow-diagram')).toBeInTheDocument();
+    expect(screen.queryByTestId('game-canvas')).toBeNull();
+  });
+
+  it('updates URL param when the Flow button is clicked', () => {
+    const status = createMockRunStatus();
+    render(<VisualizationSwitcher status={status} />);
+    replaceStateSpy.mockClear();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Flow' }));
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/?visualization=flow');
+  });
+
+  it('removes URL param when the Factory button is clicked from flow view', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=flow');
+    const status = createMockRunStatus();
+    render(<VisualizationSwitcher status={status} />);
+    replaceStateSpy.mockClear();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Factory' }));
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/');
+  });
 });

packages/factory/src/client/hooks/__tests__/useVisualizationParam.test.ts

@@ -0,0 +1,112 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useVisualizationParam } from '../useVisualizationParam.js';
+
+describe('useVisualizationParam', () => {
+  const replaceStateSpy = vi.spyOn(globalThis.history, 'replaceState');
+
+  beforeEach(() => {
+    globalThis.history.replaceState(null, '', '/');
+    replaceStateSpy.mockClear();
+  });
+
+  afterEach(() => {
+    globalThis.history.replaceState(null, '', '/');
+  });
+
+  it('returns "factory" when URL has no visualization param', () => {
+    const { result } = renderHook(() => useVisualizationParam());
+
+    expect(result.current[0]).toBe('factory');
+  });
+
+  it('returns "factory" when URL has visualization=factory and does not call replaceState', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=factory');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    expect(result.current[0]).toBe('factory');
+    expect(replaceStateSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns "flow" when URL has visualization=flow', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=flow');
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    expect(result.current[0]).toBe('flow');
+  });
+
+  it('strips invalid value from URL on mount and returns "factory"', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=unknown');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    expect(result.current[0]).toBe('factory');
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/');
+  });
+
+  it('strips invalid value from URL on mount while preserving other params', () => {
+    globalThis.history.replaceState(null, '', '/?project=alpha&ticket=T-1&visualization=unknown');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    expect(result.current[0]).toBe('factory');
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/?project=alpha&ticket=T-1');
+  });
+
+  it('setActiveView("flow") updates URL to include visualization=flow', () => {
+    const { result } = renderHook(() => useVisualizationParam());
+
+    result.current[1]('flow');
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/?visualization=flow');
+  });
+
+  it('setActiveView("factory") removes the visualization param from URL', () => {
+    globalThis.history.replaceState(null, '', '/?visualization=flow');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    result.current[1]('factory');
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/');
+  });
+
+  it('setActiveView("factory") removes the visualization param while preserving other params', () => {
+    globalThis.history.replaceState(null, '', '/?project=alpha&ticket=T-1&run=run-a&visualization=flow');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    result.current[1]('factory');
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/?project=alpha&ticket=T-1&run=run-a');
+  });
+
+  it('preserves other query params when updating the visualization param', () => {
+    globalThis.history.replaceState(null, '', '/?project=alpha&ticket=T-1&run=run-a');
+    replaceStateSpy.mockClear();
+
+    const { result } = renderHook(() => useVisualizationParam());
+
+    result.current[1]('flow');
+
+    expect(replaceStateSpy).toHaveBeenCalledWith(null, '', '/?project=alpha&ticket=T-1&run=run-a&visualization=flow');
+  });
+
+  it('setActiveView is stable across re-renders', () => {
+    const { result, rerender } = renderHook(() => useVisualizationParam());
+
+    const firstSetActiveView = result.current[1];
+    rerender();
+    const secondSetActiveView = result.current[1];
+
+    expect(firstSetActiveView).toBe(secondSetActiveView);
+  });
+});

packages/factory/src/client/hooks/useVisualizationParam.ts

@@ -0,0 +1,54 @@
+import { useCallback, useState } from 'react';
+
+export type ActiveView = 'factory' | 'flow';
+
+const PARAM_KEY = 'visualization';
+const DEFAULT_VALUE: ActiveView = 'factory';
+
+// Replace the current history entry, ignoring failures in restricted environments
+// such as sandboxed iframes.
+function safeReplaceUrl(params: URLSearchParams): void {
+  const search = params.toString();
+  const url = search ? `${globalThis.location.pathname}?${search}` : globalThis.location.pathname;
+  try {
+    globalThis.history.replaceState(null, '', url);
+  } catch {
+    // Ignore.
+  }
+}
+
+export function useVisualizationParam(): [ActiveView, (view: ActiveView) => void] {
+  const [activeView, setActiveViewState] = useState<ActiveView>(() => {
+    const params = new URLSearchParams(globalThis.location.search);
+    const raw = params.get(PARAM_KEY);
+
+    if (raw === 'factory' || raw === 'flow') {
+      return raw;
+    }
+
+    // Strip invalid param from URL on mount.
+    // Calling replaceState inside the lazy initializer is intentional: it ensures
+    // the URL is cleaned before the first render, avoiding a flash of an invalid param.
+    if (raw !== null) {
+      params.delete(PARAM_KEY);
+      safeReplaceUrl(params);
+    }
+
+    return DEFAULT_VALUE;
+  });
+
+  const setActiveView = useCallback((view: ActiveView) => {
+    const params = new URLSearchParams(globalThis.location.search);
+
+    if (view === DEFAULT_VALUE) {
+      params.delete(PARAM_KEY);
+    } else {
+      params.set(PARAM_KEY, view);
+    }
+
+    safeReplaceUrl(params);
+    setActiveViewState(view);
+  }, []);
+
+  return [activeView, setActiveView];
+}