sibujs 3.4.0 → 4.0.0

package/dist/browser.d.cts

@@ -117,7 +117,12 @@ declare function permissions(name: string): {
  * Tracks the last copied text and provides a `copied` indicator
  * that resets after 2 seconds.
  *
- * @returns Object with reactive text getter, copy function, copied indicator, and dispose
+ * OWNERSHIP: `navigator.clipboard.writeText()` is an unbounded async gap — it
+ * can sit on a permission prompt indefinitely. A write that resolves after
+ * `dispose()` must not touch state or arm a timer: the component that owned
+ * this controller is gone, so a `copied` flash it schedules fires against a
+ * torn-down subtree and keeps the controller (and its closure) alive for two
+ * more seconds for nothing.
  */
 declare function clipboard(): {
     text: () => string;
@@ -161,10 +166,16 @@ declare function dropZone(element: ElementTarget, options: {
 /**
  * title sets `document.title` reactively. Accepts a static string
  * or a reactive getter function. Returns a dispose function that
- * restores the previous document title.
+ * hands the title back to its previous owner.
  *
- * @param title Static string or reactive getter for the document title
- * @returns Dispose function that restores the original title
+ * Ownership is a STACK shared with `Head({ title })` — see
+ * `utils/documentResources`. A per-instance "previous title" snapshot, which is
+ * what this used to keep, restores a stale value whenever three owners overlap
+ * and the middle one is disposed first: it writes back the title that was
+ * current when IT mounted, overwriting the owner that is actually visible.
+ *
+ * @param value Static string or reactive getter for the document title
+ * @returns Dispose function that releases this owner's claim
  */
 declare function title(value: string | (() => string)): () => void;
 
@@ -435,12 +446,46 @@ declare function fullscreen(): {
  * wakeLock wraps the Screen Wake Lock API to keep the screen awake while the
  * app is doing something the user is watching (video, timer, recipe, nav).
  *
- * Returns a reactive `active` boolean plus `request` / `release` actions.
+ * Returns a reactive `active` boolean plus `request` / `release` / `dispose`.
  * The lock is automatically re-requested if the page becomes visible again
  * after being hidden (browsers auto-release wake locks on tab hide).
  *
  * Gracefully degrades on browsers without the API.
  *
+ * OWNERSHIP MODEL
+ * ---------------
+ * A wake lock is a native handle, and the previous implementation kept exactly
+ * one mutable reference to it with no notion of which request that reference
+ * belonged to. Three things followed, all of them reproducible:
+ *
+ *   - two overlapping `request()` calls acquired two sentinels; the second to
+ *     arrive overwrote the first, and `release()` then released only the
+ *     survivor. The other sentinel stayed held by the platform with no reference
+ *     left to release it — a leaked native handle.
+ *   - `release()` set the reference to null but did nothing about a request
+ *     still in flight, so a sentinel arriving afterwards installed itself and
+ *     the screen stayed awake after the caller had explicitly asked it not to.
+ *   - the `release` listener called `setActive(false)` unconditionally, so an
+ *     *old* sentinel being released by the platform cleared the state belonging
+ *     to the current one.
+ *
+ * The model is therefore explicit:
+ *
+ *   - `desire` is whether the controller currently wants a lock at all.
+ *   - `generation` is bumped by `request()`, `release()` and `dispose()`. A
+ *     completing request compares generations and, if it has lost ownership,
+ *     releases the sentinel it was handed immediately rather than storing it.
+ *     That is what makes a leak structurally impossible: every sentinel this
+ *     module ever receives is either the current one or released on arrival.
+ *   - concurrent `request()` calls share one in-flight acquisition, so the API
+ *     is never asked for two sentinels at once, and `request()` while an
+ *     unreleased sentinel is held is a no-op.
+ *   - `active()` is true exactly when a current, unreleased sentinel is held.
+ *   - `release()` and `dispose()` revoke the desire *before* awaiting anything,
+ *     so a request already in flight is superseded rather than raced.
+ *   - `dispose()` is idempotent and publishes `active(false)` exactly once, as
+ *     its final act; nothing is published afterwards.
+ *
  * @example
  * ```ts
  * const lock = wakeLock();

package/dist/browser.d.ts

@@ -117,7 +117,12 @@ declare function permissions(name: string): {
  * Tracks the last copied text and provides a `copied` indicator
  * that resets after 2 seconds.
  *
- * @returns Object with reactive text getter, copy function, copied indicator, and dispose
+ * OWNERSHIP: `navigator.clipboard.writeText()` is an unbounded async gap — it
+ * can sit on a permission prompt indefinitely. A write that resolves after
+ * `dispose()` must not touch state or arm a timer: the component that owned
+ * this controller is gone, so a `copied` flash it schedules fires against a
+ * torn-down subtree and keeps the controller (and its closure) alive for two
+ * more seconds for nothing.
  */
 declare function clipboard(): {
     text: () => string;
@@ -161,10 +166,16 @@ declare function dropZone(element: ElementTarget, options: {
 /**
  * title sets `document.title` reactively. Accepts a static string
  * or a reactive getter function. Returns a dispose function that
- * restores the previous document title.
+ * hands the title back to its previous owner.
  *
- * @param title Static string or reactive getter for the document title
- * @returns Dispose function that restores the original title
+ * Ownership is a STACK shared with `Head({ title })` — see
+ * `utils/documentResources`. A per-instance "previous title" snapshot, which is
+ * what this used to keep, restores a stale value whenever three owners overlap
+ * and the middle one is disposed first: it writes back the title that was
+ * current when IT mounted, overwriting the owner that is actually visible.
+ *
+ * @param value Static string or reactive getter for the document title
+ * @returns Dispose function that releases this owner's claim
  */
 declare function title(value: string | (() => string)): () => void;
 
@@ -435,12 +446,46 @@ declare function fullscreen(): {
  * wakeLock wraps the Screen Wake Lock API to keep the screen awake while the
  * app is doing something the user is watching (video, timer, recipe, nav).
  *
- * Returns a reactive `active` boolean plus `request` / `release` actions.
+ * Returns a reactive `active` boolean plus `request` / `release` / `dispose`.
  * The lock is automatically re-requested if the page becomes visible again
  * after being hidden (browsers auto-release wake locks on tab hide).
  *
  * Gracefully degrades on browsers without the API.
  *
+ * OWNERSHIP MODEL
+ * ---------------
+ * A wake lock is a native handle, and the previous implementation kept exactly
+ * one mutable reference to it with no notion of which request that reference
+ * belonged to. Three things followed, all of them reproducible:
+ *
+ *   - two overlapping `request()` calls acquired two sentinels; the second to
+ *     arrive overwrote the first, and `release()` then released only the
+ *     survivor. The other sentinel stayed held by the platform with no reference
+ *     left to release it — a leaked native handle.
+ *   - `release()` set the reference to null but did nothing about a request
+ *     still in flight, so a sentinel arriving afterwards installed itself and
+ *     the screen stayed awake after the caller had explicitly asked it not to.
+ *   - the `release` listener called `setActive(false)` unconditionally, so an
+ *     *old* sentinel being released by the platform cleared the state belonging
+ *     to the current one.
+ *
+ * The model is therefore explicit:
+ *
+ *   - `desire` is whether the controller currently wants a lock at all.
+ *   - `generation` is bumped by `request()`, `release()` and `dispose()`. A
+ *     completing request compares generations and, if it has lost ownership,
+ *     releases the sentinel it was handed immediately rather than storing it.
+ *     That is what makes a leak structurally impossible: every sentinel this
+ *     module ever receives is either the current one or released on arrival.
+ *   - concurrent `request()` calls share one in-flight acquisition, so the API
+ *     is never asked for two sentinels at once, and `request()` while an
+ *     unreleased sentinel is held is a no-op.
+ *   - `active()` is true exactly when a current, unreleased sentinel is held.
+ *   - `release()` and `dispose()` revoke the desire *before* awaiting anything,
+ *     so a request already in flight is superseded rather than raced.
+ *   - `dispose()` is idempotent and publishes `active(false)` exactly once, as
+ *     its final act; nothing is published afterwards.
+ *
  * @example
  * ```ts
  * const lock = wakeLock();

package/dist/browser.js

@@ -35,13 +35,15 @@ import {
   visibility,
   wakeLock,
   windowSize
-} from "./chunk-S3V6ZXPI.js";
+} from "./chunk-EWEE7NBF.js";
 import "./chunk-H3SRKIYX.js";
-import "./chunk-BUKYCWHX.js";
-import "./chunk-S3NFJO6L.js";
-import "./chunk-KZBEVFXZ.js";
-import "./chunk-OOUQUCNN.js";
-import "./chunk-COY6PUD2.js";
+import "./chunk-52XFPGSN.js";
+import "./chunk-7ZHH77QA.js";
+import "./chunk-PBQEW5VW.js";
+import "./chunk-TIRZCERI.js";
+import "./chunk-W55YHPEP.js";
+import "./chunk-ACBT6UZS.js";
+import "./chunk-VPP2FONR.js";
 export {
   animationFrame,
   battery,