@gjsify/spiel-native 0.0.0-stage → 0.64.12-next.281

package/src/c/spiel.map

@@ -0,0 +1,17 @@
+/* What leaves libspiel-1.0.so: the spiel_* API and nothing else.
+ *
+ * ELF has ONE flat symbol namespace, so this is not cosmetic. libspeechprovider
+ * is linked statically into this library (meson.build § ONE library), and
+ * without this script its seven speech_provider_* functions are exported — where
+ * they would interpose on (or be interposed by) the real libspeechprovider.so
+ * that a speech PROVIDER in the same process links. Measured: 89 spiel_* and 0
+ * speech_provider_* exported with this script, 89 and 7 without it. The Spiel
+ * typelib names no speech_provider_* symbol, so nothing introspectable is lost
+ * (test/check-elf-deps.py reads both facts back from the built file).
+ */
+{
+  global:
+    spiel_*;
+  local:
+    *;
+};

package/src/ts/index.ts

@@ -0,0 +1,285 @@
+// @gjsify/spiel-native — make `gi://Spiel?version=1.0` importable, and say where it
+// came from.
+//
+// This package contains no speech API. It ships libspiel (LGPL-2.1-or-later) as an
+// ADR 0017 prebuild and exposes exactly two things to the package that does — the
+// sibling `@gjsify/speech-synthesis`: {@link probeSpiel}, which answers
+// system / prebuild / absent with a reason, and {@link requireSpiel}, which is the
+// same answer as a namespace or a throw. Nothing else here is public API.
+//
+// ── WHY A PROBE AND NOT AN IMPORT ─────────────────────────────────────────────
+//
+// A static `import Spiel from 'gi://Spiel'` fails the whole module when the typelib
+// is absent, and "absent" is an ORDINARY state here: this prebuild exists only for
+// linux-x64 and linux-arm64, and even on those a consumer may have installed the
+// bridge without its optional per-target package. A speech API that cannot be
+// imported on a machine with no speech is the wrong failure — the W3C surface it
+// backs answers with an empty voice list, which needs the module to load.
+//
+// ── SYSTEM BEFORE PREBUILD, AND WHY IT TAKES WORK ─────────────────────────────
+//
+// A host libspiel wins over ours. It is the distribution's, it is the one a
+// provider package was built against, and it gets security updates we do not ship.
+//
+// That is NOT the default, and that is the whole reason this function exists.
+// Every mechanism that registers an ADR 0017 prebuild PREPENDS it —
+// `activateNativePrebuilds()` (`@gjsify/cli`) calls `prepend_search_path`, the
+// `--app gjs` bundle prologue (`gi-runtime-paths.ts`) emits the same call, and the
+// `gjsify` launcher puts the directory at the FRONT of `GI_TYPELIB_PATH`. All three
+// are right for a bridge whose library exists nowhere else (ADR 0023's
+// bundle-before-system precedence); for a library the host may genuinely have, the
+// precedence is backwards. So the system directory is prepended AGAIN, after them,
+// and therefore ahead of them.
+//
+// WHERE "the system directory" comes from, without guessing: the directory the
+// RUNNING process loaded `GLib-2.0.typelib` from. GJS has GLib loaded before any
+// of our code runs and its typelib is never a prebuild, so that directory is the
+// host's own `girepository-1.0` — the compile-time default, or whatever
+// `GI_TYPELIB_PATH` the user set, with no table of `/usr/lib64`-shaped candidates
+// to keep current per architecture and distribution.
+//
+// ── WHAT THIS DOES NOT DO ─────────────────────────────────────────────────────
+//
+// It does not start a `Spiel.Speaker`, which would open the session bus and
+// D-Bus-ACTIVATE every installed speech provider. `probeSpiel()` is a capability
+// query, in the shape `hasGamepadBackend()` established: it says the namespace is
+// usable, not that this host has a voice. Whether any provider answers is a
+// separate question, and on a Flatpak-sandboxed host the answer is usually no —
+// README.md § Provider discovery has the measurement.
+
+import { loadOptionalNativeModule, 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 const SPIEL_NAMESPACE = 'Spiel';
+
+/** The only version libspiel has ever published a typelib for. */
+export const SPIEL_VERSION = '1.0';
+
+/** The typelib file name both halves of the search look for. */
+const SPIEL_TYPELIB = `${SPIEL_NAMESPACE}-${SPIEL_VERSION}.typelib`;
+
+/** The namespace whose loaded typelib locates the host's own `girepository-1.0`. */
+const ANCHOR_NAMESPACE = 'GLib';
+
+/**
+ * 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;
+}
+
+/** girepository's two writable search paths, plus the reader the probe needs. */
+interface RepositoryPaths {
+    get_typelib_path(namespace: string): string | null;
+    prepend_search_path(directory: string): void;
+    prepend_library_path(directory: string): void;
+}
+
+interface GiWithRepository extends GiImportsView {
+    readonly versions?: Record<string, string>;
+}
+
+/** The host's `imports.gi`, or `undefined` off GJS. */
+function hostGi(): GiWithRepository | undefined {
+    return (globalThis as { imports?: { gi?: GiWithRepository } }).imports?.gi;
+}
+
+/** Directory part of a HOST path — both separators, since a win32 host uses `\`. */
+function directoryOf(path: string): string | null {
+    return /^(.*)[\\/][^\\/]*$/.exec(path)?.[1] ?? null;
+}
+
+function defaultRepository(gi: GiImportsView | undefined): RepositoryPaths | null {
+    try {
+        // `dup_default()` is GLib >= 2.86, probed as a capability: an older host
+        // simply keeps whatever precedence its environment already gives it, which
+        // is the behaviour before this module existed.
+        return (gi?.GIRepository?.Repository?.dup_default?.() as RepositoryPaths | undefined) ?? null;
+    } catch {
+        // `imports.gi.GIRepository` LOADS a namespace, and distributions ship that
+        // typelib apart from the girepository library GJS links against (Debian's
+        // `gir1.2-girepository-3.0` vs `libgirepository-2.0-0`).
+        return null;
+    }
+}
+
+/**
+ * Put the host's own typelib directory ahead of every prepended prebuild, when a
+ * system `Spiel-1.0.typelib` is really there.
+ *
+ * Conditional on the FILE, not on the directory: prepending unconditionally would
+ * reorder the search path for every other namespace in the process to no purpose,
+ * and a change with no effect is one nobody can reason about later.
+ *
+ * @returns the system typelib directory when it holds Spiel, else `null`
+ */
+function preferSystemSpiel(gi: GiImportsView | undefined, repository: RepositoryPaths | null): string | null {
+    const glib = gi?.GLib;
+    if (!repository || !glib) return null;
+    try {
+        const anchor = repository.get_typelib_path(ANCHOR_NAMESPACE);
+        const dir = anchor ? directoryOf(anchor) : null;
+        if (!dir) return null;
+        const separator = anchor?.includes('\\') && !anchor.includes('/') ? '\\' : '/';
+        if (!glib.file_test(`${dir}${separator}${SPIEL_TYPELIB}`, glib.FileTest.EXISTS)) return null;
+        repository.prepend_search_path(dir);
+        // The library too: a system libspiel in the default libdir resolves through
+        // ld.so anyway, but a host whose GI stack sits under its own prefix
+        // (`/opt/…`, jhbuild) has that libdir on neither path. `girLibraryDir` is
+        // the INSTALL layout — `<libdir>/girepository-1.0/` beside `<libdir>/`.
+        const libDir = directoryOf(dir);
+        if (libDir) repository.prepend_library_path(libDir);
+        return dir;
+    } catch {
+        // Every call is girepository reading state this process already holds; a
+        // host where it throws has no system preference to express, which leaves
+        // the prebuild — the state before this call.
+        return null;
+    }
+}
+
+let memo: SpielProbe | null = null;
+
+/**
+ * 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 function probeSpiel(options: ProbeSpielOptions = {}): SpielProbe {
+    if (memo && !options.fresh) return memo;
+
+    // `GiWithRepository` rather than `GiImportsView`: `imports.gi.versions` is a GJS
+    // property the shared view does not model, and an injected `gi` from a test is
+    // allowed to carry it too.
+    const gi: GiWithRepository | undefined = options.gi ?? hostGi();
+    const repository = defaultRepository(gi);
+    const systemDir = preferSystemSpiel(gi, repository);
+
+    // Pin the version before the namespace resolves. libspiel has published exactly
+    // one typelib version, so today this changes nothing; it is here so that a host
+    // which later has two does not silently get the other one, which is the failure
+    // `gi://Ns` without `?version=` is known for.
+    try {
+        if (gi?.versions) gi.versions[SPIEL_NAMESPACE] = SPIEL_VERSION;
+    } catch {
+        // A frozen or absent `versions` table is not a reason to stop looking.
+    }
+
+    const loaded = loadOptionalNativeModule<SpielNamespace>(
+        SPIEL_NAMESPACE,
+        // Touched after the library opens, so a namespace that resolved while its
+        // library did not reads as absent here rather than throwing at first use.
+        ['Speaker', 'Utterance'],
+        gi,
+    );
+
+    const typelibDir = (() => {
+        try {
+            const path = repository?.get_typelib_path(SPIEL_NAMESPACE) ?? null;
+            return path ? directoryOf(path) : null;
+        } catch {
+            return null;
+        }
+    })();
+
+    const probe: SpielProbe = loaded.module
+        ? {
+              // Compared against the directory we prepended, not against a path
+              // shape: "system" means THIS host's girepository-1.0, and that is the
+              // only directory anything here can say that about.
+              source: systemDir !== null && typelibDir === systemDir ? 'system' : 'prebuild',
+              module: loaded.module,
+              typelibDir,
+              reason: null,
+              error: null,
+          }
+        : {
+              source: 'absent',
+              module: null,
+              typelibDir,
+              reason: absentReason(loaded.error),
+              error: loaded.error,
+          };
+
+    if (!options.fresh) memo = probe;
+    return probe;
+}
+
+/**
+ * One sentence a user can act on.
+ *
+ * Three causes, and they need different sentences: not on GJS at all, no typelib
+ * anywhere, and a typelib whose library was found and refused. The third already
+ * carries the loader's own text (`NativeLibraryLoadError`), so it is passed through
+ * rather than summarised — the dependency it names is the actionable part.
+ */
+function absentReason(error: Error | null): string {
+    if (!error) return `${SPIEL_NAMESPACE}: not available, and nothing was measurable about why.`;
+    if (error.name === 'NativeLibraryLoadError') return error.message;
+    if (error.message.includes('imports.gi')) {
+        return `${SPIEL_NAMESPACE}: no GObject-Introspection in this process — @gjsify/spiel-native needs GJS or @gjsify/node-gi.`;
+    }
+    return (
+        `${SPIEL_NAMESPACE}-${SPIEL_VERSION}.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.'
+    );
+}
+
+/**
+ * {@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 function requireSpiel(options: ProbeSpielOptions = {}): SpielNamespace {
+    const probe = probeSpiel(options);
+    if (probe.module) return probe.module;
+    throw new Error(probe.reason ?? `${SPIEL_NAMESPACE}: not available.`, { cause: probe.error ?? undefined });
+}

package/src/ts/namespace.ts

@@ -0,0 +1,110 @@
+// The `gi://Spiel` surface, as types.
+//
+// HAND-WRITTEN rather than generated, on `@gjsify/gamepad`'s precedent
+// (`sdl-namespace.ts`): no `@girs/*` package binds Spiel-1.0 — there is no
+// `@girs/spiel-1.0` on npm — and the namespace is five classes. Read off the GIR
+// this package's own build produces, so a bump that changes the API changes this
+// file in the same commit.
+//
+// Deliberately INCOMPLETE where upstream is deprecated or unusable from JS:
+//
+//   · `Provider.get_well_known_name()` is deprecated since libspiel 1.0.4 and GJS
+//     prints a warning on every call. `identifier` is the same string and is not.
+//   · `Speaker:sink` is `introspectable="0"` in the GIR, so `speaker.sink = el`
+//     is a SILENT no-op in GJS. The only spelling that works is
+//     `set_property('sink', el)`, which lives on GObject.Object and therefore is
+//     not re-declared here — see README.md § No audible output.
+
+/** 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/subprojects/libspeechprovider.wrap

@@ -0,0 +1,23 @@
+# libspeechprovider (LGPL-2.1-or-later, docs/attribution.md) — the D-Bus
+# interface and audio-stream format shared by libspiel and every speech provider.
+# Linked STATICALLY into libspiel-1.0.so here, so this wrap produces no shipped
+# artifact of its own; see meson.build § ONE library.
+#
+# OUR OWN COPY, at the TOP LEVEL, and both halves of that are load-bearing:
+#
+#   · Top level, because libspiel resolves the interface XML through
+#     `meson.global_source_root() / 'subprojects' / 'libspeechprovider'`
+#     (libspiel/meson.build:111 at the pinned revision). A nested
+#     subprojects/libspiel/subprojects/libspeechprovider would need meson's
+#     subproject promotion to land in that path; declaring it here is the same
+#     result with nothing implicit.
+#   · Ours, because upstream's wrap says `revision = main` — an unpinned
+#     dependency makes the prebuild un-reproducible, which docs/prebuilds.md
+#     forbids. This is 1.0.3, the floor libspiel's `dependency()` requires.
+[wrap-git]
+directory = libspeechprovider
+url = https://github.com/project-spiel/libspeechprovider.git
+revision = 54b6013c2529e208e6a3385076e686fa1c71ef93
+
+[provide]
+dependency_names = speech-provider-1.0

package/subprojects/libspiel.wrap

@@ -0,0 +1,19 @@
+# libspiel — the Spiel speech-synthesis CLIENT library (LGPL-2.1-or-later,
+# docs/attribution.md). It talks D-Bus to speech providers, so this build exists
+# on Linux only; see README.md § What this is.
+#
+# PINNED TO A COMMIT, not a tag, and that is a measured choice rather than a
+# preference: the newest upstream tag is SPIEL_1_0_4 (2025-04-03), while
+# `meson.build` has said `version: '1.0.5'` since, and 1.0.4 predates the
+# subproject-tracking fix this build needs (libspiel's own meson.build copies the
+# provider interface XML through a custom_target for meson < 1.14.0). There is no
+# SPIEL_1_0_5 to pin. Bumping it: change `revision`, rebuild, re-run
+# `meson test -C build` (the ELF read-back asserts the exported symbol set) and
+# re-measure the prebuild size in README.md § Updating libspiel.
+#
+# No `depth`: a shallow clone can only fetch a commit the server offers as a tip,
+# and this revision is not one.
+[wrap-git]
+directory = libspiel
+url = https://github.com/project-spiel/libspiel.git
+revision = 7c88081b03ebb2903817cf101e4b9906052155c9

package/test/check-elf-deps.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""What `libspiel-1.0.so` links and exports, read back from the built file.
+
+Two claims meson.build makes, neither of which the build log can prove:
+
+  1. DT_NEEDED names only libc and the GNOME libraries the host provides
+     (GLib/GObject/GIO and GStreamer). libspeechprovider must NOT appear: it is
+     linked statically (meson.build § ONE library), and a NEEDED entry would mean
+     the prebuild is half a set and cannot load without a libspeechprovider
+     package — the one thing this build exists to avoid.
+  2. The dynamic symbol table exports only `spiel_*`. ELF has ONE flat symbol
+     namespace, and the statically linked libspeechprovider's seven
+     `speech_provider_*` functions would otherwise interpose on (or be
+     interposed by) the real `libspeechprovider.so` that a speech PROVIDER in the
+     same process links. Measured: 89/0 with src/c/spiel.map, 89/7 without.
+
+Prints both lists so the CI log carries the measurement, and exits 1 on any
+entry outside them. Uses `readelf` (binutils): the file format is the contract,
+not whatever meson was asked to do.
+"""
+import re
+import subprocess
+import sys
+
+# GStreamer is a load-time dependency here, unlike in the sibling bridges: Spiel
+# plays a provider's audio stream through a GStreamer pipeline, so libgstreamer,
+# libgstaudio and libgstbase are part of what `gi://Spiel` needs present.
+ALLOWED_NEEDED = re.compile(
+    r"^(libc\.so\.6|libm\.so\.6|libdl\.so\.2|libpthread\.so\.0|ld-linux[-\w.]*\.so\.\d+"
+    r"|libglib-2\.0\.so\.0|libgobject-2\.0\.so\.0|libgio-2\.0\.so\.0"
+    r"|libgstreamer-1\.0\.so\.0|libgstaudio-1\.0\.so\.0|libgstbase-1\.0\.so\.0)$"
+)
+
+# The Spiel API as of the pinned revision. A floor rather than an equality: a
+# libspiel bump that ADDS API must not fail this, while a version script that
+# stopped being applied (or a build that exported nothing) must.
+MIN_SPIEL_EXPORTS = 80
+
+
+def readelf(*args):
+    return subprocess.run(["readelf", "--wide", *args], check=True, capture_output=True, text=True).stdout
+
+
+def main(path):
+    needed = re.findall(r"\(NEEDED\)\s+Shared library: \[([^\]]+)\]", readelf("-d", path))
+    exported = []
+    for line in readelf("--dyn-syms", path).splitlines():
+        cols = line.split()
+        # Num: Value Size Type Bind Vis Ndx Name — defined (Ndx != UND), GLOBAL/WEAK.
+        if len(cols) >= 8 and cols[4] in ("GLOBAL", "WEAK") and cols[6] != "UND":
+            exported.append(cols[7].split("@")[0])
+
+    spiel = [s for s in exported if s.startswith("spiel_")]
+    other = [s for s in exported if not s.startswith("spiel_")]
+    print(f"{path}")
+    print(f"  NEEDED   ({len(needed)}): {', '.join(needed)}")
+    print(f"  exported ({len(exported)}): {len(spiel)} spiel_*" + (f", plus {other}" if other else ""))
+
+    problems = [f"NEEDED {n} is not an OS/GNOME library" for n in needed if not ALLOWED_NEEDED.match(n)]
+    problems += [f"exports {s}, which is not spiel_*" for s in other]
+    # An empty parse would pass everything above: the library links libc and
+    # exports the whole Spiel API, so neither list can be short.
+    if not needed or len(spiel) < MIN_SPIEL_EXPORTS:
+        problems.append(
+            f"parsed {len(needed)} NEEDED / {len(spiel)} spiel_* exports — "
+            "either the version script hid the API or readelf's format moved"
+        )
+    for p in problems:
+        print(f"  FAIL: {p}")
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1]))

package/test/load-typelib.gjs.js

@@ -0,0 +1,59 @@
+// The shipped PAIR under GJS: `Spiel-1.0.typelib` resolving, and the library it
+// names by bare leaf opening from beside it. The only two facts a prebuild has
+// to deliver — everything Spiel then does is upstream's.
+//
+// NOTHING HERE TOUCHES THE SESSION BUS, by design and not by caution:
+//
+//   · A `Spiel.Speaker` enumerates providers over D-Bus and asks each for its
+//     voices, which D-BUS-ACTIVATES them — this test would start speech-provider
+//     daemons on the machine running it, and would answer differently on a
+//     runner that has none. The live end-to-end check is `speak-fakesink.gjs.js`,
+//     opt-in behind GJSIFY_SPIEL_LIVE=1.
+//   · Registering the GObject TYPES is already the whole load question: every
+//     `*_get_type()` below is a symbol girepository has to find in
+//     `libspiel-1.0.so`, so a typelib naming a leaf that is not beside it, or a
+//     version script that hid the API, fails right here.
+//
+// Run by meson with GI_TYPELIB_PATH/LD_LIBRARY_PATH pointing at the build
+// directory, which is the one place all three artifacts sit together.
+
+import GObject from 'gi://GObject?version=2.0';
+import Spiel from 'gi://Spiel?version=1.0';
+
+/** @param {boolean} ok @param {string} what */
+function assert(ok, what) {
+    if (!ok) throw new Error(`FAIL: ${what}`);
+    console.log(`  ok  ${what}`);
+}
+
+// Resolving `gi://Spiel` loaded the TYPELIB only. Each `$gtype` read below runs
+// the type-init function out of the library, so this is where it opens.
+for (const name of ['Speaker', 'Utterance', 'Voice', 'Provider', 'VoicesListModel']) {
+    assert(typeof Spiel[name]?.$gtype === 'object', `Spiel.${name} registers its GType from libspiel-1.0.so`);
+}
+
+// A real call through the library, not just type registration: an Utterance is
+// a plain GObject with no bus and no provider behind it.
+const utterance = new Spiel.Utterance({ text: 'prebuild check', pitch: 1.0, rate: 1.0 });
+assert(utterance.text === 'prebuild check', 'Spiel.Utterance round-trips its text property');
+
+// THE SILENCE SWITCH, asserted rather than described. `Speaker:sink` is what
+// redirects synthesised audio away from the speakers (README.md § No audible
+// output); the property is marked `introspectable="0"` in the GIR, so
+// `speaker.sink = element` is a SILENT no-op in GJS and `set_property` is the
+// only spelling that works. What this checks is that the property is on the
+// class at all — if a libspiel bump removes it, every caller silently starts
+// playing out loud.
+//
+// `Spiel.Speaker.find_property` and not `GObject.type_class_ref(…)`: the latter
+// answers a boxed `GObject.TypeClass`, which carries none of `GObjectClass`'s
+// methods in GJS (`.find_property is not a function`). GJS puts the class-struct
+// methods on the CLASS instead, and they need no instance — which is the whole
+// point here, since a Speaker cannot be constructed without a session bus.
+assert(Spiel.Speaker.find_property('sink') !== null, 'Spiel.Speaker has the `sink` property');
+
+for (const signal of ['utterance-started', 'utterance-finished', 'utterance-error']) {
+    assert(GObject.signal_lookup(signal, Spiel.Speaker.$gtype) !== 0, `Spiel.Speaker emits \`${signal}\``);
+}
+
+console.log('load-typelib: Spiel-1.0.typelib resolved and libspiel-1.0.so opened beside it');