@gjsify/speech-synthesis 0.0.0-stage → 0.64.11

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @gjsify/speech-synthesis
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The W3C Web Speech synthesis API for GJS: `speechSynthesis`, `SpeechSynthesis`, `SpeechSynthesisUtterance`, `SpeechSynthesisVoice`, `SpeechSynthesisEvent`, `SpeechSynthesisErrorEvent`. The backend is [libspiel](https://project-spiel.org) (`gi://Spiel?version=1.0`) and its speech providers. Linux only. Tier 3 (experimental, [ADR 0003](../../../docs/adr/0003-package-tiering.md)) until promoted. See [ADR 0121](../../../docs/adr/0121-speech-synthesis-on-gjs-via-libspiel.md).
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
+
+## Installation
+
+```bash
+gjsify install @gjsify/speech-synthesis
+```
+
+## Usage
+
+```typescript
+import '@gjsify/speech-synthesis/register';
+
+speechSynthesis.addEventListener('voiceschanged', () => {
+    const voice = speechSynthesis.getVoices().find((v) => v.lang.startsWith('de'));
+    const utterance = new SpeechSynthesisUtterance('Hallo Welt');
+    if (voice) utterance.voice = voice;
+    speechSynthesis.speak(utterance);
+});
+speechSynthesis.getVoices(); // starts the probe; [] until `voiceschanged`
+```
+
+## Without a speech stack
+
+The W3C API cannot tell "no voices" from "no libspiel". Without the typelib or a provider, `getVoices()` returns `[]` and `speak()` fires an `error` event with `error: 'synthesis-unavailable'`. Ask why with the non-standard pair:
+
+```typescript
+import { hasSpeechSynthesisBackend, describeSpeechSynthesisBackend } from '@gjsify/speech-synthesis';
+
+if (!hasSpeechSynthesisBackend()) console.log(describeSpeechSynthesisBackend());
+```
+
+Install voices with the Spiel Installer flatpak `org.project_spiel.SpielInstaller`.
+
+## Notes
+
+- `voiceURI` is `<provider>#<voice>`; the first voice is `default`.
+- `rate` 0.1–10, `pitch` 0–2, `volume` 0–1 are clamped by this package.
+- `cancel()` fires `error` with `canceled`; Spiel `word-started` becomes a `boundary` event.
+- No cloud voices; apps bring their own.
+- `src/backend.ts` asks `probeSpiel()` from `@gjsify/spiel-native`: the host's libspiel wins, the bundled prebuild is the fallback, and `describeSpeechSynthesisBackend()` says which one answered.
+
+## License
+
+MIT

package/globals.mjs

@@ -0,0 +1,28 @@
+/**
+ * Re-exports the native Web Speech synthesis globals for browser builds; the libspiel GJS
+ * backend stays GJS-only.
+ *
+ * `@gjsify/resolve-npm/runtime-aliases.mjs` routes `@gjsify/speech-synthesis` here whenever
+ * `gjsify.runtimes.<target> === "native"`, so every root export a consumer may import must
+ * be answerable from here or the routed bundle dies with `MISSING_EXPORT`.
+ */
+
+export const speechSynthesis = globalThis.speechSynthesis;
+export const SpeechSynthesis = globalThis.SpeechSynthesis;
+export const SpeechSynthesisUtterance = globalThis.SpeechSynthesisUtterance;
+export const SpeechSynthesisVoice = globalThis.SpeechSynthesisVoice;
+export const SpeechSynthesisEvent = globalThis.SpeechSynthesisEvent;
+export const SpeechSynthesisErrorEvent = globalThis.SpeechSynthesisErrorEvent;
+
+/**
+ * Whether this host can speak at all. REAL rather than omitted (the README's recommended
+ * usage must build on every target): a browser ships its own voices.
+ */
+export async function hasSpeechSynthesisBackend() {
+    return typeof globalThis.speechSynthesis?.speak === 'function';
+}
+
+/** Which backend speaks, in words. In a browser: the browser's own. */
+export async function describeSpeechSynthesisBackend() {
+    return (await hasSpeechSynthesisBackend()) ? 'browser (native speechSynthesis)' : 'none';
+}

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/backend.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{SPIEL_NAMESPACE as e,probeSpiel as t}from"@gjsify/spiel-native";import{hostOs as n}from"@gjsify/utils/core";const r=`@gjsify/spiel-native`,i=`[@gjsify/speech-synthesis] No speech backend on this host — the Spiel-1.0 typelib (libspiel) is absent, so getVoices() is empty and speak() fires an error event (synthesis-unavailable). Install libspiel from your distribution, or the ${r}-<os>-<arch> package for this machine (linux-x64 and linux-arm64 only). Install a speech provider with the Spiel Installer (flatpak install flathub org.project_spiel.SpielInstaller) and add a voice there. Gate on hasSpeechSynthesisBackend().`,a=`[@gjsify/speech-synthesis] libspiel is available but no speech provider is installed, so getVoices() is empty and speak() fires an error event (synthesis-unavailable). Install a speech provider with the Spiel Installer (flatpak install flathub org.project_spiel.SpielInstaller) and add a voice there. Gate on hasSpeechSynthesisBackend().`;let o=null,s=!1;function isNoGiError(e){return e instanceof Error&&e.message.includes(`GObject-Introspection`)}function _diagnoseSpielLoadError(e,t=null){return isNoGiError(e)?{status:`absent`,diagnostic:null}:t!==null&&!(e instanceof Error&&e.name===`NativeLibraryLoadError`)?{status:`absent`,diagnostic:`${i} (${t})`}:{status:`failed`,diagnostic:`[@gjsify/speech-synthesis] The Spiel speech backend failed to load — a fault on this host, NOT a missing libspiel. getVoices() is empty until it is fixed.`}}async function probe(r){let i=(r.hostOs??n)();if(i===`darwin`||i===`win32`)return{status:`absent`,source:`absent`,speaker:null,namespace:null,error:null,diagnostic:`[@gjsify/speech-synthesis] No speech backend on this OS — libspiel exists for Linux only, so getVoices() is empty and speak() fires an error event (synthesis-unavailable).`};let o=(r.probe??t)();if(o.module===null){let{status:e,diagnostic:t}=_diagnoseSpielLoadError(o.error,o.reason??`not available`);return{status:e,source:`absent`,speaker:null,namespace:null,error:o.error,diagnostic:t}}let s,c=o.module;try{if(typeof c.Speaker?.new_sync!=`function`)throw Error(`${e} resolved without a Speaker class — unexpected Spiel ABI`);s=c.Speaker.new_sync(null),r.configureSpeaker?.(s)}catch(e){let{status:t,diagnostic:n}=_diagnoseSpielLoadError(e);return{status:t,source:o.source,speaker:null,namespace:null,error:e,diagnostic:n}}let l=s.providers.get_n_items()===0;return{status:`spiel`,source:o.source,speaker:s,namespace:c,error:null,diagnostic:l?a:null}}function loadSpeechSynthesisBackend(e={}){if(o!==null){if(e.probe||e.hostOs||e.configureSpeaker)throw Error(`loadSpeechSynthesisBackend(options) called after the probe already ran — the probe is cached per process, so the override would be ignored. Call _resetSpeechBackendCache() first (tests only).`);return o}return o=probe(e),o}function reportSpeechBackendOnce(e){s||e.diagnostic===null||(s=!0,e.status===`failed`?console.error(e.diagnostic,e.error):console.warn(e.diagnostic))}function backendCanSpeak(e){return e.status===`spiel`&&(e.speaker?.providers.get_n_items()??0)>0}async function hasSpeechSynthesisBackend(){return backendCanSpeak(await loadSpeechSynthesisBackend())}async function describeSpeechSynthesisBackend(){let e=await loadSpeechSynthesisBackend();if(e.status!==`spiel`)return`none (${e.status}): ${e.diagnostic??`not available on this target`}`;let t=e.speaker.providers.get_n_items();return t===0?`none (no-providers): ${a}`:`libspiel (${e.source===`prebuild`?`gi://Spiel from ${r}`:`gi://Spiel, system`}), ${t} provider(s), ${e.speaker.voices.get_n_items()} voice(s)`}function _resetSpeechBackendCache(){o=null,s=!1}export{_diagnoseSpielLoadError,_resetSpeechBackendCache,backendCanSpeak,describeSpeechSynthesisBackend,hasSpeechSynthesisBackend,loadSpeechSynthesisBackend,reportSpeechBackendOnce};

package/lib/esm/events.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{Event as e}from"@gjsify/dom-events";var SpeechSynthesisEvent=class extends e{utterance;charIndex;charLength;elapsedTime;name;constructor(e,t){super(e,t),this.utterance=t.utterance,this.charIndex=t.charIndex??0,this.charLength=t.charLength??0,this.elapsedTime=t.elapsedTime??0,this.name=t.name??``}get[Symbol.toStringTag](){return`SpeechSynthesisEvent`}},SpeechSynthesisErrorEvent=class extends SpeechSynthesisEvent{error;constructor(e,t){super(e,t),this.error=t.error}get[Symbol.toStringTag](){return`SpeechSynthesisErrorEvent`}};function defineEventHandler(e,t){let n=Symbol(`on${t}`);Object.defineProperty(e,`on${t}`,{configurable:!0,enumerable:!0,get(){return this[n]??null},set(e){this[n]&&this.removeEventListener(t,this[n]),this[n]=typeof e==`function`?e:null,this[n]&&this.addEventListener(t,this[n])}})}export{SpeechSynthesisErrorEvent,SpeechSynthesisEvent,defineEventHandler};

package/lib/esm/fake-spiel.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";var Emitter=class{#e=1;#t=new Map;connect(e,t){let n=this.#e++;return this.#t.set(n,{signal:e,cb:t}),n}disconnect(e){this.#t.delete(e)}emit(e,...t){for(let n of this.#t.values())n.signal===e&&n.cb(this,...t)}},FakeVoices=class extends Emitter{items;constructor(e){super(),this.items=e}get_n_items(){return this.items.length}get_item(e){return this.items[e]??null}set(e){let t=this.items.length;this.items=e,this.emit(`items-changed`,0,t,e.length)}},FakeSpeaker=class extends Emitter{voices;providers;speaking=!1;paused=!1;spoken=[];calls=[];props={};constructor(e,t){super(),this.voices=new FakeVoices(e),this.providers=new FakeVoices(t)}speak(e){this.spoken.push(e),this.calls.push(`speak`)}cancel(){this.calls.push(`cancel`),this.emit(`utterance-canceled`,this.spoken[this.spoken.length-1])}pause(){this.calls.push(`pause`)}resume(){this.calls.push(`resume`)}set_property(e,t){this.props[e]=t}get last(){return this.spoken[this.spoken.length-1]}};const e={identifier:`ai.piper.Speech.Provider`,name:`Piper`},voice=(t,n,r,i=e)=>({identifier:t,name:n,languages:r,provider:i});function fakeNamespace(e){return{Speaker:{new_sync:()=>e},Utterance:class{text=``;language=``;voice=null;pitch=1;rate=1;volume=1;constructor(e){Object.assign(this,e)}}}}export{FakeSpeaker,FakeVoices,e as PROVIDER,fakeNamespace,voice};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{describeSpeechSynthesisBackend as e,hasSpeechSynthesisBackend as t}from"./backend.js";import{SpeechSynthesisErrorEvent as n,SpeechSynthesisEvent as r}from"./events.js";import{SpeechSynthesisVoice as i}from"./voice.js";import{SpeechSynthesis as a}from"./speech-synthesis.js";import{SpeechSynthesisUtterance as o}from"./utterance.js";const s=new a;export{a as SpeechSynthesis,n as SpeechSynthesisErrorEvent,r as SpeechSynthesisEvent,o as SpeechSynthesisUtterance,i as SpeechSynthesisVoice,e as describeSpeechSynthesisBackend,t as hasSpeechSynthesisBackend,s as speechSynthesis};

package/lib/esm/register.js

@@ -0,0 +1 @@
+import{SpeechSynthesisErrorEvent as e,SpeechSynthesisEvent as t}from"./events.js";import{SpeechSynthesisVoice as n}from"./voice.js";import{SpeechSynthesis as r}from"./speech-synthesis.js";import{SpeechSynthesisUtterance as i}from"./utterance.js";const a=globalThis;a.speechSynthesis===void 0&&(a.speechSynthesis=new r,a.SpeechSynthesis=r,a.SpeechSynthesisUtterance=i,a.SpeechSynthesisVoice=n,a.SpeechSynthesisEvent=t,a.SpeechSynthesisErrorEvent=e);

package/lib/esm/speech-synthesis.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{backendCanSpeak as e,loadSpeechSynthesisBackend as t,reportSpeechBackendOnce as n}from"./backend.js";import{SpeechSynthesisErrorEvent as r,SpeechSynthesisEvent as i,defineEventHandler as a}from"./events.js";import{SPIEL_ERROR as o}from"./spiel-types.js";import{createVoice as s,spielVoiceOf as c}from"./voice.js";import{Event as l,EventTarget as u}from"@gjsify/dom-events";const clamp=(e,t,n)=>Math.min(n,Math.max(t,e));var SpeechSynthesis=class extends u{#e;#t=[];#n=null;#r=!1;#i=[];#a=null;#o=null;#s=[];#c=0;constructor(e={}){super(),this.#e=e}get speaking(){return this.#n!==null}get pending(){return this.#t.length>0}get paused(){return this.#r}getVoices(){return this.#l(),this.#i.slice()}speak(t){this.#t.push(t),this.#l().then(t=>{if(!e(t)){n(t),this.#b();return}this.#f()})}cancel(){this.#t.length=0;let e=this.#n;e!==null&&(this.#n=null,this.#r=!1,this.#a?.speaker?.cancel(),this.#S(e,`canceled`))}pause(){this.#r||this.#n===null||(this.#r=!0,this.#a?.speaker?.pause(),this.#x(this.#n,`pause`))}resume(){this.#r&&(this.#r=!1,this.#a?.speaker?.resume(),this.#n&&this.#x(this.#n,`resume`))}get[Symbol.toStringTag](){return`SpeechSynthesis`}#l(){return this.#o??=t(this.#e).then(e=>(this.#a=e,e.status===`spiel`&&e.speaker&&this.#u(e.speaker),e)),this.#o}#u(e){this.#d(e),this.#s.push(e.voices.connect(`items-changed`,()=>this.#d(e)),e.connect(`utterance-started`,()=>this.#h()),e.connect(`utterance-finished`,()=>this.#g()),e.connect(`utterance-canceled`,()=>this.#_()),e.connect(`utterance-error`,(e,t,n)=>this.#v(n)),e.connect(`word-started`,(e,t,n,r)=>this.#y(n,r)))}#d(e){let t=[],n=e.voices;for(let e=0;e<n.get_n_items();e++){let r=n.get_item(e);r&&t.push(s(r,t.length===0))}let r=t.length===this.#i.length&&t.every((e,t)=>e.voiceURI===this.#i[t].voiceURI);this.#i=t,r||this.dispatchEvent(new l(`voiceschanged`))}#f(){if(this.#n!==null||this.#t.length===0)return;let e=this.#a?.speaker;if(!e)return;let t=this.#t.shift(),n=this.#p(t);this.#n=t,this.#r=!1;try{e.speak(n)}catch{this.#n=null,this.#S(t,`synthesis-failed`),this.#f()}}#p(e){let t=c(e.voice),n={text:e.text,language:t?.languages?.[0]??e.lang??``,rate:clamp(Number(e.rate)||1,.1,10),pitch:clamp(Number.isFinite(Number(e.pitch))?Number(e.pitch):1,0,2),volume:clamp(Number.isFinite(Number(e.volume))?Number(e.volume):1,0,1)};return e.lang&&(n.language=e.lang),t&&(n.voice=t),(this.#e.createUtterance??this.#m())(n)}#m(){let e=this.#a?.namespace;if(!e)throw Error(`Spiel namespace unavailable`);return t=>new e.Utterance(t)}#h(){this.#n&&(this.#c=Date.now(),this.#x(this.#n,`start`))}#g(){let e=this.#n;e&&(this.#n=null,this.#x(e,`end`),this.#f())}#_(){let e=this.#n;e&&(this.#n=null,this.#S(e,`canceled`),this.#f())}#v(e){let t=this.#n;if(!t)return;this.#n=null;let n=e?.code===o.NO_PROVIDERS?`synthesis-unavailable`:e?.code===o.MISCONFIGURED_VOICE?`voice-unavailable`:`synthesis-failed`;this.#S(t,n),this.#f()}#y(e,t){this.#n&&this.#x(this.#n,`boundary`,{charIndex:e,charLength:Math.max(0,t-e),name:`word`})}#b(){let e=this.#t.splice(0);for(let t of e)this.#S(t,`synthesis-unavailable`)}#x(e,t,n={}){e.dispatchEvent(new i(t,{utterance:e,elapsedTime:this.#c?(Date.now()-this.#c)/1e3:0,...n}))}#S(e,t){e.dispatchEvent(new r(`error`,{utterance:e,error:t}))}};a(SpeechSynthesis.prototype,`voiceschanged`);export{SpeechSynthesis};

package/lib/esm/spiel-types.js

@@ -0,0 +1 @@
+const e={NO_PROVIDERS:0,MISCONFIGURED_VOICE:1,PROVIDER_UNEXPECTEDLY_DIED:2,INTERNAL_PROVIDER_FAILURE:3};export{e as SPIEL_ERROR};

package/lib/esm/utterance.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{defineEventHandler as e}from"./events.js";import{EventTarget as t}from"@gjsify/dom-events";var SpeechSynthesisUtterance=class extends t{text;lang=``;voice=null;volume=1;rate=1;pitch=1;constructor(e=``){super(),this.text=String(e)}get[Symbol.toStringTag](){return`SpeechSynthesisUtterance`}};for(let t of[`start`,`end`,`error`,`pause`,`resume`,`mark`,`boundary`])e(SpeechSynthesisUtterance.prototype,t);export{SpeechSynthesisUtterance};

package/lib/esm/voice.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";const e=new WeakMap;var SpeechSynthesisVoice=class{voiceURI;name;lang;localService;default;constructor(e){this.voiceURI=e.voiceURI,this.name=e.name,this.lang=e.lang,this.localService=e.localService,this.default=e.default}get[Symbol.toStringTag](){return`SpeechSynthesisVoice`}};function voiceUriOf(e){return`${e.provider.identifier}#${e.identifier}`}function createVoice(t,n){let r=new SpeechSynthesisVoice({voiceURI:voiceUriOf(t),name:t.name,lang:t.languages?.[0]??``,localService:!0,default:n});return e.set(r,t),r}function spielVoiceOf(t){return t?e.get(t):void 0}export{SpeechSynthesisVoice,createVoice,spielVoiceOf,voiceUriOf};

package/lib/types/backend.d.ts

@@ -0,0 +1,54 @@
+import { type SpielProbe, type SpielSource } from '@gjsify/spiel-native';
+import { type TargetOs } from '@gjsify/utils/core';
+import type { SpielNamespace, SpielSpeaker } from './spiel-types.js';
+export type SpeechBackendStatus = 'spiel' | 'absent' | 'failed';
+export interface SpeechBackend {
+    status: SpeechBackendStatus;
+    /** Where libspiel came from: the host (`system`), `@gjsify/spiel-native` (`prebuild`), or `absent`. */
+    source: SpielSource;
+    speaker: SpielSpeaker | null;
+    namespace: SpielNamespace | null;
+    /** The original load error for `absent`/`failed`; `null` otherwise. */
+    error: unknown;
+    /** The one-time line the USE site prints; `null` = nothing to say. */
+    diagnostic: string | null;
+}
+export interface LoadSpeechBackendOptions {
+    /** Override `probeSpiel()` from `@gjsify/spiel-native`. Tests only. */
+    probe?: () => Pick<SpielProbe, 'source' | 'module' | 'reason' | 'error'>;
+    /** Override the host OS the probe branches on. Tests only. */
+    hostOs?: () => TargetOs | undefined;
+    /**
+     * Runs on the fresh `Spiel.Speaker` before the first utterance — the place to route
+     * audio elsewhere (`speaker.set_property('sink', element)`); the specs use it to keep
+     * the real-Spiel test silent.
+     */
+    configureSpeaker?: (speaker: SpielSpeaker) => void;
+}
+/** Classify a failed Spiel probe or `Speaker` creation. Exported (underscored) for the specs. */
+export declare function _diagnoseSpielLoadError(error: unknown, reason?: string | null): {
+    status: 'absent' | 'failed';
+    diagnostic: string | null;
+};
+/**
+ * Resolve (once) what speech stack this host has. Emits NOTHING. Passing options after the
+ * probe ran THROWS instead of being ignored — call {@link _resetSpeechBackendCache} first.
+ */
+export declare function loadSpeechSynthesisBackend(options?: LoadSpeechBackendOptions): Promise<SpeechBackend>;
+/** Emit the backend's one-time diagnostic — called by `speak()`, never by the queries. */
+export declare function reportSpeechBackendOnce(backend: SpeechBackend): void;
+/** Whether `backend` can speak right now: libspiel loaded and at least one provider is there. */
+export declare function backendCanSpeak(backend: SpeechBackend): boolean;
+/**
+ * Whether this host can speak at all. `false` means `getVoices()` stays empty and every
+ * `speak()` ends in an `error` event, no matter what — which the W3C surface cannot express,
+ * since an empty voice list also means "still loading". Quiet; QUERY, not a guarantee.
+ */
+export declare function hasSpeechSynthesisBackend(): Promise<boolean>;
+/**
+ * The speech stack in words, and — when there is none — why and what to install. For a
+ * settings panel or a bug report; branch on {@link hasSpeechSynthesisBackend} instead.
+ */
+export declare function describeSpeechSynthesisBackend(): Promise<string>;
+/** Reset the cached probe and its one-time diagnostic — tests only. */
+export declare function _resetSpeechBackendCache(): void;

package/lib/types/events.d.ts

@@ -0,0 +1,36 @@
+import { Event } from '@gjsify/dom-events';
+import type { SpeechSynthesisUtterance } from './utterance.js';
+export interface SpeechSynthesisEventInit {
+    utterance: SpeechSynthesisUtterance;
+    charIndex?: number;
+    charLength?: number;
+    elapsedTime?: number;
+    name?: string;
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+}
+export declare class SpeechSynthesisEvent extends Event {
+    readonly utterance: SpeechSynthesisUtterance;
+    readonly charIndex: number;
+    readonly charLength: number;
+    readonly elapsedTime: number;
+    readonly name: string;
+    constructor(type: string, init: SpeechSynthesisEventInit);
+    get [Symbol.toStringTag](): string;
+}
+/** https://webaudio.github.io/web-speech-api/#enumdef-speechsynthesiserrorcode */
+export type SpeechSynthesisErrorCode = 'canceled' | 'interrupted' | 'audio-busy' | 'audio-hardware' | 'network' | 'synthesis-unavailable' | 'synthesis-failed' | 'language-unavailable' | 'voice-unavailable' | 'text-too-long' | 'invalid-argument' | 'not-allowed';
+export interface SpeechSynthesisErrorEventInit extends SpeechSynthesisEventInit {
+    error: SpeechSynthesisErrorCode;
+}
+export declare class SpeechSynthesisErrorEvent extends SpeechSynthesisEvent {
+    readonly error: SpeechSynthesisErrorCode;
+    constructor(type: string, init: SpeechSynthesisErrorEventInit);
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Install an `on<type>` IDL attribute on a prototype: assigning a function adds it as the
+ * listener, reassigning replaces it, `null` removes it.
+ */
+export declare function defineEventHandler(proto: object, type: string): void;

package/lib/types/fake-spiel.d.ts

@@ -0,0 +1,35 @@
+import type { SpielNamespace, SpielProvider, SpielUtterance, SpielVoice } from './spiel-types.js';
+type Cb = (...args: any[]) => void;
+declare class Emitter {
+    #private;
+    connect(signal: string, cb: Cb): number;
+    disconnect(id: number): void;
+    emit(signal: string, ...args: unknown[]): void;
+}
+export declare class FakeVoices<T> extends Emitter {
+    items: T[];
+    constructor(items: T[]);
+    get_n_items(): number;
+    get_item(i: number): T;
+    set(items: T[]): void;
+}
+export declare class FakeSpeaker extends Emitter {
+    voices: FakeVoices<SpielVoice>;
+    providers: FakeVoices<SpielProvider>;
+    speaking: boolean;
+    paused: boolean;
+    spoken: SpielUtterance[];
+    calls: string[];
+    props: Record<string, unknown>;
+    constructor(voices: SpielVoice[], providers: SpielProvider[]);
+    speak(u: SpielUtterance): void;
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+    set_property(name: string, value: unknown): void;
+    get last(): SpielUtterance;
+}
+export declare const PROVIDER: SpielProvider;
+export declare const voice: (identifier: string, name: string, languages: string[], provider?: SpielProvider) => SpielVoice;
+export declare function fakeNamespace(speaker: FakeSpeaker): SpielNamespace;
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+export { SpeechSynthesis } from './speech-synthesis.js';
+export type { SpeechSynthesisOptions } from './speech-synthesis.js';
+export { SpeechSynthesisUtterance } from './utterance.js';
+export { SpeechSynthesisVoice } from './voice.js';
+export { SpeechSynthesisEvent, SpeechSynthesisErrorEvent } from './events.js';
+export type { SpeechSynthesisErrorCode, SpeechSynthesisEventInit, SpeechSynthesisErrorEventInit } from './events.js';
+export { describeSpeechSynthesisBackend, hasSpeechSynthesisBackend } from './backend.js';
+export type { SpeechBackendStatus } from './backend.js';
+import { SpeechSynthesis } from './speech-synthesis.js';
+/** The shared instance, as `window.speechSynthesis`. */
+export declare const speechSynthesis: SpeechSynthesis;

package/lib/types/real-spiel.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/register.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/types/speech-synthesis.d.ts

@@ -0,0 +1,23 @@
+import { Event, EventTarget } from '@gjsify/dom-events';
+import { type LoadSpeechBackendOptions } from './backend.js';
+import { type SpielUtterance } from './spiel-types.js';
+import type { SpeechSynthesisUtterance } from './utterance.js';
+import { type SpeechSynthesisVoice } from './voice.js';
+export interface SpeechSynthesisOptions extends LoadSpeechBackendOptions {
+    /** Constructor of `Spiel.Utterance`; taken from the loaded namespace when omitted. Tests only. */
+    createUtterance?: (props: Partial<SpielUtterance>) => SpielUtterance;
+}
+export declare class SpeechSynthesis extends EventTarget {
+    #private;
+    onvoiceschanged: ((ev: Event) => any) | null;
+    constructor(options?: SpeechSynthesisOptions);
+    get speaking(): boolean;
+    get pending(): boolean;
+    get paused(): boolean;
+    getVoices(): SpeechSynthesisVoice[];
+    speak(utterance: SpeechSynthesisUtterance): void;
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+    get [Symbol.toStringTag](): string;
+}

package/lib/types/speech-synthesis.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/spiel-types.d.ts

@@ -0,0 +1,56 @@
+export interface SpielProvider {
+    identifier: string;
+    name: string;
+}
+export interface SpielVoice {
+    identifier: string;
+    name: string;
+    /** BCP 47 tags, best match first. */
+    languages: string[];
+    provider: SpielProvider;
+}
+export interface SpielListModel<T> {
+    get_n_items(): number;
+    get_item(position: number): T | null;
+    connect(signal: 'items-changed', cb: (model: unknown, position: number, removed: number, added: number) => void): number;
+    disconnect(id: number): void;
+}
+export interface SpielUtterance {
+    text: string;
+    language: string;
+    voice: SpielVoice | null;
+    pitch: number;
+    rate: number;
+    volume: number;
+}
+export interface SpielError {
+    code: number;
+    message: string;
+}
+export interface SpielSpeaker {
+    voices: SpielListModel<SpielVoice>;
+    providers: SpielListModel<SpielProvider>;
+    speaking: boolean;
+    paused: boolean;
+    speak(utterance: SpielUtterance): void;
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+    /** `sink` is not introspectable: only `set_property('sink', element)` reaches it. */
+    set_property(name: string, value: unknown): void;
+    connect(signal: string, cb: (...args: any[]) => void): number;
+    disconnect(id: number): void;
+}
+export interface SpielNamespace {
+    Speaker: {
+        new_sync(cancellable: null): SpielSpeaker;
+    };
+    Utterance: new (props: Partial<SpielUtterance>) => SpielUtterance;
+}
+/** `Spiel.Error` codes (the GIR enum), by number — the GIR carries no names at runtime we can rely on. */
+export declare const SPIEL_ERROR: {
+    readonly NO_PROVIDERS: 0;
+    readonly MISCONFIGURED_VOICE: 1;
+    readonly PROVIDER_UNEXPECTEDLY_DIED: 2;
+    readonly INTERNAL_PROVIDER_FAILURE: 3;
+};

package/lib/types/utterance.d.ts

@@ -0,0 +1,22 @@
+import { EventTarget } from '@gjsify/dom-events';
+import { type SpeechSynthesisErrorEvent, type SpeechSynthesisEvent } from './events.js';
+import type { SpeechSynthesisVoice } from './voice.js';
+type Handler<E> = ((this: SpeechSynthesisUtterance, ev: E) => any) | null;
+export declare class SpeechSynthesisUtterance extends EventTarget {
+    text: string;
+    lang: string;
+    voice: SpeechSynthesisVoice | null;
+    volume: number;
+    rate: number;
+    pitch: number;
+    onstart: Handler<SpeechSynthesisEvent>;
+    onend: Handler<SpeechSynthesisEvent>;
+    onerror: Handler<SpeechSynthesisErrorEvent>;
+    onpause: Handler<SpeechSynthesisEvent>;
+    onresume: Handler<SpeechSynthesisEvent>;
+    onmark: Handler<SpeechSynthesisEvent>;
+    onboundary: Handler<SpeechSynthesisEvent>;
+    constructor(text?: string);
+    get [Symbol.toStringTag](): string;
+}
+export {};

package/lib/types/voice.d.ts

@@ -0,0 +1,21 @@
+import type { SpielVoice } from './spiel-types.js';
+export declare class SpeechSynthesisVoice {
+    readonly voiceURI: string;
+    readonly name: string;
+    readonly lang: string;
+    readonly localService: boolean;
+    readonly default: boolean;
+    /** Not constructible from user code in browsers; here only `getVoices()` builds them. */
+    constructor(init: {
+        voiceURI: string;
+        name: string;
+        lang: string;
+        localService: boolean;
+        default: boolean;
+    });
+    get [Symbol.toStringTag](): string;
+}
+/** voiceURI = provider identifier + voice identifier, so two providers can offer the same voice. */
+export declare function voiceUriOf(voice: SpielVoice): string;
+export declare function createVoice(voice: SpielVoice, isDefault: boolean): SpeechSynthesisVoice;
+export declare function spielVoiceOf(voice: SpeechSynthesisVoice | null | undefined): SpielVoice | undefined;

package/package.json

@@ -1,6 +1,87 @@
 {
-  "name": "@gjsify/speech-synthesis",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/speech-synthesis",
+    "version": "0.64.11",
+    "description": "Web Speech synthesis API (speechSynthesis, SpeechSynthesisUtterance) for GJS, backed by libspiel",
+    "type": "module",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./register": {
+            "types": "./lib/types/register.d.ts",
+            "default": "./lib/esm/register.js"
+        },
+        "./globals": "./globals.mjs"
+    },
+    "files": [
+        "lib",
+        "globals.mjs"
+    ],
+    "sideEffects": [
+        "./lib/esm/register.js",
+        "./globals.mjs"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test*.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "speech",
+        "speechsynthesis",
+        "tts",
+        "libspiel"
+    ],
+    "dependencies": {
+        "@gjsify/dom-events": "^0.64.11",
+        "@gjsify/node-globals": "^0.64.11",
+        "@gjsify/spiel-native": "^0.64.11",
+        "@gjsify/utils": "^0.64.11"
+    },
+    "devDependencies": {
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@gjsify/cli": "^0.64.11",
+        "@gjsify/unit": "^0.64.11",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "partial",
+            "browser": "native",
+            "nativescript": "native"
+        },
+        "os": {
+            "linux": "supported",
+            "darwin": "none",
+            "win32": "none"
+        },
+        "osNotes": {
+            "darwin": "libspiel is a Linux/GNOME speech stack; getVoices() answers [] and speak() fires an error event with code synthesis-unavailable. describeSpeechSynthesisBackend() says why.",
+            "win32": "libspiel is a Linux/GNOME speech stack; getVoices() answers [] and speak() fires an error event with code synthesis-unavailable. describeSpeechSynthesisBackend() says why."
+        },
+        "tier": 3
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/web/speech-synthesis"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/speech-synthesis#readme"
+}