@urun-sh/core 0.2.1 → 0.2.3

package/README.md

@@ -22,33 +22,64 @@ const app = App('my-app', {
 
 const session = app.generate({ prompt: 'A sunset' })
 
+// Consume the stream the runtime produces (direction is decided by first use). Tracks
+// arrive ASYNCHRONOUSLY — subscribe with `.on('track', …)`; never read `.track` once.
 const video = session.stream('video')
-if (video.track) {
-  videoElement.srcObject = new MediaStream([video.track])
-}
+video.on('track', (track) => {
+  videoElement.srcObject = new MediaStream([track])
+})
 
-session.doc('control').set({ prompt: { text: 'A forest' } })
+// Drive the app by writing DESIRED state into the control doc; the runtime reactively
+// reconciles it (cheap config via an inline live read, structural change via `doc.bind`).
+session.doc('control').set({ desired: { prompt: { text: 'A forest' } } })
 ```
 
-The names mirror the Python side:
+The names mirror the Python side 1:1:
 
 - `App('my-app')` mirrors `urun.App('my-app')`
 - `app.generate()` mirrors `@app.function def generate(...)`
-- `session.stream('video')` mirrors `ctx.stream('video')`
+- `session.stream('video')` mirrors `ctx.stream('video', codec=...)`
 - `session.doc('control')` mirrors `ctx.doc('control')`
+- `createStore()` mirrors the runtime `store = app.store`
+
+## Streams are symmetric (produce-or-consume by first use)
+
+`session.stream(name)` is one symmetric primitive — the **first producer decides the
+direction** and the peer consumes (full-duplex = two named streams). On the runtime,
+`ctx.stream("name")` is the polymorphic I/O endpoint: the pipeline HEAD when it drives and the
+TAIL when it sinks. `attach(track)` makes the client the producer of that name (the inbound HEAD
+the runtime composes with `ctx.stream(name) | …`); calling `stream(name)` without attaching
+consumes the runtime's output. A second producer on the same name fails loud with
+`StreamDirectionConflict` — never a silent merge. The runtime `ctx.stream(codec=…)` sink owns
+media encode; the client only attaches the inbound `track` to a media element. Tracks arrive
+asynchronously — subscribe with `.on('track', …)`.
+
+## The control doc is the reactive desired-state surface
+
+The client does NOT call an imperative `start/update/stop`. It writes `desired.*` keys into a
+control doc with `session.doc(name).set(...)`. The runtime reads CHEAP config inline from the
+live `doc.desired.*` props and uses `doc.bind(construct, [live props])` (React `useMemo`) to
+reconstruct a stage on STRUCTURAL change — the single reconcile lane, no field-mapping, no
+second hand-poll (`pipeline.bind` / `stage.bind(doc, mapping)` are retired). Keep the
+`desired.<path>` names the client writes consistent with what the runtime reads.
 
 ## API
 
 - `App(appId, options)` — reference a deployed urun app.
 - `app.<function>(args?)` — call a Python function and get a session handle.
-- `session.stream(name)` — get or create a named media stream.
-- `session.stream(name).track` — read the latest inbound browser track.
-- `session.stream(name).attach(track)` — send a local browser track upstream.
-- `session.stream(name).detach()` — stop sending the local browser track.
+- `session.stream(name)` — get a named symmetric stream (media or data); first use decides direction.
+- `session.stream(name).track` — read the latest inbound track (consume side).
+- `session.stream(name).on('track', cb)` — subscribe to inbound tracks as they arrive.
+- `session.stream(name).attach(track)` — produce: send a local browser track upstream.
+- `session.stream(name).detach()` — stop producing the local browser track.
 - `session.stream(name).seek(seconds)` — seek a persisted finite stream to seconds from start.
 - `session.stream(name).seek('live')` — return a live stream to the live edge.
-- `session.doc(name).set(patch)` — update a session document.
-- `createStore(options)` — advanced global key/value access.
+- `session.doc(name).get()` — read the merged document snapshot.
+- `session.doc(name).set(patch)` — write desired state into a session document.
+- `session.doc(name).on('change', cb)` — react to runtime-published document changes.
+- `createStore(options)` — content-addressed global store: `get(key)` / `has(key)` reads and
+  `on(name, cb)` / `emit(name, data)` global streams. (App-scoped `store.cache` is a runtime
+  concern; content-addressed blobs — `store.model`/`store.path`/`store.repo` — are not app-scoped.)
 
 ## Authentication