@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-speech-recognition.d.mts

@@ -0,0 +1,150 @@
+import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-speech-recognition.d.ts
+/** One recognition hypothesis. */
+interface SpeechRecognitionAlternativeLike {
+  /** Recognized text. */
+  readonly transcript: string;
+  /** Confidence between 0 and 1. */
+  readonly confidence: number;
+}
+/** One recognition result: an array-like list of alternatives. */
+interface SpeechRecognitionResultLike {
+  /** Number of alternatives. */
+  readonly length: number;
+  /** Whether the result is final (no longer interim). */
+  readonly isFinal: boolean;
+  /** Alternative at `index`, most likely first. */
+  readonly [index: number]: SpeechRecognitionAlternativeLike;
+}
+/** Array-like list of every result of the current session. */
+interface SpeechRecognitionResultListLike {
+  /** Number of results. */
+  readonly length: number;
+  /** Result at `index`. */
+  readonly [index: number]: SpeechRecognitionResultLike;
+}
+/** Minimal `SpeechRecognition` instance consumed by {@link useSpeechRecognition}. */
+interface SpeechRecognitionLike extends EventTarget {
+  /** BCP 47 language tag. */
+  lang: string;
+  /** Keep listening after the first final result. */
+  continuous: boolean;
+  /** Report interim (non-final) results. */
+  interimResults: boolean;
+  /** Maximum alternatives per result. */
+  maxAlternatives: number;
+  /** Start listening. Throws `InvalidStateError` when already started. */
+  start(): void;
+  /** Stop listening and deliver a final result. */
+  stop(): void;
+  /** Stop listening without delivering a result. */
+  abort(): void;
+}
+/** Minimal `SpeechRecognition` constructor. */
+interface SpeechRecognitionHost {
+  /** Create a recognizer. */
+  new (): SpeechRecognitionLike;
+}
+/** Error codes defined by the Web Speech API, plus `"unknown"` for future codes. */
+type SpeechRecognitionErrorCode = "aborted" | "audio-capture" | "bad-grammar" | "language-not-supported" | "network" | "no-speech" | "not-allowed" | "phrases-not-supported" | "service-not-allowed" | "unknown";
+/** Recognition failure reported by {@link useSpeechRecognition}. */
+interface SpeechRecognitionFailure {
+  /** Normalized error code. */
+  readonly code: SpeechRecognitionErrorCode;
+  /** Implementation-provided message, possibly empty. */
+  readonly message: string;
+}
+/** Options for {@link useSpeechRecognition}. */
+interface UseSpeechRecognitionOptions {
+  /**
+   * Recognition language, applied when listening starts.
+   *
+   * @default "en-US"
+   */
+  readonly lang?: MaybeRefOrGetter<string>;
+  /**
+   * Keep listening after the first final result.
+   *
+   * @default true
+   */
+  readonly continuous?: boolean;
+  /**
+   * Report interim results through `interimResult`.
+   *
+   * @default true
+   */
+  readonly interimResults?: boolean;
+  /**
+   * Maximum alternatives per result.
+   *
+   * @default 1
+   */
+  readonly maxAlternatives?: number;
+  /**
+   * Recognizer constructor for alternate runtimes and tests. A ref (not a
+   * getter) because the host itself is a constructor function.
+   *
+   * @default window.SpeechRecognition ?? window.webkitSpeechRecognition
+   */
+  readonly host?: MaybeRef<SpeechRecognitionHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useSpeechRecognition}. */
+interface SpeechRecognitionControls {
+  /** Whether a speech recognizer is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Whether the recognizer is listening. */
+  readonly listening: Readonly<Ref<boolean>>;
+  /** Concatenated final transcript of the current session. */
+  readonly result: Readonly<Ref<string>>;
+  /** Concatenated interim transcript not yet final. */
+  readonly interimResult: Readonly<Ref<string>>;
+  /** Alternatives of the most recent result. */
+  readonly alternatives: Readonly<ShallowRef<readonly SpeechRecognitionAlternativeLike[]>>;
+  /** Most recent recognition failure, cleared when listening starts. */
+  readonly error: Readonly<ShallowRef<SpeechRecognitionFailure | undefined>>;
+  /**
+   * Start listening with the current options, clearing previous results.
+   *
+   * @returns Whether listening started.
+   */
+  readonly start: () => boolean;
+  /** Stop listening and keep the final result. */
+  readonly stop: () => void;
+  /** Stop listening immediately without a final result. */
+  readonly abort: () => void;
+  /**
+   * Start or stop listening.
+   *
+   * @param value Force listening on or off.
+   * @default value !listening
+   */
+  readonly toggle: (value?: boolean) => void;
+}
+/**
+ * Transcribe speech with the Web Speech API.
+ *
+ * `result` accumulates the final transcript of the current session and
+ * `interimResult` the text still being recognized. Options are applied each
+ * time listening starts, so a reactive `lang` takes effect on the next
+ * `start`. Errors are normalized to a closed {@link SpeechRecognitionErrorCode}
+ * union and exposed through `error` rather than thrown. The recognizer is
+ * aborted and its listeners removed when the owning reactive scope stops.
+ *
+ * Server rendering: no recognizer is created; `supported` and `listening`
+ * are false and the transcripts are empty.
+ *
+ * @example
+ * ```ts
+ * const speech = useSpeechRecognition({ lang: "ja-JP" });
+ * speech.start();
+ * watch(speech.result, (text) => console.log(text));
+ * ```
+ *
+ * @param options Recognition settings and recognizer constructor.
+ * @default options {}
+ * @returns Recognition state and actions.
+ */
+declare function useSpeechRecognition(options?: UseSpeechRecognitionOptions): SpeechRecognitionControls;
+//#endregion
+export { SpeechRecognitionAlternativeLike, SpeechRecognitionControls, SpeechRecognitionErrorCode, SpeechRecognitionFailure, SpeechRecognitionHost, SpeechRecognitionLike, SpeechRecognitionResultLike, SpeechRecognitionResultListLike, UseSpeechRecognitionOptions, useSpeechRecognition };

package/dist/use-speech-recognition.mjs

@@ -0,0 +1,168 @@
+import { computed, readonly, ref, shallowRef, toValue, unref, watch } from "vue";
+//#region src/use-speech-recognition.ts
+const errorCodes = new Set([
+	"aborted",
+	"audio-capture",
+	"bad-grammar",
+	"language-not-supported",
+	"network",
+	"no-speech",
+	"not-allowed",
+	"phrases-not-supported",
+	"service-not-allowed"
+]);
+function isErrorCode(code) {
+	return errorCodes.has(code);
+}
+function isRecognitionConstructor(candidate) {
+	return typeof candidate === "function";
+}
+function browserRecognitionHost() {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window, "SpeechRecognition") ?? Reflect.get(window, "webkitSpeechRecognition");
+	return isRecognitionConstructor(candidate) ? candidate : void 0;
+}
+function isResultEvent(event) {
+	if (!("results" in event)) return false;
+	const { results } = event;
+	return typeof results === "object" && results !== null && "length" in results;
+}
+function readString(event, key) {
+	const value = key in event ? Reflect.get(event, key) : void 0;
+	return typeof value === "string" ? value : "";
+}
+/**
+* Transcribe speech with the Web Speech API.
+*
+* `result` accumulates the final transcript of the current session and
+* `interimResult` the text still being recognized. Options are applied each
+* time listening starts, so a reactive `lang` takes effect on the next
+* `start`. Errors are normalized to a closed {@link SpeechRecognitionErrorCode}
+* union and exposed through `error` rather than thrown. The recognizer is
+* aborted and its listeners removed when the owning reactive scope stops.
+*
+* Server rendering: no recognizer is created; `supported` and `listening`
+* are false and the transcripts are empty.
+*
+* @example
+* ```ts
+* const speech = useSpeechRecognition({ lang: "ja-JP" });
+* speech.start();
+* watch(speech.result, (text) => console.log(text));
+* ```
+*
+* @param options Recognition settings and recognizer constructor.
+* @default options {}
+* @returns Recognition state and actions.
+*/
+function useSpeechRecognition(options = {}) {
+	const listening = ref(false);
+	const result = ref("");
+	const interimResult = ref("");
+	const alternatives = shallowRef([]);
+	const error = shallowRef(void 0);
+	let recognition;
+	const resolveHost = () => options.host === void 0 ? browserRecognitionHost() : unref(options.host) ?? void 0;
+	const onResult = (event) => {
+		if (!isResultEvent(event)) return;
+		const finals = [];
+		const interim = [];
+		let last;
+		for (let index = 0; index < event.results.length; index += 1) {
+			const entry = event.results[index];
+			if (!entry) continue;
+			last = entry;
+			const best = entry[0];
+			if (best) (entry.isFinal ? finals : interim).push(best.transcript);
+		}
+		result.value = finals.join("");
+		interimResult.value = interim.join("");
+		const collected = [];
+		for (let index = 0; last && index < last.length; index += 1) {
+			const alternative = last[index];
+			if (alternative) collected.push(alternative);
+		}
+		alternatives.value = collected;
+	};
+	const onError = (event) => {
+		const code = readString(event, "error");
+		error.value = {
+			code: isErrorCode(code) ? code : "unknown",
+			message: readString(event, "message")
+		};
+	};
+	const onStart = () => {
+		listening.value = true;
+	};
+	const onEnd = () => {
+		listening.value = false;
+		interimResult.value = "";
+	};
+	watch(resolveHost, (Host, _previous, onCleanup) => {
+		listening.value = false;
+		recognition = void 0;
+		if (!Host) return;
+		const instance = new Host();
+		instance.addEventListener("result", onResult);
+		instance.addEventListener("error", onError);
+		instance.addEventListener("start", onStart);
+		instance.addEventListener("end", onEnd);
+		recognition = instance;
+		onCleanup(() => {
+			instance.removeEventListener("result", onResult);
+			instance.removeEventListener("error", onError);
+			instance.removeEventListener("start", onStart);
+			instance.removeEventListener("end", onEnd);
+			if (listening.value) instance.abort();
+			listening.value = false;
+			if (recognition === instance) recognition = void 0;
+		});
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const start = () => {
+		const instance = recognition;
+		if (!instance || listening.value) return listening.value;
+		instance.lang = toValue(options.lang) ?? "en-US";
+		instance.continuous = options.continuous ?? true;
+		instance.interimResults = options.interimResults ?? true;
+		instance.maxAlternatives = options.maxAlternatives ?? 1;
+		result.value = "";
+		interimResult.value = "";
+		alternatives.value = [];
+		error.value = void 0;
+		try {
+			instance.start();
+		} catch {
+			return false;
+		}
+		listening.value = true;
+		return true;
+	};
+	const stop = () => {
+		recognition?.stop();
+	};
+	const abort = () => {
+		recognition?.abort();
+		listening.value = false;
+	};
+	const toggle = (value = !listening.value) => {
+		if (value) start();
+		else stop();
+	};
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		listening: readonly(listening),
+		result: readonly(result),
+		interimResult: readonly(interimResult),
+		alternatives,
+		error,
+		start,
+		stop,
+		abort,
+		toggle
+	};
+}
+//#endregion
+export { useSpeechRecognition };

package/dist/use-speech-synthesis.d.mts

@@ -0,0 +1,148 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-speech-synthesis.d.ts
+/** Minimal `SpeechSynthesisVoice`. */
+interface SpeechSynthesisVoiceLike {
+  /** Human-readable voice name. */
+  readonly name: string;
+  /** BCP 47 language tag. */
+  readonly lang: string;
+  /** Stable voice identifier. */
+  readonly voiceURI: string;
+  /** Whether synthesis runs locally. */
+  readonly localService: boolean;
+  /** Whether this is the platform default voice. */
+  readonly default: boolean;
+}
+/** Minimal `SpeechSynthesisUtterance`. */
+interface SpeechSynthesisUtteranceLike extends EventTarget {
+  /** Text to speak. */
+  text: string;
+  /** BCP 47 language tag. */
+  lang: string;
+  /** Pitch from 0 to 2. */
+  pitch: number;
+  /** Rate from 0.1 to 10. */
+  rate: number;
+  /** Volume from 0 to 1. */
+  volume: number;
+  /** Voice, or `null` for the platform default. */
+  voice: SpeechSynthesisVoiceLike | null;
+}
+/** Minimal `speechSynthesis` controller. */
+interface SpeechSynthesisLike extends EventTarget {
+  /** Queue an utterance. */
+  speak(utterance: SpeechSynthesisUtteranceLike): void;
+  /** Clear the queue and stop speaking. */
+  cancel(): void;
+  /** Pause speaking. */
+  pause(): void;
+  /** Resume speaking. */
+  resume(): void;
+  /** Voices available right now (may be empty until `voiceschanged`). */
+  getVoices(): readonly SpeechSynthesisVoiceLike[];
+}
+/** Capabilities used by {@link useSpeechSynthesis}. */
+interface SpeechSynthesisHost {
+  /** Synthesis controller (`window.speechSynthesis`). */
+  readonly synthesis: SpeechSynthesisLike;
+  /** Utterance constructor (`window.SpeechSynthesisUtterance`). */
+  readonly Utterance: new (text?: string) => SpeechSynthesisUtteranceLike;
+}
+/** Playback state of {@link useSpeechSynthesis}. */
+type SpeechSynthesisStatus = "idle" | "speaking" | "paused" | "ended" | "error";
+/** Error codes defined by the Web Speech API, plus `"unknown"` for future codes. */
+type SpeechSynthesisErrorCode = "audio-busy" | "audio-hardware" | "invalid-argument" | "language-unavailable" | "network" | "not-allowed" | "synthesis-failed" | "synthesis-unavailable" | "text-too-long" | "voice-unavailable" | "unknown";
+/** Options for {@link useSpeechSynthesis}. */
+interface UseSpeechSynthesisOptions {
+  /**
+   * BCP 47 language tag.
+   *
+   * @default "en-US"
+   */
+  readonly lang?: MaybeRefOrGetter<string>;
+  /**
+   * Pitch from 0 to 2.
+   *
+   * @default 1
+   */
+  readonly pitch?: MaybeRefOrGetter<number>;
+  /**
+   * Rate from 0.1 to 10.
+   *
+   * @default 1
+   */
+  readonly rate?: MaybeRefOrGetter<number>;
+  /**
+   * Volume from 0 to 1.
+   *
+   * @default 1
+   */
+  readonly volume?: MaybeRefOrGetter<number>;
+  /**
+   * Voice to use; `undefined` uses the platform default for `lang`.
+   *
+   * @default undefined
+   */
+  readonly voice?: MaybeRefOrGetter<SpeechSynthesisVoiceLike | undefined>;
+  /**
+   * Synthesis capabilities for alternate runtimes and tests.
+   *
+   * @default window.speechSynthesis and window.SpeechSynthesisUtterance
+   */
+  readonly host?: MaybeRefOrGetter<SpeechSynthesisHost | null | undefined>;
+}
+/** Reactive state and actions returned by {@link useSpeechSynthesis}. */
+interface SpeechSynthesisControls {
+  /** Whether speech synthesis is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Playback state of the utterance spoken by this composable. */
+  readonly status: Readonly<Ref<SpeechSynthesisStatus>>;
+  /** Voices offered by the platform, updated on `voiceschanged`. */
+  readonly voices: Readonly<ShallowRef<readonly SpeechSynthesisVoiceLike[]>>;
+  /** Most recent synthesis error, cleared by the next `speak`. */
+  readonly error: Readonly<ShallowRef<SpeechSynthesisErrorCode | undefined>>;
+  /**
+   * Speak the current text, cancelling anything this composable is speaking.
+   *
+   * @returns Whether an utterance was queued.
+   * @throws {RangeError} `[VIZE_COMPOSE_SPEECH_SYNTHESIS_INVALID_OPTION]` when
+   * pitch, rate, or volume is out of range.
+   */
+  readonly speak: () => boolean;
+  /** Pause speaking. */
+  readonly pause: () => void;
+  /** Resume paused speech. */
+  readonly resume: () => void;
+  /** Stop speaking and clear the queue. */
+  readonly cancel: () => void;
+}
+/**
+ * Speak text with the Web Speech API.
+ *
+ * Each `speak` creates a fresh utterance from the current reactive text,
+ * language, voice, pitch, rate, and volume (validated ranges), and cancels
+ * speech previously started by this composable. `status` follows the
+ * utterance lifecycle; interruptions caused by `cancel` return to `"idle"`
+ * instead of reporting an error. The available voices are kept current via
+ * `voiceschanged`. Speech started by this composable is cancelled and the
+ * listener removed when the owning reactive scope stops.
+ *
+ * Server rendering: nothing is spoken; `supported` is false, `status` is
+ * `"idle"`, and `voices` is empty.
+ *
+ * @example
+ * ```ts
+ * const text = ref("Hello, Vize");
+ * const { speak, status } = useSpeechSynthesis(text, { rate: 1.2 });
+ * speak();
+ * ```
+ *
+ * @param text Reactive text to speak.
+ * @param options Voice parameters and synthesis capabilities.
+ * @default options {}
+ * @returns Synthesis state and actions.
+ */
+declare function useSpeechSynthesis(text: MaybeRefOrGetter<string>, options?: UseSpeechSynthesisOptions): SpeechSynthesisControls;
+//#endregion
+export { SpeechSynthesisControls, SpeechSynthesisErrorCode, SpeechSynthesisHost, SpeechSynthesisLike, SpeechSynthesisStatus, SpeechSynthesisUtteranceLike, SpeechSynthesisVoiceLike, UseSpeechSynthesisOptions, useSpeechSynthesis };

package/dist/use-speech-synthesis.mjs

@@ -0,0 +1,152 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, readonly, ref, shallowRef, toValue, watch } from "vue";
+//#region src/use-speech-synthesis.ts
+const synthesisErrorCodes = new Set([
+	"audio-busy",
+	"audio-hardware",
+	"invalid-argument",
+	"language-unavailable",
+	"network",
+	"not-allowed",
+	"synthesis-failed",
+	"synthesis-unavailable",
+	"text-too-long",
+	"voice-unavailable"
+]);
+function isSynthesisErrorCode(code) {
+	return synthesisErrorCodes.has(code);
+}
+function browserSynthesisHost() {
+	if (typeof window === "undefined") return void 0;
+	if (!("speechSynthesis" in window) || !("SpeechSynthesisUtterance" in window)) return void 0;
+	return {
+		synthesis: window.speechSynthesis,
+		Utterance: window.SpeechSynthesisUtterance
+	};
+}
+function checkedRange(name, value, minimum, maximum) {
+	if (!Number.isFinite(value) || value < minimum || value > maximum) throw new RangeError(`[VIZE_COMPOSE_SPEECH_SYNTHESIS_INVALID_OPTION] ${name} must be between ${String(minimum)} and ${String(maximum)}; received ${String(value)}`);
+	return value;
+}
+/**
+* Speak text with the Web Speech API.
+*
+* Each `speak` creates a fresh utterance from the current reactive text,
+* language, voice, pitch, rate, and volume (validated ranges), and cancels
+* speech previously started by this composable. `status` follows the
+* utterance lifecycle; interruptions caused by `cancel` return to `"idle"`
+* instead of reporting an error. The available voices are kept current via
+* `voiceschanged`. Speech started by this composable is cancelled and the
+* listener removed when the owning reactive scope stops.
+*
+* Server rendering: nothing is spoken; `supported` is false, `status` is
+* `"idle"`, and `voices` is empty.
+*
+* @example
+* ```ts
+* const text = ref("Hello, Vize");
+* const { speak, status } = useSpeechSynthesis(text, { rate: 1.2 });
+* speak();
+* ```
+*
+* @param text Reactive text to speak.
+* @param options Voice parameters and synthesis capabilities.
+* @default options {}
+* @returns Synthesis state and actions.
+*/
+function useSpeechSynthesis(text, options = {}) {
+	const status = ref("idle");
+	const voices = shallowRef([]);
+	const error = shallowRef(void 0);
+	let current;
+	const resolveHost = () => options.host === void 0 ? browserSynthesisHost() : toValue(options.host) ?? void 0;
+	const readParameters = () => ({
+		pitch: checkedRange("pitch", toValue(options.pitch) ?? 1, 0, 2),
+		rate: checkedRange("rate", toValue(options.rate) ?? 1, .1, 10),
+		volume: checkedRange("volume", toValue(options.volume) ?? 1, 0, 1)
+	});
+	readParameters();
+	watch(() => resolveHost()?.synthesis, (synthesis, _previous, onCleanup) => {
+		voices.value = [];
+		if (!synthesis) return;
+		const update = () => {
+			voices.value = [...synthesis.getVoices()];
+		};
+		update();
+		synthesis.addEventListener("voiceschanged", update);
+		onCleanup(() => synthesis.removeEventListener("voiceschanged", update));
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	const cancel = () => {
+		const host = resolveHost();
+		const active = current;
+		current = void 0;
+		if (host && active) host.synthesis.cancel();
+		status.value = "idle";
+	};
+	const speak = () => {
+		const host = resolveHost();
+		const parameters = readParameters();
+		if (!host) return false;
+		if (current) cancel();
+		const utterance = new host.Utterance(toValue(text));
+		utterance.lang = toValue(options.lang) ?? "en-US";
+		utterance.pitch = parameters.pitch;
+		utterance.rate = parameters.rate;
+		utterance.volume = parameters.volume;
+		utterance.voice = toValue(options.voice) ?? null;
+		const own = () => current === utterance;
+		utterance.addEventListener("start", () => {
+			if (own()) status.value = "speaking";
+		});
+		utterance.addEventListener("pause", () => {
+			if (own()) status.value = "paused";
+		});
+		utterance.addEventListener("resume", () => {
+			if (own()) status.value = "speaking";
+		});
+		utterance.addEventListener("end", () => {
+			if (!own()) return;
+			current = void 0;
+			status.value = "ended";
+		});
+		utterance.addEventListener("error", (event) => {
+			if (!own()) return;
+			current = void 0;
+			const code = "error" in event ? event.error : void 0;
+			if (code === "canceled" || code === "interrupted") {
+				status.value = "idle";
+				return;
+			}
+			error.value = typeof code === "string" && isSynthesisErrorCode(code) ? code : "unknown";
+			status.value = "error";
+		});
+		error.value = void 0;
+		current = utterance;
+		host.synthesis.speak(utterance);
+		return true;
+	};
+	const pause = () => {
+		if (current) resolveHost()?.synthesis.pause();
+	};
+	const resume = () => {
+		if (current) resolveHost()?.synthesis.resume();
+	};
+	tryOnScopeDispose(() => {
+		if (current) cancel();
+	});
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		status: readonly(status),
+		voices,
+		error,
+		speak,
+		pause,
+		resume,
+		cancel
+	};
+}
+//#endregion
+export { useSpeechSynthesis };

package/dist/use-stack.d.mts

@@ -0,0 +1,83 @@
+import { ComputedRef } from "vue";
+
+//#region src/use-stack.d.ts
+/** What happens when an item is pushed while a bounded stack is full. */
+type StackOverflowPolicy = "drop-oldest" | "reject";
+/** Options for {@link useStack}. */
+interface UseStackOptions {
+  /**
+   * Maximum number of stacked items. A positive integer, or
+   * `Number.POSITIVE_INFINITY` for an unbounded stack.
+   *
+   * @default Number.POSITIVE_INFINITY
+   */
+  readonly capacity?: number;
+  /**
+   * Policy applied when an item is pushed at capacity: `"drop-oldest"`
+   * discards the bottom item to make room, `"reject"` refuses the new item.
+   *
+   * @default "drop-oldest"
+   */
+  readonly overflow?: StackOverflowPolicy;
+}
+/** Reactive last-in, first-out stack returned by {@link useStack}. */
+interface StackControls<Item> {
+  /** Snapshot of the stacked items, bottom first (the top is the last element). */
+  readonly items: ComputedRef<readonly Item[]>;
+  /** Number of stacked items. */
+  readonly size: ComputedRef<number>;
+  /** Whether the stack holds no items. */
+  readonly isEmpty: ComputedRef<boolean>;
+  /**
+   * Read the top without removing it. Reactive when read inside an effect.
+   *
+   * @returns The top item, or `undefined` when empty.
+   */
+  readonly peek: () => Item | undefined;
+  /**
+   * Push items in argument order (the last argument ends on top), applying
+   * the overflow policy.
+   *
+   * @param items Items to push.
+   * @returns How many of the given items were accepted.
+   */
+  readonly push: (...items: Item[]) => number;
+  /**
+   * Remove and return the top.
+   *
+   * @returns The removed item, or `undefined` when empty.
+   */
+  readonly pop: () => Item | undefined;
+  /** Remove every item. */
+  readonly clear: () => void;
+}
+/**
+ * Create a typed reactive LIFO stack.
+ *
+ * `push` and `pop` are O(1). A bounded stack either drops its bottom item
+ * or rejects new pushes when full. Reactivity is driven by a version
+ * counter, so `items`, `size`, `isEmpty`, and `peek` re-evaluate after
+ * every mutation.
+ *
+ * Purely synchronous state: safe during server rendering (no host globals,
+ * no timers) and nothing to dispose.
+ *
+ * @example
+ * ```ts
+ * const breadcrumbs = useStack<string>(["home"]);
+ * breadcrumbs.push("settings");
+ * breadcrumbs.pop(); // "settings"
+ * ```
+ *
+ * @typeParam Item Stacked item type, inferred from `initial` when given.
+ * @param initial Items pushed at creation, bottom first (overflow applies).
+ * @param options Capacity and overflow policy.
+ * @default initial []
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_STACK_INVALID_CAPACITY]` when `capacity`
+ * is not a positive integer or `Infinity`.
+ * @returns The reactive stack and its controls.
+ */
+declare function useStack<Item>(initial?: Iterable<Item>, options?: UseStackOptions): StackControls<Item>;
+//#endregion
+export { StackControls, StackOverflowPolicy, UseStackOptions, useStack };