@mega-yfue/eufy-sdk 0.2.0-beta.10 → 0.2.0-beta.12

package/dist/index.js

@@ -2615,16 +2615,6 @@ var StationUnreachableError = class extends Error {
     this.name = "StationUnreachableError";
   }
 };
-var StationBusyError = class extends Error {
-  servingChannel;
-  /** Always true: the station is busy now, and stops being busy when the other stream is released. */
-  retryable = true;
-  constructor(servingChannel, options) {
-    super(`the station is already serving channel ${servingChannel} to a viewer, and serves one camera at a time \u2014 stop that stream before opening another`, options);
-    this.servingChannel = servingChannel;
-    this.name = "StationBusyError";
-  }
-};
 var LiveStreamStartError = class extends Error {
   reason;
   stage;
@@ -3982,12 +3972,32 @@ function decodePowerSource(raw) {
 function recordSetting(param, value, ctx) {
   return setStationScalar(param, value, ctx.channel);
 }
-var MAINS_CAMERA_MODELS = ["T8425", "T8419"];
+var MAINS_CAMERA_MODELS = ["T8425", "T8419", "T8410"];
 var notMainsCamera = (ctx) => {
   const model = (ctx.model ?? "").toUpperCase();
   return !MAINS_CAMERA_MODELS.some((prefix) => model.startsWith(prefix));
 };
-var BATTERY_MEMBERS = {
+var CELL_PARAMS = [
+  BATTERY_PARAM.BATTERY,
+  BATTERY_PARAM.BATTERY_STATUS,
+  BATTERY_PARAM.BATTERY_TEMP,
+  BATTERY_PARAM.BATTERY_HEALTH,
+  BATTERY_PARAM.SOLAR_INTENSITY,
+  BATTERY_PARAM.SOLAR_CONNECT_24H,
+  BATTERY_PARAM.BATTERY_POWER_DATAS
+];
+function cellGated(members) {
+  const gated = Object.entries(members).map(([name, m]) => {
+    const param = m.param;
+    if (typeof param !== "number" || !CELL_PARAMS.includes(param))
+      return [name, m];
+    const own = m.available;
+    const available = own ? (ctx) => notMainsCamera(ctx) && own(ctx) : notMainsCamera;
+    return [name, { ...m, available }];
+  });
+  return Object.fromEntries(gated);
+}
+var BATTERY_MEMBERS = cellGated({
   /**
    * The headline percentage, and this capability's detection evidence: reporting 1101 is what proves a
    * device is battery-powered, which is also the fact `MediaProvider` reads to decide a stream needs a
@@ -4000,7 +4010,6 @@ var BATTERY_MEMBERS = {
     unit: "%",
     kind: "percent",
     provenance: "verified",
-    available: notMainsCamera,
     description: "Battery level 0-100 (verified: param 1101)."
   },
   /**
@@ -4013,7 +4022,6 @@ var BATTERY_MEMBERS = {
     type: "bool",
     kind: "boolean",
     provenance: "apk",
-    available: notMainsCamera,
     coerce: (v) => {
       const n = Number(v);
       return n !== 0 && n !== 2;
@@ -4184,6 +4192,11 @@ var BATTERY_MEMBERS = {
    * Reported, so it stays in the schema and answers through `getProperty` — but given no typed getter:
    * the payload's fields have never been decoded, and a getter would hand back an opaque blob typed as
    * though it meant something.
+   *
+   * `unexposed` is NOT a substitute for the cell gate. It suppresses the fluent GETTER; `propertiesOf`
+   * filters `writeOnly` and `available` and deliberately not `unexposed`, because a schema entry
+   * reachable through `getProperty` is the whole point of the mark. So a cell param needs
+   * {@link CELL_PARAMS} either way, or a mains camera publishes "battery power history" and answers it.
    */
   batteryPowerStats: {
     param: BATTERY_PARAM.BATTERY_POWER_DATAS,
@@ -4209,7 +4222,7 @@ var BATTERY_MEMBERS = {
     unexposed: true,
     description: "Raw GET_CAMERA_INFO value (1103), meaning unevidenced \u2014 read live as the constant 5 on a T8170 at 92% and a T8171 at 27%, so it is NOT a low-battery flag."
   }
-};
+});
 var BATTERY = {
   capability: "battery",
   description: "Battery level, charging, health, temperature, and solar input.",
@@ -10103,6 +10116,16 @@ function getCapabilityModule(cap) {
   return BY_CAP.get(cap);
 }
 var CAPABILITY_MODULES = Object.fromEntries(MODULES.map((m) => [m.capability, m]));
+function claimedParams(caps) {
+  const claimed = /* @__PURE__ */ new Set();
+  for (const cap of caps)
+    for (const spec of getCapabilityModule(cap)?.properties ?? []) {
+      claimed.add(spec.paramType);
+      for (const alias of spec.readAliases ?? [])
+        claimed.add(alias.paramType);
+    }
+  return claimed;
+}
 function mergeProperties(caps, ctx) {
   const seen = /* @__PURE__ */ new Set();
   const merged = [];
@@ -12394,6 +12417,11 @@ var Device = class _Device {
    * different wire ids across device families still resolves to one named value.
    */
   specByParam;
+  /**
+   * Params a resolved capability declares that this device's schema does not carry — withheld by a
+   * member's gate, so not named from the param dictionary either. See {@link Device.applyParams}.
+   */
+  withheld = /* @__PURE__ */ new Set();
   /** Which param namespace this device's ids live in (clean DPs vs security P2P). */
   namespace;
   /** The record's `device_name` as stated, before the {@link modelName} fallback is applied. */
@@ -12460,6 +12488,7 @@ var Device = class _Device {
           byParam.set(a.paramType, { spec: p, invert: a.invert ?? false });
     }
     this.specByParam = byParam;
+    this.withheld = new Set([...claimedParams(resolved.capabilities)].filter((pt) => !byParam.has(pt)));
     this.namespace = namespaceForCodec(resolved.codec);
     this.installAccessors();
   }
@@ -12622,6 +12651,16 @@ var Device = class _Device {
    * Apply a raw param map (cloud record or P2P notification). Known params update their named
    * property; unrecognised params are retained as `unknown_<paramType>` so nothing is lost.
    *
+   * Naming precedence: this device's own `PropertySpec` (curated), then the param dictionary for its
+   * namespace, then the `unknown_<paramType>` passthrough. The dictionary def is consulted even where a
+   * spec exists, because `encoding` lives there.
+   *
+   * A param a resolved capability's gate WITHHELD takes the passthrough instead of its dictionary name.
+   * The gate decided the read does not describe this device, the dictionary names it what the member
+   * would have, and republishing it there hands a caller a reading indistinguishable from one the device
+   * really answered. A capability that never resolved withholds nothing: a param arriving before its
+   * capability is still the device's own, and keeps its dictionary name.
+   *
    * @param params param_type → raw value.
    * @param ts observation time (epoch ms); defaults to `Date.now()`.
    * @returns the list of property names whose value changed.
@@ -12634,7 +12673,7 @@ var Device = class _Device {
         continue;
       const hit = this.specByParam.get(pt);
       const spec = hit?.spec;
-      const def = paramDef(this.namespace, pt);
+      const def = this.withheld.has(pt) ? void 0 : paramDef(this.namespace, pt);
       const name = spec ? spec.name : def ? def.name : `${UNKNOWN_PARAM_PREFIX}${pt}`;
       const value = def?.encoding ? decodeEncoded(rawVal, def.encoding) : spec ? coerce(spec, rawVal, hit.invert, this.logger) : def ? coerceByType(def.type, rawVal, def.name, this.logger) : String(rawVal);
       const prev = this.state.get(name);
@@ -16785,8 +16824,9 @@ var LiveStream = class extends EventEmitter3 {
    * 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.
    *
@@ -16953,7 +16993,7 @@ var LiveStream = class extends EventEmitter3 {
    *
    * 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.
    *
@@ -18003,6 +18043,8 @@ var SharedLiveSource = class {
     this.configuredFrom = void 0;
     this.ring = [];
     this._state = state;
+    if (state === "stopped")
+      this.opts.onStopped?.();
     if (startFailed && report)
       this.opts.onStartFailed?.();
   }
@@ -18085,14 +18127,14 @@ var SessionManager = class {
     this.logger = opts.logger ?? noopLogger;
   }
   /** The live session for a station, or `undefined` if not open. */
-  get(parentSn) {
-    return this.entries.get(parentSn)?.session;
+  get(key) {
+    return this.entries.get(key)?.session;
   }
-  /** Serials of stations with a live session. */
+  /** Keys of the open sessions. */
   keys() {
     return [...this.entries].filter(([, e]) => e.session).map(([sn]) => sn);
   }
-  /** 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() {
     const m = /* @__PURE__ */ new Map();
     for (const [sn, e] of this.entries)
@@ -18100,56 +18142,77 @@ var SessionManager = class {
         m.set(sn, e.session);
     return m;
   }
-  /** Get or create the lifecycle entry for a station. */
-  entry(parentSn) {
-    let e = this.entries.get(parentSn);
+  /**
+   * 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.
+   */
+  entry(key, station) {
+    let e = this.entries.get(key);
     if (!e) {
-      e = { retained: 0, holdTimers: /* @__PURE__ */ new Set(), idle: new Timer() };
-      this.entries.set(parentSn, e);
+      e = { station, retained: 0, holdTimers: /* @__PURE__ */ new Set(), idle: new Timer() };
+      this.entries.set(key, e);
     }
     return e;
   }
-  /** Register an already-built session for test seeding or an externally assembled connection. */
-  register(parentSn, session) {
-    this.entry(parentSn).session = session;
+  /**
+   * 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, session, station = key) {
+    this.entry(key, station).session = session;
   }
   /**
-   * Ensure a session to `parentSn` is open, building it via `factory` if cold. Concurrent calls for the
+   * 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.
    */
-  async acquire(parentSn, factory) {
-    const e = this.entry(parentSn);
+  async acquire(key, factory, station) {
+    const e = this.entry(key, station);
     if (e.connecting) {
-      this.logger.debug(`[session ${parentSn}] connecting \u2014 joining in-flight open`);
+      this.logger.debug(`[session ${key}] connecting \u2014 joining in-flight open`);
       return e.connecting;
     }
     if (e.session)
       return e.session;
-    this.logger.debug(`[session ${parentSn}] connecting now (on demand)`);
+    this.logger.debug(`[session ${key}] connecting now (on demand)`);
     const generation = this.generation;
     const p = factory((session) => e.session = session);
     e.connecting = p;
     try {
       const session = await p;
-      if (generation !== this.generation || this.entries.get(parentSn) !== e) {
+      if (generation !== this.generation || this.entries.get(key) !== e) {
         await session.close();
-        throw new SessionSupersededError(`P2P session start superseded for station ${parentSn}`);
+        throw new SessionSupersededError(`P2P session start superseded for ${key}`);
       }
       e.session ??= session;
-      this.logger.debug(`[session ${parentSn}] connected`);
+      this.logger.debug(`[session ${key}] connected`);
       return e.session;
     } finally {
       if (e.connecting === p)
         e.connecting = void 0;
     }
   }
-  /** Add a reason to stay connected; cancels a pending idle-close. */
-  retain(parentSn) {
-    const e = this.entry(parentSn);
+  /**
+   * 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) {
+    const e = this.entries.get(key);
+    if (!e) {
+      this.logger.warn(`[session ${key}] retain on a session that is not open \u2014 ignored`);
+      return;
+    }
     e.retained++;
     if (e.idle.pending)
-      this.logger.debug(`[session ${parentSn}] in use again \u2014 idle-detach cancelled`);
+      this.logger.debug(`[session ${key}] in use again \u2014 idle-detach cancelled`);
     e.idle.cancel();
   }
   /**
@@ -18160,44 +18223,50 @@ var SessionManager = class {
    * from scratch or complete a deferred reset a real viewer has not yet earned. Clamping to zero did
    * both silently.
    */
-  release(parentSn) {
-    const e = this.entries.get(parentSn);
+  release(key) {
+    const e = this.entries.get(key);
     if (!e)
       return;
     if (e.retained === 0) {
-      this.logger.warn(`[session ${parentSn}] release with nothing retained \u2014 ignored`);
+      this.logger.warn(`[session ${key}] release with nothing retained \u2014 ignored`);
       return;
     }
     e.retained -= 1;
     if (e.reset && e.retained <= e.holdTimers.size) {
-      void this.autoClose(parentSn).catch((error) => this.logger.error(`[session ${parentSn}] deferred reset failed`, error));
+      void this.autoClose(key).catch((error) => this.logger.error(`[session ${key}] deferred reset failed`, error));
       return;
     }
     if (e.retained === 0)
-      this.armIdle(parentSn, e);
+      this.armIdle(key, e);
   }
   /**
    * 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) {
-    this.hold(parentSn, this.opts.commandKeepAliveMs ?? COMMAND_KEEPALIVE_MS);
+  bumpCommand(key, station) {
+    this.hold(key, this.opts.commandKeepAliveMs ?? COMMAND_KEEPALIVE_MS, station);
   }
   /**
-   * 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, ms) {
-    const entry = this.entry(parentSn);
-    this.retain(parentSn);
+  hold(key, ms, station) {
+    const entry = this.entry(key, station);
+    this.retain(key);
     const timer = setTimeout(() => {
       entry.holdTimers.delete(timer);
-      this.release(parentSn);
+      this.release(key);
     }, ms);
     timer.unref?.();
     entry.holdTimers.add(timer);
@@ -18206,29 +18275,29 @@ var SessionManager = class {
    * 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.
    */
-  armIdle(parentSn, e) {
+  armIdle(key, e) {
     e.idle.cancel();
-    if ((this.opts.poweredFor?.(parentSn) ?? "wired") !== "battery") {
-      this.logger.debug(`[session ${parentSn}] idle (nothing retained) \u2014 staying persistent (wired)`);
+    if ((this.opts.poweredFor?.(e.station) ?? "wired") !== "battery") {
+      this.logger.debug(`[session ${key}] idle (nothing retained) \u2014 staying persistent (wired)`);
       return;
     }
     const idleMs = this.opts.batteryIdleMs ?? BATTERY_IDLE_MS;
-    this.logger.debug(`[session ${parentSn}] idle (nothing retained) \u2014 detaching in ${idleMs}ms unless reused`);
-    e.idle.arm(idleMs, () => this.onIdle(parentSn));
+    this.logger.debug(`[session ${key}] idle (nothing retained) \u2014 detaching in ${idleMs}ms unless reused`);
+    e.idle.arm(idleMs, () => this.onIdle(key));
   }
   /**
    * Close a station's session once its idle window elapses with nothing retained, letting the device sleep.
    * Re-checks the count first (activity between the timer firing and now re-arms instead). Dropping the
    * entry here and the session's own `close` → {@link remove} are both idempotent.
    */
-  onIdle(parentSn) {
-    const e = this.entries.get(parentSn);
+  onIdle(key) {
+    const e = this.entries.get(key);
     if (!e)
       return;
     if (e.retained > 0)
       return;
-    this.logger.debug(`[session ${parentSn}] idle window elapsed \u2014 disconnecting now (device can sleep)`);
-    void this.autoClose(parentSn).catch((error) => this.logger.error(`[session ${parentSn}] idle detach failed`, error));
+    this.logger.debug(`[session ${key}] idle window elapsed \u2014 disconnecting now (device can sleep)`);
+    void this.autoClose(key).catch((error) => this.logger.error(`[session ${key}] idle detach failed`, error));
   }
   /**
    * Close a station the manager itself decided to close, and announce it.
@@ -18246,23 +18315,23 @@ var SessionManager = class {
    * An entry that never carried a session is still torn down, but silently: a pre-warm whose open failed
    * leaves one behind, and announcing it would report a station closed that was never reported open.
    */
-  async autoClose(parentSn) {
-    const entry = this.discard(parentSn);
+  async autoClose(key) {
+    const entry = this.discard(key);
     if (!entry)
       return;
     if (entry.session)
-      this.opts.onAutoClose?.(parentSn);
+      this.opts.onAutoClose?.(key);
     await this.closeEntry(entry);
   }
   /** Drop a station's entry + timer (called from the session's `close` handler). Idempotent. */
-  remove(parentSn) {
-    const entry = this.discard(parentSn);
+  remove(key) {
+    const entry = this.discard(key);
     if (entry)
       this.settleReset(entry);
   }
   /** Close one station now and discard its lifecycle entry. */
-  async close(parentSn) {
-    const entry = this.discard(parentSn);
+  async close(key) {
+    const entry = this.discard(key);
     if (entry)
       await this.closeEntry(entry);
   }
@@ -18276,12 +18345,12 @@ var SessionManager = class {
    * 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) {
-    const entry = this.entries.get(parentSn);
+  resetWhenUnused(key) {
+    const entry = this.entries.get(key);
     if (!entry)
       return Promise.resolve();
     if (entry.retained <= entry.holdTimers.size)
-      return this.autoClose(parentSn);
+      return this.autoClose(key);
     entry.reset ??= Promise.withResolvers();
     return entry.reset.promise;
   }
@@ -18313,22 +18382,22 @@ var SessionManager = class {
    * discarded entry owns no live timer, which is what stops a deferred release from landing on whatever
    * entry next occupies this serial.
    */
-  discard(parentSn) {
-    const entry = this.entries.get(parentSn);
+  discard(key) {
+    const entry = this.entries.get(key);
     if (!entry)
       return void 0;
     entry.idle.cancel();
     for (const timer of entry.holdTimers)
       clearTimeout(timer);
     entry.holdTimers.clear();
-    this.entries.delete(parentSn);
+    this.entries.delete(key);
     return entry;
   }
   /** Close every session and clear all timers. */
   async closeAll() {
     this.generation++;
-    const entries = [...this.entries.keys()].flatMap((parentSn) => {
-      const entry = this.discard(parentSn);
+    const entries = [...this.entries.keys()].flatMap((key) => {
+      const entry = this.discard(key);
       return entry ? [entry] : [];
     });
     const results = await Promise.allSettled(entries.map((entry) => this.closeEntry(entry)));
@@ -19354,7 +19423,7 @@ function sameLiveOpt(a, b) {
 }
 var P2PCommandRouter = class _P2PCommandRouter {
   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. */
   manager;
   /** Error objects already forwarded while a station startup awaits the same session signal. */
   reportedErrors = /* @__PURE__ */ new WeakSet();
@@ -19362,6 +19431,21 @@ var P2PCommandRouter = class _P2PCommandRouter {
   liveSources = /* @__PURE__ */ new Map();
   /** The options each live source was built from, so a later caller's conflicting ones can be reported. */
   liveSourceOpts = /* @__PURE__ */ new Map();
+  /**
+   * 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.
+   */
+  liveSessionKeys = /* @__PURE__ */ new Map();
   /**
    * 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
@@ -19375,7 +19459,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
     this.manager = new SessionManager({
       poweredFor: deps.poweredFor,
       logger: deps.logger,
-      onAutoClose: (parentSn) => this.tearDownStation(parentSn),
+      onAutoClose: (key) => _P2PCommandRouter.isMediaSessionKey(key) ? this.tearDownMediaSession(key) : this.tearDownStation(key),
       ...deps.sessionIdle
     });
   }
@@ -19407,7 +19491,10 @@ var P2PCommandRouter = class _P2PCommandRouter {
   static claimsDevice(dev) {
     return typeof dev.p2pDid === "string" && dev.p2pDid.length > 0;
   }
-  /** 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() {
     return this.manager.liveSessions();
   }
@@ -19419,16 +19506,16 @@ var P2PCommandRouter = 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
    * session was deliberately closed underneath a speculative open, which is not a fault to report.
    */
   async prewarm(parentSn, ms = PREWARM_MS) {
-    this.manager.hold(parentSn, ms);
+    this.manager.hold(parentSn, ms, parentSn);
     try {
-      await this.openStation(parentSn);
+      await this.openSession(parentSn, parentSn);
     } catch (e) {
       if (e instanceof SessionSupersededError)
         return;
@@ -19445,6 +19532,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
       src.dispose();
     this.liveSources.clear();
     this.liveSourceOpts.clear();
+    this.liveSessionKeys.clear();
     await this.manager.closeAll();
   }
   /** This serial's loaded record, or `undefined` — the one place the cached list is searched by serial. */
@@ -19486,8 +19574,55 @@ var P2PCommandRouter = 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.
    */
-  async openStation(parentSn) {
-    return this.manager.acquire(parentSn, async (register) => {
+  /**
+   * The key a camera's own media session is filed under, distinct from every station serial because a
+   * serial contains no `#`.
+   */
+  static mediaSessionKey(parentSn, channel) {
+    return `${parentSn}#live:${channel}`;
+  }
+  /** Whether `key` names a media session rather than a station's own. */
+  static isMediaSessionKey(key) {
+    return key.includes("#live:");
+  }
+  /**
+   * 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.
+   */
+  async openMediaSession(parentSn, channel, signal) {
+    const session = await this.openSession(_P2PCommandRouter.mediaSessionKey(parentSn, channel), parentSn);
+    let ready = await abortable(session.awaitLevel2Key(LEVEL2_GRACE_MS, "call"), signal);
+    if (!ready && session.repromptLevel2Key()) {
+      ready = await abortable(session.awaitLevel2Key(LEVEL2_GRACE_MS, "call"), signal);
+    }
+    if (!ready)
+      throw new StationKeyUnavailableError(parentSn);
+    return session;
+  }
+  /** Open (or reuse) the session filed under `key`, dialling `parentSn`'s endpoint. */
+  async openSession(key, parentSn) {
+    return this.manager.acquire(key, async (register) => {
       const stationDev = this.recordFor(parentSn);
       if (!stationDev)
         throw new Error(`station ${parentSn} is not in the device list`);
@@ -19502,11 +19637,11 @@ var P2PCommandRouter = class _P2PCommandRouter {
         this.deps.onError(e instanceof Error ? e : new Error(String(e)));
       }
       const localAddress = this.deps.localAddresses?.[parentSn] ?? freshestLanIp(raw);
-      const session = this.makeSession(parentSn, did, raw, dskKey, localAddress);
+      const session = this.makeSession(parentSn, did, raw, dskKey, localAddress, key, key === parentSn);
       register(session);
       await session.connect();
       return session;
-    });
+    }, parentSn);
   }
   /**
    * Build + wire a {@link P2PSession} for a station (NOT yet connected — the caller awaits `connect()`).
@@ -19519,8 +19654,14 @@ var P2PCommandRouter = 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.
    */
-  makeSession(stationSn, did, raw, dskKey, localAddress) {
+  makeSession(stationSn, did, raw, dskKey, localAddress, key, announces) {
     const conn = raw?.p2p_conn ?? raw?.app_conn;
     const adminUserId = raw?.member?.admin_user_id || this.deps.mega.auth?.userId || "";
     const session = new P2PSession({
@@ -19554,6 +19695,14 @@ var P2PCommandRouter = class _P2PCommandRouter {
       },
       logger: this.deps.logger ?? noopLogger
     });
+    session.on("error", (e) => this.reportError(e));
+    if (!announces) {
+      session.on("close", () => {
+        if (this.manager.get(key) === session)
+          this.tearDownMediaSession(key);
+      });
+      return session;
+    }
     session.on("connect", () => {
       if (this.manager.get(stationSn) === session)
         this.deps.onConnect(stationSn);
@@ -19563,7 +19712,6 @@ var P2PCommandRouter = class _P2PCommandRouter {
         return;
       this.tearDownStation(stationSn);
     });
-    session.on("error", (e) => this.reportError(e));
     session.on("level2Ready", ({ cipherId }) => this.deps.onLevel2Ready(stationSn, cipherId));
     session.on("data", (f) => this.deps.onFrame(stationSn, f));
     return session;
@@ -19574,7 +19722,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
    */
   async ensureStation(parentSn, signal) {
     try {
-      const session = await this.openStation(parentSn);
+      const session = await this.openSession(parentSn, parentSn);
       if (session.isConnected)
         return;
       await new Promise((resolve, reject) => {
@@ -19622,7 +19770,7 @@ var P2PCommandRouter = class _P2PCommandRouter {
     const dev = this.recordFor(sn);
     if (!dev)
       throw new Error(`device ${sn} not found`);
-    await this.openStation(this.stationKeyFor(dev));
+    await this.openSession(this.stationKeyFor(dev), this.stationKeyFor(dev));
     return dev;
   }
   /**
@@ -19706,11 +19854,11 @@ var P2PCommandRouter = class _P2PCommandRouter {
         });
       },
       live: async (opts) => {
-        const source = await this.sharedLiveSourceFor(sn, opts);
+        const source = await this.sharedLiveSourceFor(sn, opts, true);
         return this.attachUnlessAborted(source, opts?.signal);
       },
       openReadable: async (opts) => {
-        const source = await this.sharedLiveSourceFor(sn, opts ?? {});
+        const source = await this.sharedLiveSourceFor(sn, opts ?? {}, true);
         return openReadableFromConsumer(this.attachUnlessAborted(source, opts?.signal), opts);
       },
       recordFragments: (opts) => this.recordFragments(sn, opts),
@@ -19851,10 +19999,17 @@ var P2PCommandRouter = 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.
    */
-  async sharedLiveSourceFor(sn, opts = {}) {
+  async sharedLiveSourceFor(sn, opts = {}, mayOpenOwnSession = false) {
     const { session, parentSn, channel, accountId, homeBaseAttached } = await this.resolveSession(sn, {
       waitLevel2: "soft",
       requireLevel2ForAttached: true,
@@ -19867,14 +20022,19 @@ var P2PCommandRouter = class _P2PCommandRouter {
       source = void 0;
     }
     this.releaseLingeringSiblings(parentSn, channel);
-    if (homeBaseAttached) {
-      const serving = this.occupiedSiblingChannel(parentSn, key);
-      if (serving !== void 0)
-        throw new StationBusyError(serving);
-    }
     if (!source) {
       const logger = this.deps.logger ?? noopLogger;
-      const held = { session };
+      const sessionKey = mayOpenOwnSession && homeBaseAttached && this.stationSessionInUse(parentSn, key) ? _P2PCommandRouter.mediaSessionKey(parentSn, channel) : parentSn;
+      this.liveSessionKeys.set(key, sessionKey);
+      let held;
+      try {
+        held = {
+          session: sessionKey === parentSn ? session : await this.openMediaSession(parentSn, channel, opts.signal)
+        };
+      } catch (error) {
+        this.liveSessionKeys.delete(key);
+        throw error;
+      }
       source = new SharedLiveSource({
         makeStream: (ctx) => new LiveStream(held.session, {
           channel,
@@ -19892,8 +20052,9 @@ var P2PCommandRouter = class _P2PCommandRouter {
         budgetGraceMs: opts.budgetGraceMs,
         logger,
         label: key,
-        onActive: () => this.manager.retain(parentSn),
-        onIdle: () => this.manager.release(parentSn),
+        onActive: () => this.manager.retain(sessionKey),
+        onIdle: () => this.manager.release(sessionKey),
+        onStopped: () => this.closeMediaSession(key),
         onStartFailed: () => this.onLiveStartFailed(sn, key),
         onSessionUnreachable: () => this.replaceUnreachableSession(sn, key, held)
       });
@@ -19908,14 +20069,25 @@ var P2PCommandRouter = class _P2PCommandRouter {
    * 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,
@@ -19929,28 +20101,49 @@ var P2PCommandRouter = class _P2PCommandRouter {
     for (const [key, source] of [...this.liveSources]) {
       if (!key.startsWith(`${parentSn}:`) || key === own || source.consumerCount > 0)
         continue;
-      (this.deps.logger ?? noopLogger).debug(`[live ${key}] releasing a pull nothing is attached to so ${own} can start \u2014 one station serves one camera at a time`);
+      if (source.state === "idle")
+        continue;
+      if (this.liveSessionKeys.get(key) !== parentSn)
+        continue;
+      (this.deps.logger ?? noopLogger).debug(`[live ${key}] releasing a pull nothing is attached to so ${own} can start \u2014 one session serves one camera at a time`);
       this.dropLiveSource(key);
     }
   }
   /**
-   * 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.
    */
-  occupiedSiblingChannel(parentSn, key) {
-    for (const [siblingKey, sibling] of this.liveSources) {
-      if (siblingKey === key || !siblingKey.startsWith(`${parentSn}:`))
+  stationSessionInUse(parentSn, key) {
+    for (const [siblingKey, sessionKey] of this.liveSessionKeys) {
+      if (siblingKey === key || sessionKey !== parentSn)
+        continue;
+      const sibling = this.liveSources.get(siblingKey);
+      if (!sibling)
+        return true;
+      if (sibling.state === "stopped")
         continue;
-      if (sibling.state === "stopped" || sibling.consumerCount === 0)
+      if (sibling.state !== "idle" && sibling.consumerCount === 0)
         continue;
-      const channel = Number(siblingKey.slice(parentSn.length + 1));
-      return Number.isFinite(channel) ? channel : void 0;
+      return true;
     }
-    return void 0;
+    return false;
   }
   /**
    * Whether the stream on `key` should re-assert its channel to hold the station.
@@ -19961,8 +20154,8 @@ var P2PCommandRouter = 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
@@ -19984,7 +20177,13 @@ var P2PCommandRouter = class _P2PCommandRouter {
     }
     return consumer;
   }
-  /** 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.
+   */
   dropLiveSource(key) {
     const source = this.liveSources.get(key);
     if (!source)
@@ -19992,6 +20191,34 @@ var P2PCommandRouter = class _P2PCommandRouter {
     source.dispose();
     this.liveSources.delete(key);
     this.liveSourceOpts.delete(key);
+    this.closeMediaSession(key);
+  }
+  /** Close and forget the media session `key`'s live source owned, if it owned one. */
+  closeMediaSession(key) {
+    const sessionKey = this.liveSessionKeys.get(key);
+    if (sessionKey === void 0)
+      return;
+    this.liveSessionKeys.delete(key);
+    if (!_P2PCommandRouter.isMediaSessionKey(sessionKey))
+      return;
+    void this.manager.close(sessionKey).catch((error) => this.reportError(error instanceof Error ? error : new Error(String(error))));
+  }
+  /**
+   * 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.
+   */
+  tearDownMediaSession(sessionKey) {
+    this.manager.remove(sessionKey);
+    for (const [key, owned] of this.liveSessionKeys) {
+      if (owned === sessionKey) {
+        this.liveSessionKeys.delete(key);
+        this.dropLiveSource(key);
+        return;
+      }
+    }
   }
   /**
    * Drop everything that was riding a station's session, and report the station closed.
@@ -20335,14 +20562,15 @@ var P2PCommandRouter = class _P2PCommandRouter {
     const parentSn = homeBaseAttached ? raw.parent_sn : dev.stationSn ?? sn;
     const session = this.manager.get(parentSn) ?? this.manager.get(sn) ?? (dev.stationSn ? this.manager.get(dev.stationSn) : void 0);
     if (!session) {
-      throw new Error(`no P2P session for ${sn} (known: ${this.manager.keys().join(", ") || "none"})`);
+      const stations = this.manager.keys().filter((k) => !_P2PCommandRouter.isMediaSessionKey(k));
+      throw new Error(`no P2P session for ${sn} (known: ${stations.join(", ") || "none"})`);
     }
     if (session.pathAnswering === false && !rebuilt) {
       (this.deps.logger ?? noopLogger).debug(`[p2p] ${parentSn} path stopped answering \u2014 rebuilding before use`);
       await this.manager.close(parentSn).catch((error) => this.reportError(error instanceof Error ? error : new Error(String(error))));
       return await this.resolveSession(sn, opts, true);
     }
-    this.manager.bumpCommand(parentSn);
+    this.manager.bumpCommand(parentSn, parentSn);
     const channel = typeof raw.device_channel === "number" ? raw.device_channel : 0;
     const stationAdminId = raw.member?.admin_user_id;
     const accountId = stationAdminId ?? this.deps.mega.auth?.userId ?? "";
@@ -24649,9 +24877,9 @@ var EufyMega = class extends EventEmitter9 {
   /**
    * Combine explicit P2P media with the optional passive push-thumbnail provider.
    *
-   * The retained still also becomes the answer for a live still that could not be captured. A station
-   * serves one camera at a time and a live view outranks a tile, so a still asked for while a sibling is
-   * being watched is refused at the transport. Answering the retained bytes answers the read rather than
+   * The retained still also becomes the answer for a live still that could not be captured. One session
+   * serves one camera at a time and a live view outranks a tile — a still does not open a connection of its
+   * own — so a still asked for while a sibling is being watched is refused at the transport. Answering the retained bytes answers the read rather than
    * failing it, marked {@link MediaProvider.snapshotLive} `retained` so the caller knows they are not
    * current. With nothing retained the refusal stands.
    */
@@ -25404,10 +25632,15 @@ var EufyMega = class extends EventEmitter9 {
       await sink.dispatch(cmd);
   }
   /**
-   * Stations with a live P2P session. P2P is auto-managed: wired stations are warmed at login, battery
+   * The open P2P sessions, by key. P2P is auto-managed: wired stations are warmed at login, battery
    * stations open on demand (command / stream, or an opted-in event pre-warm) and idle-detach — so this
-   * map grows and shrinks over time. `p2pConnect(stationSn)` / `p2pClose(stationSn)` events track the
-   * changes.
+   * map grows and shrinks over time.
+   *
+   * A station's own session is keyed by its serial, and `p2pConnect(stationSn)` / `p2pClose(stationSn)`
+   * track those. A station serving more than one camera at once also holds a session per extra camera,
+   * keyed `<stationSn>#live:<channel>` — these carry media alone and raise no connection events, because
+   * a station announces its state to every client that connects and reporting each copy would double
+   * every event the station's own session already delivers.
    */
   getP2pSessions() {
     return this.p2p.getSessions();
@@ -26480,7 +26713,6 @@ export {
   SolixDevice,
   SolixMqtt,
   StateConvergenceError,
-  StationBusyError,
   StationKeyUnavailableError,
   StationUnreachableError,
   StoredSnapshotUnavailableError,
@@ -26517,6 +26749,7 @@ export {
   buildRealtimeInit,
   captureSnapshotFromShared,
   cellAtPoint,
+  claimedParams,
   clamp,
   classify,
   classifyDevice,