feat(web-heartbeat-view): add standalone heartbeat package

Author: Gaubee

bun.lock

@@ -57,6 +57,8 @@
     "packages/tmux-client",
     "packages/web-chat-view",
     "packages/web-chat-view/example",
+    "packages/web-heartbeat-view",
+    "packages/web-heartbeat-view/example",
     "packages/web-components"
   ],
   "devDependencies": {

package.json

@@ -0,0 +1,12 @@
+import type { StorybookConfig } from "@storybook/svelte-vite";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.stories.@(ts|svelte)"],
+  addons: ["@storybook/addon-docs", "@storybook/addon-vitest"],
+  framework: {
+    name: "@storybook/svelte-vite",
+    options: {},
+  },
+};
+
+export default config;

packages/web-heartbeat-view/.storybook/main.ts

@@ -0,0 +1,27 @@
+import type { Preview } from "@storybook/svelte-vite";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    viewport: {
+      viewports: {
+        iphone14: {
+          name: "iPhone 14",
+          styles: {
+            width: "390px",
+            height: "844px",
+          },
+          type: "mobile",
+        },
+      },
+      defaultViewport: "iphone14",
+    },
+  },
+};
+
+export default preview;

packages/web-heartbeat-view/.storybook/preview.ts

@@ -0,0 +1,51 @@
+# `@agenter/web-heartbeat-view` SPEC
+
+This document records durable package-level law for the Heartbeat presentation atom.
+
+## 1. Package Role
+
+`@agenter/web-heartbeat-view` owns the reusable Heartbeat runtime observation surface.
+
+It owns:
+
+- grouped Heartbeat presentation over existing runtime-store facts
+- parser/materialization helpers for grouped `before-call`, `call`, `compact`, and `before-call-pending` records
+- structured rendering for text, thinking, JSON/config facts, tool calls/results, compact cards, and footer status
+- explicit `readonly | configable` capability presentation
+- host-neutral `AgenterHeartbeatConnection` types
+
+It does not own:
+
+- backend Heartbeat truth or new backend endpoints
+- Studio route/controller state
+- example app routing/bootstrap
+- authentication or authorization policy
+
+## 2. Truth Boundary
+
+Heartbeat truth remains the grouped runtime/session DB projection supplied by `@agenter/client-sdk`.
+
+The package must not rebuild Heartbeat truth from raw chat, raw `request_aux`, raw `heartbeat_part`, or model-call histories in the browser.
+
+## 3. Capability Boundary
+
+`readonly` is a frontend presentation mode that keeps the surface clean by hiding compact/config write controls.
+
+`configable` may expose bottom-statusbar compact/config actions, but those actions must call explicit host callbacks.
+
+Transport isolation belongs to authentication and authorization, not to the package's presentation mode.
+
+## 4. Host Boundary
+
+The package must not import `apps/studio`. Studio may later import this package through a thin adapter after standalone example acceptance.
+
+Framework7 page wrappers are optional host conveniences; the core `HeartbeatView` remains host-neutral.
+
+## 5. Verification Contract
+
+High-value package verification requires:
+
+- `bun run --filter '@agenter/web-heartbeat-view' typecheck`
+- `bun run --filter '@agenter/web-heartbeat-view' test`
+
+Standalone user acceptance belongs to `packages/web-heartbeat-view/example`.

packages/web-heartbeat-view/SPEC.md

@@ -0,0 +1,38 @@
+{
+  "name": "@agenter/web-heartbeat-view-example",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "typecheck": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.check.json",
+    "test": "vitest run --config ./vitest.config.ts",
+    "start": "bun run ./scripts/start-example.ts"
+  },
+  "dependencies": {
+    "@agenter/client-sdk": "workspace:*",
+    "@agenter/web-heartbeat-view": "workspace:*",
+    "@lucide/svelte": "^1.7.0",
+    "dom7": "^4.0.6",
+    "framework7": "^9.0.4",
+    "framework7-icons": "^5.0.5",
+    "framework7-svelte": "^9.0.4",
+    "idb-keyval": "^6.2.2"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^7.0.1",
+    "@sveltejs/kit": "^2.57.0",
+    "@sveltejs/vite-plugin-svelte": "^7.0.0",
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/bun": "latest",
+    "@types/node": "^24",
+    "svelte": "^5.55.2",
+    "svelte-check": "^4.4.6",
+    "typescript": "latest",
+    "vite": "^8.0.7",
+    "vitest": "^4.1.2"
+  }
+}

packages/web-heartbeat-view/example/package.json

@@ -0,0 +1,42 @@
+import net from "node:net";
+
+const preferredPort = Number(process.env.PORT ?? process.env.WEB_HEARTBEAT_VIEW_PORT ?? "4179");
+const host = process.env.HOST ?? "127.0.0.1";
+const exampleRoot = import.meta.dirname.replace(/\/scripts$/u, "");
+
+const isPortAvailable = async (port: number): Promise<boolean> => {
+  return await new Promise<boolean>((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => {
+      resolve(false);
+    });
+    server.listen(port, host, () => {
+      server.close(() => resolve(true));
+    });
+  });
+};
+
+const pickAvailablePort = async (port: number): Promise<number> => {
+  for (let candidate = port; candidate < port + 100; candidate += 1) {
+    if (await isPortAvailable(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`unable to find an available port near ${port}`);
+};
+
+const port = await pickAvailablePort(preferredPort);
+
+const proc = Bun.spawn({
+  cmd: ["bun", "run", "dev", "--", "--host", host, "--port", String(port)],
+  cwd: exampleRoot,
+  stdout: "inherit",
+  stderr: "inherit",
+  stdin: "inherit",
+});
+
+console.log(`web-heartbeat-view example: http://${host}:${port}`);
+
+const exitCode = await proc.exited;
+process.exit(exitCode);