@effect/platform-browser 4.0.0-beta.70 → 4.0.0-beta.71

package/src/BrowserPersistence.ts

@@ -1,15 +1,53 @@
 /**
- * Browser-backed persistence layers for Effect's persistence service.
+ * IndexedDB-backed persistence layers for browser Effect programs.
  *
- * This module provides IndexedDB implementations of the Effect persistence services for applications that need a
- * durable client-side cache, such as remembered query results, offline-capable workflows, or values that should survive
- * page reloads. Entries are stored by persistence store id and key in a shared IndexedDB object store, with optional
- * expiration timestamps for TTL-based invalidation.
+ * `BrowserPersistence` connects the unstable persistence services to the
+ * browser's IndexedDB storage. Use it for client-side caches that should
+ * survive page reloads, offline-capable workflows, remembered query results,
+ * and other application-managed values that can be recomputed or invalidated
+ * when storage is unavailable.
  *
- * Because this storage depends on browser IndexedDB, operations can fail when storage is unavailable, quota is exceeded,
- * data is cleared by the user or browser, or the payload cannot be structured-cloned by IndexedDB. Expired entries are
- * removed lazily when they are read, so this module is best suited for application-managed cached objects rather than
- * security-sensitive or authoritative data.
+ * **Mental model**
+ *
+ * - {@link layerIndexedDb} provides the higher-level `Persistence` service by
+ *   composing the IndexedDB backing layer with the core persistence layer.
+ * - {@link layerBackingIndexedDb} provides only `BackingPersistence` for code
+ *   that composes persistence services manually.
+ * - Entries live in one IndexedDB database, defaulting to
+ *   `"effect_persistence"`, and one object store keyed by `[storeId, key]`.
+ * - The `storeId` namespaces persisted request results; the key identifies one
+ *   entry inside that store.
+ * - Finite TTLs are stored as expiration timestamps and expired entries are
+ *   removed lazily when they are read.
+ *
+ * **Common tasks**
+ *
+ * - Provide browser persistence to `PersistedCache` or other persistence
+ *   workflows with {@link layerIndexedDb}.
+ * - Isolate tests, apps, or migrations by passing a custom `database` option.
+ * - Use {@link layerBackingIndexedDb} when another layer should decide how to
+ *   construct the higher-level `Persistence` service.
+ *
+ * **Gotchas**
+ *
+ * - This module requires browser IndexedDB and stores data per origin.
+ * - Opening IndexedDB is defected during layer acquisition if the database
+ *   cannot be opened; later store operations report `PersistenceError`.
+ * - Values must be structured-cloneable objects, and writes can fail because of
+ *   quota limits, browser settings, private browsing modes, or user-cleared
+ *   storage.
+ * - Lazy TTL cleanup makes this suitable for caches, not for authoritative or
+ *   security-sensitive state.
+ *
+ * **Example** (Providing browser persistence)
+ *
+ * ```ts
+ * import { BrowserPersistence } from "@effect/platform-browser"
+ *
+ * export const PersistenceLive = BrowserPersistence.layerIndexedDb({
+ *   database: "my-app-cache"
+ * })
+ * ```
  *
  * @since 4.0.0
  */
@@ -23,6 +61,25 @@ import * as Persistence from "effect/unstable/persistence/Persistence"
 /**
  * Creates a `BackingPersistence` layer backed by IndexedDB, optionally using the provided database name.
  *
+ * **When to use**
+ *
+ * Use when composing persistence manually and the lower-level
+ * `BackingPersistence` service should be backed by browser IndexedDB.
+ *
+ * **Details**
+ *
+ * The database name defaults to `"effect_persistence"`. Entries are stored by
+ * persistence store id and key in a shared object store, and TTL expiration is
+ * checked when values are read.
+ *
+ * **Gotchas**
+ *
+ * Opening the database is defected during layer acquisition if IndexedDB is
+ * unavailable or cannot be opened. Store operations report `PersistenceError`
+ * for IndexedDB request, transaction, quota, and structured-clone failures.
+ *
+ * @see {@link layerIndexedDb} for providing the higher-level `Persistence` service
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/BrowserRuntime.ts

@@ -28,6 +28,22 @@ import { makeRunMain, type Teardown } from "effect/Runtime"
 /**
  * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
  *
+ * **When to use**
+ *
+ * Use to launch a browser page, single-page application, demo, or browser test
+ * harness as a root Effect program.
+ *
+ * **Details**
+ *
+ * Supports both direct and curried call forms. Options are forwarded to
+ * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+ * behavior.
+ *
+ * **Gotchas**
+ *
+ * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+ * asynchronous finalizers, network work, timers, or prompts from completing.
+ *
  * @category Runtime
  * @since 4.0.0
  */
@@ -35,6 +51,22 @@ export const runMain: {
   /**
    * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
    *
+   * **When to use**
+   *
+   * Use to launch a browser page, single-page application, demo, or browser test
+   * harness as a root Effect program.
+   *
+   * **Details**
+   *
+   * Supports both direct and curried call forms. Options are forwarded to
+   * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+   * behavior.
+   *
+   * **Gotchas**
+   *
+   * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+   * asynchronous finalizers, network work, timers, or prompts from completing.
+   *
    * @category Runtime
    * @since 4.0.0
    */
@@ -47,6 +79,22 @@ export const runMain: {
   /**
    * Runs an effect as the browser main program and interrupts its fiber when the page receives a `beforeunload` event.
    *
+   * **When to use**
+   *
+   * Use to launch a browser page, single-page application, demo, or browser test
+   * harness as a root Effect program.
+   *
+   * **Details**
+   *
+   * Supports both direct and curried call forms. Options are forwarded to
+   * `makeRunMain`, including `disableErrorReporting` and custom `teardown`
+   * behavior.
+   *
+   * **Gotchas**
+   *
+   * The `beforeunload` interruption is best-effort. Browser teardown may prevent
+   * asynchronous finalizers, network work, timers, or prompts from completing.
+   *
    * @category Runtime
    * @since 4.0.0
    */

package/src/BrowserSocket.ts

@@ -1,26 +1,40 @@
 /**
- * Browser WebSocket layers for Effect sockets.
- *
- * This module provides the browser entry point for `Socket.Socket` values
- * backed by the platform `WebSocket` implementation. Use `layerWebSocket` when
- * client-side Effect programs, browser tests, RPC transports, or realtime UI
- * features need a bidirectional socket connected to a WebSocket URL, and use
- * `layerWebSocketConstructor` when lower-level socket APIs need access to the
- * browser constructor service.
- *
- * Browser WebSocket rules still apply. Connections are created through
- * `globalThis.WebSocket`, so URL schemes, subprotocol negotiation, mixed-content
- * blocking, cookies, authentication, CORS-like origin checks, and extension
- * negotiation are controlled by the browser and server rather than by Effect.
- * Close events are translated into socket errors unless the provided
- * `closeCodeIsError` predicate classifies the close code as clean, which is
- * useful for protocols that use application-specific close codes.
- *
- * Messages are delivered as strings or binary `Uint8Array` values; browser
- * `Blob` messages are read into bytes before they reach the socket handler.
- * Outgoing data should already be serialized to a string or bytes, and protocol
- * frames that represent an intentional close should be sent as `CloseEvent`
- * values so the underlying `WebSocket.close` code and reason are preserved.
+ * Provide Effect sockets backed by the browser `WebSocket` implementation.
+ *
+ * This module is the browser entry point for Effect's socket abstraction. Use
+ * {@link layerWebSocket} when a client-side Effect program needs a complete
+ * `Socket.Socket` connected to a WebSocket URL. Use
+ * {@link layerWebSocketConstructor} when lower-level socket code only needs the
+ * browser-backed constructor service.
+ *
+ * ## Mental model
+ *
+ * `layerWebSocket` delegates socket behavior to Effect's WebSocket support and
+ * supplies `globalThis.WebSocket` as the constructor. Incoming browser messages
+ * are normalized to strings or binary `Uint8Array` values. Browser `Blob`
+ * messages are read into bytes before they reach the socket consumer.
+ *
+ * Outgoing data should already be serialized to a string or bytes. To close the
+ * underlying browser socket with a specific code and reason, send a
+ * `CloseEvent` value so the close metadata is preserved.
+ *
+ * ## Common tasks
+ *
+ * - Connect RPC transports, browser tests, or realtime UI features to a
+ *   WebSocket URL with {@link layerWebSocket}.
+ * - Provide only the browser constructor service with
+ *   {@link layerWebSocketConstructor} when another socket layer builds the
+ *   connection.
+ * - Customize `closeCodeIsError` for protocols that treat specific close codes
+ *   as normal completion instead of socket failure.
+ *
+ * ## Gotchas
+ *
+ * Browser WebSocket rules still apply. URL schemes, subprotocol negotiation,
+ * mixed-content blocking, cookies, authentication, server origin checks, and
+ * extension negotiation are controlled by the browser and server rather than by
+ * Effect. Close events become socket errors unless `closeCodeIsError`
+ * classifies the close code as clean.
  *
  * @since 4.0.0
  */
@@ -30,6 +44,25 @@ import * as Socket from "effect/unstable/socket/Socket"
 /**
  * Creates a `Socket` layer connected to the given URL using the browser `WebSocket` constructor.
  *
+ * **When to use**
+ *
+ * Use when browser or client-side code needs a complete `Socket` layer
+ * connected to a WebSocket URL.
+ *
+ * **Details**
+ *
+ * Delegates socket construction to `Socket.makeWebSocket` and provides the
+ * browser-backed `WebSocketConstructor` service.
+ *
+ * **Gotchas**
+ *
+ * Browser WebSocket rules still control URL schemes, mixed-content blocking,
+ * cookies, authentication, origin checks, subprotocols, and extensions. Close
+ * events are errors unless `closeCodeIsError` classifies the close code as
+ * clean.
+ *
+ * @see {@link layerWebSocketConstructor} for providing only the browser constructor service
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/BrowserStream.ts

@@ -1,25 +1,40 @@
 /**
- * Browser `Stream` constructors for DOM event targets.
+ * Convert browser DOM events into Effect streams.
  *
- * This module provides typed helpers for turning `window.addEventListener` and
- * `document.addEventListener` callbacks into Effect `Stream`s. They are useful
- * for UI and runtime signals such as resize, visibility, keyboard, pointer,
- * focus, online / offline, and other browser events that should be composed
- * with Effect stream operators and finalized with the consuming fiber.
+ * This module provides typed constructors for listening to `window` and
+ * `document` events from Effect programs. Use {@link fromEventListenerWindow}
+ * for viewport, network, focus, pointer, keyboard, and other `Window` events,
+ * and use {@link fromEventListenerDocument} for document lifecycle,
+ * visibility, selection, fullscreen, and other `Document` events.
  *
- * Browser events are push-based `EventTarget` notifications, so they do not
- * apply Web Streams backpressure to the browser event source. Events are
- * buffered until downstream pulls them; the default buffer is unbounded, so
- * high-frequency sources like scroll, pointermove, or mousemove should usually
- * set `bufferSize` and use stream operators that sample, debounce, throttle, or
- * drop work as appropriate.
+ * ## Mental model
  *
- * These helpers are for DOM events, not for adapting `ReadableStream` request
- * or response bodies. Fetch bodies follow the Web Streams body rules, including
- * single-consumer locking and disturbed bodies after reads, and should be
- * handled with body-specific HTTP or Web Streams APIs instead. When using the
- * browser `once` option, pair the stream with `Stream.take(1)` if a finite
- * stream is required.
+ * Each constructor registers a DOM `addEventListener` callback when the stream
+ * is consumed and removes it when the stream is finalized. Browser events are
+ * push-based `EventTarget` notifications, so the browser does not slow down the
+ * event source when downstream stream processing is busy. Events are buffered
+ * inside the stream until a consumer pulls them.
+ *
+ * ## Common tasks
+ *
+ * - Track browser state such as resize, online / offline, focus, visibility, or
+ *   pointer activity with Effect stream operators.
+ * - Scope DOM listeners to a fiber so they are removed when the consuming
+ *   effect is interrupted or completes.
+ * - Set `bufferSize` for bursty event sources before applying sampling,
+ *   throttling, debouncing, or dropping logic downstream.
+ *
+ * ## Gotchas
+ *
+ * The default buffer is unbounded. High-frequency sources such as `scroll`,
+ * `pointermove`, or `mousemove` should usually specify `bufferSize` and reduce
+ * the event rate with stream operators.
+ *
+ * These helpers are for DOM events, not for `ReadableStream` request or
+ * response bodies. Fetch bodies follow Web Streams rules such as
+ * single-consumer locking and disturbed bodies after reads. When using the DOM
+ * `once` option, also use `Stream.take(1)` if the consuming code needs a finite
+ * stream.
  *
  * @since 4.0.0
  */

package/src/BrowserWorker.ts

@@ -1,22 +1,37 @@
 /**
- * Parent-side browser support for Effect workers.
- *
- * This module provides the `WorkerPlatform` used by browser applications that
- * spawn or connect to `Worker`, `SharedWorker`, and `MessagePort` endpoints
- * through Effect's worker protocol. Pair it with `BrowserWorkerRunner` in the
- * worker entrypoint when building worker-backed RPC clients, moving CPU-bound
- * work off the main thread, isolating browser-only services, or adapting an
- * existing `MessageChannel` in tests and custom transports.
- *
- * Dedicated workers communicate through the worker object itself, while shared
- * workers communicate through `worker.port`; raw `MessagePort` values are also
- * accepted and are started when supported. Messages are posted with the browser
- * structured-clone algorithm, so payloads must be cloneable by the target
- * runtime. Transfer lists can avoid copying values such as `ArrayBuffer` or
- * `MessagePort`, but transferring moves ownership away from the sender and
- * invalid or mismatched transferables can fail the send. Scope finalization
- * sends the worker close signal over the port; the application that created a
- * dedicated `Worker` remains responsible for any broader lifecycle such as
+ * Parent-side browser platform for running Effect workers.
+ *
+ * This module provides the `WorkerPlatform` used by browser code that spawns or
+ * connects to `Worker`, `SharedWorker`, and `MessagePort` endpoints through
+ * Effect's worker protocol. Pair it with `BrowserWorkerRunner` in the worker
+ * entrypoint when building worker-backed RPC clients, moving CPU-bound work off
+ * the main thread, isolating browser-only services, or adapting an existing
+ * `MessageChannel` in tests.
+ *
+ * **Mental model**
+ *
+ * Browser worker communication is normalized to a message port. Dedicated
+ * workers post messages on the worker object itself, shared workers post
+ * through `worker.port`, and raw `MessagePort` values can be supplied directly.
+ * `layerPlatform` provides only the browser platform, while `layer` combines
+ * the platform with a `Spawner` that creates a worker endpoint for each worker
+ * id.
+ *
+ * **Common tasks**
+ *
+ * Use `layer` when parent code should both provide browser worker messaging and
+ * define how workers are spawned. Use `layerPlatform` when a spawner is already
+ * provided elsewhere. Return a `MessagePort` from the spawner for tests or
+ * custom channels, a `Worker` for dedicated workers, or a `SharedWorker` when
+ * multiple browser contexts should share one worker runtime.
+ *
+ * **Gotchas**
+ *
+ * Messages use the browser structured-clone algorithm, so payloads and transfer
+ * lists must be accepted by the target runtime. Transferring an `ArrayBuffer` or
+ * `MessagePort` moves ownership away from the sender. Scope finalization sends
+ * the worker close signal over the port, but code that created a dedicated
+ * `Worker` remains responsible for broader lifecycle concerns such as
  * terminating it.
  *
  * @since 4.0.0
@@ -31,6 +46,23 @@ import { WorkerError, WorkerReceiveError } from "effect/unstable/workers/WorkerE
 /**
  * Creates browser worker layers by combining the default `WorkerPlatform` with a spawner for `Worker`, `SharedWorker`, or `MessagePort` instances.
  *
+ * **When to use**
+ *
+ * Use when browser parent or client code needs both the browser
+ * `WorkerPlatform` and a `Spawner` from one layer.
+ *
+ * **Details**
+ *
+ * The `spawn` callback receives the numeric worker id and may return a
+ * `Worker`, `SharedWorker`, or `MessagePort`.
+ *
+ * **Gotchas**
+ *
+ * Scope finalization sends the worker close protocol over the port. Dedicated
+ * workers created by `spawn` are not terminated by this layer.
+ *
+ * @see {@link layerPlatform} for providing only the browser worker platform
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/BrowserWorkerRunner.ts

@@ -1,21 +1,33 @@
 /**
- * Browser runtime support for Effect worker runners.
+ * Runner-side browser platform for Effect worker handlers.
  *
- * This module is intended for code that is already executing in a browser
- * worker context, or for tests and adapters that supply a `MessagePort` or
- * `Window` endpoint directly. It provides the `WorkerRunnerPlatform` used by
- * `WorkerRunner` and `RpcServer.layerProtocolWorkerRunner` to receive parent
- * or client requests, run Effect handlers, and send responses through the
- * browser `postMessage` channel.
+ * This module is for code already executing inside a browser worker, or for
+ * tests and adapters that pass a `MessagePort` or `Window` endpoint directly.
+ * It provides the `WorkerRunnerPlatform` used by `WorkerRunner` and protocols
+ * such as `RpcServer.layerProtocolWorkerRunner` to receive parent or client
+ * requests, run Effect handlers, and post responses back through the browser
+ * messaging channel.
  *
- * Use it with `BrowserWorker` when a browser application needs to move RPC
+ * **Mental model**
+ *
+ * Dedicated workers use the ambient `self` endpoint. Shared workers receive one
+ * `MessagePort` per `onconnect` event, and this module caches ports that arrive
+ * before the runner layer starts. `layer` reads from the global worker `self`;
+ * `make` and `layerMessagePort` are for explicit endpoints supplied by tests,
+ * custom channels, or adapter code.
+ *
+ * **Common tasks**
+ *
+ * Pair this module with `BrowserWorker` in the parent page when moving RPC
  * handlers, CPU-bound computations, or browser-only services into a dedicated
- * worker or shared worker. Dedicated workers communicate through the current
- * `self` endpoint; shared workers accept multiple `onconnect` ports and cache
- * ports that connect before the runner layer starts. Messages still use the
- * browser structured-clone algorithm, so payload schemas, transfer lists,
- * `messageerror` events, and the lifetime of each `MessagePort` must be
- * considered when crossing worker boundaries.
+ * worker or shared worker. Use `layer` in normal worker entry points and
+ * `layerMessagePort` when a test or integration already owns the transport.
+ *
+ * **Gotchas**
+ *
+ * Payloads and transfer lists must satisfy the browser structured-clone
+ * algorithm. `messageerror` and `error` events fail the runner, and each
+ * connected `MessagePort` is closed when its scope finalizes.
  *
  * @since 4.0.0
  */
@@ -173,6 +185,25 @@ export const make = (self: MessagePort | Window): WorkerRunner.WorkerRunnerPlatf
 /**
  * Layer that provides a browser `WorkerRunnerPlatform` using the global `self` worker context.
  *
+ * **When to use**
+ *
+ * Use when a browser worker entry point uses the ambient `self` object as the
+ * worker transport.
+ *
+ * **Details**
+ *
+ * Delegates to `make(self)` and provides the runner-side platform used by
+ * protocols such as `RpcServer.layerProtocolWorkerRunner`.
+ *
+ * **Gotchas**
+ *
+ * This layer depends on the browser worker global `self`. Use
+ * `layerMessagePort` when the transport is an explicit `MessagePort` or
+ * `Window`.
+ *
+ * @see {@link make} for constructing a runner platform from an explicit endpoint
+ * @see {@link layerMessagePort} for providing a platform from an explicit endpoint
+ *
  * @category layers
  * @since 4.0.0
  */

package/src/Clipboard.ts

@@ -1,19 +1,35 @@
 /**
- * Browser clipboard service for Effect programs.
- *
- * This module wraps the browser `navigator.clipboard` API in a `Clipboard`
- * service so client-side applications can read, write, and clear clipboard
- * contents as typed Effects. It is useful for common UI workflows such as copy
- * buttons, paste/import actions, sharing generated text, and moving rich
- * clipboard payloads like `Blob`-backed `ClipboardItem`s through an Effect
- * environment.
- *
- * Browser clipboard rules still apply. Clipboard access generally requires a
- * secure context, and browsers may require a user gesture, permission prompt, or
- * active focused document before reads or writes are allowed. Support also
- * varies by operation and payload type: text helpers are the most portable,
- * while `ClipboardItem` and non-text MIME types may be unavailable or restricted
- * in some browsers. Failed browser operations are surfaced as `ClipboardError`.
+ * Browser clipboard integration for Effect programs.
+ *
+ * This module provides a `Clipboard` service backed by `navigator.clipboard`.
+ * It keeps copy, paste, clear, and rich clipboard operations inside the Effect
+ * environment so browser UI code can require clipboard capability without
+ * calling the global API directly. Text helpers cover portable copy and paste
+ * flows, while `read`, `write`, and `writeBlob` expose `ClipboardItem` payloads
+ * for browsers that support richer MIME types.
+ *
+ * **Mental model**
+ *
+ * `Clipboard` is a capability service. Application code depends on the service
+ * tag, {@link layer} supplies the live browser implementation, and {@link make}
+ * builds custom implementations for tests, unsupported browsers, or constrained
+ * capabilities. Browser failures are converted to {@link ClipboardError}.
+ *
+ * **Common tasks**
+ *
+ * - Provide {@link layer} near the browser application edge.
+ * - Use `writeString` for copy buttons and generated text.
+ * - Use `readString` for paste or import workflows.
+ * - Use `write` or `writeBlob` for rich clipboard payloads when
+ *   `ClipboardItem` is available.
+ * - Use `clear` to replace the clipboard with an empty string.
+ *
+ * **Gotchas**
+ *
+ * Clipboard access requires a secure context in modern browsers and may also
+ * require user activation, permissions, and a focused document. Support differs
+ * between reads, writes, text, and custom MIME payloads, so feature detection or
+ * graceful fallback is often needed around `ClipboardItem` usage.
  *
  * @since 4.0.0
  */
@@ -28,6 +44,19 @@ const ErrorTypeId = "~@effect/platform-browser/Clipboard/ClipboardError"
 /**
  * Service interface for reading from, writing to, and clearing the browser clipboard.
  *
+ * **Details**
+ *
+ * `read` and `write` work with `ClipboardItem` arrays. `readString` and
+ * `writeString` use text, `writeBlob` writes one `Blob`, and `clear` writes an
+ * empty string.
+ *
+ * **Gotchas**
+ *
+ * Clipboard access generally requires a secure context and may require user
+ * activation, permissions, or a focused document. `ClipboardItem` and non-text
+ * MIME type support varies by browser. Failed browser operations are surfaced
+ * as `ClipboardError`.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -57,6 +86,14 @@ export class ClipboardError extends Data.TaggedError("ClipboardError")<{
 /**
  * Service tag for the browser `Clipboard` service.
  *
+ * **When to use**
+ *
+ * Use when an Effect needs to require or provide clipboard capabilities through
+ * the context.
+ *
+ * @see {@link make} for building a custom clipboard service
+ * @see {@link layer} for providing the browser-backed clipboard service
+ *
  * @category services
  * @since 4.0.0
  */

package/src/Geolocation.ts

@@ -1,19 +1,35 @@
 /**
- * Browser geolocation support for Effect programs.
- *
- * This module provides a `Geolocation` service and browser-backed layer for
- * reading device location through `navigator.geolocation`. Use
- * `getCurrentPosition` when an application needs one location fix, such as a
- * nearby-search, check-in, or delivery estimate, and `watchPosition` when it
- * needs a stream of updates for navigation, tracking, or location-aware UI.
- *
- * The implementation is browser-only and relies on the browser permission and
- * policy model for geolocation. Calls may prompt the user, fail when permission
- * is denied, time out, or report that position data is unavailable because of
- * device, browser, privacy, origin, or secure-context restrictions. Watched
- * positions are scoped so the underlying browser watch is cleared when the
- * stream is finalized, and slow consumers should account for the sliding
- * buffer used by `watchPosition`.
+ * Browser geolocation integration for Effect programs.
+ *
+ * This module exposes a `Geolocation` service backed by
+ * `navigator.geolocation`. Use it for browser features that need a single
+ * position fix, such as nearby search or delivery estimates, or a stream of
+ * position updates for navigation, tracking, and location-aware interfaces.
+ * Browser failures are represented as typed `GeolocationError` values instead
+ * of raw callback errors.
+ *
+ * **Mental model**
+ *
+ * - The service delegates to the browser Geolocation API and follows the
+ *   browser's permission, privacy, origin, and secure-context rules.
+ * - `getCurrentPosition` reads one position fix from the service.
+ * - {@link watchPosition} turns browser position callbacks into a `Stream` and
+ *   clears the underlying browser watch when the stream is finalized.
+ *
+ * **Common tasks**
+ *
+ * - Provide the live browser implementation with {@link layer}.
+ * - Read a one-shot position from the `Geolocation` service.
+ * - Stream position updates with {@link watchPosition}.
+ * - Handle denied permissions, timeouts, and unavailable position data with
+ *   {@link GeolocationError}.
+ *
+ * **Gotchas**
+ *
+ * - Browsers may prompt the user, reject access outside secure contexts, block
+ *   access by permissions policy, or report that position data is unavailable.
+ * - {@link watchPosition} uses a sliding buffer; increase `bufferSize` if slow
+ *   consumers must not skip older positions.
  *
  * @since 4.0.0
  */
@@ -31,6 +47,26 @@ const ErrorTypeId = "~@effect/platform-browser/Geolocation/GeolocationError"
 /**
  * Service interface for browser geolocation, providing effects for the current position and streams of watched positions.
  *
+ * **When to use**
+ *
+ * Use when browser code needs a typed Effect service for one-shot location
+ * reads or streamed location updates.
+ *
+ * **Details**
+ *
+ * `getCurrentPosition` returns one position effect. `watchPosition` returns a
+ * stream and accepts the browser `PositionOptions` plus an optional sliding
+ * `bufferSize`.
+ *
+ * **Gotchas**
+ *
+ * Browser permission prompts, denied permissions, timeouts, unavailable
+ * position data, secure-context restrictions, and policy restrictions are
+ * surfaced as `GeolocationError`.
+ *
+ * @see {@link GeolocationError} for represented browser geolocation failures
+ * @see {@link layer} for the browser-backed service implementation
+ *
  * @category models
  * @since 4.0.0
  */
@@ -51,6 +87,13 @@ export interface Geolocation {
 /**
  * Service tag for the browser `Geolocation` service.
  *
+ * **When to use**
+ *
+ * Use when an Effect needs to access or provide geolocation capabilities
+ * through the context.
+ *
+ * @see {@link layer} for providing the browser-backed geolocation service
+ *
  * @category services
  * @since 4.0.0
  */