@nativedesktop/native 0.1.0

package/include/nd.h

@@ -0,0 +1,157 @@
+/* include/nd.h — the ONLY public surface of libnd. Hand-written; kept in
+   lockstep with src/abi.zig by compile-time @sizeOf asserts. Canonical copy
+   lives in include/; packages/native/include/ carries a machine-synced copy
+   (scripts/sync-native-headers.sh, cmp-checked in CI) — edit include/ only. */
+#ifndef ND_H
+#define ND_H
+#include <stdint.h>
+#include <stdbool.h>
+#include "nd_plugin.h"
+
+typedef void* nd_widget;              /* opaque backend handle (GtkWidget* / NSView*) */
+typedef struct nd_context nd_context; /* opaque core instance */
+
+/* Geometry in logical window-top-left space (matches getTree contract). */
+typedef struct { int32_t x, y, w, h; } nd_rect;
+
+/* The backend vtable: the embedder fills these; the core calls up through them.
+   `props_json` / `arg_json` are NUL-terminated UTF-8 JSON (M6a-D2). All calls
+   arrive on the embedder's UI thread (the core marshals). */
+typedef struct nd_backend {
+  /* structural + prop ops (mirror the Zig seam) */
+  nd_widget (*create)(nd_context*, const char* kind, const char* props_json);
+  void (*apply_props)(nd_context*, nd_widget, const char* kind, const char* props_json);
+  void (*append_child)(nd_context*, nd_widget parent, const char* parent_kind,
+                       nd_widget child, const char* attached_json);
+  void (*insert_before)(nd_context*, nd_widget parent, const char* parent_kind,
+                        nd_widget child, nd_widget before /* nullable */,
+                        const char* attached_json);
+  void (*remove_child)(nd_context*, nd_widget parent, const char* parent_kind, nd_widget child);
+  void (*set_text)(nd_context*, nd_widget, const char* text);
+  void (*set_visible)(nd_context*, nd_widget, bool visible);
+  void (*apply_style)(nd_context*, nd_widget, uint32_t node_id, const char* style_json);
+  void (*connect_events)(nd_context*, nd_widget, const char* kind, uint32_t node_id);
+  bool (*has_parent)(nd_context*, nd_widget);
+  void (*unparent)(nd_context*, nd_widget);
+  nd_widget (*get_window)(nd_context*);
+
+  /* embedder UI-thread marshal + host chrome (M6a Task 3): the core's
+     commit-apply/child-exit/overlay paint call up through these instead of
+     importing glib/gio directly. GTK fills marshal_async with
+     g_main_context_invoke_full; the Mac shell fills it with
+     dispatch_async_f. `show_overlay("")` (empty message) is the clear
+     sentinel — the core calls it that way from its dev-mode Restart/respawn
+     path instead of a dedicated clear-overlay vtable field. */
+  void (*marshal_async)(nd_context*, void (*fn)(void*), void* data);
+  void (*show_overlay)(nd_context*, const char* message);
+
+  /* automation backend half (M6a-D3) */
+  bool (*node_visible)(nd_context*, nd_widget);
+  bool (*node_bounds)(nd_context*, nd_widget, nd_rect* out);   /* false = no bounds */
+  bool (*snapshot)(nd_context*, const char* png_path);         /* in-process render */
+  /* action: "click"|"setValue"|"type"|"scroll"; arg_json carries params.
+     returns 0 ok, or a negative JSON-RPC-style code; err_json_out (nullable,
+     caller frees via nd_free) gets a data object on failure. */
+  int32_t (*semantic_action)(nd_context*, nd_widget, uint32_t node_id,
+                             const char* action, const char* arg_json,
+                             char** result_json_out, char** err_json_out);
+
+  /* app -> widget imperative command (M14, widgetCommand NDP frame): `command`
+     is one of the widget's schema-declared commands (widgets.json commands[]),
+     `arg_json` its JSON argument (or "null"). Arrives on the UI thread. */
+  void (*widget_command)(nd_context*, nd_widget, const char* kind,
+                         const char* command, const char* arg_json);
+
+  /* multi-window reconstruction (per-window generalization of get_window):
+     given a Window node's stored handle, return the handle to REBIND to when a
+     crash/dev-Restart respawn re-creates that window, so the core reuses the
+     surviving OS window instead of opening a duplicate. GTK returns the handle
+     unchanged (its gtk.Window handle is stable); the AppKit shell resolves it
+     to the window's CURRENT content view (which differs once a SplitView took
+     over as contentViewController). */
+  nd_widget (*resolve_window)(nd_context*, nd_widget);
+
+  /* widget-preserving cross-window move (drag a tab between windows): relocate
+     an EXISTING live native widget from `old_parent` to `new_parent` WITHOUT
+     destroying it, so a <webview>'s loaded page / scroll / JS state survives —
+     a remove+create would reload it. Reuses each backend's ordinary remove +
+     append/insert per parent kind, so the target attaches correctly whatever
+     the parent (Box slot, Window, ...). `before` (nullable) positions the child;
+     NULL appends. `old_parent` may be NULL (the child is a detached pool node
+     not yet shown in any window). The handle stays alive across the unparent
+     (GTK g_object_ref brackets the move; the AppKit shell relies on the core's
+     create-time retain). Arrives on the UI thread. Appended (append-only
+     vtable) — bumps @sizeOf(NdBackend) to 21 words in src/abi.zig. */
+  void (*reparent_child)(nd_context*, nd_widget child,
+                         nd_widget old_parent /* nullable */, const char* old_parent_kind,
+                         nd_widget new_parent, const char* new_parent_kind,
+                         nd_widget before /* nullable */, const char* attached_json);
+
+  /* app -> host system capability request (systemRequest NDP frame). `method`
+     is a dotted capability (e.g. "dialog.openFile"), `params_json` its JSON
+     argument. Fire-and-forget: the backend delivers the (possibly async)
+     result later via nd_system_response. Arrives on the UI thread. Appended
+     (append-only vtable) — bumps @sizeOf(NdBackend) to 22 words in src/abi.zig. */
+  void (*system_request)(nd_context*, uint32_t id, const char* method, const char* params_json);
+
+  /* drop the backend's per-node ownership reference when the core forgets a
+     node id (tree remove / generation GC / clearAppNodes). GTK: g_object_unref
+     of the create-time ref_sink; the Mac shell: Unmanaged.release of the
+     create-time retain. The widget object stays alive while native parents
+     still reference it. Arrives on the UI thread. Appended (append-only
+     vtable) — bumps @sizeOf(NdBackend) to 23 words in src/abi.zig. */
+  void (*release_node)(nd_context*, nd_widget);
+} nd_backend;
+
+/* lifecycle */
+nd_context* nd_init(void);                                  /* create core, spawn nothing yet */
+void nd_register_backend(nd_context*, const nd_backend*);   /* store the vtable */
+/* Name the active widget backend ("gtk" | "appkit"). The core echoes it in the
+   NDP helloAck so the Bun child's Platform.backend can branch on the renderer
+   (which the OS alone can't reveal — GTK runs on macOS too). Call before
+   nd_start_runtime; absent = "unknown". */
+void nd_set_backend_name(nd_context*, const char* name);
+int32_t nd_start_runtime(nd_context*);                      /* open NDP socket, spawn bun child */
+int32_t nd_start_automation(nd_context*);                   /* open automation socket + thread */
+void nd_shutdown(nd_context*);                              /* stop runtime; destroy views/plugins */
+/* Capability ACL (D12): install a per-window grants manifest (NUL-terminated
+   JSON; see docs). Absent = safe default (core UI ops granted, plugin ops
+   denied). Call before nd_start_runtime. */
+void nd_set_acl(nd_context*, const char* grants_json);
+/* Load a native nd_plugin_v1 shared library (opt-in). Returns 0 ok, negative
+   on ABI mismatch / missing entry / capability-denied. */
+int32_t nd_load_plugin(nd_context*, const char* path);
+/* Load every plugin listed in ND_PLUGIN_PATHS (colon-separated; legacy
+   single-path ND_PLUGIN_PATH as fallback), skipping empty segments. Prints
+   one "ND_PLUGIN_LOAD_FAILED path=... rc=..." diagnostic per failed path. */
+void nd_load_plugins_from_env(nd_context*);
+
+/* Host-side native-view bridge (plugin ABI v2): the generic <nativeView>
+   widget's create/apply/command/destroy route through these into the loaded
+   plugin's nd_view_impl registered under `view_kind`. The GTK backend calls the
+   Zig fns in src/plugin.zig directly; the AppKit/Swift shell calls these C
+   wrappers. create returns NULL when no module registered `view_kind` (the
+   backend then renders an empty placeholder). */
+nd_widget nd_plugin_view_create(nd_context*, const char* view_kind, const char* props_json);
+void nd_plugin_view_apply_props(nd_context*, const char* view_kind, nd_widget, const char* props_json);
+void nd_plugin_view_connect(nd_context*, const char* view_kind, nd_widget, uint32_t node_id);
+void nd_plugin_view_command(nd_context*, const char* view_kind, nd_widget, const char* command, const char* arg_json);
+void nd_plugin_view_destroy(nd_context*, const char* view_kind, nd_widget);
+
+void nd_free(void* p);                                      /* free a core-allocated string */
+
+/* embedder -> core: a native event happened (button clicked, text changed, …).
+   `payload_json` is a NUL-terminated JSON object or "{}". */
+void nd_emit_event(nd_context*, uint32_t node_id, const char* name, const char* payload_json);
+
+/* backend -> core: the (possibly async) result of an earlier system_request,
+   correlated by `id`. ok=true splices `json` verbatim into the systemResponse
+   `result`; ok=false carries `json` as the error message string. */
+void nd_system_response(nd_context*, uint32_t id, bool ok, const char* json);
+/* backend -> core: an app-level event not tied to a widget node (app
+   activation, OS open-url/open-file launch, notification click, file drop,
+   capability event stream). `channel` names the stream; `data_json` is its
+   NUL-terminated JSON payload. */
+void nd_system_event(nd_context*, const char* channel, const char* data_json);
+
+#endif /* ND_H */

package/include/nd_plugin.h

@@ -0,0 +1,71 @@
+/* include/nd_plugin.h — the nd_plugin_v1 native-plugin ABI (spec §9, D12).
+   A native plugin is a C-ABI shared library exporting nd_plugin_entry(), which
+   returns a pointer to a statically-lived nd_plugin_v1. Capability strings are
+   checked against the NDP-dispatch ACL; a command runs only if its plugin's
+   declared permission is granted for the window. Opt-in: nothing loads a
+   plugin unless the embedder calls nd_load_plugin (include/nd.h). Canonical
+   copy lives in include/; packages/native/include/ carries a machine-synced
+   copy (scripts/sync-native-headers.sh, cmp-checked in CI) — edit include/
+   only. */
+#ifndef ND_PLUGIN_H
+#define ND_PLUGIN_H
+#include <stdint.h>
+#include <stddef.h>
+
+/* Append-only ABI history:
+   v2 adds register_view + nd_view_impl so a plugin can register its own native
+   widget. v3 appends connect + emit_event so that widget can emit events for a
+   retained node. v1/v2 plugins keep loading unchanged; consumers must only read
+   fields available in the plugin's declared abi_version. */
+#define ND_PLUGIN_ABI_VERSION 3
+
+typedef struct nd_plugin_registry nd_plugin_registry;
+
+/* A plugin command handler: receives the arg JSON (NUL-terminated) and writes
+   a malloc'd result JSON to *result_out (freed by the core via nd_free).
+   Returns 0 ok, negative JSON-RPC-style code on error. */
+typedef int32_t (*nd_command_fn)(const char* arg_json, char** result_out);
+
+/* A native-view factory a plugin registers under a `view_kind` string. The
+   handle each fn returns/takes is the backend-native widget as an opaque
+   pointer (GtkWidget* on GTK, NSView* on AppKit) — the core never dereferences
+   it; it flows through append_child/apply_style/unparent by parent kind alone.
+   `props_json`/`arg_json` are NUL-terminated JSON. Native views are inherently
+   backend-specific: a module ships a GTK impl and/or an AppKit impl. */
+typedef struct nd_view_impl {
+  void* (*create)(const char* props_json);
+  void  (*apply_props)(void* view, const char* props_json);
+  void  (*command)(void* view, const char* command, const char* arg_json);
+  void  (*destroy)(void* view);
+  /* v3: called after creation once the core node identity is known. */
+  void  (*connect)(void* view, uint32_t node_id);
+} nd_view_impl;
+
+/* Host callbacks a plugin uses from init(). register_command associates a
+   command name (reachable over NDP as {"type":"pluginCommand","name",...})
+   with a handler; the core namespaces it as plugin:<plugin-name>.<command>.
+   register_view (v2, appended) associates a `view_kind` string with a native-
+   view factory the generic <nativeView> widget routes to. emit_event is v3 and
+   becomes valid only after connect supplies a node id. The core copies the
+   nd_view_impl by value, so it may live on the plugin's stack in init(). */
+struct nd_plugin_registry {
+  void* host;   /* opaque core handle; pass back to the callbacks */
+  void (*register_command)(nd_plugin_registry*, const char* command, nd_command_fn);
+  void (*register_view)(nd_plugin_registry*, const char* view_kind, const nd_view_impl*);
+  /* v3: emit a generic event for a connected node through the core. */
+  void (*emit_event)(nd_plugin_registry*, uint32_t node_id, const char* name,
+                     const char* payload_json);
+};
+
+typedef struct nd_plugin_v1 {
+  uint32_t abi_version;         /* 1, 2, or ND_PLUGIN_ABI_VERSION; old layouts remain valid */
+  const char* name;             /* plugin identity, e.g. "hello" */
+  const char* const* capabilities; /* NULL-terminated permission strings, e.g. {"plugin:hello.greet", NULL} */
+  int32_t (*init)(nd_plugin_registry*);  /* register commands/widgets; 0 ok */
+  void (*deinit)(void);
+} nd_plugin_v1;
+
+/* Every plugin shared library exports this symbol. */
+typedef const nd_plugin_v1* (*nd_plugin_entry_fn)(void);
+
+#endif /* ND_PLUGIN_H */

package/linux/nd_native_gtk.h

@@ -0,0 +1,24 @@
+#ifndef ND_NATIVE_GTK_H
+#define ND_NATIVE_GTK_H
+
+#include <gtk/gtk.h>
+#include "../include/nd_plugin.h"
+
+/* Small C convenience layer for app-owned GTK plugins. The app still exports
+   nd_plugin_entry and owns every widget/state allocation. */
+typedef struct nd_gtk_view_state {
+  nd_plugin_registry* registry;
+  uint32_t node_id;
+} nd_gtk_view_state;
+
+static inline void nd_gtk_connect_state(nd_gtk_view_state* state, nd_plugin_registry* registry, uint32_t node_id) {
+  state->registry = registry;
+  state->node_id = node_id;
+}
+
+static inline void nd_gtk_emit(nd_gtk_view_state* state, const char* name, const char* payload_json) {
+  if (state && state->registry && state->registry->emit_event)
+    state->registry->emit_event(state->registry, state->node_id, name, payload_json ? payload_json : "{}");
+}
+
+#endif

package/macos/NativeDesktopNative.swift

@@ -0,0 +1,103 @@
+import AppKit
+import SwiftUI
+import CNdPlugin
+
+/// Protocol implemented by app-owned AppKit views hosted by NativeDesktop.
+public protocol NativeDesktopView: AnyObject {
+    func apply(propsJSON: String)
+    func connect(nodeID: UInt32, emit: @escaping (_ name: String, _ payloadJSON: String) -> Void)
+    func command(_ name: String, argJSON: String)
+    func destroy()
+}
+
+public extension NativeDesktopView {
+    func connect(nodeID: UInt32, emit: @escaping (String, String) -> Void) {}
+    func command(_ name: String, argJSON: String) {}
+    func destroy() {}
+}
+
+/// C-ABI glue for plugins written against NativeDesktopView. nd_view_impl
+/// callbacks carry no context pointer, so registerView supports one view kind
+/// per plugin; hand-roll an nd_view_impl to register more.
+public enum NativeDesktopPlugin {
+    private static var registry: UnsafeMutablePointer<nd_plugin_registry>?
+    private static var factory: ((String) -> NSView & NativeDesktopView)?
+
+    /// Allocates an nd_plugin_v1 with the stable lifetime the ABI requires;
+    /// return the result from @_cdecl("nd_plugin_entry").
+    public static func descriptor(
+        name: String,
+        capabilities: [String] = [],
+        initialize: @escaping @convention(c) (UnsafeMutablePointer<nd_plugin_registry>?) -> Int32,
+        deinitialize: @escaping @convention(c) () -> Void = {}
+    ) -> UnsafePointer<nd_plugin_v1> {
+        let caps = UnsafeMutablePointer<UnsafePointer<CChar>?>.allocate(capacity: capabilities.count + 1)
+        for (index, capability) in capabilities.enumerated() { caps[index] = UnsafePointer(strdup(capability)) }
+        caps[capabilities.count] = nil
+        let plugin = UnsafeMutablePointer<nd_plugin_v1>.allocate(capacity: 1)
+        plugin.initialize(to: nd_plugin_v1(abi_version: UInt32(ND_PLUGIN_ABI_VERSION), name: UnsafePointer(strdup(name)), capabilities: UnsafePointer(caps), init: initialize, deinit: deinitialize))
+        return UnsafePointer(plugin)
+    }
+
+    /// Call from the descriptor's initialize callback.
+    public static func registerView(
+        _ registry: UnsafeMutablePointer<nd_plugin_registry>,
+        kind: String,
+        factory: @escaping (String) -> NSView & NativeDesktopView
+    ) {
+        self.registry = registry
+        self.factory = factory
+        var impl = nd_view_impl(
+            create: { props in
+                guard let view = NativeDesktopPlugin.factory?(NativeDesktopPlugin.string(props)) else { return nil }
+                return Unmanaged.passRetained(view as NSView).toOpaque()
+            },
+            apply_props: { raw, props in
+                NativeDesktopPlugin.view(raw)?.apply(propsJSON: NativeDesktopPlugin.string(props))
+            },
+            command: { raw, name, arg in
+                guard let name else { return }
+                NativeDesktopPlugin.view(raw)?.command(String(cString: name), argJSON: NativeDesktopPlugin.string(arg))
+            },
+            destroy: { raw in
+                guard let raw else { return }
+                NativeDesktopPlugin.view(raw)?.destroy()
+                Unmanaged<NSView>.fromOpaque(raw).release()
+            },
+            connect: { raw, nodeID in
+                NativeDesktopPlugin.view(raw)?.connect(nodeID: nodeID) { name, payload in
+                    guard let registry = NativeDesktopPlugin.registry, let emit = registry.pointee.emit_event else { return }
+                    name.withCString { n in payload.withCString { p in emit(registry, nodeID, n, p) } }
+                }
+            }
+        )
+        registry.pointee.register_view(registry, kind, &impl)
+    }
+
+    private static func view(_ raw: UnsafeMutableRawPointer?) -> (NSView & NativeDesktopView)? {
+        raw.flatMap { Unmanaged<NSView>.fromOpaque($0).takeUnretainedValue() as? NSView & NativeDesktopView }
+    }
+
+    private static func string(_ pointer: UnsafePointer<CChar>?) -> String {
+        pointer.map { String(cString: $0) } ?? "{}"
+    }
+}
+
+/// AppKit host for a SwiftUI component. Updating `rootView` preserves the
+/// ordinary NSView identity expected by NativeDesktop's retained tree.
+public final class NativeDesktopSwiftUIView<Content: View>: NSHostingView<Content>, NativeDesktopView {
+    private let updateRoot: (String) -> Content
+
+    public init(initialPropsJSON: String, content: @escaping (String) -> Content) {
+        self.updateRoot = content
+        super.init(rootView: content(initialPropsJSON))
+    }
+
+    @available(*, unavailable)
+    required init(rootView: Content) { fatalError("use init(initialPropsJSON:content:)") }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("init(coder:) is unavailable") }
+
+    public func apply(propsJSON: String) { rootView = updateRoot(propsJSON) }
+}

package/macos/module.modulemap

@@ -0,0 +1,4 @@
+module CNdPlugin {
+  header "../include/nd_plugin.h"
+  export *
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@nativedesktop/native",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
+  "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FormalSnake/NativeDesktop.git",
+    "directory": "packages/native"
+  },
+  "publishConfig": {
+  "access": "public"
+},
+"files": ["include", "macos", "linux"],
+"exports": {
+  "./include/nd.h": "./include/nd.h",
+  "./include/nd_plugin.h": "./include/nd_plugin.h",
+  "./macos": "./macos/NativeDesktopNative.swift",
+  "./linux": "./linux/nd_native_gtk.h"
+}
+}