diff --git a/.agent/knowledge/repo_discoveries.md b/.agent/knowledge/repo_discoveries.md index e64c9c4d..1ce848cb 100644 --- a/.agent/knowledge/repo_discoveries.md +++ b/.agent/knowledge/repo_discoveries.md @@ -14,6 +14,14 @@ Use this log for durable findings that future contributors and agents should reu ## Discoveries +- Date: 2026-03-20 +- Area: activities | syncdeck | embedded activity console +- Discovery: SyncDeck’s instructor embedded-activity UX is split between an ad hoc `Activities` launcher and a separate `Running activities` manager, but both surfaces already depend on the same local embedded-activity state (`embeddedActivities`, `activeEmbeddedInstanceKey`, and instance-key anchor helpers). A unified activities panel can stay client-side by reusing the existing launch flow for new instances and the existing resync/navigation helpers for switching to running instances. +- Why it matters: This is a UI/state composition problem more than a data-contract problem. Future embedded-activity console changes should prefer reusing instance-key navigation helpers instead of introducing new server state just to support switching among running embedded sessions. +- Evidence: `activities/syncdeck/client/manager/SyncDeckManager.tsx`; `activities/syncdeck/client/manager/SyncDeckManager.test.tsx`; `activities/syncdeck/COMBINED_ACTIVITIES_CONTROL_PLAN.md` +- Follow-up action: If the unified panel is implemented, keep launch actions and running-instance actions distinct in the UI so switching never accidentally creates a second child session on the same anchor. +- Owner: Codex + - Date: 2026-03-19 - Area: server | activities | persistent-bootstrap - Discovery: Persistent-session startup now copies canonical permalink `selectedOptions` into the started live session's `data.embeddedLaunch.selectedOptions`, and Algorithm Demo manager bootstrap reads its initial algorithm from that embedded-launch state instead of the manage-route query string. diff --git a/activities/syncdeck/COMBINED_ACTIVITIES_CONTROL_PLAN.md b/activities/syncdeck/COMBINED_ACTIVITIES_CONTROL_PLAN.md new file mode 100644 index 00000000..d0eea060 --- /dev/null +++ b/activities/syncdeck/COMBINED_ACTIVITIES_CONTROL_PLAN.md @@ -0,0 +1,178 @@ +# SyncDeck Combined Activities Control Plan + +## Goal + +Replace the separate `Activities` launcher button and `Running activities: N` management chip in the SyncDeck instructor console with a single control that supports both: + +- launching ad hoc embedded activities on the current slide anchor +- switching among all currently running embedded activities + +The combined control should behave like the primary embedded-activity entry point for the instructor. + +## Current State + +Today the instructor console exposes two adjacent controls in +[`activities/syncdeck/client/manager/SyncDeckManager.tsx`](/workspaces/ActiveBits/activities/syncdeck/client/manager/SyncDeckManager.tsx): + +- `Activities` + - opens `syncdeck-activity-picker-panel` + - lists launchable activities only + - does not show running instances +- `Running activities: N` + - opens `syncdeck-running-activities-panel` + - lists already running embedded activity instances + - supports end/report actions + - does not support launching a new activity + +This split makes the instructor switch mental models depending on whether they want to start or manage an activity, even though both actions are part of the same embedded-activity workflow. + +## Target UX + +Use a single `Activities` button as the only embedded-activity console entry point. + +The button should: + +- remain visible in the instructor toolbar +- show useful running-state context, for example `Activities (2)` when there are running instances +- open one unified panel instead of two separate panels + +The unified panel should contain two sections: + +1. `Running Activities` + - appears first when one or more embedded activities exist + - lets the instructor switch to any running activity + - preserves existing end/report controls + - clearly marks the currently active embedded instance + +2. `Launch Activity` + - lists launchable activity types + - preserves the current ad hoc launch behavior + - continues to launch on the current slide anchor using the existing start flow + +## Interaction Model + +### Button behavior + +- Clicking `Activities` toggles a single panel. +- The old `Running activities: N` button should be removed. +- The button label should incorporate running count when non-zero. + +### Running activity switching + +Selecting a running activity should: + +- navigate the instructor view to that activity's anchor if needed +- surface that activity as the active embedded manager overlay +- avoid launching a duplicate embedded child if the chosen instance already exists + +Expected implementation direction: + +- reuse the existing instance-key based positioning helpers +- use `buildManagerResyncCommandForInstanceKey(instanceKey)` when the requested activity is not currently active +- close the unified panel after switching + +### Launch behavior + +Launching from the unified panel should: + +- keep the existing `handleActivityPickerLaunch` / `handleResolvedActivityRequests` flow +- close the unified panel after a successful launch request is initiated +- remain disabled when the configure panel is open + +### Empty state behavior + +When no embedded activities are running: + +- the unified panel should still open normally +- the running section should show a simple empty state +- the launch section should still be immediately available + +## Proposed Implementation Steps + +- [ ] Introduce a single panel state for the combined activities control in `SyncDeckManager`. +- [ ] Remove the standalone running-activities button and panel. +- [ ] Move the running-activity list UI into the combined activities panel. +- [ ] Add a switch action for each running instance. +- [ ] Preserve existing end-confirmation and report-download affordances for running instances. +- [ ] Update the button label so it communicates current running count. +- [ ] Ensure launch and switch actions close or preserve panel state intentionally. +- [ ] Add or update tests for unified button rendering, empty/running panel states, and switch behavior helpers. +- [ ] Update durable notes if implementation reveals reusable SyncDeck embedded-activity navigation guidance. + +## Data and State Notes + +No server contract change is expected for the first pass. + +This should remain a manager-only UI/state refactor built on the existing client-side data: + +- `embeddedActivities` +- `runningEmbeddedActivityCount` +- `activeEmbeddedInstanceKey` +- `resolveManagerActiveEmbeddedInstanceKey(...)` +- `buildManagerResyncCommandForInstanceKey(...)` +- existing embedded end/report handlers + +## Risks and Design Questions + +### 1. Switch semantics versus launch semantics + +Launching creates a new child session. Switching should not. + +Guardrail: + +- keep launch actions wired only to activity-type entries +- keep switch actions wired only to existing instance keys + +### 2. Multiple running instances of the same activity type + +The panel must distinguish instances by more than `activityId`. + +Recommendation: + +- show activity name plus instance key or anchor context +- keep child session id available as secondary metadata when useful + +### 3. Active-instance discoverability + +The instructor should understand which embedded activity is currently shown. + +Recommendation: + +- preserve the current `Active` indicator in the running section +- add a `Switch` or `Open` button for non-active rows +- consider replacing the action with `Viewing` for the active row + +### 4. Panel density + +Combining both sections into one panel may increase height. + +Recommendation: + +- keep the panel scrollable +- prioritize the running section first so active management is not hidden below the launch list + +## Verification Plan + +Minimum checks after implementation: + +- `npm_config_target=activities/syncdeck npm --workspace activities run test:scope` +- `npm_config_target=activities/syncdeck npm --workspace activities run lint:scope` +- `npm --workspace activities run typecheck` + +Suggested test coverage: + +- manager renders one combined `Activities` control instead of separate controls +- combined panel shows running-count context when instances exist +- combined panel renders empty running state when none exist +- helper logic for switching to a running instance resolves the correct navigation command +- launch list remains available inside the combined panel + +## Success Criteria + +The work is complete when: + +- instructors use one `Activities` entry point for both launch and running-instance management +- running activities are switchable without opening a separate panel +- existing end/report capabilities remain intact +- ad hoc launch still works from the same surface +- SyncDeck manager tests, lint, and typecheck pass