@mega-yfue/eufy-sdk 0.2.0-beta.1 → 0.2.0-beta.11

package/dist/transport/p2p/command-router.d.ts

@@ -18,6 +18,23 @@ import type { FfmpegLevel } from "../ffmpeg.js";
 import { SharedLiveSource } from "./shared-live-source.js";
 import { type PowerTier, type SessionManagerOpts } from "./session-manager.js";
 import { FragmentRecording } from "./fragment-recording.js";
+/**
+ * What a caller's own deadline on a station call has to clear, in milliseconds.
+ *
+ * A caller that bounds one of these calls itself races these waits, and a bound below them reports the
+ * caller's own expiry in place of the reason this SDK was about to give — the two are indistinguishable to
+ * whoever reads the outcome, and they call for different next steps. Published so that bound can be derived
+ * rather than copied: a literal in a caller's source is a second source of truth that goes stale silently
+ * when these change.
+ *
+ * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
+ * up. `level2Grace` applies twice where the key is required: the negotiation is re-prompted once.
+ */
+export declare const P2P_STATION_WAITS: {
+    readonly connect: 20000;
+    readonly level2Grace: 25000;
+    readonly level2Settle: 8000;
+};
 /**
  * Options accepted when warming a {@link SharedLiveSource} for a device (all optional).
  *
@@ -71,7 +88,7 @@ export interface P2PRouterDeps {
 }
 export declare class P2PCommandRouter {
     private readonly deps;
-    /** Per-station P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount. */
+    /** P2P session lifecycle: on-demand open + battery-aware idle-detach + refcount, per session key. */
     private readonly manager;
     /** Error objects already forwarded while a station startup awaits the same session signal. */
     private readonly reportedErrors;
@@ -79,6 +96,21 @@ export declare class P2PCommandRouter {
     private readonly liveSources;
     /** The options each live source was built from, so a later caller's conflicting ones can be reported. */
     private readonly liveSourceOpts;
+    /**
+     * The session each live source pulls over — the station's own serial, or the source's own media
+     * session key.
+     *
+     * Written the instant the choice is made and BEFORE the connection is opened, which is what makes it
+     * a reservation rather than a record. Two cameras started together (the four-tile case this feature
+     * exists for) would otherwise both find the station's session free: a consumer attaches only after
+     * `sharedLiveSourceFor` returns, so neither is visible to the other through consumer counts, and both
+     * would take the shared connection and contend on it.
+     *
+     * A station entry is kept as well as a media one, because "is the station's own session already
+     * claimed" is the question being asked, and an entry that is present but not yet in
+     * {@link liveSources} is a claim in flight.
+     */
+    private readonly liveSessionKeys;
     /**
      * The open talkback per `${parentSn}:${channel}`, if any. The device plays one audio stream at a
      * time and the session carries one audio sequence, so this path is exclusive where a live pull is
@@ -90,6 +122,12 @@ export declare class P2PCommandRouter {
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
+    /**
+     * Emit a live trace under a station session's handle, for work this router does ON that session before
+     * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+     * handle as everything the session goes on to trace, which is what groups one attempt.
+     */
+    private traceOnStation;
     /**
      * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
      * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a
@@ -99,7 +137,10 @@ export declare class P2PCommandRouter {
      * `no P2P session`.
      */
     static claimsDevice(dev: EufyDevice): boolean;
-    /** Stations with a live P2P session (a snapshot; mutate via the lifecycle methods, not this map). */
+    /**
+     * The open P2P sessions by key — a station's own under its serial, a camera's media session under
+     * `<stationSn>#live:<channel>` (a snapshot; mutate via the lifecycle methods, not this map).
+     */
     getSessions(): Map<string, P2PSession>;
     /**
      * Speculatively open + briefly hold a station's session (e.g. after a doorbell ring) so a
@@ -109,7 +150,7 @@ export declare class P2PCommandRouter {
      *
      * One hold, taken before the open so a slow connect can't idle-close mid-flight. It expires on its
      * own, which arms the station's idle window rather than closing the session, per {@link PREWARM_MS}.
-     * A second hold after the open would buy nothing: {@link openStation} returns once the socket is bound
+     * A second hold after the open would buy nothing: {@link openSession} returns once the socket is bound
      * and the lookups are away, not once the peer has answered, so both would expire together.
      *
      * Best-effort — a failed open surfaces via `onError`. A {@link SessionSupersededError} does not: the
@@ -142,7 +183,41 @@ export declare class P2PCommandRouter {
      * when present, else the freshest private IP in the record ({@link freshestLanIp}) — so P2P works
      * on-LAN even when broadcast is blocked (AP isolation) or the record's `ip_addr` went stale.
      */
-    private openStation;
+    /**
+     * The key a camera's own media session is filed under, distinct from every station serial because a
+     * serial contains no `#`.
+     */
+    private static mediaSessionKey;
+    /** Whether `key` names a media session rather than a station's own. */
+    private static isMediaSessionKey;
+    /**
+     * Open (or reuse) a SECOND connection to a station, carrying one camera's media and nothing else.
+     *
+     * One session serves one camera: a station fans its cameras over a session and answers the most recent
+     * start on it, so two cameras down one tunnel take it from each other in turn. Another connection is
+     * how a station serves another camera.
+     *
+     * The hardware was shown to do this before the SDK did. A first-party display showing four tiles was
+     * captured opening one PPCS session per camera, with three cameras' video arriving in the same second
+     * at 2304x1296, 1600x1200 and 3840x2160 — three geometries at once, which no composed stream can be.
+     * Reproduced here afterwards on a base carrying two attached cameras, one at 3840x2160, both holding
+     * full frame rate at once over a session each, where the same pair down one session could only take
+     * turns.
+     *
+     * It carries media alone. The station announces its state to every client that connects, so a session
+     * wired to the same fan-out would report every event a second time; {@link makeSession} leaves this one
+     * unannounced, and the station's own session stays the single source of connection state, control
+     * notifications and frames.
+     *
+     * The level-2 key is waited for here on the same terms the station's own session gets, because a
+     * connection is not usable for this without one: an attached camera's media start has no level-1 form,
+     * so a start issued before the key arrives is dropped as `media-command-unsent`, and the stream then
+     * shows nothing until a later keepalive tick happens to find the key. A connected session that cannot
+     * carry the start is not a connected session, so this refuses rather than returning one.
+     */
+    private openMediaSession;
+    /** Open (or reuse) the session filed under `key`, dialling `parentSn`'s endpoint. */
+    private openSession;
     /**
      * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
      *
@@ -154,6 +229,12 @@ export declare class P2PCommandRouter {
      *
      * The `close` handler drops the session from the {@link SessionManager} and disposes any shared live
      * source riding this station (consumers get `stop`; a later attach rebuilds via the factory).
+     *
+     * A session filed under a media key is wired for errors and its own teardown ONLY. Connection state,
+     * level-2 readiness and inbound frames all reach the owner through the station's own session, and a
+     * station announces those to every client that connects — so fanning a second connection's copies out
+     * under the same station serial would report each one twice, and a close would tear down the station
+     * while its own session is still serving.
      */
     private makeSession;
     /**
@@ -262,22 +343,40 @@ export declare class P2PCommandRouter {
      * {@link releaseLingeringSiblings}. A pull with consumers is never touched. The release runs before the
      * reuse branch, so a reuse frees the station as a cold start does.
      *
+     * `mayOpenOwnSession` decides whether a camera that finds the station's own session claimed may open a
+     * connection of its own for it. Only the continuous-pull egresses pass it. A still must not: it wants one
+     * frame, and a socket plus a level-2 negotiation per thumbnail is a cost a tile refresh cannot justify —
+     * so a still asked for while a sibling is being watched contends as it always did, and the caller's
+     * retained image answers it. A live view still outranks a tile; what changed is that two live views no
+     * longer have to outrank each other.
+     *
      * The session goes into a {@link HeldSession} cell, so it can be replaced under a source that stays in
      * place.
      */
-    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts): Promise<SharedLiveSource>;
+    sharedLiveSourceFor(sn: string, opts?: SharedLiveOpts, mayOpenOwnSession?: boolean): Promise<SharedLiveSource>;
     /**
      * Tear down any pull on this station that is lingering for ANOTHER camera, before starting this one.
      *
      * A lingering pull has no consumers but is still held open, and on an attached camera holding it open means
-     * re-sending the full media start every keepalive tick. Two channels doing that at once on a station that
-     * serves one camera at a time leaves the new stream receiving nothing but the old camera's frames for as
-     * long as the linger lasts.
+     * re-sending the full media start every keepalive tick. Two channels doing that at once over ONE session,
+     * which serves one camera at a time, leaves the new stream receiving nothing but the old camera's frames
+     * for as long as the linger lasts.
      *
      * Several cameras genuinely being WATCHED together are never disturbed — the linger exists to make
      * re-opening the SAME camera cheap, and it keeps doing that. What it may not do is keep a camera nobody is
      * looking at competing with one somebody just asked for.
      *
+     * An `idle` source is skipped, because it is not a linger and holds nothing: it has never warmed, so it
+     * has sent no media start and is competing for nothing. Without that, two cameras opened at the same
+     * moment destroy each other — the second finds the first's source built but not yet attached to, reads
+     * zero consumers as a linger, and disposes the source its caller is holding. Which is the four-tile case
+     * this whole path exists for.
+     *
+     * A sibling lingering on a connection of its OWN is skipped for the same reason stated the other way: the
+     * contention this releases is contention over one session, and that sibling is not on this one. Dropping
+     * it would close a socket and throw away the cheap re-attach the linger exists to provide, to relieve a
+     * competition that is not happening.
+     *
      * A snapshot tile is nobody looking. Opening a live view in the Home app takes that cell fullscreen, so the
      * pulls refreshing the other cells are off screen, yet each goes on re-issuing its own media start every
      * retry tick — measured as four pulls warming together off one HomeBase, a live request landing 1.4 s later,
@@ -288,14 +387,27 @@ export declare class P2PCommandRouter {
      */
     private releaseLingeringSiblings;
     /**
-     * The channel a live viewer already holds on this station, if any, ignoring `key` itself.
+     * Whether another camera has already claimed this station's OWN session, ignoring `key`.
+     *
+     * The question a newcomer has to answer is not whether the station is busy — it can serve one camera
+     * per connection — but whether the connection it would otherwise share is taken. A camera on a media
+     * session of its own does not hold this one, so a station whose first camera has since stopped hands
+     * its own session to the next arrival rather than opening a socket beside an idle one.
+     *
+     * A claim counts while its source is still `idle`, source or no source. That is a start that has been
+     * handed to its caller but not yet attached to, and it is the only state in which two cameras asked for
+     * at the same moment can see each other: consumers attach after this method has already run for both.
+     *
+     * The cost is that a pull genuinely abandoned before its first attach goes on holding the station's own
+     * session, and the next camera pays for a connection of its own rather than reclaiming it. That is one
+     * socket against destroying a start someone is waiting on, which is not a close trade.
      *
      * A stopped source is skipped even when consumers are still attached to it. A failed start fails its
      * consumers without detaching them, so a caller still holding a dead handle leaves the count non-zero,
-     * and counting that as a viewer would refuse every later stream on the station until the client
-     * restarted. Only a source that can still deliver holds a place.
+     * and counting that as a viewer would put every later camera on a connection of its own until the
+     * client restarted. Only a source that can still deliver holds a place.
      */
-    private occupiedSiblingChannel;
+    private stationSessionInUse;
     /**
      * Whether the stream on `key` should re-assert its channel to hold the station.
      *
@@ -305,8 +417,8 @@ export declare class P2PCommandRouter {
      *  - Nothing attached: no. There is nobody to take the station for.
      *  - A live viewer attached: yes. That is the picture someone is looking at.
      *  - Held only for stills, while a sibling on this station has a live viewer: no. A still refreshes a
-     *    tile that is off screen while the live view is on it, and a station serving one camera at a time
-     *    cannot satisfy both. Measured: a still on a sibling halved a live view's frame rate for as long as
+     *    tile that is off screen while the live view is on it, and one session serving one camera at a time
+     *    cannot satisfy both — and a still does not open a connection of its own. Measured: a still on a sibling halved a live view's frame rate for as long as
      *    it took, and its own capture then took fifteen seconds because it was contending.
      *
      * A still with no live sibling re-asserts, so a tile refreshing on a quiet station is
@@ -321,8 +433,24 @@ export declare class P2PCommandRouter {
      * not.
      */
     private attachUnlessAborted;
-    /** Dispose one cached live source and forget it, so the next acquisition builds a fresh one. */
+    /**
+     * Dispose one cached live source and forget it, so the next acquisition builds a fresh one. Its claim
+     * on a session goes with it, and a media session opened for this source alone is closed: nothing else
+     * can reach that connection, so leaving it open would hold a socket and a station keepalive for a
+     * camera no longer being pulled. A claim on the STATION's own session is released without closing
+     * anything — that connection carries the station's control traffic and outlives any one camera.
+     */
     private dropLiveSource;
+    /** Close and forget the media session `key`'s live source owned, if it owned one. */
+    private closeMediaSession;
+    /**
+     * Drop the live source a media session was carrying, after that session closed on its own.
+     *
+     * The source holds the closed connection and never re-resolves it, so it can only answer its retained
+     * keyframe and then fail on its warm-up deadline. Its consumers get `stop`, and the next attach builds
+     * a fresh source — which, finding the station busy again, opens a fresh media session for it.
+     */
+    private tearDownMediaSession;
     /**
      * Drop everything that was riding a station's session, and report the station closed.
      *

package/dist/transport/p2p/index.d.ts

@@ -10,4 +10,5 @@ export * from "./envelope.js";
 export * from "./write-commands.js";
 export * from "./lan-ip.js";
 export { LIVE_TRACE_MESSAGE, type LiveTrace } from "./live-trace.js";
+export { P2P_STATION_WAITS } from "./command-router.js";
 export * as p2pCodec from "./codec.js";

package/dist/transport/p2p/live-stream.d.ts

@@ -67,7 +67,7 @@ export interface LiveStreamOptions {
      * How long an attached stream tolerates silence on its own channel before re-asserting again, in ms.
      *
      * The re-assert is settled by the first own-channel frame, because settling it is what stops two attached
-     * streams contending on a station that serves one camera at a time. Silence for this long says the station
+     * streams contending over one session, which serves one camera at a time. Silence for this long says the station
      * is no longer serving this camera, which is the only condition the re-assert was for. Defaults to twice
      * the keepalive interval, so a stream whose media flows never reaches it.
      */
@@ -129,8 +129,9 @@ export declare class LiveStream extends EventEmitter {
      * Stop re-issuing the media start once this camera's own media has arrived, on an attached camera.
      *
      * The nudge differs by topology and only one branch is a ping: an own-session camera sends a small
-     * keepalive, while an attached camera has no such state and re-sends the FULL media start. On a station that
-     * serves one camera at a time that restart re-asserts this channel against whatever else is warm, so two
+     * keepalive, while an attached camera has no such state and re-sends the FULL media start. Over one session,
+     * which serves one camera at a time, that restart re-asserts this channel against whatever else is warm on
+     * it, so two
      * attached streams restart every interval and contend for the station continuously — measured on a real base
      * as a full start every 3 s from each.
      *
@@ -185,7 +186,7 @@ export declare class LiveStream extends EventEmitter {
      *
      * The match is UNCONDITIONAL, however long a station serves another camera instead of this one.
      *
-     * A station serving one camera at a time hands a newly opened camera nothing but its sibling's frames until
+     * One session serving one camera at a time hands a newly opened camera nothing but its sibling's frames until
      * it switches, so "no media of my own yet, plenty for someone else" is what an ordinary handover looks like
      * and does not distinguish a station that tags differently from one that is simply busy.
      *

package/dist/transport/p2p/live-trace.d.ts

@@ -63,12 +63,37 @@ export type LiveTrace =
     phase: "sequence-restart";
     dataType: number;
 }
+/**
+ * Work on a station is holding for its session to connect, with the milliseconds it will wait.
+ *
+ * The earliest phase there is: nothing else on a station can be attempted until its session is up, and a
+ * caller whose own deadline expires inside this wait has this record and no other. Emitted only where a wait
+ * actually happens, so its absence states that the session was already connected.
+ */
+ | {
+    phase: "session-connect-wait";
+    waitMs: number;
+}
+/** The session connected, after this long. */
+ | {
+    phase: "session-connected";
+    waitedMs: number;
+}
+/**
+ * The session did not connect within its wait, so nothing on this station can be attempted.
+ *
+ * The one outcome that is otherwise indistinguishable from a station that answered and then refused: both
+ * leave a caller with no media and no phase naming a station.
+ */
+ | {
+    phase: "session-unreachable";
+    waitedMs: number;
+}
 /**
  * A live start is holding for the station's level-2 key, with the milliseconds it will wait.
  *
- * The first of three phases that account for the wait before any media command is sent. A start that looks
- * slow is either waiting here, waiting for the station to serve the channel it was asked for, or being
- * re-issued — and only these separate them.
+ * A start that looks slow is either waiting here, waiting for its session to connect, waiting for the station
+ * to serve the channel it was asked for, or being re-issued — and only these phases separate them.
  */
  | {
     phase: "level2-wait";
@@ -79,10 +104,63 @@ export type LiveTrace =
     phase: "level2-ready";
     cipherId: number;
 }
-/** The level-2 key did not arrive in its grace, so the start proceeds at level 1 or not at all. */
+/**
+ * The station's key is not coming, why, and the cipher where a station named one.
+ *
+ * Every ending of a level-2 wait carries one of these reasons, so a start refused for want of a key is
+ * accounted for however it ended. `grace-elapsed` is a wait that ran out and states how long was waited;
+ * the rest are answered without waiting, because the negotiation is one-shot per connection and a
+ * concluded one is final. `no-cipher-key` and `derivation-failed` are about this account's cipher
+ * material, `not-negotiating` and `session-closed` about the station or its connection — and only a
+ * reason reached under a negotiation has a cipher to name.
+ *
+ * A `grace-elapsed` start proceeds at level 1 where it has such a form, and not at all where it does not.
+ */
  | {
-    phase: "level2-absent";
-    waitedMs: number;
+    phase: "level2-unavailable";
+    reason: "no-cipher-key" | "derivation-failed" | "not-negotiating" | "session-closed" | "grace-elapsed";
+    cipherId?: number;
+    waitedMs?: number;
+}
+/**
+ * A station's cipher was answered with material for a DIFFERENT cipher, which was used in its place.
+ *
+ * The one lookup outcome no other phase accounts for: material for the cipher the station named is followed
+ * by `level2-ready` or by `level2-unavailable` with `derivation-failed`, an answer holding none by
+ * `no-cipher-key`, and a lookup that threw is reported as an error. Substituted material derives to
+ * nothing and otherwise reads as a station fault. `cipherId` is the cipher the station asked for,
+ * `answeredCipherId` the one whose material was used.
+ */
+ | {
+    phase: "cipher-fallback";
+    cipherId: number;
+    answeredCipherId: number;
+}
+/**
+ * The station answered its gateway-info prompt, so a key derivation has begun under the cipher it named.
+ *
+ * What separates a station that never answered the prompt from one that answered and produced no usable key:
+ * without it, `level2-unavailable` with `not-negotiating` covers both, and they are a station or network
+ * problem and an account cipher-material problem respectively.
+ */
+ | {
+    phase: "level2-negotiating";
+    cipherId: number;
+}
+/**
+ * A station was resolved for a call, stating what the caller's device is on it and whose station it is.
+ *
+ * Emitted before anything is sent, so it is the only account of the intended topology on a call that fails
+ * during resolution: an attached camera's media start has no unencrypted form, so whether a device was taken
+ * as attached decides what its failure means. `stationAdmin` states whether the signed-in account is the
+ * station's administrator, which is what a key the account cannot resolve turns on; `unstated` is a device
+ * record that names no administrator, which is not the same as naming another.
+ */
+ | {
+    phase: "station-resolved";
+    topology: "attached" | "own";
+    channel: number;
+    stationAdmin: "self" | "other" | "unstated";
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {
@@ -110,6 +188,22 @@ export type LiveTrace =
  | {
     phase: "path-stale";
     silentMs: number;
+}
+/**
+ * A stream received nothing on its own channel for the stall window, and what was done about it.
+ *
+ * A station that switches to a sibling leaves the stream it was serving with no frames, no error and no
+ * stop, so this silence is the only statement that it happened. `reasserted` re-issued the media start,
+ * which is the repair; `declined` left the channel alone because nothing is attached to this pull and
+ * taking the station back would take it from a camera someone is watching.
+ *
+ * Media still arriving means this never fires, so a picture that stopped advancing while this is silent
+ * stopped for a reason upstream of the station's attention.
+ */
+ | {
+    phase: "channel-silent";
+    silentMs: number;
+    outcome: "reasserted" | "declined";
 };
 /**
  * Record one startup observation at debug level.

package/dist/transport/p2p/media.d.ts

@@ -34,11 +34,22 @@ export declare function openLiveStream(session: P2PSession, opts?: LiveStreamOpt
  * The header states the stream's geometry when the capture started, and a stream that reconfigures
  * mid-burst leaves it describing something the returned bytes contradict; the return value describes an
  * image, so the image is its source of truth.
+ *
+ * The consumer is detached the moment the collected run is complete, and the decode that follows holds no
+ * station: it works on bytes already in memory. One session serves one camera at a time and a still never
+ * opens a second one, so a still that kept its pull attached across its own decode would deny
+ * that station to every live request for the length of an FFmpeg run — measured on a real base as a live
+ * request refused 370ms after the still it was waiting on had already collected everything it needed.
+ *
+ * `signal` ends the collection itself, not only the wait for it, and rejects with the signal's own reason
+ * because the abandonment is the caller's fact and not a failure of the source. It reaches only the
+ * collection: past that the station is already free, so there is nothing left for it to release.
  */
 export declare function captureSnapshotFromShared(source: SharedLiveSource, opts?: {
     timeoutMs?: number;
     collectMs?: number;
     skipKeyframes?: number;
+    signal?: AbortSignal;
     logger?: Logger;
     ffmpegLevel?: FfmpegLevel;
     ffmpegPath?: string;

package/dist/transport/p2p/p2p-session.d.ts

@@ -208,6 +208,10 @@ export declare class P2PSession extends EventEmitter {
      * cameras from that second group streamed normally at level-1 — including one of the same firmware as an
      * own-session camera that delivered no video at all for a reason of its own. An expired grace therefore
      * separates nothing on this path, and a start failure on such a session is not evidence about it.
+     *
+     * Every `false` answer carries a `level2-unavailable` trace naming its reason, wherever the wait ended: a
+     * `terminal` outcome is the one already stated where the negotiation concluded, since that is where the
+     * cipher and the cause are known, and re-stating it here would double every settled negotiation.
      */
     awaitLevel2Key(graceMs: number, graceFrom?: "call" | "session"): Promise<boolean>;
     /**

package/dist/transport/p2p/session-manager.d.ts

@@ -26,24 +26,35 @@ export interface SessionManagerOpts {
     batteryIdleMs?: number;
     /** Keepalive a single command holds after dispatch (ms). Default {@link COMMAND_KEEPALIVE_MS}. */
     commandKeepAliveMs?: number;
-    /** Power tier per station serial — injected by the facade (no model import). Default: everything `wired`. */
+    /**
+     * Power tier per station serial — injected by the facade (no model import). Default: everything
+     * `wired`. Asked about the STATION a session connects to, never the key it is filed under, so every
+     * session to one station gets that station's idle window.
+     */
     poweredFor?: (parentSn: string) => PowerTier;
     /**
-     * Called after the manager closes a station on its OWN initiative — an elapsed idle window, or a
-     * deferred reset falling due.
+     * Called with the KEY of a session the manager closed on its OWN initiative — an elapsed idle window,
+     * or a deferred reset falling due. The key, not the station: several sessions can share a station and
+     * only the one that closed is stale, so an owner told the station would tear down connections that are
+     * still serving.
      *
      * Those two are the only closes with no caller to follow up: everything riding the session is stale the
      * moment it goes, and only the owner knows what that is. A close a caller asked for is that caller's to
      * clean up after, which is why this does not fire for {@link SessionManager.close},
      * {@link SessionManager.closeAll}, or a superseded open.
      */
-    onAutoClose?: (parentSn: string) => void;
+    onAutoClose?: (key: string) => void;
     /** Diagnostics sink for the lifecycle transitions (open / idle-arm / detach). Omit for silence. */
     logger?: Logger;
 }
 /**
- * Manages P2P sessions keyed by **parent station serial**. The router builds/wires the actual
- * `P2PSession` (it owns the socket + event fan-out); this decides open/close timing.
+ * Manages P2P sessions by **key**, each recording the station it connects to. The router builds and
+ * wires the actual `P2PSession` (it owns the socket and event fan-out); this decides open/close timing.
+ *
+ * A key is the station's serial for the one session that carries its control traffic and its events.
+ * Where a station has to serve more than one camera at once it also holds a session per camera, filed
+ * under a key of the router's choosing and recording the same station — so each has its own refcount and
+ * its own idle window, and releasing one never disturbs another.
  */
 export declare class SessionManager {
     private readonly opts;
@@ -53,23 +64,40 @@ export declare class SessionManager {
     private readonly logger;
     constructor(opts?: SessionManagerOpts);
     /** The live session for a station, or `undefined` if not open. */
-    get(parentSn: string): P2PSession | undefined;
-    /** Serials of stations with a live session. */
+    get(key: string): P2PSession | undefined;
+    /** Keys of the open sessions. */
     keys(): string[];
-    /** A plain `Map<parentSn, P2PSession>` snapshot of the live sessions (for `getSessions()` / tests). */
+    /** A plain `Map<key, P2PSession>` snapshot of the open sessions (for `getSessions()` / tests). */
     liveSessions(): Map<string, P2PSession>;
-    /** Get or create the lifecycle entry for a station. */
+    /**
+     * Get or create the lifecycle entry under `key`, recording which station it connects to. An existing
+     * entry keeps the station it was opened with — the key owns one connection for its lifetime, and a
+     * later caller passing a different station would otherwise re-point a live entry's power tier.
+     */
     private entry;
-    /** Register an already-built session for test seeding or an externally assembled connection. */
-    register(parentSn: string, session: P2PSession): void;
     /**
-     * Ensure a session to `parentSn` is open, building it via `factory` if cold. Concurrent calls for the
+     * Register an already-built session for test seeding or an externally assembled connection.
+     *
+     * `station` defaults to the key, which is safe HERE and nowhere else in this class: the paths that open a
+     * session under a key that is not a station serial all go through {@link acquire}, which requires it. A
+     * caller seeding one under such a key must pass it.
+     */
+    register(key: string, session: P2PSession, station?: string): void;
+    /**
+     * Ensure a session to `key` is open, building it via `factory` if cold. Concurrent calls for the
      * same cold station share ONE connect (the `connecting` promise); `factory` builds + wires + awaits
      * `connect()` and resolves the connected session.
      */
-    acquire(parentSn: string, factory: (register: (session: P2PSession) => void) => Promise<P2PSession>): Promise<P2PSession>;
-    /** Add a reason to stay connected; cancels a pending idle-close. */
-    retain(parentSn: string): void;
+    acquire(key: string, factory: (register: (session: P2PSession) => void) => Promise<P2PSession>, station: string): Promise<P2PSession>;
+    /**
+     * Add a reason to stay connected; cancels a pending idle-close.
+     *
+     * Refused when nothing is open under `key`, for the reason {@link release} gives in the other direction: a
+     * retain names a session that was acquired, and one that names nothing would file an entry with no
+     * connection behind it. {@link hold} is the path that legitimately creates one, and it opens the entry
+     * itself before retaining it.
+     */
+    retain(key: string): void;
     /**
      * Release a reason; arm the idle-close when the last one goes.
      *
@@ -78,22 +106,28 @@ export declare class SessionManager {
      * from scratch or complete a deferred reset a real viewer has not yet earned. Clamping to zero did
      * both silently.
      */
-    release(parentSn: string): void;
+    release(key: string): void;
     /**
      * Hold a session warm for `commandKeepAliveMs` after a control command, then release. A burst of
      * commands each re-holds before the previous release fires, so the session never idles mid-burst.
      */
-    bumpCommand(parentSn: string): void;
+    bumpCommand(key: string, station: string): void;
     /**
-     * Retain a station and release it again after `ms` — the primitive behind command-keepalive and event
+     * Retain a session and release it again after `ms` — the primitive behind command-keepalive and event
      * pre-warm, and the only way to hold one open without an attachment to release it.
      *
+     * `station` is required rather than defaulted from the key, because this is the one path that can
+     * CREATE an entry: a pre-warm takes its hold before the open. An entry filed under a media key with
+     * that key as its own station would be asked for the power tier of a serial that does not exist, be
+     * answered `wired`, and never idle-detach — which on a battery station is the drain this class exists
+     * to prevent, and is invisible until the battery is flat.
+     *
      * The timer is owned by the entry, so {@link discard} cancels it. That ownership is the point: keyed
      * only by serial, an expiring hold would otherwise outlive the entry it was taken on and release a
      * retain counted by the SUCCESSOR entry — dropping a live viewer's count and arming an idle-detach
      * underneath it.
      */
-    hold(parentSn: string, ms: number): void;
+    hold(key: string, ms: number, station: string): void;
     /**
      * Arm the idle-close timer for a station whose retain count just reached zero. A wired station with
      * an infinite window is left persistent (no timer). Any subsequent {@link retain} cancels it.
@@ -123,9 +157,9 @@ export declare class SessionManager {
      */
     private autoClose;
     /** Drop a station's entry + timer (called from the session's `close` handler). Idempotent. */
-    remove(parentSn: string): void;
+    remove(key: string): void;
     /** Close one station now and discard its lifecycle entry. */
-    close(parentSn: string): Promise<void>;
+    close(key: string): Promise<void>;
     /**
      * Reset once every viewer detaches, ignoring only expiring holds.
      *
@@ -136,7 +170,7 @@ export declare class SessionManager {
      * Both branches close through {@link autoClose}: the caller asked for a recycle, not for the station's
      * live sources to be dropped, so it does not clean up after one — exactly like the idle path.
      */
-    resetWhenUnused(parentSn: string): Promise<void>;
+    resetWhenUnused(key: string): Promise<void>;
     /** Settle a discarded entry's reset callers with the same outcome as its session close. */
     private settleReset;
     /** Close one discarded entry and settle only its own reset callers before preserving any failure. */

package/dist/transport/p2p/shared-live-source.d.ts

@@ -10,7 +10,7 @@ export interface SharedLiveSourceOptions {
      * `.start()` itself.
      *
      * `ctx.reassertWanted` answers whether this pull still has anyone attached. A stream that re-asserts a
-     * channel to hold it open should consult it, so a pull nothing is watching stops competing for a station
+     * channel to hold it open should consult it, so a pull nothing is watching stops competing for a session
      * that serves one camera at a time.
      */
     makeStream: (ctx: {
@@ -73,6 +73,15 @@ export interface SharedLiveSourceOptions {
      * an owner does in response to this callback.
      */
     onStartFailed?: () => void;
+    /**
+     * The pull has ended and will not resume: the linger elapsed, the battery budget ran out, or the source
+     * was torn down. A later attach builds a fresh stream rather than reviving this one.
+     *
+     * Distinct from {@link onIdle} by what is still running. `onIdle` fires at the last detach, while the
+     * linger is still holding the pull open so a quick re-attach costs nothing; between the two the pull is
+     * alive. This fires when it is not.
+     */
+    onStopped?: () => void;
     /**
      * A media start was abandoned unacknowledged before anything was delivered, so this session is not being
      * heard. The owner is asked for a replacement and calls {@link SharedLiveSource.rewarm} once it has one.