@beanx/cathygo-web-core

Last updated: 2026-07-03

Shared CathyGO Web UI and state package.

Current active upgrade plan:

• ../../docs/session-runtime-vnext-upgrade-plan.md

vNext Role

This package owns the selected-session view model for:

• single-session transcript rendering
• session event reduction
• optimistic user input reconciliation by client_input_id
• session-scoped stop state
• replay-safe hydration after refresh or reconnect
• selectors used by local Web and beanx-home

Host applications still own account routing, agent selection, transport setup, selected session id, lightweight session lists, and product-specific shell UI. They should not own a second session execution runtime.

Shell Top Bar Breadcrumb

Shared shell navigation for nested CathyGO surfaces (local Web, future beanx-home):

• TopBarBreadcrumbModel / buildLearningPackTopBarBreadcrumb() — data model for parent task / learning pack hierarchy
• CathyGOShellBreadcrumb — render segment / current in the host top bar
• CathyGOShellLearningChatToggle — split-panel icon to show/hide the learning-pack side chat
• LEARNING_PACK_PARENT_TASK_SEGMENT_ID — click target for navigating back to the parent session

Hosts wire onSegmentClick('parent_task') to their own router. LearningPackDetailView accepts showPageBreadcrumb={false} and showPageHeader={false} when the host renders breadcrumb and learning-chat toggle in its shell.

Learning Pack Workspace

Shared learning-pack detail page and side learning chat for local Web and future cloud hosts:

• LearningPackWorkspaceClient — host implements session create/subscribe/input/stop/delete and pack file loading
• useLearningPackWorkspace() — owns learning-chat ChatState, composer state, shell chrome, and event routing hooks
• LearningPackWorkspaceView / LearningPackWorkspaceViewBody — renders pack content + learning chat UI
• useLearningPackShellChrome() — breadcrumb and chat-toggle model for host top bars
• createLearningPackEventRouter() — demux turn events between parent session and learning-chat session

Learning-pack side chat uses the shared transcript and composer primitives in a plain chat presentation: no per-turn run duration header, the shared ThinkingIndicator before the first assistant token, stop generation through the composer action button, and a compact ... menu for actions such as clearing the current learning-chat session. Clearing sends a reset create request so the Gateway archives all active learning-chat sessions for the same parent task and pack before returning a fresh empty session. Hydration keeps optimistic local messages only while the session is actively mutating; idle reloads follow the server transcript to avoid stale tail bubbles. The main task chat keeps its task presentation by default.

Local Web implements the client in web/src/local-host/createLocalLearningPackClient.ts and wires useLocalChatHost to LearningPackWorkspaceViewBody plus shell chrome from useLearningPackWorkspace.

Learning canvas injection (renderCanvas)

web-core does not depend on @beanx/cathygo-learning-canvas. Host apps inject the board via:

<LearningPackWorkspaceView
  {...workspaceOptions}
  renderCanvas={(props) => <LearningCanvasBoard {...props} />}
/>

or pass the same prop through LearningPackWorkspaceViewBody. Copy the pattern from cathygo-agent/web/src/features/learning-pack/LearningPackCanvasHost.tsx when wiring beanx-home.

Session Host Helpers (@0.1.4)

• buildSessionLoadedAction / conversationMessagesToChatMessages
• createSessionEventRouter
• selectCanSend, selectCanStop, selectActiveTurnId, selectSessionStatus, selectIsMutating

First vNext Deliverables

• Keep the current single-session ChatState reducer exported.
• Session host helpers and selectors (above).
• Add reducer tests for interrupt, replay, stop, and optimistic reconciliation.
• Prove the implementation in cathygo-agent/web before publishing npm bumps on the 0.1.x line (0.2.0 reserved for breaking renames).