@vizejs/composable 0.426.3 → 0.428.0

package/dist/use-builtin-ai.d.mts

@@ -0,0 +1,342 @@
+import { ComputedRef, MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-builtin-ai.d.ts
+/** Model availability reported by the built-in AI APIs. */
+type BuiltinAiAvailability = "unavailable" | "downloadable" | "downloading" | "available";
+/** Lifecycle of a built-in AI session owned by a composable. */
+type BuiltinAiStatus = "unsupported" | "idle" | "downloading" | "creating" | "ready" | "error";
+/** `downloadprogress` event: `loaded` is a fraction of `total` (usually 1). */
+interface BuiltinAiDownloadProgressEvent {
+  /** Downloaded amount. */
+  readonly loaded: number;
+  /** Total amount (1 in current browsers). */
+  readonly total?: number | undefined;
+}
+/** Monitor handed to the `monitor` callback of `create()`. */
+interface BuiltinAiMonitorLike {
+  /** Subscribe to model download progress. */
+  addEventListener(type: "downloadprogress", listener: (event: BuiltinAiDownloadProgressEvent) => void): void;
+}
+/** Options added by the composables to every `create()` call. */
+interface BuiltinAiCreateMonitorOptions {
+  /** Receives the download monitor. */
+  readonly monitor: (monitor: BuiltinAiMonitorLike) => void;
+  /** Aborts creation when the session is destroyed. */
+  readonly signal: AbortSignal;
+}
+/** Streaming output of a built-in AI call (a `ReadableStream<string>`). */
+type BuiltinAiTextStream = AsyncIterable<string> | {
+  /** Lock the stream and read chunks. */getReader(): {
+    /** Read the next chunk. */read(): Promise<{
+      readonly done: boolean;
+      readonly value?: string | undefined;
+    }>; /** Release the lock. */
+    releaseLock(): void;
+  };
+};
+/** Common state and actions of every built-in AI composable. */
+interface BuiltinAiSessionControls {
+  /** Whether the API's global constructor is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Session lifecycle. */
+  readonly status: ComputedRef<BuiltinAiStatus>;
+  /** Model download progress (0..1) during `create()`. */
+  readonly downloadProgress: Readonly<Ref<number>>;
+  /** Most recent failure, cleared by the next successful call. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Ask whether the model for the current options is usable.
+   *
+   * @returns The availability; `"unavailable"` when unsupported or on failure.
+   */
+  readonly availability: () => Promise<BuiltinAiAvailability>;
+  /**
+   * Create the session (downloading the model when needed). Browsers require
+   * a user gesture for a download. Operations create it lazily.
+   *
+   * @returns Whether the session is ready.
+   */
+  readonly create: () => Promise<boolean>;
+  /** Destroy the session and abort a pending creation. Repeated calls are safe. */
+  readonly destroy: () => void;
+}
+/** Minimal `Translator` instance. */
+interface TranslatorLike {
+  /** Translate `input`. */
+  translate(input: string): Promise<string>;
+  /** Translate `input`, streaming chunks. */
+  translateStreaming(input: string): BuiltinAiTextStream;
+  /** Release the session. */
+  destroy(): void;
+}
+/** Language pair of a translator. */
+interface TranslatorLanguages {
+  /** BCP 47 source language. */
+  readonly sourceLanguage: string;
+  /** BCP 47 target language. */
+  readonly targetLanguage: string;
+}
+/** Minimal global `Translator` class (static methods). */
+interface TranslatorHost {
+  /** Availability of a language pair. */
+  availability(options: TranslatorLanguages): Promise<BuiltinAiAvailability>;
+  /** Create a translator. */
+  create(options: TranslatorLanguages & BuiltinAiCreateMonitorOptions): Promise<TranslatorLike>;
+}
+/** Options for {@link useTranslator}. */
+interface UseTranslatorOptions {
+  /** BCP 47 source language; a change destroys the current session. */
+  readonly sourceLanguage: MaybeRefOrGetter<string>;
+  /** BCP 47 target language; a change destroys the current session. */
+  readonly targetLanguage: MaybeRefOrGetter<string>;
+  /**
+   * `Translator` class. A ref (not a getter) because the host is a class.
+   *
+   * @default window.Translator when it exists
+   */
+  readonly host?: MaybeRef<TranslatorHost | null | undefined>;
+}
+/** State and actions returned by {@link useTranslator}. */
+interface TranslatorControls extends BuiltinAiSessionControls {
+  /**
+   * Translate text, creating the session on first use. Rejects with a
+   * tagged `Error` when unsupported or with the host's failure.
+   *
+   * @param text Text to translate.
+   * @returns The translation.
+   */
+  readonly translate: (text: string) => Promise<string>;
+  /**
+   * Translate text as a stream of chunks.
+   *
+   * @param text Text to translate.
+   * @returns Async iterable of translated chunks.
+   */
+  readonly translateStreaming: (text: string) => AsyncIterable<string>;
+}
+/** One candidate returned by `LanguageDetector.detect`. */
+interface LanguageDetectionResult {
+  /** BCP 47 language tag (`"und"` for unknown). */
+  readonly detectedLanguage: string;
+  /** Confidence between 0 and 1. */
+  readonly confidence: number;
+}
+/** Minimal `LanguageDetector` instance. */
+interface LanguageDetectorLike {
+  /** Rank candidate languages for `input`. */
+  detect(input: string): Promise<readonly LanguageDetectionResult[]>;
+  /** Release the session. */
+  destroy(): void;
+}
+/** Creation options of a language detector. */
+interface LanguageDetectorCreateOptions {
+  /**
+   * Languages the input is expected to be in.
+   *
+   * @default undefined
+   */
+  readonly expectedInputLanguages?: readonly string[];
+}
+/** Minimal global `LanguageDetector` class (static methods). */
+interface LanguageDetectorHost {
+  /** Availability of the detector. */
+  availability(options: LanguageDetectorCreateOptions): Promise<BuiltinAiAvailability>;
+  /** Create a detector. */
+  create(options: LanguageDetectorCreateOptions & BuiltinAiCreateMonitorOptions): Promise<LanguageDetectorLike>;
+}
+/** Options for {@link useLanguageDetector}. */
+interface UseLanguageDetectorOptions {
+  /**
+   * Languages the input is expected to be in; a change destroys the session.
+   *
+   * @default undefined
+   */
+  readonly expectedInputLanguages?: MaybeRefOrGetter<readonly string[] | undefined>;
+  /**
+   * `LanguageDetector` class.
+   *
+   * @default window.LanguageDetector when it exists
+   */
+  readonly host?: MaybeRef<LanguageDetectorHost | null | undefined>;
+}
+/** State and actions returned by {@link useLanguageDetector}. */
+interface LanguageDetectorControls extends BuiltinAiSessionControls {
+  /**
+   * Detect the language of text, creating the session on first use.
+   *
+   * @param text Text to inspect.
+   * @returns Candidates ordered by confidence.
+   */
+  readonly detect: (text: string) => Promise<readonly LanguageDetectionResult[]>;
+}
+/** Summary kinds. */
+type SummarizerType = "tldr" | "teaser" | "key-points" | "headline";
+/** Summary output formats. */
+type SummarizerFormat = "plain-text" | "markdown";
+/** Summary lengths. */
+type SummarizerLength = "short" | "medium" | "long";
+/** Creation options of a summarizer. */
+interface SummarizerCreateOptions {
+  /** Summary kind. */
+  readonly type: SummarizerType;
+  /** Output format. */
+  readonly format: SummarizerFormat;
+  /** Output length. */
+  readonly length: SummarizerLength;
+  /**
+   * Background shared by every summary.
+   *
+   * @default undefined
+   */
+  readonly sharedContext?: string;
+}
+/** Per-call options of `summarize`. */
+interface SummarizeCallOptions {
+  /**
+   * Background for this input only.
+   *
+   * @default undefined
+   */
+  readonly context?: string;
+}
+/** Minimal `Summarizer` instance. */
+interface SummarizerLike {
+  /** Summarize `input`. */
+  summarize(input: string, options?: SummarizeCallOptions): Promise<string>;
+  /** Summarize `input`, streaming chunks. */
+  summarizeStreaming(input: string, options?: SummarizeCallOptions): BuiltinAiTextStream;
+  /** Release the session. */
+  destroy(): void;
+}
+/** Minimal global `Summarizer` class (static methods). */
+interface SummarizerHost {
+  /** Availability of the summarizer. */
+  availability(options: SummarizerCreateOptions): Promise<BuiltinAiAvailability>;
+  /** Create a summarizer. */
+  create(options: SummarizerCreateOptions & BuiltinAiCreateMonitorOptions): Promise<SummarizerLike>;
+}
+/** Options for {@link useSummarizer}. */
+interface UseSummarizerOptions {
+  /**
+   * Summary kind; a change destroys the session.
+   *
+   * @default "key-points"
+   */
+  readonly type?: MaybeRefOrGetter<SummarizerType>;
+  /**
+   * Output format; a change destroys the session.
+   *
+   * @default "markdown"
+   */
+  readonly format?: MaybeRefOrGetter<SummarizerFormat>;
+  /**
+   * Output length; a change destroys the session.
+   *
+   * @default "short"
+   */
+  readonly length?: MaybeRefOrGetter<SummarizerLength>;
+  /**
+   * Background shared by every summary; a change destroys the session.
+   *
+   * @default undefined
+   */
+  readonly sharedContext?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * `Summarizer` class.
+   *
+   * @default window.Summarizer when it exists
+   */
+  readonly host?: MaybeRef<SummarizerHost | null | undefined>;
+}
+/** State and actions returned by {@link useSummarizer}. */
+interface SummarizerControls extends BuiltinAiSessionControls {
+  /**
+   * Summarize text, creating the session on first use.
+   *
+   * @param text Text to summarize.
+   * @param options Per-call context.
+   * @returns The summary.
+   */
+  readonly summarize: (text: string, options?: SummarizeCallOptions) => Promise<string>;
+  /**
+   * Summarize text as a stream of chunks.
+   *
+   * @param text Text to summarize.
+   * @param options Per-call context.
+   * @returns Async iterable of summary chunks.
+   */
+  readonly summarizeStreaming: (text: string, options?: SummarizeCallOptions) => AsyncIterable<string>;
+}
+/**
+ * Translate text on-device with Chrome's built-in `Translator` API.
+ *
+ * The session is created lazily by the first `translate` (or explicitly by
+ * `create()`, which browsers require inside a user gesture when the model
+ * must be downloaded); `downloadProgress` follows the download. Changing a
+ * language destroys the session. The session is destroyed and a pending
+ * creation aborted when the owning reactive scope stops; outside a scope
+ * call `destroy()`.
+ *
+ * Server rendering: nothing is created, `supported` is false and `status`
+ * is `"unsupported"`.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const translator = useTranslator({ sourceLanguage: "en", targetLanguage: "ja" });
+ * const japanese = await translator.translate("Hello");
+ * ```
+ *
+ * @param options Language pair and class override.
+ * @returns Translator state and actions.
+ */
+declare function useTranslator(options: UseTranslatorOptions): TranslatorControls;
+/**
+ * Detect the language of text on-device with Chrome's built-in
+ * `LanguageDetector` API.
+ *
+ * Shares the lifecycle of {@link useTranslator}: lazy creation, download
+ * progress, destruction with the owning reactive scope.
+ *
+ * Server rendering: nothing is created, `supported` is false and `status`
+ * is `"unsupported"`.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const detector = useLanguageDetector();
+ * const [best] = await detector.detect(input.value);
+ * ```
+ *
+ * @param options Expected languages and class override.
+ * @default options {}
+ * @returns Detector state and actions.
+ */
+declare function useLanguageDetector(options?: UseLanguageDetectorOptions): LanguageDetectorControls;
+/**
+ * Summarize text on-device with Chrome's built-in `Summarizer` API.
+ *
+ * Shares the lifecycle of {@link useTranslator}: lazy creation, download
+ * progress, destruction with the owning reactive scope; changing `type`,
+ * `format`, `length` or `sharedContext` destroys the session.
+ *
+ * Server rendering: nothing is created, `supported` is false and `status`
+ * is `"unsupported"`.
+ * Inside a component `supported` turns true only after mounting, so
+ * hydration renders this server state first.
+ *
+ * @example
+ * ```ts
+ * const summarizer = useSummarizer({ type: "tldr", length: "medium" });
+ * for await (const chunk of summarizer.summarizeStreaming(article.value)) output.value += chunk;
+ * ```
+ *
+ * @param options Summary shape and class override.
+ * @default options {}
+ * @returns Summarizer state and actions.
+ */
+declare function useSummarizer(options?: UseSummarizerOptions): SummarizerControls;
+//#endregion
+export { BuiltinAiAvailability, BuiltinAiCreateMonitorOptions, BuiltinAiDownloadProgressEvent, BuiltinAiMonitorLike, BuiltinAiSessionControls, BuiltinAiStatus, BuiltinAiTextStream, LanguageDetectionResult, LanguageDetectorControls, LanguageDetectorCreateOptions, LanguageDetectorHost, LanguageDetectorLike, SummarizeCallOptions, SummarizerControls, SummarizerCreateOptions, SummarizerFormat, SummarizerHost, SummarizerLength, SummarizerLike, SummarizerType, TranslatorControls, TranslatorHost, TranslatorLanguages, TranslatorLike, UseLanguageDetectorOptions, UseSummarizerOptions, UseTranslatorOptions, useLanguageDetector, useSummarizer, useTranslator };

package/dist/use-builtin-ai.mjs

@@ -0,0 +1,261 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowRef, toValue, unref, watch, watchPostEffect } from "vue";
+//#region src/use-builtin-ai.ts
+function isFactory(candidate) {
+	return typeof candidate === "function" && typeof Reflect.get(candidate, "create") === "function" && typeof Reflect.get(candidate, "availability") === "function";
+}
+function browserFactory(name) {
+	if (typeof window === "undefined") return void 0;
+	const candidate = Reflect.get(window, name);
+	return isFactory(candidate) ? candidate : void 0;
+}
+function useAiSession(name, host, createOptions) {
+	const phase = ref("idle");
+	const downloadProgress = ref(0);
+	const error = shallowRef(void 0);
+	let instance;
+	let creating;
+	let controller;
+	let generation = 0;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveFactory = () => host === void 0 ? browserFactory(name) : unref(host) ?? void 0;
+	const fail = (cause) => {
+		error.value = cause;
+		throw cause;
+	};
+	const ensure = () => {
+		if (instance) return Promise.resolve(instance);
+		if (creating) return creating;
+		const factory = resolveFactory();
+		if (!factory) return Promise.reject(/* @__PURE__ */ new Error(`[VIZE_COMPOSE_BUILTIN_AI_UNSUPPORTED] ${name} is not available.`)).catch(fail);
+		const current = ++generation;
+		const abort = new AbortController();
+		controller = abort;
+		phase.value = "creating";
+		downloadProgress.value = 0;
+		const monitor = (target) => {
+			target.addEventListener("downloadprogress", ({ loaded, total }) => {
+				if (current !== generation) return;
+				const fraction = total !== void 0 && total > 0 ? loaded / total : loaded;
+				downloadProgress.value = Math.min(1, Math.max(0, fraction));
+				phase.value = "downloading";
+			});
+		};
+		let requested;
+		try {
+			requested = factory.create({
+				...createOptions(),
+				monitor,
+				signal: abort.signal
+			});
+		} catch (cause) {
+			controller = void 0;
+			phase.value = "error";
+			error.value = cause;
+			return Promise.reject(cause);
+		}
+		creating = requested.then((created) => {
+			if (current !== generation) {
+				created.destroy();
+				throw new DOMException("The session was destroyed.", "AbortError");
+			}
+			instance = created;
+			creating = void 0;
+			phase.value = "ready";
+			downloadProgress.value = 1;
+			error.value = void 0;
+			return created;
+		}, (cause) => {
+			if (current === generation) {
+				creating = void 0;
+				phase.value = "error";
+				error.value = cause;
+			}
+			throw cause;
+		});
+		return creating;
+	};
+	const destroy = () => {
+		generation += 1;
+		controller?.abort(new DOMException("The session was destroyed.", "AbortError"));
+		controller = void 0;
+		creating = void 0;
+		instance?.destroy();
+		instance = void 0;
+		phase.value = "idle";
+		downloadProgress.value = 0;
+	};
+	const run = async (action) => {
+		const session = await ensure();
+		try {
+			const value = await action(session);
+			error.value = void 0;
+			return value;
+		} catch (cause) {
+			return fail(cause);
+		}
+	};
+	async function* stream(open) {
+		const session = await ensure();
+		try {
+			const source = open(session);
+			if (Symbol.asyncIterator in source) for await (const chunk of source) yield chunk;
+			else {
+				const reader = source.getReader();
+				try {
+					for (;;) {
+						const { done, value } = await reader.read();
+						if (done) break;
+						if (value !== void 0) yield value;
+					}
+				} finally {
+					reader.releaseLock();
+				}
+			}
+			error.value = void 0;
+		} catch (cause) {
+			fail(cause);
+		}
+	}
+	const availability = async () => {
+		const factory = resolveFactory();
+		if (!factory) return "unavailable";
+		try {
+			return await factory.availability(createOptions());
+		} catch (cause) {
+			error.value = cause;
+			return "unavailable";
+		}
+	};
+	watch(createOptions, () => {
+		if (instance || creating) destroy();
+	});
+	tryOnScopeDispose(destroy);
+	const supported = computed(() => hydrated.value && resolveFactory() !== void 0);
+	return {
+		controls: {
+			supported,
+			status: computed(() => supported.value ? phase.value : "unsupported"),
+			downloadProgress: readonly(downloadProgress),
+			error: readonly(error),
+			availability,
+			create: () => ensure().then(() => true, () => false),
+			destroy
+		},
+		run,
+		stream
+	};
+}
+/**
+* Translate text on-device with Chrome's built-in `Translator` API.
+*
+* The session is created lazily by the first `translate` (or explicitly by
+* `create()`, which browsers require inside a user gesture when the model
+* must be downloaded); `downloadProgress` follows the download. Changing a
+* language destroys the session. The session is destroyed and a pending
+* creation aborted when the owning reactive scope stops; outside a scope
+* call `destroy()`.
+*
+* Server rendering: nothing is created, `supported` is false and `status`
+* is `"unsupported"`.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const translator = useTranslator({ sourceLanguage: "en", targetLanguage: "ja" });
+* const japanese = await translator.translate("Hello");
+* ```
+*
+* @param options Language pair and class override.
+* @returns Translator state and actions.
+*/
+function useTranslator(options) {
+	const session = useAiSession("Translator", options.host, () => ({
+		sourceLanguage: toValue(options.sourceLanguage),
+		targetLanguage: toValue(options.targetLanguage)
+	}));
+	return {
+		...session.controls,
+		translate: (text) => session.run((translator) => translator.translate(text)),
+		translateStreaming: (text) => session.stream((translator) => translator.translateStreaming(text))
+	};
+}
+/**
+* Detect the language of text on-device with Chrome's built-in
+* `LanguageDetector` API.
+*
+* Shares the lifecycle of {@link useTranslator}: lazy creation, download
+* progress, destruction with the owning reactive scope.
+*
+* Server rendering: nothing is created, `supported` is false and `status`
+* is `"unsupported"`.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const detector = useLanguageDetector();
+* const [best] = await detector.detect(input.value);
+* ```
+*
+* @param options Expected languages and class override.
+* @default options {}
+* @returns Detector state and actions.
+*/
+function useLanguageDetector(options = {}) {
+	const session = useAiSession("LanguageDetector", options.host, () => {
+		const expectedInputLanguages = toValue(options.expectedInputLanguages);
+		return expectedInputLanguages ? { expectedInputLanguages } : {};
+	});
+	return {
+		...session.controls,
+		detect: (text) => session.run((detector) => detector.detect(text))
+	};
+}
+/**
+* Summarize text on-device with Chrome's built-in `Summarizer` API.
+*
+* Shares the lifecycle of {@link useTranslator}: lazy creation, download
+* progress, destruction with the owning reactive scope; changing `type`,
+* `format`, `length` or `sharedContext` destroys the session.
+*
+* Server rendering: nothing is created, `supported` is false and `status`
+* is `"unsupported"`.
+* Inside a component `supported` turns true only after mounting, so
+* hydration renders this server state first.
+*
+* @example
+* ```ts
+* const summarizer = useSummarizer({ type: "tldr", length: "medium" });
+* for await (const chunk of summarizer.summarizeStreaming(article.value)) output.value += chunk;
+* ```
+*
+* @param options Summary shape and class override.
+* @default options {}
+* @returns Summarizer state and actions.
+*/
+function useSummarizer(options = {}) {
+	const session = useAiSession("Summarizer", options.host, () => {
+		const base = {
+			type: toValue(options.type) ?? "key-points",
+			format: toValue(options.format) ?? "markdown",
+			length: toValue(options.length) ?? "short"
+		};
+		const sharedContext = toValue(options.sharedContext);
+		return sharedContext === void 0 ? base : {
+			...base,
+			sharedContext
+		};
+	});
+	return {
+		...session.controls,
+		summarize: (text, callOptions) => session.run((summarizer) => summarizer.summarize(text, callOptions)),
+		summarizeStreaming: (text, callOptions) => session.stream((summarizer) => summarizer.summarizeStreaming(text, callOptions))
+	};
+}
+//#endregion
+export { useLanguageDetector, useSummarizer, useTranslator };