|
| 1 | +# Implementation Notes |
| 2 | + |
| 3 | +## Apply Alignment |
| 4 | + |
| 5 | +- `plans/plan.md`, package spec, example spec, and deferred Studio migration spec agree on package ownership, grouped Heartbeat truth, `readonly | configable`, mobile-first example acceptance, and first-phase Studio migration deferral. |
| 6 | +- Avatar catalog rows are HeartbeatPage targets regardless of running state. Running only changes live-push/active status. |
| 7 | +- `AgenterHeartbeatConnection` is the first accepted connection boundary name. |
| 8 | +- First apply does not add or reshape backend endpoints. If an endpoint shape change appears necessary, implementation must pause for user discussion. |
| 9 | +- `readonly` is a frontend presentation mode for clean UI. It is not an auth or isolation boundary. Existing `createSession({ autoStart:false })` remains allowed for materializing/reusing stopped session metadata so persisted Heartbeat DB facts can be read. |
| 10 | +- User decision to preserve verbatim: "readonly只是前端上的限制，目的只是为了让界面干净点，真正要做隔离，也不是从接口设计上去隔离，而是要从接口认证上去隔离。" |
| 11 | + |
| 12 | +## `packages/web-chat-view` Files To Mirror |
| 13 | + |
| 14 | +- Mirror package shape: |
| 15 | + - `packages/web-chat-view/package.json` |
| 16 | + - `packages/web-chat-view/tsconfig.json` |
| 17 | + - `packages/web-chat-view/svelte.config.js` |
| 18 | + - `packages/web-chat-view/vitest.config.ts` |
| 19 | + - `packages/web-chat-view/.storybook/main.ts` |
| 20 | + - `packages/web-chat-view/.storybook/preview.ts` |
| 21 | +- Mirror package/example boundary: |
| 22 | + - package owns reusable Svelte primitives and typed exports |
| 23 | + - `example` owns Framework7 host shell, app bootstrap, routes, and connection UI |
| 24 | +- Mirror Framework7 runtime helpers only if needed: |
| 25 | + - `src/framework7-components.ts` |
| 26 | + - `src/framework7.ts` |
| 27 | + - `src/framework7-host.ts` |
| 28 | +- Intentionally diverge: |
| 29 | + - no chat composer, contacts, search, resource preview, or CodeMirror dependencies in first Heartbeat package slice |
| 30 | + - example root is Avatar directory first, not the web-chat review shell |
| 31 | + |
| 32 | +## Studio Heartbeat Files To Migrate Or Recreate |
| 33 | + |
| 34 | +- Copy/reorganize into package-owned code: |
| 35 | + - `runtime-heartbeat-parts.ts` |
| 36 | + - `runtime-heartbeat-tool-visual-hints.ts` |
| 37 | + - `runtime-heartbeat-statusbar-state.ts` |
| 38 | + - `runtime-heartbeat-config-state.ts` |
| 39 | + - `runtime-shell-format.ts` time-format helpers used by Heartbeat entries |
| 40 | +- Recreate as package Svelte components without Studio imports: |
| 41 | + - `runtime-stage-heartbeat.svelte` -> `HeartbeatView.svelte` |
| 42 | + - `runtime-heartbeat-group.svelte` -> `heartbeat-group.svelte` |
| 43 | + - `runtime-heartbeat-entry.svelte` -> `heartbeat-entry.svelte` |
| 44 | + - `runtime-heartbeat-part-content.svelte` -> `heartbeat-part-content.svelte` |
| 45 | + - `runtime-heartbeat-tool-block.svelte` -> `heartbeat-tool-block.svelte` |
| 46 | + - `runtime-heartbeat-statusbar.svelte` -> `heartbeat-statusbar.svelte` |
| 47 | + - `runtime-heartbeat-config-panel.svelte` -> package-local statusbar action surface |
| 48 | + - `runtime-heartbeat-status-context.svelte` and status shimmer -> package-local status readouts |
| 49 | +- Leave behind in first apply: |
| 50 | + - Studio route/controller wiring |
| 51 | + - Studio runtime shell rebinding |
| 52 | + - Studio stories except as behavioral reference |
| 53 | + |
| 54 | +## Existing Data Path To Use |
| 55 | + |
| 56 | +- Studio Avatar route opens Heartbeat by `runtimeStore.createSession({ cwd, avatar, autoStart:false })`, then navigates to `/avatars/runtime/{session.id}/heartbeat`. |
| 57 | +- `resolveAvatarRuntimeId(avatar)` derives deterministic UUID from normalized nickname. |
| 58 | +- `resolveAvatarSessionId(avatar)` returns `resolveAvatarRuntimeId(avatar)`. |
| 59 | +- session catalog `create(...)` creates/reuses a stopped session using that deterministic id. |
| 60 | +- client-sdk `createSession(...)` calls existing `session.create`, then hydrates runtime state. |
| 61 | +- client-sdk `loadHeartbeatGroups(sessionId)` and `loadMoreHeartbeatGroups(sessionId)` call existing `runtime.heartbeatGroupsPage({ sessionId })`. |
| 62 | +- app-server `pageHeartbeatGroups(sessionId)` reads the session DB projection when session metadata exists; no Avatar-specific Heartbeat endpoint is required. |
| 63 | + |
| 64 | +## External UI Reference |
| 65 | + |
| 66 | +Context7 lookup for `/sikandarjodd/ai-elements` confirmed the relevant component families for this package: Conversation, Message, Reasoning, Tool, Context, Loader, and Actions. The reference is a component-pattern source, not a transport or truth-source law. |
| 67 | + |
| 68 | +## Verification Evidence |
| 69 | + |
| 70 | +- `bun run --filter '@agenter/web-heartbeat-view' typecheck`: passed with 0 errors and 0 warnings. |
| 71 | +- `bun run --filter '@agenter/web-heartbeat-view' test`: passed with unit, Storybook browser, and DOM browser projects. |
| 72 | +- `bun run --filter '@agenter/web-heartbeat-view-example' typecheck`: passed with 0 errors and 0 warnings. |
| 73 | +- `bun run --filter '@agenter/web-heartbeat-view-example' test`: passed. |
| 74 | +- Static scan found no `any`, `as any`, or `@ts-nocheck` under `packages/web-heartbeat-view`. |
| 75 | +- Static scan found no backend or Studio code diff in `packages/app-server`, `packages/client-sdk`, or `apps/studio`. |
| 76 | +- Route-level evidence is stored under `.screenshot/web-heartbeat-view/` for mobile and desktop directory/Heartbeat flows. |
| 77 | +- The live acceptance URL for this apply round is `http://127.0.0.1:4180/?wsUrl=ws%3A%2F%2F127.0.0.1%3A4590%2Ftrpc`. |
0 commit comments