@gjsify/node-gi 0.13.0

package/globals.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi/globals — seed GJS's ambient globals on Node.
+//
+// GJS source relies on a handful of globals that exist implicitly under gjs:
+// `print` / `printerr` / `log` / `logError`, the `ARGV` array, and the legacy
+// `imports` object (`imports.gi.Gtk`, `imports.gi.versions`, `imports.system`,
+// `imports.gettext`, …). On Node these don't exist, so importing this module
+// (a side effect) installs Node-backed equivalents that route through the same
+// node-gi backend `gi://` uses. The gjsify `--app node` build injects this for
+// any bundle that references those globals; it is also importable directly.
+//
+// Reference: GJS's global definitions (gjs/modules/{print,system,gettext}). The
+// legacy `imports.*` namespace mirrors gjs/modules/esm/gi.js's require shape.
+import { requireGi } from './gi.js';
+
+// GJS stringifies each argument with String() and joins with a space (no
+// util.inspect object formatting) — match that for fidelity.
+function gjsFormat(args) {
+  return args.map((a) => String(a)).join(' ');
+}
+
+/**
+ * Install the GJS ambient globals on `globalThis` (idempotent — each global is
+ * only defined if absent, so it never clobbers a host that already provides it).
+ */
+export function installGjsGlobals() {
+  const g = globalThis;
+
+  if (typeof g.print === 'undefined') {
+    g.print = (...args) => console.log(gjsFormat(args));
+  }
+  if (typeof g.printerr === 'undefined') {
+    g.printerr = (...args) => console.error(gjsFormat(args));
+  }
+  if (typeof g.log === 'undefined') {
+    // GJS `log` writes to the GLib structured log (stderr/journal).
+    g.log = (...args) => console.error(gjsFormat(args));
+  }
+  if (typeof g.logError === 'undefined') {
+    g.logError = (error, prefix) => {
+      const head = prefix ? `${prefix}: ` : '';
+      const body = error && error.stack ? error.stack : String(error);
+      console.error(head + body);
+    };
+  }
+  if (typeof g.ARGV === 'undefined') {
+    // GJS ARGV excludes the interpreter + the script path (Node's argv[0]+[1]).
+    g.ARGV = (typeof process !== 'undefined' && Array.isArray(process.argv))
+      ? process.argv.slice(2)
+      : [];
+  }
+
+  if (typeof g.imports === 'undefined') {
+    g.imports = makeImports();
+  }
+
+  return g.imports;
+}
+
+// Build the legacy `imports` object. `imports.gi.<Ns>` resolves a namespace via
+// the node-gi backend, honouring a version pinned in `imports.gi.versions.<Ns>`
+// (which GJS code sets before the first access).
+function makeImports() {
+  const giVersions = Object.create(null);
+  const giCache = new Map();
+  const gi = new Proxy(
+    { versions: giVersions },
+    {
+      get(target, name) {
+        if (name === 'versions') return giVersions;
+        if (typeof name !== 'string') return target[name];
+        if (giCache.has(name)) return giCache.get(name);
+        const ns = requireGi(name, giVersions[name]);
+        giCache.set(name, ns);
+        return ns;
+      },
+      has(_target, name) {
+        return name === 'versions' || typeof name === 'string';
+      },
+    },
+  );
+
+  // Minimal `imports.system` — the most-used members (exit, gc, the program
+  // identity). Backed by Node's process where there is an equivalent.
+  const system = {
+    exit(code) {
+      if (typeof process !== 'undefined') process.exit(code ?? 0);
+    },
+    gc() {
+      if (typeof globalThis.gc === 'function') globalThis.gc();
+    },
+    get programInvocationName() {
+      return (typeof process !== 'undefined' && process.argv[1]) || '';
+    },
+    get programPath() {
+      return (typeof process !== 'undefined' && process.argv[1]) || null;
+    },
+    version: 0,
+    addressOf() {
+      return '0x0';
+    },
+    refcount() {
+      return 0;
+    },
+    breakpoint() {},
+    dumpHeap() {},
+    dumpMemoryInfo() {},
+  };
+
+  // Minimal `imports.gettext` — a no-translation passthrough (the strings are
+  // returned untranslated, which is the correct fallback when no catalog is
+  // bound). Mirrors the surface GJS apps call at module load.
+  const identity = (s) => s;
+  const gettext = {
+    gettext: identity,
+    dgettext: (_domain, s) => s,
+    dcgettext: (_domain, s) => s,
+    ngettext: (s, p, n) => (n === 1 ? s : p),
+    dngettext: (_domain, s, p, n) => (n === 1 ? s : p),
+    pgettext: (_ctx, s) => s,
+    dpgettext: (_domain, _ctx, s) => s,
+    domain: (_domain) => ({
+      gettext: identity,
+      ngettext: (s, p, n) => (n === 1 ? s : p),
+      pgettext: (_ctx, s) => s,
+    }),
+    setlocale: () => null,
+    bindtextdomain: () => null,
+    textdomain: () => null,
+    bindtextdomainCodeset: () => null,
+    LocaleCategory: { ALL: 6, COLLATE: 3, CTYPE: 0, MESSAGES: 5, MONETARY: 4, NUMERIC: 1, TIME: 2 },
+  };
+
+  return { gi, system, gettext, versions: Object.create(null) };
+}
+
+// Side effect on import: seed the globals.
+installGjsGlobals();
+
+export default installGjsGlobals;

package/index.d.ts

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi — public type surface (milestone 1: headless-core scaffold).
+
+/** Result of requiring a GObject-Introspection namespace. */
+export interface RequiredNamespace {
+  /** The namespace name, e.g. "GLib". */
+  namespace: string;
+  /** The resolved typelib version, e.g. "2.0". */
+  version: string;
+  /** Number of top-level introspection infos in the namespace. */
+  infoCount: number;
+}
+
+/**
+ * Require a GObject-Introspection namespace and report its resolved version and
+ * top-level info count. The Node twin of GJS's `gi://` / `imports.gi` load step.
+ */
+export function requireNamespace(namespace: string, version?: string): RequiredNamespace;
+
+/** Enumerate the top-level introspection-info names of an already-required namespace. */
+export function listInfoNames(namespace: string): string[];
+
+/** The introspection kind of a top-level namespace member. */
+export type InfoKind =
+  | 'function'
+  | 'object'
+  | 'interface'
+  | 'struct'
+  | 'union'
+  | 'enum'
+  | 'flags'
+  | 'constant'
+  | 'callback'
+  | 'other';
+
+/**
+ * Classify a top-level namespace member so the L1 wrapper can decide how to
+ * surface it (class vs function vs enum vs constant). Returns `null` when the
+ * name is not found in the namespace.
+ */
+export function findInfo(namespace: string, name: string): { kind: InfoKind } | null;
+
+/** Read a namespace-level GI constant (e.g. `GLib.PRIORITY_DEFAULT`). */
+export function getConstantValue(namespace: string, name: string): unknown;
+
+/**
+ * Enumerate an enum/flags type's members as `{ rawGiName: number }`. The L1
+ * wrapper re-keys them GJS-style (UPPER_CASE, `-` → `_`).
+ */
+export function getEnumValues(namespace: string, name: string): Record<string, number>;
+
+/** Prepend a directory to the GIRepository typelib search path. */
+export function prependSearchPath(path: string): void;
+
+/**
+ * Invoke a namespace-level GObject-Introspection function (not an instance
+ * method) with IN-only primitive/string arguments. Returns the marshalled
+ * return value. Milestone 1: numbers, booleans and strings.
+ */
+export function callFunction(namespace: string, functionName: string, args?: unknown[]): unknown;
+
+/**
+ * Invoke an instance method on a GObject handle with IN-only
+ * primitive/string/object/enum args. The method is resolved against the
+ * instance's introspection type (own + implemented-interface methods, then up
+ * the parent chain). The Node twin of `obj.method(...)`.
+ */
+export function callMethod(handle: GObjectHandle, methodName: string, args?: unknown[]): unknown;
+
+/**
+ * Invoke a type-level constructor/static function (e.g. `Gio.File.new_for_path`,
+ * `Gtk.Label.new`) — a function found on a type but taking no instance. The Node
+ * twin of `Ns.Class.method(...)`.
+ */
+export function callStaticMethod(
+  namespace: string,
+  typeName: string,
+  methodName: string,
+  args?: unknown[],
+): unknown;
+
+/**
+ * Opaque handle to a live GObject instance, owned by node-gi and released when
+ * the handle is garbage-collected. Pass it back to {@link getProperty} /
+ * {@link setProperty} / {@link getTypeName}.
+ */
+export type GObjectHandle = { readonly __nodeGiGObject: unique symbol };
+
+/**
+ * Construct a GObject of `namespace.typeName` with optional construct/settable
+ * properties. Milestone 1: fundamental-typed properties (numbers, booleans,
+ * strings, enums/flags).
+ */
+export function newObject(
+  namespace: string,
+  typeName: string,
+  props?: Record<string, unknown>,
+): GObjectHandle;
+
+/**
+ * Opaque handle to a registered GType (from {@link registerClass}). Pass it to
+ * {@link constructType}.
+ */
+export type TypeHandle = { readonly __nodeGiGType: unique symbol };
+
+/** A custom GObject property declaration for {@link registerClass}. */
+export interface PropertySpec {
+  /** Property name (canonical, e.g. "my-prop"). */
+  name: string;
+  /** Value type. */
+  type: 'string' | 'boolean' | 'int' | 'uint' | 'int64' | 'uint64' | 'double' | 'float';
+  /** `GParamFlags` bitfield (default `G_PARAM_READWRITE`). */
+  flags?: number;
+  /** Default value (type-appropriate). */
+  default?: string | number | boolean;
+  /** Minimum (numeric types). */
+  minimum?: number;
+  /** Maximum (numeric types). */
+  maximum?: number;
+}
+
+/** A custom GObject signal declaration for {@link registerClass}. */
+export interface SignalSpec {
+  /** Signal name (e.g. "my-signal"). */
+  name: string;
+  /** Parameter types (same vocabulary as {@link PropertySpec.type}, plus "object"). */
+  paramTypes?: string[];
+  /** Return type ("void" by default). */
+  returnType?: string;
+  /** `GSignalFlags` bitfield (default `G_SIGNAL_RUN_LAST`). */
+  flags?: number;
+}
+
+/**
+ * Custom vfunc overrides for a {@link registerClass} subtype: a map from a parent
+ * GObject vfunc name (e.g. `"constructed"`) to the JS function that overrides it.
+ * The override is invoked as a method on the instance — `this` is the GObject
+ * handle — with the vfunc's declared arguments as JS arguments, and its return is
+ * marshalled back to C. Chain-up to the parent vfunc lands in a later milestone,
+ * so an override fully replaces the inherited implementation.
+ */
+export type VFuncMap = Record<string, (this: GObjectHandle, ...args: unknown[]) => unknown>;
+
+/** Custom properties, signals + vfunc overrides installed on a {@link registerClass} subtype. */
+export interface RegisterClassOptions {
+  properties?: PropertySpec[];
+  signals?: SignalSpec[];
+  vfuncs?: VFuncMap;
+}
+
+/**
+ * Register a new GObject subclass of `parentNamespace.parentTypeName` named
+ * `name`, inheriting the parent's class/instance layout, and return an opaque
+ * type handle. `options` installs custom properties (backed by a per-instance
+ * value store), signals, and vfunc overrides (an ffi closure written into the new
+ * type's class vtable) in the new type's `class_init` — the Node twin of (the
+ * engine half of) GJS's `GObject.registerClass`. vfunc chain-up to the parent
+ * implementation lands in a later milestone.
+ */
+export function registerClass(
+  name: string,
+  parentNamespace: string,
+  parentTypeName: string,
+  options?: RegisterClassOptions,
+): TypeHandle;
+
+/**
+ * Construct a GObject of a registered type handle (from {@link registerClass})
+ * with optional construct/settable properties.
+ */
+export function constructType(typeHandle: TypeHandle, props?: Record<string, unknown>): GObjectHandle;
+
+/** Read a GObject property. */
+export function getProperty(handle: GObjectHandle, name: string): unknown;
+
+/** Write a GObject property. */
+export function setProperty(handle: GObjectHandle, name: string, value: unknown): void;
+
+/**
+ * Whether the instance's type has a GObject property by this name (kebab- or
+ * snake-case). The L1 wrapper uses it to route `obj.foo` to a property read vs
+ * an `obj.foo()` method call.
+ */
+export function hasProperty(handle: GObjectHandle, name: string): boolean;
+
+/** The runtime GType name of a GObject handle (e.g. "GSimpleAction"). */
+export function getTypeName(handle: GObjectHandle): string;
+
+/**
+ * Whether `value` is one of node-gi's GObject-instance handles (tag-checked, no
+ * dereference). Lets the L1 wrapper wrap object-typed return values for chaining
+ * without misclassifying a {@link TypeHandle}.
+ */
+export function isGObjectHandle(value: unknown): boolean;
+
+/**
+ * Opaque handle to a boxed/struct instance (e.g. a GMainLoop), owned by node-gi
+ * and released when garbage-collected (a fully-owned boxed is `g_boxed_free`d).
+ * Pass it to {@link callBoxedMethod}.
+ */
+export type BoxedHandle = { readonly __nodeGiBoxed: unique symbol };
+
+/**
+ * Invoke an instance method on a boxed/struct handle (e.g. `mainLoop.run()` /
+ * `mainLoop.quit()`). The method is resolved against the boxed GType's
+ * introspection info and invoked with the boxed pointer as the instance.
+ */
+export function callBoxedMethod(handle: BoxedHandle, methodName: string, args?: unknown[]): unknown;
+
+/**
+ * Whether `value` is one of node-gi's boxed/struct handles (tag-checked, no
+ * dereference). The L1 wrapper uses it to wrap boxed return values with a
+ * method-routing proxy.
+ */
+export function isBoxedHandle(value: unknown): boolean;
+
+/**
+ * Attach the libuv-backed GSource to the default GLib main context so a blocking
+ * GLib main loop (`GLib.MainLoop.run()`, `Gio.Application.run()`) keeps Node's
+ * timers, promises and I/O alive — the Node twin of GJS running the GLib loop as
+ * the process loop. Idempotent and harmless until a GLib loop actually runs.
+ */
+export function startMainLoop(): void;
+
+/**
+ * Connect a JS callback to a GObject signal; returns a handler id. The callback
+ * receives the signal arguments (the emitter instance is not passed in this
+ * milestone).
+ */
+export function connectSignal(
+  handle: GObjectHandle,
+  signalName: string,
+  callback: (...args: unknown[]) => unknown,
+  after?: boolean,
+): number;
+
+/** Emit a signal; returns the signal's return value (undefined for void signals). */
+export function emitSignal(handle: GObjectHandle, signalName: string, args?: unknown[]): unknown;
+
+/** Disconnect a previously connected signal handler. */
+export function disconnectSignal(handle: GObjectHandle, handlerId: number): void;
+
+declare const native: {
+  requireNamespace: typeof requireNamespace;
+  listInfoNames: typeof listInfoNames;
+  findInfo: typeof findInfo;
+  getConstantValue: typeof getConstantValue;
+  getEnumValues: typeof getEnumValues;
+  prependSearchPath: typeof prependSearchPath;
+  callFunction: typeof callFunction;
+  callMethod: typeof callMethod;
+  callStaticMethod: typeof callStaticMethod;
+  newObject: typeof newObject;
+  registerClass: typeof registerClass;
+  constructType: typeof constructType;
+  getProperty: typeof getProperty;
+  setProperty: typeof setProperty;
+  hasProperty: typeof hasProperty;
+  getTypeName: typeof getTypeName;
+  isGObjectHandle: typeof isGObjectHandle;
+  callBoxedMethod: typeof callBoxedMethod;
+  isBoxedHandle: typeof isBoxedHandle;
+  startMainLoop: typeof startMainLoop;
+  connectSignal: typeof connectSignal;
+  emitSignal: typeof emitSignal;
+  disconnectSignal: typeof disconnectSignal;
+};
+export default native;

package/index.js

@@ -0,0 +1,261 @@
+// SPDX-License-Identifier: MIT
+// @gjsify/node-gi — thin ESM loader for the native GObject-Introspection addon.
+//
+// Reference: refs/node-gtk (romgrk, MIT). Hand-authored loader shim — a native
+// package's JS entry is a loader, not a tsc artifact, and the repo ignores
+// `lib/`, so it lives at the package root. The native binary is built by
+// node-gyp into build/{Release,Debug}.
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const here = dirname(fileURLToPath(import.meta.url)); // package root
+
+function loadNative() {
+  const candidates = [
+    join(here, 'build', 'Release', 'node_gi.node'),
+    join(here, 'build', 'Debug', 'node_gi.node'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return require(candidate);
+  }
+  throw new Error(
+    '@gjsify/node-gi: native addon not built. Run `node-gyp rebuild` in ' +
+      here +
+      ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers).',
+  );
+}
+
+const native = loadNative();
+
+/**
+ * Require a GObject-Introspection namespace and report its resolved version
+ * and top-level info count. The Node twin of GJS's gi:// / imports.gi load step.
+ * @param {string} namespace e.g. "GLib"
+ * @param {string} [version] e.g. "2.0" (omit to let GIRepository resolve)
+ * @returns {{ namespace: string, version: string, infoCount: number }}
+ */
+export const requireNamespace = native.requireNamespace;
+
+/**
+ * Enumerate the top-level introspection-info names of an already-required namespace.
+ * @param {string} namespace
+ * @returns {string[]}
+ */
+export const listInfoNames = native.listInfoNames;
+
+/**
+ * Classify a top-level namespace member (so the L1 wrapper knows whether it is a
+ * constructible class, a callable function, an enum, a constant, …). Returns
+ * `null` when the name is not found.
+ * @param {string} namespace
+ * @param {string} name
+ * @returns {{ kind: 'function'|'object'|'interface'|'struct'|'union'|'enum'|'flags'|'constant'|'callback'|'other' } | null}
+ */
+export const findInfo = native.findInfo;
+
+/**
+ * Read a namespace-level GI constant (e.g. `GLib.PRIORITY_DEFAULT`) and marshal
+ * it to a JS value.
+ * @param {string} namespace
+ * @param {string} name
+ * @returns {unknown}
+ */
+export const getConstantValue = native.getConstantValue;
+
+/**
+ * Enumerate an enum/flags type's members as `{ rawGiName: number }` (the L1
+ * wrapper re-keys them GJS-style: UPPER_CASE with `-` → `_`).
+ * @param {string} namespace
+ * @param {string} name
+ * @returns {Record<string, number>}
+ */
+export const getEnumValues = native.getEnumValues;
+
+/**
+ * Prepend a directory to the GIRepository typelib search path (call before
+ * requireNamespace for non-system typelibs).
+ * @param {string} path
+ * @returns {void}
+ */
+export const prependSearchPath = native.prependSearchPath;
+
+/**
+ * Invoke a namespace-level GObject-Introspection function (not an instance
+ * method) with IN-only primitive/string arguments. The first marshalling slice;
+ * instance methods, OUT/INOUT params and compound types follow.
+ * @param {string} namespace e.g. "GLib"
+ * @param {string} functionName e.g. "get_host_name"
+ * @param {unknown[]} [args]
+ * @returns {unknown}
+ */
+export const callFunction = native.callFunction;
+
+/**
+ * Invoke an instance method on a GObject handle with IN-only
+ * primitive/string/object/enum args. The method is resolved against the
+ * instance's introspection type (own + implemented-interface methods, then up
+ * the parent chain) — the Node twin of `obj.method(...)`.
+ * @param {unknown} handle a handle from {@link newObject}
+ * @param {string} methodName GI method name, e.g. "get_name"
+ * @param {unknown[]} [args]
+ * @returns {unknown}
+ */
+export const callMethod = native.callMethod;
+
+/**
+ * Invoke a type-level constructor/static function (e.g. `Gio.File.new_for_path`,
+ * `Gtk.Label.new`) — a function found on a type but taking no instance. The Node
+ * twin of `Ns.Class.method(...)`.
+ * @param {string} namespace e.g. "Gio"
+ * @param {string} typeName e.g. "File"
+ * @param {string} methodName e.g. "new_for_path"
+ * @param {unknown[]} [args]
+ * @returns {unknown}
+ */
+export const callStaticMethod = native.callStaticMethod;
+
+/**
+ * Construct a GObject of `namespace.typeName` with optional construct/settable
+ * properties, returning an opaque handle owned by node-gi (released on GC).
+ * @param {string} namespace e.g. "Gio"
+ * @param {string} typeName e.g. "SimpleAction"
+ * @param {Record<string, unknown>} [props]
+ * @returns {unknown} opaque GObject handle
+ */
+export const newObject = native.newObject;
+
+/**
+ * Register a new GObject subclass of `parentNamespace.parentTypeName` named
+ * `name`, inheriting the parent's class/instance layout, and return an opaque
+ * type handle. Construct instances of it with {@link constructType}. The optional
+ * `options` installs custom properties (backed by a per-instance value store),
+ * signals, and vfunc overrides in the new type's `class_init` — the Node twin of
+ * (the engine half of) GJS's `GObject.registerClass`. A `vfuncs` entry maps a
+ * parent vfunc name (e.g. `constructed`) to a JS function that overrides it; the
+ * override runs as a method on the instance (`this` is the GObject handle). vfunc
+ * chain-up to the parent implementation lands in a later milestone.
+ * @param {string} name unique GType name, e.g. "MyAction"
+ * @param {string} parentNamespace e.g. "Gio"
+ * @param {string} parentTypeName e.g. "SimpleAction"
+ * @param {{ properties?: Array<{name:string,type:string,flags?:number,default?:unknown,minimum?:number,maximum?:number}>, signals?: Array<{name:string,paramTypes?:string[],returnType?:string,flags?:number}>, vfuncs?: Record<string, (...args: unknown[]) => unknown> }} [options]
+ * @returns {unknown} opaque type handle
+ */
+export const registerClass = native.registerClass;
+
+/**
+ * Construct a GObject of a registered type handle (from {@link registerClass})
+ * with optional construct/settable properties, returning an owned handle.
+ * @param {unknown} typeHandle a handle from {@link registerClass}
+ * @param {Record<string, unknown>} [props]
+ * @returns {unknown} opaque GObject handle
+ */
+export const constructType = native.constructType;
+
+/**
+ * Read a GObject property.
+ * @param {unknown} handle a handle from {@link newObject}
+ * @param {string} name property name (kebab- or snake-case as GObject expects)
+ * @returns {unknown}
+ */
+export const getProperty = native.getProperty;
+
+/**
+ * Write a GObject property.
+ * @param {unknown} handle a handle from {@link newObject}
+ * @param {string} name property name
+ * @param {unknown} value
+ * @returns {void}
+ */
+export const setProperty = native.setProperty;
+
+/**
+ * Whether the instance's type has a GObject property by this name (kebab- or
+ * snake-case). The L1 wrapper uses it to route `obj.foo` to a property read vs
+ * an `obj.foo()` method call.
+ * @param {unknown} handle
+ * @param {string} name
+ * @returns {boolean}
+ */
+export const hasProperty = native.hasProperty;
+
+/**
+ * The runtime GType name of a GObject handle (e.g. "GSimpleAction").
+ * @param {unknown} handle
+ * @returns {string}
+ */
+export const getTypeName = native.getTypeName;
+
+/**
+ * Whether `value` is one of node-gi's GObject-instance handles (tag-checked, no
+ * dereference). Lets the L1 wrapper wrap object-typed return values for chaining
+ * without misclassifying a registerClass type handle.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isGObjectHandle = native.isGObjectHandle;
+
+/**
+ * Invoke an instance method on a boxed/struct handle (e.g. `mainLoop.run()` /
+ * `mainLoop.quit()`). The method is resolved against the boxed GType's
+ * introspection info and invoked with the boxed pointer as the instance.
+ * @param {unknown} handle a boxed handle (e.g. from `GLib.MainLoop.new(...)`)
+ * @param {string} methodName GI method name, e.g. "run"
+ * @param {unknown[]} [args]
+ * @returns {unknown}
+ */
+export const callBoxedMethod = native.callBoxedMethod;
+
+/**
+ * Whether `value` is one of node-gi's boxed/struct handles (tag-checked, no
+ * dereference). The L1 wrapper uses it to wrap boxed return values (GMainLoop,
+ * …) with a method-routing proxy.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export const isBoxedHandle = native.isBoxedHandle;
+
+/**
+ * Attach the libuv-backed GSource to the default GLib main context so a blocking
+ * GLib main loop (`GLib.MainLoop.run()`, `Gio.Application.run()`) keeps Node's
+ * timers, promises and I/O alive — the Node twin of GJS running the GLib loop as
+ * the process loop. Idempotent and harmless until a GLib loop actually runs (it
+ * adds no libuv handle, so it neither keeps Node alive nor pumps libuv on its
+ * own). The L1 layer calls it once when a namespace is first required.
+ * @returns {void}
+ */
+export const startMainLoop = native.startMainLoop;
+
+/**
+ * Connect a JS callback to a GObject signal. Returns a handler id for
+ * {@link disconnectSignal}. The callback receives the signal arguments
+ * (the emitter instance is not passed in this milestone).
+ * @param {unknown} handle a handle from {@link newObject}
+ * @param {string} signalName
+ * @param {(...args: unknown[]) => unknown} callback
+ * @param {boolean} [after] connect in the "after" phase
+ * @returns {number} handler id
+ */
+export const connectSignal = native.connectSignal;
+
+/**
+ * Emit a signal on a GObject with optional arguments; returns the signal's
+ * return value (or undefined for void signals).
+ * @param {unknown} handle
+ * @param {string} signalName
+ * @param {unknown[]} [args]
+ * @returns {unknown}
+ */
+export const emitSignal = native.emitSignal;
+
+/**
+ * Disconnect a previously connected signal handler.
+ * @param {unknown} handle
+ * @param {number} handlerId from {@link connectSignal}
+ * @returns {void}
+ */
+export const disconnectSignal = native.disconnectSignal;
+
+export default native;