@pinecall/room 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Pinecall
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,283 @@
+# @pinecall/room
+
+The caller's side of a Pinecall call, in a browser. A visitor talks to your agent, writes to it, or
+asks it to ring their phone; the page draws what is happening from the call's own log. No
+framework, no key in the page.
+
+## One store, three imports
+
+Everything is one store: a value you read, a function you subscribe with, and a handful of verbs
+that change it. The package has three entry points, and each one is for a different place.
+
+| import | where it runs | what it gives you |
+|---|---|---|
+| `@pinecall/room` | the page | `room()`, the store of one conversation, and `rowsOf`, `knownBy`, `brief` to draw it |
+| `@pinecall/room/react` | the page, in React | `useRoom()` and `useStore()` |
+| `@pinecall/room/server` | your server | `mint()`, `dial()` and `GatewayRefused`: the only code that touches the key |
+
+A conversation has two parts, and they are not the same thing. **The seat** is a LiveKit room: it
+carries the audio and the typed lines. **The log** is the call's record on the gateway, relayed by
+your server: every turn, every tool the agent called and what came back, the agent's own state, and
+at the end the cost and the score. The store joins the two. What the page draws is the log folded
+by `@pinecall/protocol`, the same fold the Pinecall console draws from.
+
+## Install
+
+```bash
+pnpm add @pinecall/room livekit-client
+```
+
+`livekit-client` is only loaded when a seat is taken, so a page that only offers "call me" never
+downloads it. React is optional: `@pinecall/room/react` needs React 18 or 19, the rest needs
+nothing. The server entry needs Node 24 or anything else with `fetch`.
+
+## From a page
+
+```ts
+import { room, rowsOf } from "@pinecall/room";
+
+const call = room({
+  tokens: async (scope) => {
+    const answer = await fetch("/api/token", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ scope }),
+    });
+    const body = await answer.json();
+    if (!answer.ok) throw new Error(body.detail ?? `the server answered ${answer.status}`);
+    return body;
+  },
+  log: (call) => `/api/log?call=${encodeURIComponent(call)}`,
+});
+
+call.subscribe((state) => {
+  status.textContent = state.phase === "failed" ? state.error : state.phase;
+  lines.replaceChildren(
+    ...rowsOf(state.log).map((row) => {
+      const line = document.createElement("p");
+      line.textContent = row.kind === "turn" ? `${row.role}: ${row.text}` : `${row.name}(${row.args})`;
+      return line;
+    }),
+  );
+});
+
+talkButton.onclick = () => call.start("talk");
+chatButton.onclick = () => call.start("chat");
+form.onsubmit = (event) => {
+  event.preventDefault();
+  void call.send(input.value);
+  input.value = "";
+};
+hangUp.onclick = () => call.leave();
+```
+
+`start` is safe to call from a button that gets clicked twice: while a conversation is opening or
+live, it does nothing. Once one has ended or failed, it opens a new one. When the page goes away,
+`call.close()` takes everything down at once.
+
+## With React
+
+```tsx
+import { useRoom } from "@pinecall/room/react";
+import { rowsOf } from "@pinecall/room";
+
+// `tokens` is the function from the page above.
+export function Visitor() {
+  const call = useRoom({ tokens, log: (id) => `/api/log?call=${encodeURIComponent(id)}` });
+
+  if (call.phase === "idle") return <button onClick={() => call.start("talk")}>Talk</button>;
+  if (call.phase === "failed") return <p>{call.error}</p>;
+  return (
+    <>
+      {call.wantsSound && <button onClick={call.playSound}>Turn the sound on</button>}
+      {rowsOf(call.log).map((row) => (
+        <p key={row.key}>{row.kind === "turn" ? row.text : row.name}</p>
+      ))}
+      {call.phase === "live" && <button onClick={() => call.leave()}>Hang up</button>}
+    </>
+  );
+}
+```
+
+`useRoom` makes one room per mounted component and closes it when the component unmounts. The
+options are read when they are used, not when the room is made, so a `tokens` written inline — a
+new function every render — is fine: the one from the last render is the one that runs. It hands
+back the state with the five verbs beside it.
+
+`useStore(store)` is the plain version: any store of this package, read with React's
+`useSyncExternalStore`. `useRoom` is `useStore` over a room it owns.
+
+## Your server: the three routes
+
+The page never holds a key. Every question it asks goes to your own server, which asks the
+gateway with the org's key and hands back only what that one visitor needs. The key needs two
+scopes: `talk` (a ticket, a dial) and `calls` (reading a call's log). It never reaches the page.
+
+| route | the page sends | your server does | it answers |
+|---|---|---|---|
+| `POST /api/token` | `{scope}`, `talk` or `chat` | `mint(key, {url, agent, scope})` | `{server_url, participant_token, call}` |
+| `GET /api/log?call=` | the call id, and `last-event-id` on a resume | streams `GET /v1/calls/{call}/events` with the key | the gateway's stream, its status passed through: `204` when the call is sealed |
+| `POST /api/call-me` | `{to}`, a number in E.164 | `dial(key, {url, agent, to})` | `{call}` |
+
+The names of the routes are yours; the page only knows the functions you give `room()`. With
+Hono:
+
+```ts
+import { Hono } from "hono";
+import { dial, GatewayRefused, mint } from "@pinecall/room/server";
+
+const KEY = process.env.PINECALL_KEY!;
+const url = "https://box.pinecall.io";
+const agent = "clinica-norte";
+const app = new Hono();
+
+// A refusal keeps the gateway's own sentence and status: it names the fix.
+const refused = (error: unknown) => {
+  if (error instanceof GatewayRefused) return Response.json({ detail: error.message }, { status: error.status });
+  throw error;
+};
+
+app.post("/api/token", async (c) => {
+  const { scope } = await c.req.json();
+  return mint(KEY, { url, agent, scope }).then((minted) => c.json(minted), refused);
+});
+
+app.post("/api/call-me", async (c) => {
+  const { to } = await c.req.json();
+  return dial(KEY, { url, agent, to }).then(({ call }) => c.json({ call }), refused);
+});
+
+app.get("/api/log", async (c) => {
+  const call = c.req.query("call") ?? "";
+  if (!mine(c, call)) return c.body(null, 404);
+  const resume = c.req.header("last-event-id");
+  const answer = await fetch(`${url}/v1/calls/${encodeURIComponent(call)}/events`, {
+    headers: { authorization: `Bearer ${KEY}`, accept: "text/event-stream", ...(resume ? { "last-event-id": resume } : {}) },
+    signal: c.req.raw.signal,
+  });
+  return new Response(answer.body, { status: answer.status, headers: { "content-type": "text/event-stream" } });
+});
+```
+
+The relay is four lines that matter: the call, the resume cursor, the key on the header, and the
+gateway's status and body passed through as they came. It forwards `last-event-id`, so a page
+whose stream dropped picks up where it was; and it passes a `204` through, so a sealed call is
+known to be over rather than retried.
+
+`mine(c, call)` is yours to write, and it is not optional: a relay that streams any call id it is
+handed is a window onto every call of the org. Keep the call ids a visitor's session minted or
+dialled, and relay only those.
+
+## Have the agent call me
+
+Give `room()` a `callMe`, and the page can ask for a phone call instead of a seat:
+
+```ts
+const call = room({
+  tokens,
+  log: (id) => `/api/log?call=${encodeURIComponent(id)}`,
+  callMe: async (to) => {
+    const answer = await fetch("/api/call-me", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ to }),
+    });
+    const body = await answer.json();
+    if (!answer.ok) throw new Error(body.detail ?? `the server answered ${answer.status}`);
+    return body;
+  },
+});
+
+await call.callMe("+34600000001");
+```
+
+There is no seat on a phone call: the conversation happens on the phone, and the page only
+watches. Everything it says comes from the log. The phase is `ringing` while the call is being
+placed, `live` once the log says it was answered, and `ended` when the log says it is over — or
+straight from `ringing` when nobody picked up. `speaking` comes from the log too.
+
+The gateway refuses a dial to a number that has never called or written to the org, and counts
+dials per minute and per day. Those refusals reach the page as a failed call with the gateway's
+sentence.
+
+## What `state` says
+
+Every field is the truth at the moment it was published. A new state is a new object; one you were
+handed is never changed afterwards, so it can be compared by reference and kept.
+
+| field | what it is |
+|---|---|
+| `phase` | `idle` · `opening` (minting, joining) · `ringing` (a phone call not yet answered) · `live` · `ended` · `failed` |
+| `mode` | `talk`, `chat`, `phone`, or `null` before anything started |
+| `call` | the call id, once the tokens or the dial answered it; `""` before |
+| `error` | the sentence to show when `phase` is `failed`; `""` otherwise |
+| `log` | the call as `@pinecall/protocol` folds it: `turns`, `tools`, `app_state`, `status`, `live` (the words being said right now), `cost` |
+| `entries` | every entry of the log read so far, in order |
+| `connection` | the log's stream: `connecting` · `live` · `reconnecting` · `ended` (also before anything opened) |
+| `wantsSound` | `true` when the browser has not let the page play sound yet: show a button that calls `playSound()` |
+| `speaking` | `{agent, user, level}`: who is making a sound right now, and how loud the agent is, 0 to 1 |
+
+The phase and everything around it — `error`, `connection`, `wantsSound`, `speaking` — are
+published the moment they change. The log is painted at most ten times a second: a burst of
+entries inside one turn is one repaint, not forty.
+
+The log is read for a while after the seat closes. The agent's last words, the call's cost and its
+score are entries that arrive after the visitor has gone, so `cost` is `null` until `call.summary`,
+which comes after `call.ended`. The stream is followed until `call.score`, the last thing a log ever
+says, or for `linger` milliseconds after the call ended (60 000 by default: the worker notices a caller has gone some twenty seconds after the fact, and the score comes after that), whichever is first.
+
+A stream that drops is opened again from the last entry read, after half a second, doubling to
+eight seconds while the relay does not answer.
+
+## Drawing the conversation
+
+```ts
+import { brief, knownBy, rowsOf } from "@pinecall/room";
+```
+
+`rowsOf(state.log)` is the conversation as one column, in the order things happened: every turn,
+and every tool run above the reply it was called for. A turn row has `role`, `text`, and for the
+agent `ms` (how long the reply took, end to end), `ttft` (the model's time to its first token —
+what a written call has, since nobody spoke) and `interrupted`. A tool row has `name`, `args` and `output`
+as one short line each, `status` (`running`, `done`, `failed`) and `error` — and `raw`, the
+`arguments` and `output` as they are, for a page that draws more than one line.
+
+`knownBy(state.log)` is the agent's own declared fields, in the order its class writes them, as
+`[name, value]` pairs with the empty ones left out. `brief(value, max)` is a value as one line of
+JSON, cut at `max` characters. A field that is an object is opened one level — `person.name`, `person.email` — so a page shows a name rather than a JSON blob.
+
+## Sound and the browser's permission
+
+In `talk`, the microphone is turned on once the room is joined, and the agent's voice plays through
+a hidden audio element at the end of the page. `chat` joins the same room — the typed lines ride it
+on LiveKit's `lk.chat` topic — and never asks for the microphone and never plays a sound.
+
+A browser plays sound only after the visitor has done something on the page. When it has not let
+the page yet, `wantsSound` is `true`: show a button, and call `playSound()` from its click. It is
+asked for once, not on every event the browser fires about it, and after the click it is `false`
+until the browser changes its mind.
+
+The microphone is the browser's to give. When the visitor says no, or the device is missing, the
+call fails with a sentence meant for them (below), and the page can offer to write instead.
+
+## When something is refused
+
+Nothing fails silently. Every refusal is a phase and a sentence, or a rejected promise.
+
+| what happened | the state |
+|---|---|
+| `tokens` threw (your server, or the gateway behind it, said no) | `failed`, `error` is its message; nothing was opened |
+| the microphone was refused in `talk` | `failed`, `error` is "I could not get to your microphone. Check the browser's permission, or write instead." |
+| the room could not be joined in `chat` | `failed`, `error` is LiveKit's message |
+| `livekit-client` could not be loaded | `failed`, `error` is the loader's message |
+| `callMe` threw | `failed`, `error` is its message |
+| `callMe()` on a room given no `callMe` | `failed`, `error` says so |
+| the log relay answered something other than 2xx or 204 | on the phone: `failed`, "the log answered 401". In a room: `connection` is `ended` and the phase is left to the seat, which is the call |
+| the room closed from the other side | `ended`; the log is read on until the score |
+| an entry of the log this version cannot read | skipped; `onSkipped(why)` is called, and the rest of the call still draws |
+| `send()` outside a live seat | the promise rejects with "not in a call"; an empty line is nothing |
+
+On the server, `mint` and `dial` throw `GatewayRefused` for a refusal: `status` is the gateway's,
+and `detail` its sentence when it sent one (`null` when the body was not the gateway's JSON). The
+sentence names the fix — a quota, a scope the key does not hold, a number the org cannot call —
+so pass it on rather than rewording it.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/** @pinecall/room: the caller's side of a Pinecall call in a browser — one store, no framework. */
+export { room } from "./room.js";
+export type { Minted, Mode, Phase, RoomOptions, RoomState, RoomStore } from "./room.js";
+export type { Store } from "./store.js";
+export type { Connection } from "./log/follow.js";
+export type { Speaking } from "./seat/join.js";
+export type { LivekitModule } from "./seat/livekit.js";
+export { brief, knownBy, rowsOf, type Row } from "./rows.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mGAAmG;AAEnG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACxF,YAAY,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,YAAY,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+/** @pinecall/room: the caller's side of a Pinecall call in a browser — one store, no framework. */
+export { room } from "./room.js";
+export { brief, knownBy, rowsOf } from "./rows.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mGAAmG;AAEnG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAMjC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAY,MAAM,WAAW,CAAC"}

package/dist/log/fold.d.ts

@@ -0,0 +1,23 @@
+/** The log folded as it arrives: the protocol's own reducer, one entry at a time, every entry kept. */
+import { type Entry, type State } from "@pinecall/protocol";
+import type { SseMessage } from "./sse.js";
+/** What the page draws from: the call as the protocol folds it, and the entries it was folded from. */
+export interface Folded {
+    log: State;
+    entries: Entry[];
+}
+/**
+ * One call's log, folding. The protocol's `apply` mutates the state it is given, so what this
+ * holds is a working copy: `snapshot()` is what leaves it, and nothing that left is ever changed.
+ */
+export declare class LogFold {
+    #private;
+    constructor(onSkipped: (why: string) => void);
+    /** The working state, for a question asked right now. Read it; never keep it or hand it out. */
+    get now(): Readonly<State>;
+    /** Fold one message in. An entry this copy of the wire cannot read is one entry, not a broken call. */
+    take(message: SseMessage): Entry | null;
+    /** A copy to publish: the page may keep it, compare it and hand it to React. */
+    snapshot(): Folded;
+}
+//# sourceMappingURL=fold.d.ts.map

package/dist/log/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/log/fold.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG,OAAO,EAAoC,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,uGAAuG;AACvG,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,KAAK,CAAC;IACX,OAAO,EAAE,KAAK,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,OAAO;;IAKlB,YAAY,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAE3C;IAED,gGAAgG;IAChG,IAAI,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,CAEzB;IAED,uGAAuG;IACvG,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,KAAK,GAAG,IAAI,CAatC;IAED,gFAAgF;IAChF,QAAQ,IAAI,MAAM,CAEjB;CACF"}

package/dist/log/fold.js

@@ -0,0 +1,40 @@
+/** The log folded as it arrives: the protocol's own reducer, one entry at a time, every entry kept. */
+import { apply, decodeEntry, initialState } from "@pinecall/protocol";
+/**
+ * One call's log, folding. The protocol's `apply` mutates the state it is given, so what this
+ * holds is a working copy: `snapshot()` is what leaves it, and nothing that left is ever changed.
+ */
+export class LogFold {
+    #state = initialState();
+    #entries = [];
+    #onSkipped;
+    constructor(onSkipped) {
+        this.#onSkipped = onSkipped;
+    }
+    /** The working state, for a question asked right now. Read it; never keep it or hand it out. */
+    get now() {
+        return this.#state;
+    }
+    /** Fold one message in. An entry this copy of the wire cannot read is one entry, not a broken call. */
+    take(message) {
+        if (message.data === "")
+            return null;
+        let entry;
+        try {
+            entry = decodeEntry(JSON.parse(message.data));
+        }
+        catch (why) {
+            const said = why instanceof Error ? why.message : String(why);
+            this.#onSkipped(`${message.event ?? "a message"} at ${message.id ?? "no id"}: ${said.split("\n")[0] ?? said}`);
+            return null;
+        }
+        this.#state = apply(this.#state, entry);
+        this.#entries.push(entry);
+        return entry;
+    }
+    /** A copy to publish: the page may keep it, compare it and hand it to React. */
+    snapshot() {
+        return { log: structuredClone(this.#state), entries: [...this.#entries] };
+    }
+}
+//# sourceMappingURL=fold.js.map

package/dist/log/fold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.js","sourceRoot":"","sources":["../../src/log/fold.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAA0B,MAAM,oBAAoB,CAAC;AAU9F;;;GAGG;AACH,MAAM,OAAO,OAAO;IAClB,MAAM,GAAU,YAAY,EAAE,CAAC;IAC/B,QAAQ,GAAY,EAAE,CAAC;IACd,UAAU,CAAwB;IAE3C,YAAY,SAAgC;QAC1C,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,gGAAgG;IAChG,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,uGAAuG;IACvG,IAAI,CAAC,OAAmB;QACtB,IAAI,OAAO,CAAC,IAAI,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,KAAY,CAAC;QACjB,IAAI,CAAC;YACH,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC9D,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,OAAO,OAAO,CAAC,EAAE,IAAI,OAAO,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YAC/G,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,gFAAgF;IAChF,QAAQ;QACN,OAAO,EAAE,GAAG,EAAE,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC5E,CAAC;CACF"}

package/dist/log/follow.d.ts

@@ -0,0 +1,24 @@
+/** Follow a call's log over fetch: from where it was, through a dropped stream, to the score. */
+import { type SseMessage } from "./sse.js";
+/** What the page can honestly say about its stream. Nothing here is a guess. */
+export type Connection = "connecting" | "live" | "reconnecting" | "ended";
+/** Why a follow stopped by itself: the score arrived, the call was sealed, or the relay said no. */
+export type Ending = {
+    kind: "scored";
+} | {
+    kind: "sealed";
+} | {
+    kind: "refused";
+    status: number;
+};
+/** What the room wants of its stream: every message in order, and how the connection is going. */
+export interface LogReader {
+    /** Every message, in seq order, the moment it is framed. The cursor has already moved past it. */
+    onMessage: (message: SseMessage) => void;
+    onConnection: (connection: Exclude<Connection, "ended">) => void;
+    /** Called once, and nothing is said after it. Never called when the room stopped the follow. */
+    onEnded: (ending: Ending) => void;
+}
+/** Open the log at `url`. Returns the call that stops it; stopping twice is stopping once. */
+export declare function followLog(url: string, reader: LogReader, fetcher: typeof fetch): () => void;
+//# sourceMappingURL=follow.d.ts.map

package/dist/log/follow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow.d.ts","sourceRoot":"","sources":["../../src/log/follow.ts"],"names":[],"mappings":"AAAA,iGAAiG;AAIjG,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtD,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,OAAO,CAAC;AAE1E,oGAAoG;AACpG,MAAM,MAAM,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACxB,kGAAkG;IAClG,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,YAAY,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACjE,gGAAgG;IAChG,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAUD,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,KAAK,GAAG,MAAM,IAAI,CAsE3F"}