@gjsify/spiel-native 0.0.0-stage → 0.64.11

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# @gjsify/spiel-native
 
-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.
+[libspiel](https://github.com/project-spiel/libspiel), the GNOME **Spiel**
+speech-synthesis client library, built as one relocatable shared library plus its
+GObject-Introspection typelib — so `gi://Spiel?version=1.0` can be imported on a host
+that has no libspiel installed.
+
+This is the backend of [`@gjsify/speech-synthesis`](../speech-synthesis/README.md). It
+contains no speech API of its own.
+
+## What it is
+
+Spiel is a **D-Bus protocol**, not an engine. A client discovers *speech providers* by
+their well-known names on the session bus, asks them to synthesise, and plays the audio
+they stream back through GStreamer. libspiel is the client half; the voices live in
+separate processes (`ai.piper.Speech.Provider`, `org.espeak.Speech.Provider`, …).
+
+| ships | from |
+|---|---|
+| `libspiel-1.0.so` + `Spiel-1.0.typelib`, per target, in `@gjsify/spiel-native-<os>-<arch>` | this package's meson build |
+| `probeSpiel()` / `requireSpiel()` | `src/ts/index.ts` |
+| hand-written `Spiel-1.0` types | `src/ts/namespace.ts` — there is no `@girs/spiel-1.0` on npm |
+
+Linux only, and that is not a gap to fill later: macOS and Windows have no session bus
+and no provider implementation, so a prebuild there would load and then find nothing,
+permanently.
+
+## The API
+
+```ts
+import { probeSpiel, requireSpiel } from '@gjsify/spiel-native';
+
+const probe = probeSpiel();
+// probe.source     'system' | 'prebuild' | 'absent'
+// probe.module     the Spiel namespace, or null exactly when absent
+// probe.typelibDir where the typelib was loaded from, or null
+// probe.reason     one sentence naming what is missing, or null
+// probe.error      the underlying Error, for a caller that logs a cause
+```
+
+`probeSpiel()` is memoised and **never throws** — absent is an answer, not a fault, and a
+caller deciding how to degrade should not have to guard the question. `requireSpiel()` is
+the same answer as a namespace or a throw whose `cause` is `probe.error`.
+
+It is a capability query, in the shape `hasGamepadBackend()` established: it says the
+namespace is usable, not that this host has a voice. It deliberately does **not**
+construct a `Spiel.Speaker`, which would open the session bus and D-Bus-activate every
+installed provider.
+
+### A system libspiel wins
+
+A host libspiel takes precedence over the prebuild: it is the distribution's, it is the
+build every installed provider was made against, and it gets security updates we do not
+ship.
+
+That needs work, because it is the opposite of the default. Every mechanism that
+registers an ADR 0017 prebuild **prepends** it — `activateNativePrebuilds()`, the
+`--app gjs` bundle prologue, and the `gjsify` launcher's `GI_TYPELIB_PATH`. All three are
+right for a bridge whose library exists nowhere else (ADR 0023); for a library the host
+may genuinely have, the precedence is backwards. So `probeSpiel()` prepends the system
+directory *again*, after them, and therefore ahead of them.
+
+"The system directory" is measured, not guessed: it is the directory the running process
+loaded `GLib-2.0.typelib` from (`Repository.get_typelib_path('GLib')`). GJS has GLib
+loaded before any of our code runs and its typelib is never a prebuild, so that is the
+host's own `girepository-1.0` — with no table of `/usr/lib64`-shaped candidates to keep
+current per architecture and distribution. The prepend is conditional on
+`Spiel-1.0.typelib` actually being in it, so the search path of every other namespace in
+the process is left alone.
+
+## Provider discovery, and Flatpak
+
+From `spiel-registry.c`: libspiel calls `ListActivatableNames` and then `ListNames` on the
+session bus, keeps every name ending in `.Speech.Provider` (`PROVIDER_SUFFIX`), and
+subscribes to `ActivatableServicesChanged` + `NameOwnerChanged` to stay current. There is
+no central registry and no GSettings requirement — libspiel installs
+`org.monotonous.libspiel` but works without it.
+
+**A Flatpak app therefore needs an explicit D-Bus permission, or it sees zero voices.**
+Measured on Fedora 44 against a sandboxed app (`gdbus` inside `app.devsuite.Ptyxis`), with
+two providers running on the host:
+
+| finish args | `*.Speech.Provider` visible |
+|---|---|
+| *(default sandbox, no talk-name)* | **none** — in neither `ListActivatableNames` nor `ListNames` |
+| `--talk-name=ai.piper.Speech.Provider` | yes, that one |
+| `--talk-name=ai.piper.*` | yes |
+| `--socket=session-bus` | yes, everything (and that is the point — it is full bus access) |
+| `--talk-name=*.Speech.Provider` | rejected: `error: Invalid dbus name` |
+| `--talk-name=ai.*.Speech.Provider` | rejected: `error: Invalid dbus name` |
+| `--talk-name=ai.*` / `org.*` / `*` | rejected: `error: Invalid dbus name` |
+
+Flatpak's name matching is **prefix-only**. There is no pattern that means "any provider",
+because the `.Speech.Provider` suffix is the discriminator and a suffix wildcard is not
+expressible. So an app ships either one `--talk-name` per provider it supports, or
+`--socket=session-bus`. No Flatpak template in this repository has been changed for Spiel;
+an app that wants speech makes that trade itself, with this table to make it with.
+
+## No audible output in tests
+
+`Spiel.Speaker` has a `sink` property (a `GstElement`) which replaces the autoaudiosink.
+Point it at a `fakesink` or a `filesink` and synthesis runs end to end in silence.
+
+The GIR marks `Speaker:sink` `introspectable="0"`, so the property **accessor silently
+does nothing**:
+
+```js
+speaker.sink = fakesink;                 // no-op, no warning
+speaker.set_property('sink', fakesink);  // works
+```
+
+(Related GJS trap met while measuring this: `GObject.type_class_ref(gtype)` returns a boxed
+`TypeClass` with no `find_property` — use the class-level `Spiel.Speaker.find_property()`
+/ `list_properties()`. And `Provider:well-known-name` is deprecated since 1.0.4; read
+`provider.identifier`.)
+
+## Building
+
+```sh
+gjsify workspace @gjsify/spiel-native run build:prebuilds   # meson + stage-prebuild
+```
+
+`meson setup` clones the two pinned upstream checkouts, so the first setup needs network
+access. Three things in `meson.build` are worth knowing:
+
+- **libspeechprovider is linked statically** (`default_library=static`,
+  `introspection=false`). It is libspiel's own dependency; vendoring it as a second shared
+  object would mean a second typelib and an `$ORIGIN` RUNPATH to find it. One file ships.
+- **libspeechprovider is pinned in OUR top-level `subprojects/`**, not left to libspiel's
+  own wrap, because libspiel resolves its interface XML through
+  `meson.global_source_root() / 'subprojects' / 'libspeechprovider'` — from *our* root.
+- **Symbols are hidden with a version script**, applied with
+  `add_global_link_arguments('-Wl,--version-script=…')` before `subproject()`, so it covers
+  the subproject's objects too. Measured on the built artifact: 89 exported symbols, all
+  `spiel_*`, none else.
+
+The versioned SONAME is handled without patching upstream: `cp -L` to a plain
+`libspiel-1.0.so`, rewrite the `.gir`'s `shared-library`, recompile the typelib with
+`--shared-library libspiel-1.0.so`. The ELF SONAME stays `libspiel-1.0.so.1`, which is
+harmless — nothing links against this file, it is `dlopen`ed by name.
+
+Measured DT_NEEDED: `libgio-2.0`, `libgobject-2.0`, `libglib-2.0`, `libgstreamer-1.0`,
+`libgstaudio-1.0`, `libgstbase-1.0`, `libc`. No RUNPATH, no RPATH.
+
+**arm64 is built by CI only** (`prebuilds.yml`, the `ubuntu-24.04-arm` leg).
+
+## Testing
+
+```sh
+gjsify workspace @gjsify/spiel-native run test:meson
+```
+
+- `elf-deps` — reads DT_NEEDED, RUNPATH and the exported symbol table back off the built
+  file (`test/check-elf-deps.py`).
+- `load-typelib-gjs` — imports `gi://Spiel?version=1.0` under `gjs` from the build
+  directory and touches the classes, which is what proves the rewritten GIR and the
+  recompiled typelib agree with the library.
+- `speak-fakesink-gjs` — the end-to-end one, **opt-in**: it needs a session bus with real
+  providers, so it exits 77 (skip) unless `GJSIFY_SPIEL_LIVE=1`. With it set, measured on
+  Fedora 44: 2 providers, 5 voices, `utterance-started` → `utterance-finished` into a
+  `fakesink`. Silent by construction.
+
+## Updating libspiel
+
+Both wraps pin a **commit**, not a tag, and `subprojects/libspiel.wrap` carries no
+`depth=1` — a shallow clone cannot fetch a non-tip revision.
+
+The pin is a commit on purpose: the newest upstream tag is `SPIEL_1_0_4` (2025-04-03),
+which predates the subproject-tracking fix this build needs under meson < 1.14, and
+upstream's own `meson.build` already reads 1.0.5 with no tag cut. Move to a tag as soon as
+one exists at or past the pinned commit.
+
+To update: change the `revision` in `subprojects/libspiel.wrap` (and
+`libspeechprovider.wrap` if its 1.0.x moves), rebuild, run the tests, and re-measure the
+two numbers above — exported symbols and DT_NEEDED. Only GLib/GObject/Gio, GStreamer and
+libc may appear.
+
+## License
+
+This package is MIT.
+
+The **prebuilt library** in `@gjsify/spiel-native-linux-x64` /
+`-linux-arm64` is `MIT AND LGPL-2.1-or-later`: it contains libspiel and, statically
+linked, libspeechprovider — both © the Spiel contributors, both LGPL-2.1-or-later. The
+pinned commits in `subprojects/*.wrap` are the corresponding source those packages'
+recipients are entitled to, and the shared library is relinkable against a modified
+libspiel by replacing the file. See [`docs/attribution.md`](../../../docs/attribution.md).

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/index.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{loadOptionalNativeModule as e}from"@gjsify/utils/core";const t=`Spiel`,n=`1.0`,r=`${t}-1.0.typelib`;function hostGi(){return globalThis.imports?.gi}function directoryOf(e){return/^(.*)[\\/][^\\/]*$/.exec(e)?.[1]??null}function defaultRepository(e){try{return e?.GIRepository?.Repository?.dup_default?.()??null}catch{return null}}function preferSystemSpiel(e,t){let n=e?.GLib;if(!t||!n)return null;try{let e=t.get_typelib_path(`GLib`),i=e?directoryOf(e):null;if(!i)return null;let a=e?.includes(`\\`)&&!e.includes(`/`)?`\\`:`/`;if(!n.file_test(`${i}${a}${r}`,n.FileTest.EXISTS))return null;t.prepend_search_path(i);let o=directoryOf(i);return o&&t.prepend_library_path(o),i}catch{return null}}let i=null;function probeSpiel(n={}){if(i&&!n.fresh)return i;let r=n.gi??hostGi(),a=defaultRepository(r),o=preferSystemSpiel(r,a);try{r?.versions&&(r.versions[t]=`1.0`)}catch{}let s=e(t,[`Speaker`,`Utterance`],r),c=(()=>{try{let e=a?.get_typelib_path(`Spiel`)??null;return e?directoryOf(e):null}catch{return null}})(),l=s.module?{source:o!==null&&c===o?`system`:`prebuild`,module:s.module,typelibDir:c,reason:null,error:null}:{source:`absent`,module:null,typelibDir:c,reason:absentReason(s.error),error:s.error};return n.fresh||(i=l),l}function absentReason(e){return e?e.name===`NativeLibraryLoadError`?e.message:e.message.includes(`imports.gi`)?`${t}: no GObject-Introspection in this process — @gjsify/spiel-native needs GJS or @gjsify/node-gi.`:`${t}-1.0.typelib was not found. Install libspiel, or the \`@gjsify/spiel-native-<os>-<arch>\` package for this machine — it is an optional dependency and exists for linux-x64 and linux-arm64 only.`:`${t}: not available, and nothing was measurable about why.`}function requireSpiel(e={}){let t=probeSpiel(e);if(t.module)return t.module;throw Error(t.reason??`Spiel: not available.`,{cause:t.error??void 0})}export{t as SPIEL_NAMESPACE,n as SPIEL_VERSION,probeSpiel,requireSpiel};

package/lib/types/index.d.ts

@@ -0,0 +1,58 @@
+import { type GiImportsView } from '@gjsify/utils/core';
+import type { SpielNamespace } from './namespace.js';
+export type { SpielListModel, SpielNamespace, SpielProvider, SpielSpeaker, SpielSpeakerSignals, SpielUtterance, SpielVoice, } from './namespace.js';
+/** The GI namespace this package makes importable. */
+export declare const SPIEL_NAMESPACE = "Spiel";
+/** The only version libspiel has ever published a typelib for. */
+export declare const SPIEL_VERSION = "1.0";
+/**
+ * Where the `Spiel` typelib came from.
+ *
+ * - `system`   — the host's own libspiel, on the directory its GLib typelib lives in.
+ *   Preferred: it is the build every installed speech provider was made against.
+ * - `prebuild` — this package's `@gjsify/spiel-native-<target>` artifact, or any other
+ *   directory a caller put on girepository's search path.
+ * - `absent`   — no typelib, or one whose library will not open. {@link SpielProbe.reason}
+ *   says which.
+ */
+export type SpielSource = 'system' | 'prebuild' | 'absent';
+/** What {@link probeSpiel} found. */
+export interface SpielProbe {
+    readonly source: SpielSource;
+    /** The namespace, or `null` exactly when `source` is `absent`. */
+    readonly module: SpielNamespace | null;
+    /** The directory the typelib was loaded from; `null` when none was. */
+    readonly typelibDir: string | null;
+    /**
+     * One sentence naming what is missing — `null` exactly when `source` is not
+     * `absent`. Safe to show a user: it names the file and, for a library that was
+     * found and refused, the dependency the loader could not resolve.
+     */
+    readonly reason: string | null;
+    /** The underlying error behind `reason`, for a caller that wants to log a cause. */
+    readonly error: Error | null;
+}
+/** Overrides. Tests only — every default here reads the running GJS host. */
+export interface ProbeSpielOptions {
+    /** The `imports.gi` to use. */
+    readonly gi?: GiImportsView | undefined;
+    /** Skip the memo, so a spec can drive more than one outcome per process. */
+    readonly fresh?: boolean;
+}
+/**
+ * Find `Spiel`, system first, and say what was found.
+ *
+ * Memoized: the answer cannot change within a process (girepository caches a loaded
+ * typelib, and the directories were decided at the first call), and the search path
+ * must not be rewritten on every query. Never throws — `absent` is an answer, not a
+ * fault, and a caller deciding how to degrade must not have to guard the question.
+ */
+export declare function probeSpiel(options?: ProbeSpielOptions): SpielProbe;
+/**
+ * {@link probeSpiel} as a namespace or a throw — for a caller that has already
+ * decided Spiel is required and wants the reason in the stack trace.
+ *
+ * The `cause` carries the original error, so a loader fault keeps the file and the
+ * missing dependency the probe measured.
+ */
+export declare function requireSpiel(options?: ProbeSpielOptions): SpielNamespace;

package/lib/types/namespace.d.ts

@@ -0,0 +1,85 @@
+/** A `Gio.ListModel` of `T`, as the two members a consumer of this package uses. */
+export interface SpielListModel<T> {
+    get_n_items(): number;
+    get_item(position: number): T | null;
+}
+/** `Spiel.Voice` — one voice offered by one provider. */
+export interface SpielVoice {
+    get_name(): string;
+    /** Stable within a provider; the half of a voice id that is not the provider. */
+    get_identifier(): string;
+    /** BCP-47 tags this voice speaks. */
+    get_languages(): string[];
+    get_provider(): SpielProvider | null;
+    /** `SpeechProvider.VoiceFeature` flags, as the plain bitfield GJS sees. */
+    get_features(): number;
+    hash(): number;
+    equal(other: SpielVoice): boolean;
+    compare(other: SpielVoice, ...rest: unknown[]): number;
+}
+/** `Spiel.Provider` — one speech-provider daemon on the session bus. */
+export interface SpielProvider {
+    /** The D-Bus well-known name, e.g. `org.espeak.Speech.Provider`. */
+    get_identifier(): string;
+    get_name(): string;
+    get_voices(): SpielListModel<SpielVoice> | null;
+}
+/** `Spiel.Utterance` — a request to speak, with its per-utterance settings. */
+export interface SpielUtterance {
+    get_text(): string | null;
+    set_text(text: string | null): void;
+    get_language(): string | null;
+    set_language(language: string | null): void;
+    get_voice(): SpielVoice | null;
+    set_voice(voice: SpielVoice | null): void;
+    /** 0..10, 1 is the voice's own. */
+    get_rate(): number;
+    set_rate(rate: number): void;
+    get_pitch(): number;
+    set_pitch(pitch: number): void;
+    get_volume(): number;
+    set_volume(volume: number): void;
+    get_is_ssml(): boolean;
+    set_is_ssml(isSsml: boolean): void;
+}
+/** The signals `Spiel.Speaker` emits, with the arguments each carries after the speaker. */
+export interface SpielSpeakerSignals {
+    'utterance-started': [utterance: SpielUtterance];
+    'utterance-finished': [utterance: SpielUtterance];
+    'utterance-canceled': [utterance: SpielUtterance];
+    'utterance-error': [utterance: SpielUtterance, error: unknown];
+    'word-started': [utterance: SpielUtterance, start: number, end: number];
+    'sentence-started': [utterance: SpielUtterance, start: number, end: number];
+    'range-started': [utterance: SpielUtterance, start: number, end: number];
+    'mark-reached': [utterance: SpielUtterance, name: string];
+}
+/** `Spiel.Speaker` — the client. One per process is enough; it owns the registry. */
+export interface SpielSpeaker {
+    speak(utterance: SpielUtterance): void;
+    pause(): void;
+    resume(): void;
+    cancel(): void;
+    get_voices(): SpielListModel<SpielVoice> | null;
+    get_providers(): SpielListModel<SpielProvider> | null;
+    /** GObject.Object — the only way to reach the `introspectable="0"` `sink`. */
+    set_property(name: string, value: unknown): void;
+    get_property(name: string): unknown;
+    connect<K extends keyof SpielSpeakerSignals>(signal: K, callback: (speaker: SpielSpeaker, ...args: SpielSpeakerSignals[K]) => void): number;
+    connect(signal: string, callback: (...args: never[]) => void): number;
+    disconnect(id: number): void;
+}
+/** The `gi://Spiel?version=1.0` namespace — the subset this package answers for. */
+export interface SpielNamespace {
+    readonly Speaker: {
+        /** Blocks until the registry has answered the bus. Throws on failure. */
+        new_sync(cancellable?: unknown): SpielSpeaker;
+        new (cancellable: unknown, callback: (source: unknown, result: unknown) => void): void;
+        new_finish(result: unknown): SpielSpeaker;
+    };
+    readonly Utterance: {
+        new (props?: Record<string, unknown>): SpielUtterance;
+    };
+    readonly Provider: object;
+    readonly Voice: object;
+    readonly VoicesListModel: object;
+}

package/meson.build

@@ -0,0 +1,208 @@
+# GjsifySpiel — libspiel, the Spiel speech-synthesis CLIENT library, shipped as
+# ONE relocatable shared library plus its typelib (ADR 0017), so `gi://Spiel` can
+# be imported on a host that has no libspiel package.
+#
+# No C of our own: unlike the sibling bridges here, this build wraps an UPSTREAM
+# GNOME library unchanged (LGPL-2.1-or-later, see README.md § License and
+# docs/attribution.md). What this file adds is only what makes the upstream build
+# shippable as a prebuild — three properties, each measured rather than assumed,
+# and each with its own section below:
+#
+#   1. ONE library, not two (libspeechprovider is linked statically),
+#   2. nothing but spiel_* leaves it (version script),
+#   3. an UNVERSIONED leaf the typelib names (`libspiel-1.0.so`).
+#
+# LINUX ONLY, and that is a property of Spiel rather than of this build: a client
+# finds its speech providers over the D-Bus SESSION BUS and plays their audio
+# through GStreamer. There is no provider protocol on win32 or darwin, so a
+# prebuild for them would load and then find nothing, forever. README.md
+# § Provider discovery has the measurement.
+project('GjsifySpiel', 'c',
+    version: '1.0.5',
+    meson_version: '>= 1.3.2',
+    license: 'LGPL-2.1-or-later',
+    # `-Os` WITHOUT `-g`, spelled as the two options rather than as a buildtype,
+    # because no buildtype is both: meson's `minsize` carries `debug=true`, and
+    # `plain` carries no optimisation at all. The size of this prebuild IS the
+    # size of upstream's objects — there is no code of ours to optimise — and a
+    # `-g` build would put object-file paths from the CI runner into the shipped
+    # image (docs/prebuilds.md § Reproducibility).
+    default_options: ['optimization=s', 'debug=false'],
+)
+
+fs = import('fs')
+
+if host_machine.system() != 'linux'
+    error('@gjsify/spiel-native builds for linux only — Spiel finds its providers on the ' +
+          'D-Bus session bus, which exists on no other target (README.md § Provider discovery). ' +
+          'This host is ' + host_machine.system() + '.')
+endif
+
+# ----------------------------------------------------------------------------
+# 2. WHAT LEAVES THE LIBRARY — the version script, delivered GLOBALLY.
+#
+# This has to be set BEFORE `subproject()`, and it has to be `add_global_link_arguments`
+# rather than an option on the subproject. Both halves are measured:
+#
+#   · `-Dlibspiel:c_link_args=…` is ACCEPTED, stored and echoed back by `meson
+#     configure` — and never reaches the linker, because a subproject's
+#     `c_link_args` is a per-project option that `shared_library()` in that
+#     project does not consume for a target declared without `link_args`.
+#     Measured: 89 spiel_* and 7 speech_provider_* exported, i.e. no script.
+#   · `LDFLAGS` in the environment does work, and is exactly the kind of fact
+#     that is true in one shell and false in the next — `build:prebuilds` would
+#     ship a different library depending on who ran it.
+#
+# A global link argument is neither: it is recorded in the build definition and
+# applied to every link in this build tree, subprojects included. Measured with
+# this arrangement: 89 spiel_* and 0 speech_provider_*, which is what
+# test/check-elf-deps.py reads back from the built file on every run.
+# ----------------------------------------------------------------------------
+spiel_map = meson.current_source_dir() / 'src' / 'c' / 'spiel.map'
+add_global_link_arguments('-Wl,--version-script=' + spiel_map, language: 'c')
+
+# ----------------------------------------------------------------------------
+# 1. ONE LIBRARY — libspeechprovider linked STATICALLY into libspiel.
+#
+# Upstream builds libspeechprovider as a second shared library that libspiel
+# links. Shipped that way, a prebuild would be two `.so` files, the second
+# findable only through an `$ORIGIN` RUNPATH this build would have to inject
+# (upstream sets none) — and a second typelib nobody imports. Static collapses
+# all of it: one file, no RUNPATH, no loader-path question for
+# `check-prebuild-loader-path.mjs` to answer. `Spiel-1.0.gir` references ZERO
+# `speech_provider_*` symbols (measured), so nothing introspectable is lost —
+# which is also what makes hiding them above safe.
+#
+# `introspection=false` on the subproject's subproject for the same reason: a
+# `SpeechProvider-1.0.typelib` naming a library that is no longer shipped is a
+# broken artifact, and nothing here imports it.
+# ----------------------------------------------------------------------------
+libspiel = subproject('libspiel',
+    default_options: [
+        'docs=false',
+        'tests=false',
+        'utils=false',
+        'introspection=true',
+        'libspeechprovider:default_library=static',
+        'libspeechprovider:introspection=false',
+        'libspeechprovider:docs=false',
+        'libspeechprovider:tests=false',
+    ],
+)
+spiel_lib = libspiel.get_variable('spiel_lib')
+# `gnome.generate_gir()` answers [gir, typelib]; only the GIR is taken, because
+# the typelib beside it was compiled from a `shared-library` this package does
+# not ship (below).
+spiel_gir = libspiel.get_variable('spiel_gir')[0]
+
+# ----------------------------------------------------------------------------
+# 3. THE UNVERSIONED LEAF, and why nothing upstream is patched.
+#
+# meson's `version:` makes `libspiel-1.0.so.1.0.5` with `libspiel-1.0.so.1` and
+# `libspiel-1.0.so` as SYMLINKS to it, and records the middle one in the GIR's
+# `shared-library`. A prebuild directory is copied file by file by
+# `stage-prebuild.mjs` — symlinks become copies — so shipping the chain would
+# ship three identical megabytes, and shipping only what the GIR names would ship
+# a leaf whose own name says it is one of a set.
+#
+# So the shipped set is re-derived rather than patched: the real file under a
+# plain name, the GIR rewritten to name it, and the typelib recompiled from that
+# GIR. The same three steps as gamepad-native/meson.build:238-251, for the same
+# reason — the typelib's `shared-library` entry must name a file that is actually
+# in the directory beside it.
+#
+# The ELF SONAME stays `libspiel-1.0.so.1` and that is harmless: a SONAME is what
+# the loader records in a DEPENDENT's DT_NEEDED, and nothing here depends on this
+# library — girepository opens it by the path the typelib names.
+#
+# All three land in the TOP-LEVEL build directory on purpose: `stage-prebuild.mjs`
+# reads it with a NON-RECURSIVE `readdirSync`, so an artifact in
+# `build/subprojects/libspiel/libspiel/` is not shipped at all.
+# ----------------------------------------------------------------------------
+spiel_so_leaf = 'libspiel-1.0.so'
+
+spiel_so = custom_target(spiel_so_leaf,
+    input: spiel_lib,
+    output: spiel_so_leaf,
+    # `cp` dereferences, so this is the real file even though `@INPUT@` may be
+    # the versioned one meson built.
+    command: ['cp', '-L', '@INPUT@', '@OUTPUT@'],
+    build_by_default: true,
+)
+
+sed = find_program('sed')
+spiel_gir_relinked = custom_target('Spiel-1.0.gir',
+    input: spiel_gir,
+    output: 'Spiel-1.0.gir',
+    # NO BACKSLASH ESCAPES in this pattern, and that is not laziness: meson
+    # rewrites `\\.` in a string literal to `/.` by the time the argument reaches
+    # the program (seen in `ninja -t commands`), so the escaped form matches
+    # nothing and the rewrite silently does not happen — which is exactly how it
+    # failed first. Unescaped `.` matches any character, which over this literal
+    # is a distinction without a difference.
+    command: [sed, '-e', 's|shared-library="libspiel-1.0.so.1"|shared-library="' + spiel_so_leaf + '"|', '@INPUT@'],
+    capture: true,
+    build_by_default: true,
+)
+
+spiel_typelib = custom_target('Spiel-1.0.typelib',
+    input: spiel_gir_relinked,
+    output: 'Spiel-1.0.typelib',
+    command: [
+        find_program('g-ir-compiler', 'gi-compile-repository'),
+        '--output', '@OUTPUT@',
+        # Belt and braces with the rewrite above: this is the entry girepository
+        # reads, and `check-prebuild-loader-path.mjs` asserts the file it names
+        # is in the staged directory.
+        '--shared-library', spiel_so_leaf,
+        '@INPUT@',
+    ],
+    depends: [spiel_so],
+    build_by_default: true,
+)
+
+# ----------------------------------------------------------------------------
+# Tests — what this build CLAIMS, read back from what it produced.
+#
+# Nothing here synthesises speech, and that is not caution about CI noise: a
+# `speak()` on a developer's machine comes out of their speakers. The gjs leg
+# sets a `fakesink` before it touches a Speaker at all (see the file).
+# ----------------------------------------------------------------------------
+python3 = find_program('python3', required: false)
+if python3.found()
+    # python3 is `required: false` for the same reason as in gamepad-native: a
+    # host without it gets a tree that builds with the test SKIPPED. The BUILD
+    # needs python3 regardless (both upstream projects run it), so in practice
+    # this only ever skips where nothing built either.
+    test('elf-deps', python3,
+         args: [files('test/check-elf-deps.py'), spiel_so.full_path()],
+         depends: [spiel_so])
+endif
+
+gjs = find_program('gjs', required: false)
+if gjs.found()
+    # The shipped PAIR, through girepository, exactly as a consumer reaches it:
+    # the typelib names `libspiel-1.0.so` by bare leaf and finds it beside
+    # itself. Both are in this directory only because of the three targets above.
+    gi_env = {
+        'GI_TYPELIB_PATH': meson.current_build_dir(),
+        'LD_LIBRARY_PATH': meson.current_build_dir(),
+    }
+    test('load-typelib-gjs', gjs,
+         args: ['-m', files('test/load-typelib.gjs.js')],
+         depends: [spiel_so, spiel_typelib],
+         timeout: 60,
+         env: gi_env)
+
+    # The live leg, registered always and SKIPPED (exit 77) without
+    # GJSIFY_SPIEL_LIVE=1 — see the file for why it cannot be the default: it
+    # D-Bus-activates the speech providers of whoever runs it. Registered rather
+    # than left out so `meson test --list` shows it exists; a check nobody can
+    # see is a check nobody runs.
+    test('speak-fakesink-gjs', gjs,
+         args: ['-m', files('test/speak-fakesink.gjs.js')],
+         depends: [spiel_so, spiel_typelib],
+         timeout: 120,
+         is_parallel: false,
+         env: gi_env)
+endif

package/package.json

@@ -1,6 +1,92 @@
 {
-  "name": "@gjsify/spiel-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/spiel-native",
+    "version": "0.64.11",
+    "description": "libspiel, the GNOME Spiel speech-synthesis client library, built as one relocatable shared library plus its typelib so `gi://Spiel` can be imported without a system libspiel — the backend of @gjsify/speech-synthesis. The prebuilt library arrives through per-target optionalDependencies; this package adds only the probe that says where Spiel came from.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "meson.build",
+        "src",
+        "subprojects",
+        "test"
+    ],
+    "gjsify": {
+        "platforms": [
+            "linux-x64",
+            "linux-arm64"
+        ],
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "os": {
+            "linux": "partial",
+            "darwin": "none",
+            "win32": "none"
+        },
+        "osNotes": {
+            "linux": "Builds for linux-x64 and linux-arm64 against the host GLib, GObject, Gio and GStreamer; libspeechprovider is linked statically, so the prebuild is one `.so` with no RUNPATH. `gi://Spiel` loads from the staged directory and `Speaker.new_sync()` reaches the session bus — measured on Fedora 44 / x86_64 with two providers answering. arm64 is built by CI only.",
+            "darwin": "Not built. Spiel is a D-Bus protocol: a client finds providers by their `*.Speech.Provider` well-known names on the session bus and plays their audio through GStreamer. macOS has no session bus and no provider implementation, so a prebuild would load and then find nothing, permanently.",
+            "win32": "Not built, for the same reason as darwin."
+        },
+        "prebuildLicense": "MIT AND LGPL-2.1-or-later",
+        "tier": 3
+    },
+    "scripts": {
+        "clear": "gjsify clear lib build tsconfig.tsbuildinfo",
+        "check": "gjsify tsc --noEmit",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
+        "build:types": "gjsify tsc -b --force",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:prebuilds": "gjsify run build:meson && node ../../../scripts/stage-prebuild.mjs .",
+        "test": "echo 'native only — see test:meson (runs on every prebuild leg)'",
+        "test:meson": "meson test -C build --print-errorlogs"
+    },
+    "keywords": [
+        "gjs",
+        "spiel",
+        "speech-synthesis",
+        "tts",
+        "gnome",
+        "linux"
+    ],
+    "dependencies": {
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gobject-2.0": "5.4.0",
+        "@gjsify/utils": "^0.64.11"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.64.11",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/web/spiel-native"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/web/spiel-native#readme",
+    "optionalDependencies": {
+        "@gjsify/spiel-native-linux-arm64": "0.64.11",
+        "@gjsify/spiel-native-linux-x64": "0.64.11"
+    }
+}