@pokit/reporter-web 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokit/reporter-web",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Web/React event reporter for pok CLI applications",
   "keywords": [
     "cli",
@@ -25,9 +25,8 @@
   "bugs": {
     "url": "https://github.com/notation-dev/openpok/issues"
   },
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -38,7 +37,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
@@ -46,11 +46,11 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/react": "^18.2.0",
-    "@pokit/core": "0.0.1"
+    "@pokit/core": "0.0.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "@pokit/core": "0.0.1"
+    "@pokit/core": "0.0.2"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/adapter.ts

@@ -0,0 +1,57 @@
+/**
+ * Web Reporter Adapter
+ *
+ * Implements the ReporterAdapter interface for web/React environments.
+ * Connects the EventBus to a ReporterStore for state management.
+ */
+
+import type { ReporterAdapter, ReporterAdapterController, EventBus } from '@pokit/core';
+import type { ReporterStoreWithHandler } from './store';
+
+/**
+ * Create a web reporter adapter that pipes events to a store
+ *
+ * @param store - The reporter store (must be created with createReporterStore)
+ * @returns ReporterAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createReporterStore, createWebReporterAdapter } from '@pokit/reporter-web';
+ * import { createEventBus } from '@pokit/core';
+ *
+ * const store = createReporterStore();
+ * const adapter = createWebReporterAdapter(store);
+ * const bus = createEventBus();
+ *
+ * const controller = adapter.start(bus);
+ *
+ * // Events emitted to the bus will update the store
+ * bus.emit({ type: 'root:start', appName: 'my-app' });
+ *
+ * // In React:
+ * // const state = useReporterState(store);
+ *
+ * // Cleanup
+ * controller.stop();
+ * ```
+ */
+export function createWebReporterAdapter(store: ReporterStoreWithHandler): ReporterAdapter {
+  return {
+    start(bus: EventBus): ReporterAdapterController {
+      let stopped = false;
+
+      const unsubscribe = bus.on((event) => {
+        if (stopped) return;
+        store._handleEvent(event);
+      });
+
+      return {
+        stop(): void {
+          if (stopped) return;
+          stopped = true;
+          unsubscribe();
+        },
+      };
+    },
+  };
+}

package/src/components/CommandBlock.tsx

@@ -0,0 +1,94 @@
+/**
+ * CommandBlock - A headless component for displaying shell commands with output.
+ *
+ * CSS Variables Contract:
+ * - --tutorial-code-bg: Background color for command/output area
+ * - --tutorial-bg: Default background color
+ * - --tutorial-text: Primary text color
+ * - --tutorial-text-muted: Secondary/muted text color
+ * - --tutorial-border: Border color
+ * - --tutorial-action-bg: Action button background
+ * - --tutorial-action-hover: Action button hover background
+ *
+ * Data Attributes:
+ * - [data-status="idle|running|complete|failed"]: Command status for styling
+ */
+
+export type CommandBlockStatus = 'idle' | 'running' | 'complete' | 'failed';
+
+export type CommandBlockActionProps = {
+  onClick: () => void;
+  status: CommandBlockStatus;
+  disabled: boolean;
+};
+
+export type CommandBlockProps = {
+  /** Command to display */
+  command: string;
+  /** Current status of the command execution */
+  status: CommandBlockStatus;
+  /** Output lines from the command */
+  output?: string[];
+  /** Callback when run action is triggered (if no renderAction provided) */
+  onRun?: () => void;
+  /** Render prop for custom action button */
+  renderAction?: (props: CommandBlockActionProps) => React.ReactNode;
+};
+
+export function CommandBlock({
+  command,
+  status,
+  output,
+  onRun,
+  renderAction,
+}: CommandBlockProps) {
+  const disabled = status === 'running';
+  const handleClick = () => {
+    if (!disabled && onRun) {
+      onRun();
+    }
+  };
+
+  const actionProps: CommandBlockActionProps = {
+    onClick: handleClick,
+    status,
+    disabled,
+  };
+
+  return (
+    <div className="command-block" data-status={status}>
+      <div className="command-block-command">
+        <span className="command-block-prompt">$</span>
+        <span className="command-block-text">{command}</span>
+      </div>
+      {output && output.length > 0 && (
+        <div className="command-block-output">
+          {output.map((line, index) => (
+            <div key={index} className="command-block-output-line">
+              {line}
+            </div>
+          ))}
+        </div>
+      )}
+      {(renderAction || onRun) && (
+        <div className="command-block-actions">
+          {renderAction ? (
+            renderAction(actionProps)
+          ) : (
+            <button
+              className="command-block-action-button"
+              onClick={handleClick}
+              disabled={disabled}
+              data-status={status}
+            >
+              {status === 'idle' && 'Run'}
+              {status === 'running' && 'Running...'}
+              {status === 'complete' && 'Run Again'}
+              {status === 'failed' && 'Retry'}
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/ContentBox.tsx

@@ -0,0 +1,32 @@
+/**
+ * ContentBox - A headless container component for info/tip/warning content.
+ *
+ * CSS Variables Contract:
+ * - --tutorial-bg: Default background color
+ * - --tutorial-text: Primary text color
+ * - --tutorial-text-muted: Secondary/muted text color
+ * - --tutorial-border: Border color
+ *
+ * Data Attributes:
+ * - [data-variant="info|tip|warning"]: Content variant for styling
+ */
+
+export type ContentBoxVariant = 'info' | 'tip' | 'warning';
+
+export type ContentBoxProps = {
+  /** Visual variant of the content box */
+  variant: ContentBoxVariant;
+  /** Optional title for the content box */
+  title?: string;
+  /** Content to display inside the box */
+  children: React.ReactNode;
+};
+
+export function ContentBox({ variant, title, children }: ContentBoxProps) {
+  return (
+    <div className="content-box" data-variant={variant}>
+      {title && <div className="content-box-title">{title}</div>}
+      <div className="content-box-content">{children}</div>
+    </div>
+  );
+}

package/src/components/FilePreview.tsx

@@ -0,0 +1,99 @@
+/**
+ * FilePreview - A headless component for displaying file content with action slot.
+ *
+ * CSS Variables Contract:
+ * - --tutorial-code-bg: Background color for code/file content area
+ * - --tutorial-bg: Default background color
+ * - --tutorial-text: Primary text color
+ * - --tutorial-text-muted: Secondary/muted text color
+ * - --tutorial-border: Border color
+ * - --tutorial-action-bg: Action button background
+ * - --tutorial-action-hover: Action button hover background
+ *
+ * Data Attributes:
+ * - [data-status="pending|creating|created"]: File status for styling
+ * - [data-language="..."]: Language hint for syntax highlighting
+ */
+
+export type FilePreviewStatus = 'pending' | 'creating' | 'created';
+
+export type FilePreviewActionProps = {
+  onClick: () => void;
+  status: FilePreviewStatus;
+  disabled: boolean;
+};
+
+export type FilePreviewProps = {
+  /** File path to display in header */
+  path: string;
+  /** File content to display */
+  content: string;
+  /** Language for syntax highlighting hint */
+  language?: string;
+  /** Current status of the file operation */
+  status: FilePreviewStatus;
+  /** Callback when action is triggered (if no renderAction provided) */
+  onAction?: () => void;
+  /** Render prop for custom action button */
+  renderAction?: (props: FilePreviewActionProps) => React.ReactNode;
+};
+
+export function FilePreview({
+  path,
+  content,
+  language,
+  status,
+  onAction,
+  renderAction,
+}: FilePreviewProps) {
+  const disabled = status === 'creating' || status === 'created';
+  const handleClick = () => {
+    if (!disabled && onAction) {
+      onAction();
+    }
+  };
+
+  const actionProps: FilePreviewActionProps = {
+    onClick: handleClick,
+    status,
+    disabled,
+  };
+
+  return (
+    <div
+      className="file-preview"
+      data-status={status}
+      data-language={language}
+    >
+      <div className="file-preview-header">
+        <span className="file-preview-path">{path}</span>
+        {language && (
+          <span className="file-preview-language">{language}</span>
+        )}
+      </div>
+      <div className="file-preview-content">
+        <pre className="file-preview-code">
+          <code>{content}</code>
+        </pre>
+      </div>
+      {(renderAction || onAction) && (
+        <div className="file-preview-actions">
+          {renderAction ? (
+            renderAction(actionProps)
+          ) : (
+            <button
+              className="file-preview-action-button"
+              onClick={handleClick}
+              disabled={disabled}
+              data-status={status}
+            >
+              {status === 'pending' && 'Create'}
+              {status === 'creating' && 'Creating...'}
+              {status === 'created' && 'Created'}
+            </button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/ProgressIndicator.tsx

@@ -0,0 +1,46 @@
+/**
+ * ProgressIndicator - A headless component for displaying tutorial progress.
+ *
+ * CSS Variables Contract:
+ * - --tutorial-text: Primary text color
+ * - --tutorial-text-muted: Secondary/muted text color
+ *
+ * Data Attributes:
+ * - [data-progress]: Current progress ratio (0-1) as data attribute
+ * - [data-complete="true"]: When current equals total
+ */
+
+export type ProgressIndicatorProps = {
+  /** Current step number (1-indexed) */
+  current: number;
+  /** Total number of steps */
+  total: number;
+  /** Optional custom label (defaults to "Step X of Y") */
+  label?: string;
+};
+
+export function ProgressIndicator({
+  current,
+  total,
+  label,
+}: ProgressIndicatorProps) {
+  const progress = total > 0 ? current / total : 0;
+  const isComplete = current >= total;
+  const displayLabel = label ?? `Step ${current} of ${total}`;
+
+  return (
+    <div
+      className="progress-indicator"
+      data-progress={progress.toFixed(2)}
+      data-complete={isComplete ? 'true' : undefined}
+    >
+      <span className="progress-indicator-label">{displayLabel}</span>
+      <div className="progress-indicator-bar">
+        <div
+          className="progress-indicator-fill"
+          style={{ width: `${progress * 100}%` }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/TutorialStep.tsx

@@ -0,0 +1,45 @@
+/**
+ * TutorialStep - A headless component for rendering tutorial step containers.
+ *
+ * CSS Variables Contract:
+ * - --tutorial-step-active: Background/border color for active step
+ * - --tutorial-step-complete: Background/border color for complete step
+ * - --tutorial-step-pending: Background/border color for pending step
+ * - --tutorial-bg: Default background color
+ * - --tutorial-text: Primary text color
+ * - --tutorial-text-muted: Secondary/muted text color
+ * - --tutorial-border: Border color
+ *
+ * Data Attributes:
+ * - [data-status="pending|active|complete"]: Step status for styling
+ */
+
+export type TutorialStepStatus = 'pending' | 'active' | 'complete';
+
+export type TutorialStepProps = {
+  /** Step number displayed in the header */
+  number: number;
+  /** Step title */
+  title: string;
+  /** Current status of the step */
+  status: TutorialStepStatus;
+  /** Step content */
+  children: React.ReactNode;
+};
+
+export function TutorialStep({
+  number,
+  title,
+  status,
+  children,
+}: TutorialStepProps) {
+  return (
+    <div className="tutorial-step" data-status={status}>
+      <div className="tutorial-step-header">
+        <span className="tutorial-step-number">{number}</span>
+        <span className="tutorial-step-title">{title}</span>
+      </div>
+      <div className="tutorial-step-content">{children}</div>
+    </div>
+  );
+}

package/src/components/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Tutorial Renderer Components
+ *
+ * Headless React components for rendering tutorial content.
+ * All components use CSS variables and data attributes for styling,
+ * allowing full customization by the consuming application.
+ *
+ * CSS Variables Contract:
+ * --tutorial-bg              Default background color
+ * --tutorial-step-active     Background/border for active step
+ * --tutorial-step-complete   Background/border for complete step
+ * --tutorial-step-pending    Background/border for pending step
+ * --tutorial-code-bg         Background for code/command blocks
+ * --tutorial-action-bg       Action button background
+ * --tutorial-action-hover    Action button hover background
+ * --tutorial-border          Border color
+ * --tutorial-text            Primary text color
+ * --tutorial-text-muted      Secondary/muted text color
+ */
+
+// TutorialStep
+export { TutorialStep } from './TutorialStep';
+export type {
+  TutorialStepProps,
+  TutorialStepStatus,
+} from './TutorialStep';
+
+// FilePreview
+export { FilePreview } from './FilePreview';
+export type {
+  FilePreviewProps,
+  FilePreviewStatus,
+  FilePreviewActionProps,
+} from './FilePreview';
+
+// CommandBlock
+export { CommandBlock } from './CommandBlock';
+export type {
+  CommandBlockProps,
+  CommandBlockStatus,
+  CommandBlockActionProps,
+} from './CommandBlock';
+
+// ProgressIndicator
+export { ProgressIndicator } from './ProgressIndicator';
+export type { ProgressIndicatorProps } from './ProgressIndicator';
+
+// ContentBox
+export { ContentBox } from './ContentBox';
+export type {
+  ContentBoxProps,
+  ContentBoxVariant,
+} from './ContentBox';

package/src/hooks.ts

@@ -0,0 +1,242 @@
+/**
+ * Reporter Web React Hooks
+ *
+ * React hooks for subscribing to reporter state using useSyncExternalStore.
+ * Provides full state subscription and selective subscriptions for individual
+ * activities and groups.
+ */
+
+import { useSyncExternalStore, useCallback, useRef } from 'react';
+import type { ActivityId, GroupId } from '@pokit/core';
+import type { ReporterStore, ReporterState, ActivityState, GroupState } from './types';
+
+/**
+ * Subscribe to the full reporter state
+ *
+ * @param store - The reporter store
+ * @returns Current reporter state
+ *
+ * @example
+ * ```tsx
+ * const state = useReporterState(store);
+ * return <div>Status: {state.root.status}</div>;
+ * ```
+ */
+export function useReporterState(store: ReporterStore): ReporterState {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+}
+
+/**
+ * Subscribe to a single activity by ID
+ * Returns undefined if activity doesn't exist
+ *
+ * @param store - The reporter store
+ * @param id - Activity ID to subscribe to
+ * @returns Activity state or undefined
+ *
+ * @example
+ * ```tsx
+ * const activity = useActivity(store, 'task-1');
+ * if (!activity) return null;
+ * return <div>{activity.label}: {activity.status}</div>;
+ * ```
+ */
+export function useActivity(store: ReporterStore, id: ActivityId): ActivityState | undefined {
+  // Track the previous activity reference for shallow comparison
+  const prevActivityRef = useRef<ActivityState | undefined>(undefined);
+
+  const getSnapshot = useCallback(() => {
+    const state = store.getSnapshot();
+    const activity = state.activities.get(id);
+
+    // Return same reference if activity hasn't changed (shallow comparison)
+    if (prevActivityRef.current === activity) {
+      return prevActivityRef.current;
+    }
+
+    // Check if activity content is the same (for Map recreation scenarios)
+    if (
+      prevActivityRef.current &&
+      activity &&
+      prevActivityRef.current.id === activity.id &&
+      prevActivityRef.current.status === activity.status &&
+      prevActivityRef.current.progress === activity.progress &&
+      prevActivityRef.current.message === activity.message &&
+      prevActivityRef.current.justStarted === activity.justStarted &&
+      prevActivityRef.current.justCompleted === activity.justCompleted &&
+      prevActivityRef.current.justFailed === activity.justFailed &&
+      prevActivityRef.current.completedAt === activity.completedAt
+    ) {
+      return prevActivityRef.current;
+    }
+
+    prevActivityRef.current = activity;
+    return activity;
+  }, [store, id]);
+
+  const getServerSnapshot = useCallback(() => {
+    return store.getServerSnapshot().activities.get(id);
+  }, [store, id]);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Subscribe to a single group by ID
+ * Returns undefined if group doesn't exist
+ *
+ * @param store - The reporter store
+ * @param id - Group ID to subscribe to
+ * @returns Group state or undefined
+ *
+ * @example
+ * ```tsx
+ * const group = useGroup(store, 'checks');
+ * if (!group) return null;
+ * return <div>{group.label} ({group.activityIds.length} tasks)</div>;
+ * ```
+ */
+export function useGroup(store: ReporterStore, id: GroupId): GroupState | undefined {
+  // Track the previous group reference for shallow comparison
+  const prevGroupRef = useRef<GroupState | undefined>(undefined);
+
+  const getSnapshot = useCallback(() => {
+    const state = store.getSnapshot();
+    const group = state.groups.get(id);
+
+    // Return same reference if group hasn't changed
+    if (prevGroupRef.current === group) {
+      return prevGroupRef.current;
+    }
+
+    // Check if group content is the same (for Map recreation scenarios)
+    if (
+      prevGroupRef.current &&
+      group &&
+      prevGroupRef.current.id === group.id &&
+      prevGroupRef.current.label === group.label &&
+      prevGroupRef.current.hasFailure === group.hasFailure &&
+      prevGroupRef.current.justStarted_group === group.justStarted_group &&
+      prevGroupRef.current.justEnded === group.justEnded &&
+      prevGroupRef.current.endedAt === group.endedAt &&
+      prevGroupRef.current.activityIds.length === group.activityIds.length &&
+      prevGroupRef.current.childGroupIds.length === group.childGroupIds.length
+    ) {
+      return prevGroupRef.current;
+    }
+
+    prevGroupRef.current = group;
+    return group;
+  }, [store, id]);
+
+  const getServerSnapshot = useCallback(() => {
+    return store.getServerSnapshot().groups.get(id);
+  }, [store, id]);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Subscribe to root state only
+ * More efficient than useReporterState when you only need root info
+ *
+ * @param store - The reporter store
+ * @returns Root state
+ *
+ * @example
+ * ```tsx
+ * const root = useRootState(store);
+ * return <div>App: {root.appName} - {root.status}</div>;
+ * ```
+ */
+export function useRootState(store: ReporterStore): ReporterState['root'] {
+  const prevRootRef = useRef<ReporterState['root'] | undefined>(undefined);
+
+  const getSnapshot = useCallback(() => {
+    const state = store.getSnapshot();
+    const root = state.root;
+
+    // Return same reference if root hasn't changed
+    if (
+      prevRootRef.current &&
+      prevRootRef.current.status === root.status &&
+      prevRootRef.current.appName === root.appName &&
+      prevRootRef.current.exitCode === root.exitCode
+    ) {
+      return prevRootRef.current;
+    }
+
+    prevRootRef.current = root;
+    return root;
+  }, [store]);
+
+  const getServerSnapshot = useCallback(() => {
+    return store.getServerSnapshot().root;
+  }, [store]);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Subscribe to logs
+ * Returns the full log array
+ *
+ * @param store - The reporter store
+ * @returns Array of log entries
+ *
+ * @example
+ * ```tsx
+ * const logs = useLogs(store);
+ * return (
+ *   <ul>
+ *     {logs.map(log => <li key={log.id}>{log.message}</li>)}
+ *   </ul>
+ * );
+ * ```
+ */
+export function useLogs(store: ReporterStore): ReporterState['logs'] {
+  const prevLogsRef = useRef<ReporterState['logs'] | undefined>(undefined);
+
+  const getSnapshot = useCallback(() => {
+    const state = store.getSnapshot();
+    const logs = state.logs;
+
+    // Return same reference if logs haven't changed
+    if (prevLogsRef.current && prevLogsRef.current.length === logs.length) {
+      // Quick check - if lengths match and last item is same, assume unchanged
+      if (
+        logs.length === 0 ||
+        prevLogsRef.current[logs.length - 1]?.id === logs[logs.length - 1]?.id
+      ) {
+        return prevLogsRef.current;
+      }
+    }
+
+    prevLogsRef.current = logs;
+    return logs;
+  }, [store]);
+
+  const getServerSnapshot = useCallback(() => {
+    return store.getServerSnapshot().logs;
+  }, [store]);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Subscribe to suspended state
+ *
+ * @param store - The reporter store
+ * @returns Whether reporter is suspended
+ */
+export function useSuspended(store: ReporterStore): boolean {
+  const getSnapshot = useCallback(() => {
+    return store.getSnapshot().suspended;
+  }, [store]);
+
+  const getServerSnapshot = useCallback(() => {
+    return store.getServerSnapshot().suspended;
+  }, [store]);
+
+  return useSyncExternalStore(store.subscribe, getSnapshot, getServerSnapshot);
+}

package/src/store.ts

@@ -0,0 +1,414 @@
+/**
+ * Reporter Web Store
+ *
+ * Creates an external store for React integration.
+ * Handles all CLIEvent types and maintains normalized state.
+ */
+
+import type { CLIEvent, ActivityId, GroupId } from '@pokit/core';
+import type {
+  ReporterState,
+  ReporterStore,
+  StateListener,
+  ActivityState,
+  GroupState,
+  LogEntry,
+} from './types';
+
+/** Default delay for clearing temporal markers (ms) */
+const TEMPORAL_MARKER_DELAY = 600;
+
+/** Counter for generating unique log IDs */
+let logIdCounter = 0;
+
+/**
+ * Create initial reporter state
+ */
+function createInitialState(): ReporterState {
+  return {
+    root: {
+      status: 'idle',
+    },
+    groups: new Map(),
+    activities: new Map(),
+    logs: [],
+    suspended: false,
+  };
+}
+
+/**
+ * Options for creating a reporter store
+ */
+export type CreateReporterStoreOptions = {
+  /** Custom delay for clearing temporal markers (default: 600ms) */
+  temporalMarkerDelay?: number;
+  /** Disable temporal marker auto-clearing (useful for testing) */
+  disableTemporalMarkerClearing?: boolean;
+};
+
+/**
+ * Type for the store with internal event handler exposed
+ */
+export type ReporterStoreWithHandler = ReporterStore & {
+  _handleEvent: (event: CLIEvent) => void;
+};
+
+/**
+ * Create a reporter store for React integration
+ *
+ * @param options - Optional configuration
+ * @returns Store compatible with useSyncExternalStore
+ */
+export function createReporterStore(options?: CreateReporterStoreOptions): ReporterStoreWithHandler {
+  const temporalMarkerDelay = options?.temporalMarkerDelay ?? TEMPORAL_MARKER_DELAY;
+  const disableTemporalMarkerClearing = options?.disableTemporalMarkerClearing ?? false;
+
+  let state = createInitialState();
+  const listeners = new Set<StateListener>();
+
+  /**
+   * Notify all listeners of state change
+   */
+  function notifyListeners(): void {
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  /**
+   * Schedule clearing of temporal markers for an activity
+   */
+  function scheduleActivityMarkerClear(activityId: ActivityId, markers: (keyof ActivityState)[]): void {
+    if (disableTemporalMarkerClearing) return;
+
+    setTimeout(() => {
+      const activity = state.activities.get(activityId);
+      if (!activity) return;
+
+      // Check if any markers are still set
+      const hasMarkers = markers.some((marker) => activity[marker]);
+      if (!hasMarkers) return;
+
+      // Create new state with cleared markers
+      const updatedActivity = { ...activity };
+      for (const marker of markers) {
+        delete updatedActivity[marker];
+      }
+
+      const newActivities = new Map(state.activities);
+      newActivities.set(activityId, updatedActivity);
+
+      state = {
+        ...state,
+        activities: newActivities,
+      };
+      notifyListeners();
+    }, temporalMarkerDelay);
+  }
+
+  /**
+   * Schedule clearing of temporal markers for a group
+   */
+  function scheduleGroupMarkerClear(groupId: GroupId, markers: (keyof GroupState)[]): void {
+    if (disableTemporalMarkerClearing) return;
+
+    setTimeout(() => {
+      const group = state.groups.get(groupId);
+      if (!group) return;
+
+      // Check if any markers are still set
+      const hasMarkers = markers.some((marker) => group[marker]);
+      if (!hasMarkers) return;
+
+      // Create new state with cleared markers
+      const updatedGroup = { ...group };
+      for (const marker of markers) {
+        delete updatedGroup[marker];
+      }
+
+      const newGroups = new Map(state.groups);
+      newGroups.set(groupId, updatedGroup);
+
+      state = {
+        ...state,
+        groups: newGroups,
+      };
+      notifyListeners();
+    }, temporalMarkerDelay);
+  }
+
+  /**
+   * Handle a CLI event and update state
+   */
+  function handleEvent(event: CLIEvent): void {
+    switch (event.type) {
+      case 'root:start': {
+        state = {
+          ...state,
+          root: {
+            status: 'running',
+            appName: event.appName,
+            version: event.version,
+            startedAt: Date.now(),
+          },
+        };
+        notifyListeners();
+        break;
+      }
+
+      case 'root:end': {
+        state = {
+          ...state,
+          root: {
+            ...state.root,
+            status: event.exitCode === 0 ? 'complete' : 'error',
+            exitCode: event.exitCode,
+            endedAt: Date.now(),
+          },
+        };
+        notifyListeners();
+        break;
+      }
+
+      case 'group:start': {
+        const newGroup: GroupState = {
+          id: event.id,
+          parentId: event.parentId,
+          label: event.label,
+          layout: event.layout,
+          activityIds: [],
+          childGroupIds: [],
+          hasFailure: false,
+          startedAt: Date.now(),
+          justStarted_group: true,
+        };
+
+        const newGroups = new Map(state.groups);
+        newGroups.set(event.id, newGroup);
+
+        // Add to parent's childGroupIds if parent exists
+        if (event.parentId) {
+          const parent = state.groups.get(event.parentId);
+          if (parent) {
+            newGroups.set(event.parentId, {
+              ...parent,
+              childGroupIds: [...parent.childGroupIds, event.id],
+            });
+          }
+        }
+
+        state = {
+          ...state,
+          groups: newGroups,
+        };
+        notifyListeners();
+        scheduleGroupMarkerClear(event.id, ['justStarted_group']);
+        break;
+      }
+
+      case 'group:end': {
+        const group = state.groups.get(event.id);
+        if (!group) break;
+
+        const newGroups = new Map(state.groups);
+        newGroups.set(event.id, {
+          ...group,
+          endedAt: Date.now(),
+          justEnded: true,
+        });
+
+        state = {
+          ...state,
+          groups: newGroups,
+        };
+        notifyListeners();
+        scheduleGroupMarkerClear(event.id, ['justEnded']);
+        break;
+      }
+
+      case 'activity:start': {
+        const newActivity: ActivityState = {
+          id: event.id,
+          parentId: event.parentId,
+          label: event.label,
+          status: 'running',
+          meta: event.meta,
+          startedAt: Date.now(),
+          justStarted: true,
+        };
+
+        const newActivities = new Map(state.activities);
+        newActivities.set(event.id, newActivity);
+
+        // Add to parent group's activityIds if parent is a group
+        const newGroups = new Map(state.groups);
+        if (event.parentId) {
+          const parentGroup = state.groups.get(event.parentId as GroupId);
+          if (parentGroup) {
+            newGroups.set(event.parentId as GroupId, {
+              ...parentGroup,
+              activityIds: [...parentGroup.activityIds, event.id],
+            });
+          }
+        }
+
+        state = {
+          ...state,
+          activities: newActivities,
+          groups: newGroups,
+        };
+        notifyListeners();
+        scheduleActivityMarkerClear(event.id, ['justStarted']);
+        break;
+      }
+
+      case 'activity:update': {
+        const activity = state.activities.get(event.id);
+        if (!activity) break;
+
+        const { progress, message, ...rest } = event.payload;
+
+        const newActivities = new Map(state.activities);
+        newActivities.set(event.id, {
+          ...activity,
+          progress: progress ?? activity.progress,
+          message: message ?? activity.message,
+          payload: {
+            ...activity.payload,
+            ...rest,
+          },
+        });
+
+        state = {
+          ...state,
+          activities: newActivities,
+        };
+        notifyListeners();
+        break;
+      }
+
+      case 'activity:success': {
+        const activity = state.activities.get(event.id);
+        if (!activity) break;
+
+        const newActivities = new Map(state.activities);
+        newActivities.set(event.id, {
+          ...activity,
+          status: 'success',
+          completedAt: Date.now(),
+          justCompleted: true,
+        });
+
+        state = {
+          ...state,
+          activities: newActivities,
+        };
+        notifyListeners();
+        scheduleActivityMarkerClear(event.id, ['justCompleted']);
+        break;
+      }
+
+      case 'activity:failure': {
+        const activity = state.activities.get(event.id);
+        if (!activity) break;
+
+        const errorMessage = event.error instanceof Error ? event.error.message : String(event.error);
+
+        const newActivities = new Map(state.activities);
+        newActivities.set(event.id, {
+          ...activity,
+          status: 'failure',
+          completedAt: Date.now(),
+          justFailed: true,
+          error: {
+            message: errorMessage,
+            remediation: event.remediation,
+            documentationUrl: event.documentationUrl,
+          },
+        });
+
+        // Mark parent group as having failure
+        const newGroups = new Map(state.groups);
+        if (activity.parentId) {
+          const parentGroup = state.groups.get(activity.parentId as GroupId);
+          if (parentGroup) {
+            newGroups.set(activity.parentId as GroupId, {
+              ...parentGroup,
+              hasFailure: true,
+            });
+          }
+        }
+
+        state = {
+          ...state,
+          activities: newActivities,
+          groups: newGroups,
+        };
+        notifyListeners();
+        scheduleActivityMarkerClear(event.id, ['justFailed']);
+        break;
+      }
+
+      case 'log': {
+        const logEntry: LogEntry = {
+          id: `log-${++logIdCounter}`,
+          activityId: event.activityId,
+          level: event.level,
+          message: event.message,
+          timestamp: Date.now(),
+        };
+
+        state = {
+          ...state,
+          logs: [...state.logs, logEntry],
+        };
+        notifyListeners();
+        break;
+      }
+
+      case 'reporter:suspend': {
+        state = {
+          ...state,
+          suspended: true,
+        };
+        notifyListeners();
+        break;
+      }
+
+      case 'reporter:resume': {
+        state = {
+          ...state,
+          suspended: false,
+        };
+        notifyListeners();
+        break;
+      }
+    }
+  }
+
+  return {
+    getState(): ReporterState {
+      return state;
+    },
+
+    getSnapshot(): ReporterState {
+      return state;
+    },
+
+    getServerSnapshot(): ReporterState {
+      return state;
+    },
+
+    subscribe(listener: StateListener): () => void {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    /**
+     * Internal method to handle events - exposed for adapter use
+     */
+    _handleEvent: handleEvent,
+  };
+}

package/src/types.ts

@@ -0,0 +1,141 @@
+/**
+ * Reporter Web Types
+ *
+ * State shape definitions for the web reporter store.
+ * Designed for React integration via useSyncExternalStore.
+ */
+
+import type { ActivityId, GroupId, GroupLayout, LogLevel } from '@pokit/core';
+
+/**
+ * Root lifecycle status
+ */
+export type RootStatus = 'idle' | 'running' | 'complete' | 'error';
+
+/**
+ * Activity status
+ */
+export type ActivityStatus = 'pending' | 'running' | 'success' | 'failure';
+
+/**
+ * Temporal markers for animation hints
+ * These auto-clear after a short delay (600ms) to enable smooth UI transitions
+ */
+export type TemporalMarkers = {
+  /** Activity just started (for entrance animations) */
+  justStarted?: boolean;
+  /** Activity just completed successfully (for success animations) */
+  justCompleted?: boolean;
+  /** Activity just failed (for error animations) */
+  justFailed?: boolean;
+  /** Group just started */
+  justStarted_group?: boolean;
+  /** Group just ended */
+  justEnded?: boolean;
+};
+
+/**
+ * Activity state - represents a unit of work
+ */
+export type ActivityState = TemporalMarkers & {
+  id: ActivityId;
+  parentId?: GroupId | ActivityId;
+  label: string;
+  status: ActivityStatus;
+  /** Progress 0-100 */
+  progress?: number;
+  /** Current status message */
+  message?: string;
+  /** Custom metadata */
+  meta?: Record<string, unknown>;
+  /** Error information if failed */
+  error?: {
+    message: string;
+    remediation?: string[];
+    documentationUrl?: string;
+  };
+  /** Custom payload data from updates */
+  payload?: Record<string, unknown>;
+  /** Timestamp when started */
+  startedAt: number;
+  /** Timestamp when completed (success or failure) */
+  completedAt?: number;
+};
+
+/**
+ * Group state - represents a container for activities
+ */
+export type GroupState = TemporalMarkers & {
+  id: GroupId;
+  parentId?: GroupId;
+  label: string;
+  layout: GroupLayout;
+  /** Child activity IDs in order */
+  activityIds: ActivityId[];
+  /** Child group IDs in order */
+  childGroupIds: GroupId[];
+  /** Whether any child has failed */
+  hasFailure: boolean;
+  /** Timestamp when started */
+  startedAt: number;
+  /** Timestamp when ended */
+  endedAt?: number;
+};
+
+/**
+ * Log entry
+ */
+export type LogEntry = {
+  id: string;
+  activityId?: ActivityId;
+  level: LogLevel;
+  message: string;
+  timestamp: number;
+};
+
+/**
+ * Root state for the reporter
+ */
+export type RootState = {
+  appName?: string;
+  version?: string;
+  status: RootStatus;
+  startedAt?: number;
+  endedAt?: number;
+  exitCode?: number;
+};
+
+/**
+ * Complete reporter state
+ */
+export type ReporterState = {
+  /** Root lifecycle state */
+  root: RootState;
+  /** Groups indexed by ID */
+  groups: Map<GroupId, GroupState>;
+  /** Activities indexed by ID */
+  activities: Map<ActivityId, ActivityState>;
+  /** Log entries in chronological order */
+  logs: LogEntry[];
+  /** Whether reporter output is suspended */
+  suspended: boolean;
+};
+
+/**
+ * Subscription callback type
+ */
+export type StateListener = () => void;
+
+/**
+ * Reporter store interface compatible with useSyncExternalStore
+ */
+export type ReporterStore = {
+  /** Get current state snapshot */
+  getState(): ReporterState;
+  /** Get snapshot for useSyncExternalStore (same as getState for immutable updates) */
+  getSnapshot(): ReporterState;
+  /** Subscribe to state changes */
+  subscribe(listener: StateListener): () => void;
+  /** Get server snapshot for SSR (returns same as getSnapshot) */
+  getServerSnapshot(): ReporterState;
+};