@gjsify/adwaita-gobject-native 0.0.0-stage → 0.60.0

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# @gjsify/adwaita-gobject-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.
+Real GObject behind `@gjsify/adwaita-core`'s GObject subset (ADR 0105): a `GObjectEngine` whose
+property store, `notify`, signal bus, emission-stopping and `bind_property` are a live GObject,
+reached through `@gjsify/node-gi` (ADR 0104).
+
+```ts
+import { createGObject } from '@gjsify/adwaita-core';
+import { createRealGioEngine } from '@gjsify/adwaita-gobject-native';
+
+const GObject = createGObject(door, createRealGioEngine(requireGi));
+```
+
+`requireGi` is `@gjsify/node-gi/gi`'s loader — injected, not imported, so this package names the
+bridge nowhere: a static import of a non-workspace member fails `build:types` on every job that
+has not linked it, and a dynamic `gi://` load would mis-declare the package's runtime triplet in
+`scripts/audit-runtimes.mjs`. GJS's own `imports.gi` answers the same calls.
+
+## What the engine does and does not own
+
+The engine is a value store and a signal bus, nothing else. `registerClass`'s refusals, the
+accessor rule, the construct order and every error message stay in `@gjsify/adwaita-core` — so a
+class the subset refuses is refused here identically, and the vectors of `GOBJECT_VECTORS` that
+decide a refusal hold unchanged. What the engine can change is only what a read, a write and an
+emission DO.
+
+- A registered subset class gets a real GType; each instance gets one real instance of it, its
+  **twin**, held beside the instance and keyed by it. The twins mirror the subset's own class
+  chain. A handler is always called with the INSTANCE, never with the twin, and a `notify::`
+  handler gets the SUBSET's `ParamSpec`.
+- The twin declares every property `READWRITE`, including the construct-only ones: after the twin
+  exists, the only writer left is the engine itself, from the core's `defineConstructOnly`.
+  Construct-only is still enforced — by the core, on the same vector.
+- `setValue` tells the core it owes no `notify`: `g_object_set_property` already emitted one to
+  the handlers connected to the twin.
+- GType names are suffixed per registration (`<name>_RealGio<n>`). A GType name is process-global
+  and a duplicate throws, while the vectors register the same class names on every subject.
+- `bind` makes a real `GBinding` when both sides have twins, and falls back to the core's portable
+  `bindProperties` when either side is a door widget the engine never registered.
+
+## The portable list model in a real `Gio.ListStore`
+
+```ts
+import { createRealGioListStore } from '@gjsify/adwaita-gobject-native';
+
+const model = createRealGioListStore(requireGi);
+model.onItemsChanged(({ position, removed, added }) => redrawRange(position, removed, added));
+model.setModel([{ value: 'a', label: 'A' }]); // → { position: 0, removed: 0, added: 1 }
+model.store; // a real GListModel — what `Adw.ComboRow:model` / `Gtk.DropDown:model` take
+```
+
+`@gjsify/adwaita-core`'s `listItemsChanged` computes the ONE minimal splice from the old model to
+the new one (ADR 0046), which is `g_list_store_splice`'s shape. This hands that splice to the real
+store: the arithmetic, the item vocabulary and the equality rule stay the core's, and nothing here
+decides anything. Items outside the splice carry over as the same item objects, which is what the
+vectors' `survivors` counts — here counted off the live store by identity rather than derived.
+
+**The `null` `listItemsChanged` returns for an equal model is load-bearing, and the real store is
+what shows it.** `g_list_store_splice` emits `items-changed` UNCONDITIONALLY: a `splice(1, 0, [])`
+emits `(1, 0, 0)` — a change of nothing that every listener must re-read the model for (measured,
+GLib 2.86 through node-gi). So "an equal model emits nothing, as GTK does" is kept by not splicing,
+never by splicing zeros; in pure JS the two are the same no-op.
+
+## What is measured
+
+`src/engine.node-gi.spec.ts` drives all 24 rows of `@gjsify/adwaita-core/conformance`'s
+`GOBJECT_VECTORS` against `createGObject(door, createRealGioEngine(requireGi))` under Node:
+
+```sh
+gjsify workspace @gjsify/adwaita-gobject-native run test:gjs-on-node
+```
+
+Unlike the oracle leg in `adwaita-core` (`isOracle: true`, which skips the seven `holds: 'subset'`
+rows because real GObject accepts what the subset refuses), this subject IS the subset, so the
+refusals run too — they are the one claim an engine swap could silently break. The four
+`widget: true` rows run as well: the door is the same two-fake-widget door `gobject.spec.ts` uses,
+so no display is involved.
+
+`src/list-store.node-gi.spec.ts` drives every row of `LIST_ITEMS_CHANGED_VECTORS` through a real
+store on the same leg, asserting the three numbers, that there is exactly ONE emission, and that
+the store then reads as the new model with `survivors` items carried over by identity.
+
+Both subjects run in CI in `node-gi.yml`'s `gtk-host-node` job, beside the stage-0 ORACLE leg that
+drives the same `GOBJECT_VECTORS` against node-gi directly. The pair is the point: the oracle says
+what the right answer is on this binding, this package says the subset still gives it with a real
+store underneath.
+
+## What is NOT measured
+
+Nothing here has run on Android. `@gjsify/adwaita-nativescript`'s `createGObject(door)` does not
+pass this engine yet, and the reason is in a comment at that call: the line is evaluated at module
+load, so a `requireGi` that throws on NativeScript's V8 would take an app down at startup, and
+whether node-gi loads there at all is ADR 0105's own open question. The evidence for everything
+above is node-gi on Linux.
+
+## Runtimes
+
+`nativescript: 'native'` is the target — this is where real GObject reaches Android. The `node`
+slot is `'polyfill'` rather than `'none'`, which is an exception to the convention in
+[AGENTS.md](../AGENTS.md): node-gi makes the engine measurable on Linux CI, and a leg that cannot
+run is a claim nobody checks.

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

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{bindProperties as e}from"@gjsify/adwaita-core";const t={gchararray:`string`,gboolean:`boolean`,gint:`int`,guint:`uint`,gdouble:`double`},n={bidirectional:`BIDIRECTIONAL`,"sync-create":`SYNC_CREATE`,"invert-boolean":`INVERT_BOOLEAN`},r={int:[-2147483648,2147483647],uint:[0,4294967295],double:[-Number.MAX_VALUE,Number.MAX_VALUE]};function aliasesOf(e){return[e,e.replace(/-/g,`_`),e.replace(/-([a-z])/g,(e,t)=>t.toUpperCase())]}function createRealGioEngine(i){let a=i(`GObject`,`2.0`),o=a.ParamFlags.READWRITE,s=new WeakMap,c=new WeakMap,l=new WeakMap,u=new WeakMap,d=new WeakMap,f=new WeakMap,p=0;function touch(e,t){let n=f.get(e);n||f.set(e,n=new Set);let r=!n.has(t);return n.add(t),r}function uniqueTypeName(e){return`${e.replace(/[^A-Za-z0-9_+-]/g,`_`).replace(/^[^A-Za-z_]/,`_`)||`_`}_RealGio${++p}`}function paramSpecFor(e){let{name:t,nick:n,blurb:i}=e,s=e.kind===`string`||e.kind===`boolean`?void 0:r[e.kind],c=e.minimum??s?.[0]??0,l=e.maximum??s?.[1]??0,u=e.get_default_value();switch(e.kind){case`boolean`:return a.ParamSpec.boolean(t,n,i,o,u);case`string`:return a.ParamSpec.string(t,n,i,o,u??void 0);case`int`:return a.ParamSpec.int(t,n,i,o,c,l,u);case`uint`:return a.ParamSpec.uint(t,n,i,o,c,l,u);case`double`:return a.ParamSpec.double(t,n,i,o,c,l,u)}}function signalTypeOf(e){let n=t[e.name];if(n===void 0)throw TypeError(`real-gio engine: no GObject signal parameter type for '${e.name}'`);return n}function parentTwinOf(e){for(let t=Object.getPrototypeOf(e);typeof t==`function`;){let e=s.get(t);if(e)return e;t=Object.getPrototypeOf(t)}return a.Object}function registeredChainOf(e){let t=[];for(let n=e.constructor;typeof n==`function`;){let e=c.get(n);e&&t.push(e),n=Object.getPrototypeOf(n)}return t}function twinClassOf(e){for(let t=e.constructor;typeof t==`function`;){let e=s.get(t);if(e)return e;t=Object.getPrototypeOf(t)}}function twinOf(e){let t=l.get(e);if(t)return t;let n=twinClassOf(e);if(!n){let t=e.constructor?.name??String(e);throw Error(`real-gio engine: '${t}' was never registered against this engine`)}let r=new n;return l.set(e,r),r}function specOf(e,t){for(let n of registeredChainOf(e))for(let e of n.properties)if(e.name===t)return e}function canonicalPropertyOf(e,t){for(let n of registeredChainOf(e))for(let e of n.properties)if(aliasesOf(e.name).includes(t))return e.name;return t}function withEmission(e,t,n){let r=d.get(e);r||d.set(e,r=[]),r.push({key:t,stopped:!1});try{n()}finally{r.pop()}}return{name:`real-gio`,register(e){let t=parentTwinOf(e.klass),n={};for(let t of e.properties)n[t.name]=paramSpecFor(t);let r={};for(let[t,n]of Object.entries(e.signals))r[t]={param_types:n.map(signalTypeOf)};s.set(e.klass,a.registerClass({GTypeName:uniqueTypeName(e.typeName),Properties:n,Signals:r},class extends t{})),c.set(e.klass,e)},getValue(e,t){let n=twinOf(e);return touch(e,t.name),n[t.name]},setValue(e,t,n){let r=twinOf(e);return!touch(e,t.name)&&r[t.name]===n||withEmission(e,`notify::${t.name}`,()=>{r.set_property(t.name,n)}),!1},addHandler(e,t,n,r){let i=twinOf(e),a=n.startsWith(`notify::`)?specOf(e,n.slice(8)):void 0,o=i.connect(n,(t,...n)=>a===void 0?r(e,...n):r(e,a)),s=u.get(e);s||u.set(e,s=new Map),s.set(t,o)},removeHandler(e,t){let n=u.get(e),r=n?.get(t);return r===void 0?!1:(n.delete(t),twinOf(e).disconnect(r),!0)},emit(e,t,n){withEmission(e,t,()=>{twinOf(e).emit(t,...n)})},notify(e,t){withEmission(e,`notify::${t.name}`,()=>{twinOf(e).notify(t.name)})},stopEmission(e,t){let n=d.get(e)??[];for(let r=n.length-1;r>=0;r--){let i=n[r];if(i.key===t&&!i.stopped)return i.stopped=!0,a.signal_stop_emission_by_name(twinOf(e),t),!0}return!1},bind(t,r,i,o,s){if(!twinClassOf(t)||!twinClassOf(i))return e(t,r,i,o,s);let c=s.reduce((e,t)=>e|(a.BindingFlags[n[t]]??0),a.BindingFlags.DEFAULT??0),l=twinOf(t).bind_property(canonicalPropertyOf(t,r),twinOf(i),canonicalPropertyOf(i,o),c);return{unbind:()=>l.unbind()}}}}export{createRealGioEngine};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{createRealGioEngine as e}from"./engine.js";import{useRealGObjectEngine as t}from"./opt-in.js";import{createRealGioListStore as n}from"./list-store.js";import{SUBSET_SUBJECT_NAME as r,createSubsetSubject as i}from"./vector-subject.js";export{r as SUBSET_SUBJECT_NAME,e as createRealGioEngine,n as createRealGioListStore,i as createSubsetSubject,t as useRealGObjectEngine};

package/lib/esm/list-store.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{listItemsChanged as e}from"@gjsify/adwaita-core";let t=0;function createRealGioListStore(n){let r=n(`GObject`,`2.0`),i=n(`Gio`,`2.0`),a=r.ParamFlags.READWRITE,o=r.registerClass({GTypeName:`AdwPortableListItem_RealGio${++t}`,Properties:{value:r.ParamSpec.string(`value`,`Value`,`The value the item is addressed by`,a,``),label:r.ParamSpec.string(`label`,`Label`,`The text the item draws`,a,``)}},class AdwPortableListItem extends r.Object{}),s=new i.ListStore({item_type:o.$gtype});function read(){let e=[];for(let t=0;t<s.get_n_items();t++){let n=s.get_item(t);n&&e.push({value:n.value,label:n.label})}return e}return{store:s,read,setModel(t){let n=e(read(),t??[]);if(!n)return null;let r=(t??[]).slice(n.position,n.position+n.added).map(({value:e,label:t})=>new o({value:e,label:t}));return s.splice(n.position,n.removed,r),n},onItemsChanged(e){let t=s.connect(`items-changed`,(t,n,r,i)=>e({position:n,removed:r,added:i}));return()=>s.disconnect(t)}}}export{createRealGioListStore};

package/lib/esm/opt-in.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{createRealGioEngine as e}from"./engine.js";import{registerGObjectEngine as t}from"@gjsify/adwaita-core";function useRealGObjectEngine(n){let r;try{r=e(n)}catch(e){let t=Error(`useRealGObjectEngine: real GObject is not reachable, so the opt-in cannot be honoured. requireGi('GObject', '2.0') failed — the app opted in but '@gjsify/gi-runtime-android' did not deliver: check that it is a dependency of the app, that the APK carries 'lib/<abi>/libnode_gi.so' for this device's ABI, and that NativeScript extracted 'app/girepository-1.0' into the app's files dir. Remove the opt-in to run on pure JS.`);throw t.cause=e,t}return t(r),r}export{useRealGObjectEngine};

package/lib/esm/vector-subject.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{createGObject as e}from"@gjsify/adwaita-core";const t=`adwaita-core on real GObject (node-gi engine)`;function createSubsetSubject(n,r=t){let i,a,o=e({name:`test door`,dispatch(e,t){throw Error(`test door: nothing to dispatch '${t}' on`)},listen(e,t){throw Error(`test door: nothing to listen '${t}' on`)},createFromTree(e,t){let n={},byId=e=>e===`template`?t.instance:n[e],build=e=>{let r=e.tag===`GtkSwitch`?i:e.tag===`GtkButton`?a:void 0;if(!r)throw Error(`test door: no fake widget for ${e.tag}`);let o=new r;e.id!==void 0&&(n[e.id]=o);for(let n of e.signals??[])o.connect(n.name,t.handler(n.handler,{flags:n.flags}));for(let[n,r]of Object.entries(e.bindings??{})){let e=[];r.flags?.includes(`bidirectional`)&&e.push(`bidirectional`),r.flags?.includes(`inverted`)&&e.push(`invert-boolean`),r.flags?.includes(`no-sync-create`)||e.push(`sync-create`),t.bind(byId(r.source),r.property,o,n,e)}return o};return{children:(e.children??[]).map(build),objects:n}},attach(){},register(){}},n),{ParamSpec:s,ParamFlags:c}=o;return i=o.registerClass({GTypeName:`FakeSwitch`,Properties:{active:s.boolean(`active`,``,``,c.READWRITE,!1)}},class extends o.Object{}),a=o.registerClass({GTypeName:`FakeButton`,Signals:{clicked:{param_types:[]}}},class extends o.Object{}),{name:r,isOracle:!1,GObject:o,Widget:o.Object,template:e=>e.tree,bind:(e,t,r,i,a)=>{n.bind(e,t,r,i,a)}}}export{t as SUBSET_SUBJECT_NAME,createSubsetSubject};

package/lib/types/engine.d.ts

@@ -0,0 +1,14 @@
+import type { GObjectEngine } from '@gjsify/adwaita-core';
+/**
+ * `@gjsify/node-gi/gi`'s default export, as much of it as this engine uses. Declared rather than
+ * imported for the reason in the header — the bridge's own types are not resolvable in a job that
+ * has not linked it.
+ */
+export type RequireGi = (namespace: string, version?: string) => unknown;
+/**
+ * A real {@link GObjectEngine}: every registered class gets a GType, every instance a GObject.
+ *
+ * `requireGi` is `@gjsify/node-gi/gi`'s loader (or anything GJS-shaped — `imports.gi` answers the
+ * same calls), so the only thing this package needs of the bridge is handed to it.
+ */
+export declare function createRealGioEngine(requireGi: RequireGi): GObjectEngine;

package/lib/types/engine.node-gi.spec.d.ts

@@ -0,0 +1,2 @@
+import { type RequireGi } from './engine.js';
+export declare const realGioEngineSuite: (requireGi: RequireGi) => () => Promise<void>;

package/lib/types/index.d.ts

@@ -0,0 +1,6 @@
+export { useRealGObjectEngine } from './opt-in.js';
+export { createRealGioEngine } from './engine.js';
+export type { RequireGi } from './engine.js';
+export { createRealGioListStore } from './list-store.js';
+export type { RealGioListStore } from './list-store.js';
+export { createSubsetSubject, SUBSET_SUBJECT_NAME } from './vector-subject.js';

package/lib/types/list-store.d.ts

@@ -0,0 +1,29 @@
+import type { AdwComboOption, AdwListItemsChanged, AdwListModel } from '@gjsify/adwaita-core';
+import type { RequireGi } from './engine.js';
+/** The portable list model, stored in a real `Gio.ListStore`. */
+export interface RealGioListStore {
+    /**
+     * The real `Gio.ListStore`. This is the value a GTK widget's `model` property takes — handed
+     * out untyped because the typed one would need `@girs/gio-2.0`, which this package does not
+     * depend on for the reason `engine.ts`'s header gives.
+     */
+    readonly store: unknown;
+    /** The store's content, read back OUT of it as portable items. */
+    read(): AdwComboOption[];
+    /**
+     * Replace the content with `next` and answer the one `items-changed` the store emitted, or
+     * `null` when nothing was spliced because the two models are equal.
+     *
+     * Items outside the splice carry over as the SAME item objects: a consumer holding an item
+     * view per item keeps it, which is what the portable vectors' `survivors` counts.
+     */
+    setModel(next: AdwListModel | null | undefined): AdwListItemsChanged | null;
+    /** Subscribe to the store's REAL `items-changed`; the returned function disconnects. */
+    onItemsChanged(handler: (change: AdwListItemsChanged) => void): () => void;
+}
+/**
+ * A portable list model whose store is a real `Gio.ListStore`.
+ *
+ * `requireGi` is injected for the same reason the engine's is — see `engine.ts`'s header.
+ */
+export declare function createRealGioListStore(requireGi: RequireGi): RealGioListStore;

package/lib/types/list-store.node-gi.spec.d.ts

@@ -0,0 +1,2 @@
+import type { RequireGi } from './engine.js';
+export declare const realGioListStoreSuite: (requireGi: RequireGi) => () => Promise<void>;

package/lib/types/opt-in.d.ts

@@ -0,0 +1,12 @@
+import { type GObjectEngine } from '@gjsify/adwaita-core';
+import { type RequireGi } from './engine.js';
+/**
+ * Builds the real-GObject engine over `requireGi` and registers it as THE engine of this app.
+ * Returns it, so a caller that wants to assert on `engine.name` can.
+ *
+ * Throws — never falls back — when `requireGi` cannot produce GObject, and when the core's slot
+ * was already read or already filled. The app passes `requireGi` itself (`@gjsify/node-gi/gi`'s
+ * default export) for the reason in `engine.ts`' header: nothing in this package may import the
+ * bridge statically.
+ */
+export declare function useRealGObjectEngine(requireGi: RequireGi): GObjectEngine;

package/lib/types/opt-in.spec.d.ts

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

package/lib/types/vector-subject.d.ts

@@ -0,0 +1,12 @@
+import { type GObjectEngine } from '@gjsify/adwaita-core';
+import type { GObjectSubject } from '@gjsify/adwaita-core/conformance';
+/** The name the real-engine leg has reported since ADR 0105 stage 2; a leg may name itself. */
+export declare const SUBSET_SUBJECT_NAME = "adwaita-core on real GObject (node-gi engine)";
+/**
+ * The GObject subset with `engine` behind it, as a {@link GObjectSubject} the conformance driver
+ * takes.
+ *
+ * @param engine the engine under test — `createRealGioEngine(requireGi)` on both legs
+ * @param name what the driver calls the suite, so a device run is distinguishable in logcat
+ */
+export declare function createSubsetSubject(engine: GObjectEngine, name?: string): GObjectSubject;

package/package.json

@@ -1,6 +1,70 @@
 {
-  "name": "@gjsify/adwaita-gobject-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/adwaita-gobject-native",
+    "version": "0.60.0",
+    "description": "Real GObject behind @gjsify/adwaita-core's GObject subset — a GObjectEngine whose property store and signal bus are a live GObject reached through node-gi (ADR 0105)",
+    "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"
+        }
+    },
+    "files": [
+        "lib",
+        "!lib/types/**/*.d.mts",
+        "!lib/types/**/*.spec.d.ts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp dist tsconfig.tsbuildinfo",
+        "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:node-gi",
+        "build:test:node-gi": "gjsify build src/test.node-gi.mts --app node --outfile dist/test.node-gi.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test",
+        "test:gjs-on-node": "gjsify run build:test:node-gi && node dist/test.node-gi.mjs"
+    },
+    "keywords": [
+        "gjs",
+        "gobject",
+        "node-gi",
+        "nativescript",
+        "android",
+        "adwaita"
+    ],
+    "dependencies": {
+        "@gjsify/adwaita-core": "^0.60.0"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.60.0",
+        "@gjsify/node-gi": "file:../../node-gi/node-gi",
+        "@gjsify/unit": "^0.60.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "none",
+            "node": "polyfill",
+            "browser": "none",
+            "nativescript": "native"
+        },
+        "tier": 3,
+        "nativescriptPlatforms": [
+            "android"
+        ]
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/nativescript-bridge/gobject"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/nativescript-bridge/gobject#readme"
+}