@signality/core 0.0.1-alpha.2 → 0.0.1-alpha.3

package/browser/gamepad/index.d.ts

@@ -1,28 +1,58 @@
 import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface GamepadRef {
-    /** Whether Gamepad API is supported */
+    /**
+     * Whether the Gamepad API is supported in the current browser.
+     *
+     * @see [Gamepad API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Array of connected gamepads */
+    /**
+     * Array of all connected gamepads. Indices match the gamepad's `index` property. May contain `null` for disconnected slots.
+     *
+     * @see [Navigator: getGamepads() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getGamepads)
+     */
     readonly gamepads: Signal<(Gamepad | null)[]>;
-    /** First connected gamepad */
+    /**
+     * The first connected gamepad, or `undefined` if none are connected.
+     *
+     * @see [Gamepad on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad)
+     */
     readonly activeGamepad: Signal<Gamepad | undefined>;
-    /** Axes values of active gamepad */
+    /**
+     * Axes values of the active gamepad. Each value is in the range `[-1, 1]`.
+     *
+     * @see [Gamepad: axes on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/axes)
+     */
     readonly axes: Signal<readonly number[]>;
-    /** Button states of active gamepad */
+    /**
+     * Button states of the active gamepad.
+     *
+     * @see [Gamepad: buttons on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/buttons)
+     */
     readonly buttons: Signal<readonly GamepadButton[]>;
 }
 /**
- * Signal-based wrapper around the Gamepad API.
+ * Signal-based wrapper around the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API).
  *
  * @param options - Optional injector for DI context
  * @returns A GamepadRef with gamepad state signals
  *
  * @example
  * ```typescript
- * const gp = gamepad();
- *
- * // In template: @for (pad of gp.gamepads(); track pad?.index) { ... }
+ * @Component({
+ *   template: `
+ *     @if (gp.isSupported()) {
+ *       @for (pad of gp.gamepads(); track pad?.index) {
+ *         <p>{{ pad?.id }}</p>
+ *       }
+ *       <p>Axes: {{ gp.axes() }}</p>
+ *     }
+ *   `
+ * })
+ * export class GamepadDemo {
+ *   readonly gp = gamepad();
+ * }
  * ```
  */
 export declare function gamepad(options?: WithInjector): GamepadRef;

package/browser/geolocation/index.d.ts

@@ -2,40 +2,71 @@ import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface GeolocationOptions extends WithInjector {
     /**
-     * Start tracking immediately.
-     * @default true
+     * Start tracking immediately on initialization.
+     *
+     * @default false
      */
     readonly immediate?: boolean;
     /**
-     * Use GPS for better accuracy.
+     * Use GPS for higher accuracy. May be slower and consume more power.
+     *
      * @default true
+     * @see [PositionOptions: enableHighAccuracy on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/enableHighAccuracy)
      */
     readonly enableHighAccuracy?: boolean;
     /**
-     * Max age of cached position (ms).
+     * Maximum age of a cached position in milliseconds. `0` forces a fresh lookup.
+     *
      * @default 0
+     * @see [PositionOptions: maximumAge on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/maximumAge)
      */
     readonly maximumAge?: number;
     /**
-     * Request timeout (ms).
+     * Maximum time in milliseconds allowed to retrieve a position before erroring.
+     *
      * @default Infinity
+     * @see [PositionOptions: timeout on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/timeout)
      */
     readonly timeout?: number;
 }
 export interface GeolocationRef {
-    /** Whether Geolocation is supported */
+    /**
+     * Whether the Geolocation API is supported in the current browser.
+     *
+     * @see [Geolocation API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Full position object with timestamp */
+    /**
+     * The most recent position, including coordinates and timestamp. `null` until first fix.
+     *
+     * @see [GeolocationPosition on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition)
+     */
     readonly position: Signal<GeolocationPosition | null>;
-    /** Last error */
+    /**
+     * The last error returned by the Geolocation API, or `null` if no error.
+     *
+     * @see [GeolocationPositionError on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError)
+     */
     readonly error: Signal<GeolocationPositionError | null>;
-    /** Whether location tracking is currently active */
+    /**
+     * Whether position watching is currently active.
+     */
     readonly isActive: Signal<boolean>;
-    /** Whether currently fetching location */
+    /**
+     * Whether a position fix is currently being fetched.
+     */
     readonly isLoading: Signal<boolean>;
-    /** Start/resume watching position */
+    /**
+     * Start watching the device position.
+     *
+     * @see [Geolocation: watchPosition() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition)
+     */
     readonly start: () => void;
-    /** Stop watching position */
+    /**
+     * Stop watching the device position.
+     *
+     * @see [Geolocation: clearWatch() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/clearWatch)
+     */
     readonly stop: () => void;
 }
 /**
@@ -56,7 +87,7 @@ export interface GeolocationRef {
  *     <button (click)="geo.stop()">Stop</button>
  *     <button (click)="geo.start()">Start</button>
  * })
- * class LocationComponent {
+ * export class LocationDemo {
  *   readonly geo = geolocation();
  * }
  * ```

package/browser/index.d.ts

@@ -7,8 +7,10 @@ export * from '@signality/core/browser/clipboard';
 export * from '@signality/core/browser/device-posture';
 export * from '@signality/core/browser/display-media';
 export * from '@signality/core/browser/eye-dropper';
+export * from '@signality/core/browser/file-dialog';
 export * from '@signality/core/browser/favicon';
 export * from '@signality/core/browser/fps';
+export * from '@signality/core/browser/fullscreen';
 export * from '@signality/core/browser/gamepad';
 export * from '@signality/core/browser/geolocation';
 export * from '@signality/core/browser/input-modality';
@@ -16,14 +18,19 @@ export * from '@signality/core/browser/listener';
 export * from '@signality/core/browser/media-query';
 export * from '@signality/core/browser/network';
 export * from '@signality/core/browser/online';
+export * from '@signality/core/browser/permission-state';
 export * from '@signality/core/browser/page-visibility';
 export * from '@signality/core/browser/picture-in-picture';
-export * from '@signality/core/browser/web-share';
+export * from '@signality/core/browser/screen-orientation';
 export * from '@signality/core/browser/speech-recognition';
 export * from '@signality/core/browser/speech-synthesis';
 export * from '@signality/core/browser/storage';
 export * from '@signality/core/browser/text-direction';
+export * from '@signality/core/browser/text-selection';
 export * from '@signality/core/browser/vibration';
 export * from '@signality/core/browser/wake-lock';
 export * from '@signality/core/browser/web-notification';
+export * from '@signality/core/browser/web-share';
 export * from '@signality/core/browser/web-worker';
+export * from '@signality/core/browser/window-focus';
+export * from '@signality/core/browser/window-size';

package/browser/input-modality/index.d.ts

@@ -17,7 +17,7 @@ export type InputModality = 'keyboard' | 'mouse' | 'touch' | null;
  *     </div>
  *   `
  * })
- * export class ModalityComponent {
+ * export class ModalityDemo {
  *   readonly modality = inputModality();
  * }
  * ```

package/browser/listener/index.d.ts

@@ -32,7 +32,7 @@ export interface ListenerFunction {
  * @Component({
  *   template: `<button #btn>Click me</button>`,
  * })
- * class ListenerComponent {
+ * export class ListenerDemo {
  *   readonly btn = viewChild<ElementRef>('btn');
  *
  *   constructor() {

package/browser/media-query/index.d.ts

@@ -26,7 +26,7 @@ export interface MediaQueryOptions extends CreateSignalOptions<boolean>, WithInj
  *     }
  *   `
  * })
- * class ThemeComponent {
+ * export class ThemeDemo {
  *   readonly prefersDark = mediaQuery('(prefers-color-scheme: dark)');
  * }
  * ```

package/browser/network/index.d.ts

@@ -4,23 +4,51 @@ export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
 export type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'wifi' | 'wimax' | 'none' | 'other' | 'unknown';
 export type NetworkOptions = WithInjector;
 export interface NetworkRef {
-    /** Whether Network Information API is supported */
+    /**
+     * Whether the Network Information API is supported in the current browser.
+     *
+     * @see [Network Information API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether the browser is online */
+    /**
+     * Whether the browser currently has network connectivity.
+     *
+     * @see [Navigator: onLine on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine)
+     */
     readonly isOnline: Signal<boolean>;
-    /** Effective connection type */
+    /**
+     * Estimated effective connection type based on recently observed network conditions.
+     *
+     * @see [NetworkInformation: effectiveType on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType)
+     */
     readonly effectiveType: Signal<EffectiveConnectionType | undefined>;
-    /** Downlink speed in Mbps */
+    /**
+     * Estimated downlink bandwidth in Mbps.
+     *
+     * @see [NetworkInformation: downlink on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/downlink)
+     */
     readonly downlink: Signal<number | undefined>;
-    /** Round-trip time in ms */
+    /**
+     * Estimated round-trip latency in milliseconds.
+     *
+     * @see [NetworkInformation: rtt on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/rtt)
+     */
     readonly rtt: Signal<number | undefined>;
-    /** Whether user has data saver enabled */
+    /**
+     * Whether the user has enabled a data-saving mode in their browser or OS.
+     *
+     * @see [NetworkInformation: saveData on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData)
+     */
     readonly saveData: Signal<boolean>;
-    /** Connection type (wifi, cellular, etc.) */
+    /**
+     * The physical connection type (e.g. `'wifi'`, `'cellular'`).
+     *
+     * @see [NetworkInformation: type on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/type)
+     */
     readonly type: Signal<ConnectionType | undefined>;
 }
 /**
- * Signal-based wrapper around the Network Information API and online/offline events.
+ * Signal-based wrapper around the [Network Information API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) and online/offline events.
  *
  * @param options - Optional configuration including injector
  * @returns A NetworkRef with network status signals
@@ -35,7 +63,7 @@ export interface NetworkRef {
  *     }
  *   `
  * })
- * class NetworkComponent {
+ * export class NetworkComponent {
  *   readonly net = network();
  * }
  * ```

package/browser/online/index.d.ts

@@ -18,7 +18,7 @@ export type OnlineOptions = CreateSignalOptions<boolean> & WithInjector;
  *     }
  *   `
  * })
- * class NetworkStatusComponent {
+ * export class NetworkStatus {
  *   readonly isOnline = online();
  * }
  * ```

package/browser/page-visibility/index.d.ts

@@ -18,7 +18,7 @@ export type PageVisibilityOptions = CreateSignalOptions<DocumentVisibilityState>
  *     }
  *   `
  * })
- * class VisibilityComponent {
+ * export class VisibilityDemo {
  *   readonly visibility = pageVisibility();
  * }
  * ```

package/browser/permission-state/index.d.ts

@@ -0,0 +1,23 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type PermissionStateOptions = CreateSignalOptions<PermissionState> & WithInjector;
+/**
+ * Signal-based wrapper around the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API).
+ *
+ * @param name - The permission name to query
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the current `PermissionState` (`'granted'`, `'denied'`, or `'prompt'`)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>Camera permission: {{ cameraPermission() }}</p>
+ *   `
+ * })
+ * export class PermissionDemo {
+ *   readonly cameraPermission = permissionState('camera');
+ * }
+ * ```
+ */
+export declare function permissionState(name: PermissionName, options?: PermissionStateOptions): Signal<PermissionState>;

package/browser/picture-in-picture/index.d.ts

@@ -2,15 +2,33 @@ import { type Signal } from '@angular/core';
 import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
 export type PictureInPictureOptions = WithInjector;
 export interface PictureInPictureRef {
-    /** Whether Picture-in-Picture API is supported */
+    /**
+     * Whether the Picture-in-Picture API is supported in the current browser.
+     *
+     * @see [Picture-in-Picture API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether Picture-in-Picture is active */
+    /**
+     * Whether the target video element is currently displayed in Picture-in-Picture mode.
+     *
+     * @see [Document: pictureInPictureElement on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/pictureInPictureElement)
+     */
     readonly isActive: Signal<boolean>;
-    /** Enter Picture-in-Picture mode */
+    /**
+     * Enter Picture-in-Picture mode for the target video element.
+     *
+     * @see [HTMLVideoElement: requestPictureInPicture() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestPictureInPicture)
+     */
     readonly enter: () => Promise<void>;
-    /** Exit Picture-in-Picture mode */
+    /**
+     * Exit Picture-in-Picture mode.
+     *
+     * @see [Document: exitPictureInPicture() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/exitPictureInPicture)
+     */
     readonly exit: () => Promise<void>;
-    /** Toggle Picture-in-Picture mode */
+    /**
+     * Toggle Picture-in-Picture mode — enters if inactive, exits if active.
+     */
     readonly toggle: () => Promise<void>;
 }
 /**
@@ -33,7 +51,7 @@ export interface PictureInPictureRef {
  *     }
  *   `
  * })
- * class PiPComponent {
+ * export class PiPDemo {
  *   readonly video = viewChild<HTMLVideoElement>('video');
  *   readonly pip = pictureInPicture(this.video);
  * }

package/browser/screen-orientation/index.d.ts

@@ -21,7 +21,7 @@ export interface ScreenOrientationOptions extends CreateSignalOptions<Orientatio
  *     <p>Orientation: {{ orientation() }}</p>
  *   `
  * })
- * class OrientationComponent {
+ * export class OrientationDemo {
  *   readonly orientation = screenOrientation();
  * }
  * ```

package/browser/speech-recognition/index.d.ts

@@ -2,42 +2,80 @@ import { type Signal } from '@angular/core';
 import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface SpeechRecognitionOptions extends WithInjector {
     /**
-     * Language for speech recognition.
+     * BCP 47 language tag for recognition (e.g. `'en-US'`).
+     *
      * @default 'en-US'
+     * @see [SpeechRecognition: lang on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/lang)
      */
     readonly lang?: MaybeSignal<string>;
     /**
-     * Whether to return interim results.
+     * Whether to return interim (in-progress) results alongside final ones.
+     *
      * @default false
+     * @see [SpeechRecognition: interimResults on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/interimResults)
      */
     readonly interimResults?: boolean;
     /**
-     * Whether to continue recognition after speech ends.
+     * Whether recognition continues after the user stops speaking.
+     *
      * @default false
+     * @see [SpeechRecognition: continuous on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/continuous)
      */
     readonly continuous?: boolean;
     /**
-     * Maximum number of alternative transcripts.
+     * Maximum number of alternative recognition results per utterance.
+     *
      * @default 1
+     * @see [SpeechRecognition: maxAlternatives on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/maxAlternatives)
      */
     readonly maxAlternatives?: number;
 }
 export interface SpeechRecognitionRef {
-    /** Whether Speech Recognition API is supported */
+    /**
+     * Whether the Speech Recognition API is supported in the current browser.
+     *
+     * @see [SpeechRecognition browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether recognition is currently active */
+    /**
+     * Whether speech recognition is currently active and listening.
+     */
     readonly isListening: Signal<boolean>;
-    /** Final transcript text */
+    /**
+     * Accumulated final transcript text.
+     *
+     * @see [SpeechRecognitionResult on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionResult)
+     */
     readonly text: Signal<string>;
-    /** Interim transcript text */
+    /**
+     * In-progress interim transcript. Only populated when `interimResults` is `true`.
+     *
+     * @see [SpeechRecognition: interimResults on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/interimResults)
+     */
     readonly interimText: Signal<string>;
-    /** Error if recognition failed */
+    /**
+     * The last recognition error, or `null` if no error occurred.
+     *
+     * @see [SpeechRecognitionErrorEvent on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionErrorEvent)
+     */
     readonly error: Signal<SpeechRecognitionErrorEvent | Error | null>;
-    /** Start speech recognition */
+    /**
+     * Start listening for speech input.
+     *
+     * @see [SpeechRecognition: start() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/start)
+     */
     readonly start: () => void;
-    /** Stop speech recognition */
+    /**
+     * Stop listening and return any remaining results.
+     *
+     * @see [SpeechRecognition: stop() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/stop)
+     */
     readonly stop: () => void;
-    /** Abort speech recognition */
+    /**
+     * Abort recognition immediately without returning results.
+     *
+     * @see [SpeechRecognition: abort() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/abort)
+     */
     readonly abort: () => void;
 }
 /**
@@ -61,7 +99,7 @@ export interface SpeechRecognitionRef {
  *     }
  *   `
  * })
- * class SpeechComponent {
+ * export class SpeechComponent {
  *   readonly recognition = speechRecognition();
  *
  *   toggleRecognition() {

package/browser/speech-synthesis/index.d.ts

@@ -1,49 +1,93 @@
 import { type Signal } from '@angular/core';
-import type { WithInjector } from '@signality/core/types';
-export interface SpeechSynthesisSpeakOptions {
-    /** Text to speak */
-    readonly text: string;
-    /** Language code (e.g., 'en-US') */
-    readonly lang?: string;
-    /** Speech rate (0.1 to 10) */
-    readonly rate?: number;
-    /** Speech pitch (0 to 2) */
-    readonly pitch?: number;
-    /** Speech volume (0 to 1) */
-    readonly volume?: number;
-    /** Voice to use */
-    readonly voice?: SpeechSynthesisVoice;
-}
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface SpeechSynthesisOptions extends WithInjector {
-    /** Default language */
-    readonly lang?: string;
-    /** Default speech rate */
-    readonly rate?: number;
-    /** Default pitch */
-    readonly pitch?: number;
-    /** Default volume */
-    readonly volume?: number;
-    /** Default voice */
-    readonly voice?: SpeechSynthesisVoice;
+    /**
+     * BCP 47 language tag (e.g. `'en-US'`). Supports reactive values.
+     *
+     * @see [SpeechSynthesisUtterance: lang on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/lang)
+     */
+    readonly lang?: MaybeSignal<string>;
+    /**
+     * Speech rate from `0.1` to `10`. Supports reactive values.
+     *
+     * @default 1
+     * @see [SpeechSynthesisUtterance: rate on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/rate)
+     */
+    readonly rate?: MaybeSignal<number>;
+    /**
+     * Speech pitch from `0` to `2`. Supports reactive values.
+     *
+     * @default 1
+     * @see [SpeechSynthesisUtterance: pitch on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/pitch)
+     */
+    readonly pitch?: MaybeSignal<number>;
+    /**
+     * Speech volume from `0` to `1`. Supports reactive values.
+     *
+     * @default 1
+     * @see [SpeechSynthesisUtterance: volume on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/volume)
+     */
+    readonly volume?: MaybeSignal<number>;
+    /**
+     * Voice to use for synthesis. Supports reactive values.
+     *
+     * @see [SpeechSynthesisUtterance: voice on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesisUtterance/voice)
+     */
+    readonly voice?: MaybeSignal<SpeechSynthesisVoice>;
 }
 export interface SpeechSynthesisRef {
-    /** Whether Speech Synthesis API is supported */
+    /**
+     * Whether the Speech Synthesis API is supported in the current browser.
+     *
+     * @see [SpeechSynthesis browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether speech is currently playing */
+    /**
+     * Whether speech is currently being synthesized.
+     *
+     * @see [SpeechSynthesis: speaking on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/speaking)
+     */
     readonly isSpeaking: Signal<boolean>;
-    /** Whether speech is currently paused */
+    /**
+     * Whether speech synthesis is currently paused.
+     *
+     * @see [SpeechSynthesis: paused on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/paused)
+     */
     readonly isPaused: Signal<boolean>;
-    /** Available voices */
+    /**
+     * List of available synthesis voices for the current device and browser.
+     *
+     * @see [SpeechSynthesis: getVoices() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/getVoices)
+     */
     readonly voices: Signal<SpeechSynthesisVoice[]>;
-    /** Current speaking text */
+    /**
+     * The text currently being spoken, or `''` if idle.
+     */
     readonly currentText: Signal<string>;
-    /** Speak text */
-    readonly speak: (text: string, options?: Partial<SpeechSynthesisSpeakOptions>) => void;
-    /** Stop speaking */
+    /**
+     * Speak the given text, cancelling any ongoing utterance.
+     * Reads current reactive option values (`lang`, `rate`, `pitch`, `volume`, `voice`) at call time.
+     *
+     * @see [SpeechSynthesis: speak() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/speak)
+     */
+    readonly speak: (text: string) => void;
+    /**
+     * Cancel and stop the current utterance.
+     *
+     * @see [SpeechSynthesis: cancel() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/cancel)
+     */
     readonly stop: () => void;
-    /** Pause speaking */
+    /**
+     * Pause the current utterance.
+     *
+     * @see [SpeechSynthesis: pause() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/pause)
+     */
     readonly pause: () => void;
-    /** Resume speaking */
+    /**
+     * Resume a paused utterance.
+     *
+     * @see [SpeechSynthesis: resume() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis/resume)
+     */
     readonly resume: () => void;
 }
 /**
@@ -57,19 +101,15 @@ export interface SpeechSynthesisRef {
  * @Component({
  *   template: `
  *     @if (synthesis.isSupported()) {
- *       <button (click)="speakText()" [disabled]="synthesis.isSpeaking()">
+ *       <button (click)="synthesis.speak('Hello, world!')" [disabled]="synthesis.isSpeaking()">
  *         {{ synthesis.isSpeaking() ? 'Speaking...' : 'Speak' }}
  *       </button>
  *       <button (click)="synthesis.stop()">Stop</button>
  *     }
  *   `
  * })
- * class TextToSpeechComponent {
- *   readonly synthesis = speechSynthesis();
- *
- *   speakText() {
- *     this.synthesis.speak('Hello, world!');
- *   }
+ * export class TextToSpeechDemo {
+ *   readonly synthesis = speechSynthesis({ rate: 1.5 });
  * }
  * ```
  */

package/browser/storage/index.d.ts

@@ -85,7 +85,7 @@ export interface Serializer<T> {
  *     <button (click)="count.set(count() + 1)">Increment</button>
  *   '
  * })
- * class UserComponent {
+ * export class UserPreview {
  *   readonly username = storage('username', '');
  *   readonly count = storage('counter', 0); // number serialization inferred
  *   readonly lastVisit = storage('lastVisit', new Date()); // Date serialization inferred