@nativedesktop/react 0.1.0

package/dist/packages/react/src/native-component.d.ts

@@ -0,0 +1,23 @@
+import type { JSX, NdNodeRef } from "./generated/intrinsics.ts";
+export interface NativeComponentOptions {
+    /** Factory key registered by the app's platform-native library. */
+    viewKind: string;
+}
+type NativeViewHostProps = Omit<JSX.IntrinsicElements["nativeview"], "viewKind" | "props" | "onNativeEvent" | "ref" | "children">;
+export interface NativeComponentProps<Props, Event = unknown> extends NativeViewHostProps {
+    props: Props;
+    onNativeEvent?: (event: {
+        name: string;
+        data: Event;
+    }) => void;
+}
+export interface NativeComponentRef<Command = unknown> extends NdNodeRef<"nativeview"> {
+    send(command: string, arg?: Command): void;
+}
+/**
+ * Defines a typed React component backed by an app-owned GTK/AppKit native view.
+ * Props cross the stable NativeView ABI as JSON; events and commands use the
+ * generic channel, so app components never require edits to widgets.json.
+ */
+export declare function defineNativeComponent<Props extends object, Event = unknown, Command = unknown>(options: NativeComponentOptions): import("react").ForwardRefExoticComponent<NativeComponentProps<Props, Event> & import("react").RefAttributes<NativeComponentRef<Command>>>;
+export {};

package/dist/packages/react/src/ops.d.ts

@@ -0,0 +1,20 @@
+import type { Op } from "../../../runtime/ndp.ts";
+export declare class Batch {
+    private ops;
+    push(op: Op): void;
+    drain(): Op[];
+    get length(): number;
+}
+export type Handler = (payload?: unknown) => void;
+export interface NodeRecord {
+    id: number;
+    type: string;
+    props: Record<string, unknown>;
+    handlers: Record<string, Handler>;
+}
+export declare class NodeRegistry {
+    private byId;
+    register(rec: NodeRecord): void;
+    get(id: number): NodeRecord | undefined;
+    unregister(id: number): void;
+}

package/dist/packages/react/src/paths.d.ts

@@ -0,0 +1,4 @@
+/** The per-platform user-data directory for this app. Does not create it. */
+export declare function getAppDataDir(): string;
+/** Like `getAppDataDir`, but also creates the directory (recursively) if missing. */
+export declare function ensureAppDataDir(): string;

package/dist/packages/react/src/platform.d.ts

@@ -0,0 +1,45 @@
+export type Backend = "gtk" | "appkit" | "unknown";
+export type OS = "macos" | "linux" | "windows";
+interface PlatformState {
+    backend: Backend;
+    hostWidgets: Set<string> | null;
+    hostCommands: Set<string> | null;
+}
+declare global {
+    var __nd_platform: PlatformState | undefined;
+}
+/** Package-internal (metrics.ts): runs `cb` once the backend is known —
+ * immediately when it already is. */
+export declare function onBackendKnown(cb: () => void): void;
+/** Renderer-internal: called once from `render()` after the handshake. */
+export declare function setBackend(name: string): void;
+/** Renderer-internal: called once from `render()` beside `setBackend`. */
+export declare function setHostManifest(widgets: Set<string> | null, commands: Set<string> | null): void;
+/**
+ * True when the connected host build knows the intrinsic (e.g.
+ * `hasWidget("sourcetree")`). Answers from the host's handshake manifest;
+ * against an older host that doesn't send one, falls back to this runtime's
+ * own schema table (i.e. "the JS side knows it").
+ */
+export declare function hasWidget(type: string): boolean;
+/**
+ * True when the connected host build dispatches `command` on `type` (e.g.
+ * `hasCommand("window", "present")`). Same manifest-with-fallback semantics
+ * as `hasWidget`. Replaces try/catch around `sendCommand` for feature
+ * detection.
+ */
+export declare function hasCommand(type: string, command: string): boolean;
+export declare const Platform: {
+    /** The native widget backend drawing this app: "gtk" | "appkit". */
+    readonly backend: Backend;
+    /** The OS this app is running on. */
+    readonly os: OS;
+    /**
+     * Pick a value by the active backend, like React Native's `Platform.select`.
+     * Returns `default` when the active backend has no matching entry.
+     */
+    select<T>(spec: Partial<Record<Backend, T>> & {
+        default?: T;
+    }): T | undefined;
+};
+export {};

package/dist/packages/react/src/renderer.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode, ReactPortal } from "react";
+import type { NdNodeRef, WidgetType } from "./generated/intrinsics.ts";
+import { type WidgetCommandNames } from "./generated/schema-meta.ts";
+export declare function render(element: ReactNode): Promise<void>;
+export declare function sendCommand<T extends keyof WidgetCommandNames & WidgetType>(node: NdNodeRef<T>, command: WidgetCommandNames[T], arg?: unknown): void;
+export declare function sendNativeCommand(node: NdNodeRef<"nativeview">, command: string, arg?: unknown): void;
+export interface Pool {
+    readonly rootId: null;
+}
+export declare function createPool(): Pool;
+export declare function createPortal(children: ReactNode, pool?: Pool): ReactPortal;
+export declare function moveNode(node: NdNodeRef, toParent: NdNodeRef, before?: NdNodeRef | null): void;

package/dist/packages/react/src/shell.d.ts

@@ -0,0 +1,6 @@
+/** Opens `url` in the OS default browser/handler (`open` on macOS, `xdg-open` on Linux). */
+export declare function openExternal(url: string): Promise<void>;
+/** Opens `path` with its OS-registered default application. */
+export declare function openPath(path: string): Promise<void>;
+/** Reveals `path` in the OS file manager, selecting it if the file manager supports that. On Linux, tries the freedesktop FileManager1 DBus interface first (selects the file) and falls back to opening its containing directory if that fails (e.g. no DBus session or no file manager registered on it). */
+export declare function revealPath(path: string): Promise<void>;

package/dist/packages/react/src/store.d.ts

@@ -0,0 +1,61 @@
+export interface StoreOptions<T> {
+    /** File is `${name}.json` under `dir` (default: getAppDataDir()). */
+    name: string;
+    version: number;
+    defaults: T;
+    /** Validate AND upgrade in one hook. Called on EVERY load, including a
+     * current-version file (type guards and sanitizing live here, not in a
+     * second option). Return null to reject the file and start from defaults. */
+    migrate?: (raw: unknown, fromVersion: number) => T | null;
+    /** Override for tests / env vars. */
+    dir?: string;
+    /** Default 250. */
+    debounceMs?: number;
+}
+export interface Store<T> {
+    readonly name: string;
+    readonly path: string;
+    /** Idempotent; repeat calls return the same promise. */
+    load(): Promise<T>;
+    /** Synchronous after load() resolves; throws a named error before that. */
+    get(): T;
+    set(next: T): void;
+    update(fn: (prev: T) => T): void;
+    subscribe(cb: (value: T) => void): () => void;
+    /** Awaits the pending debounced write plus every queued one. */
+    flush(): Promise<void>;
+    /** Set when a corrupt/unmigratable file was backed up and reset. */
+    readonly loadError: Error | undefined;
+}
+declare class StoreImpl<T> implements Store<T> {
+    #private;
+    readonly name: string;
+    readonly path: string;
+    readonly corruptPath: string;
+    loadError: Error | undefined;
+    constructor(options: StoreOptions<T>, path: string);
+    load(): Promise<T>;
+    get(): T;
+    set(next: T): void;
+    update(fn: (prev: T) => T): void;
+    subscribe(cb: (value: T) => void): () => void;
+    flush(): Promise<void>;
+    /** Exit-path flush: synchronous, no allocation of new timers, safe inside
+     * a signal handler or the "exit" event. */
+    writeSyncPending(): void;
+}
+interface StoreRegistry {
+    stores: Map<string, StoreImpl<unknown>>;
+    exitHooked: boolean;
+}
+declare global {
+    var __nd_stores: StoreRegistry | undefined;
+}
+/** Deduped by resolved file path: the same name+dir always returns the same
+ * instance (a `dir` override in tests is a distinct instance). */
+export declare function createStore<T>(options: StoreOptions<T>): Store<T>;
+/** Subscribes a component to the store (or a selection of it). The selected
+ * snapshot is cached per store value, so `select` may return a fresh object
+ * without re-render loops, but it must be pure. */
+export declare function useStoreValue<T, S = T>(store: Store<T>, select?: (value: T) => S): S;
+export {};

package/dist/packages/react/src/style-validate.d.ts

@@ -0,0 +1,3 @@
+export declare class StyleError extends Error {
+}
+export declare function validateStyle(style: unknown): void;

package/dist/packages/react/src/system.d.ts

@@ -0,0 +1,166 @@
+type SystemEventHandler = (data: unknown) => void;
+declare global {
+    var __nd_system_events: Map<string, Set<SystemEventHandler>> | undefined;
+    var __nd_notification_data: Map<string, unknown> | undefined;
+    var __nd_app_active: boolean | undefined;
+}
+/** Wired up by renderer.ts from `ndp.onSystemEvent()` — not part of the public API. */
+export declare function dispatchSystemEvent(channel: string, data: unknown): void;
+/** A native file-picker filter, e.g. `{ name: "Images", extensions: ["png", "jpg"] }`. */
+export interface FileFilter {
+    name: string;
+    extensions: string[];
+}
+export interface OpenFileOptions {
+    title?: string;
+    defaultPath?: string;
+    filters?: FileFilter[];
+    multiple?: boolean;
+    directories?: boolean;
+}
+export interface SaveFileOptions {
+    title?: string;
+    defaultPath?: string;
+    defaultName?: string;
+    filters?: FileFilter[];
+}
+export type MessageLevel = "info" | "warning" | "error";
+export interface MessageOptions {
+    message: string;
+    detail?: string;
+    level?: MessageLevel;
+    buttons?: string[];
+    defaultButton?: number;
+}
+export interface NotificationOptions {
+    title: string;
+    body?: string;
+    /**
+     * App payload echoed on the matching `onClick` event. Held in a
+     * process-local map (never sent to the host), so it survives `bun --hot`
+     * re-evals but NOT an app restart — a click arriving after a restart is
+     * dropped by the transport today anyway (no host-side buffering), so the
+     * same-session limit costs nothing extra.
+     */
+    data?: unknown;
+}
+/** Native file/message dialogs. Default-granted (no ACL manifest entry needed). */
+export declare const dialog: {
+    /** Opens a native "choose file(s)" dialog. Resolves to the chosen paths, or `[]` if the user cancels. */
+    openFile(options?: OpenFileOptions): Promise<string[]>;
+    /** Opens a native "save file" dialog. Resolves to the chosen path, or `null` if the user cancels. */
+    saveFile(options?: SaveFileOptions): Promise<string | null>;
+    /** Shows a native modal alert. Resolves to the 0-based index of the button the user clicked. */
+    showMessage(options: MessageOptions): Promise<number>;
+};
+export declare const clipboard: {
+    /** Reads text from the system clipboard. Default-denied — needs `core:clipboard.readText` in ND_ACL_GRANTS, or rejects with "capability denied". */
+    readText(): Promise<string>;
+    /** Writes text to the system clipboard. Default-granted. */
+    writeText(text: string): Promise<void>;
+    /** Reads the clipboard's image, written to a host-local temp PNG. Default-denied — needs `core:clipboard.read.image`. Rejects when the clipboard holds no image. */
+    readImage(): Promise<{
+        path: string;
+        width: number;
+        height: number;
+        bytes: number;
+    }>;
+};
+export declare const notifications: {
+    /** Shows a native OS notification. Resolves to the notification's id (correlates a later `notification.click` event). Default-granted. */
+    show(options: NotificationOptions): Promise<string>;
+    /** Subscribes to notification-click events; `e.data` is the payload passed to `show()`, same-session only. Returns an unsubscribe function, usable directly as a `useEffect` cleanup. */
+    onClick(handler: (e: {
+        id: string;
+        data?: unknown;
+    }) => void): () => void;
+};
+export declare const recentDocuments: {
+    /** Adds `path` to the OS's recent-documents list. Default-granted. */
+    add(path: string): Promise<void>;
+    /** Clears the OS's recent-documents list. Default-granted. */
+    clear(): Promise<void>;
+};
+/** OS keychain / credential storage. Default-denied — needs `core:credentials.*` in ND_ACL_GRANTS, or these reject with "capability denied". */
+export declare const credentials: {
+    /** Stores `secret` under (`service`, `account`) in the OS credential store. */
+    set(service: string, account: string, secret: string): Promise<void>;
+    /** Reads the secret stored under (`service`, `account`), or `null` if none exists. */
+    get(service: string, account: string): Promise<string | null>;
+    /** Removes the secret stored under (`service`, `account`). */
+    delete(service: string, account: string): Promise<void>;
+};
+export declare const app: {
+    /**
+     * Whether the app is currently active (frontmost), synchronously. Backed by
+     * the host's app.activate/app.deactivate stream — the host replays the
+     * standing state right after the handshake, so this is correct from the
+     * first render. Defaults to true before any transition has been seen.
+     */
+    isActive(): boolean;
+    /** Subscribes to app-activation (e.g. Dock/taskbar re-activation). Returns an unsubscribe function. */
+    onActivate(handler: () => void): () => void;
+    /** Subscribes to app-deactivation. Returns an unsubscribe function. */
+    onDeactivate(handler: () => void): () => void;
+    /** Subscribes to OS "open URL" launch requests (e.g. a registered custom URL scheme). Returns an unsubscribe function. */
+    onOpenUrl(handler: (url: string) => void): () => void;
+    /** Subscribes to OS "open file" launch requests (e.g. double-clicking a registered document type). Returns an unsubscribe function. */
+    onOpenFile(handler: (paths: string[]) => void): () => void;
+    /** Subscribes to files dropped onto a window. Returns an unsubscribe function. */
+    onFileDrop(handler: (e: {
+        paths: string[];
+        windowId: number;
+    }) => void): () => void;
+};
+export type Appearance = "dark" | "light";
+/** Result of `system.getAppearance` and payload of `onAppearanceChange`:
+ *  light/dark plus the OS accent as `#rrggbb` (AdwStyleManager accent-color
+ *  on Linux, `NSColor.controlAccentColor` on macOS). */
+export interface AppearanceInfo {
+    appearance: Appearance;
+    accentColor: string;
+}
+export declare const system: {
+    /** Reads the OS's current light/dark appearance + accent color. Default-granted. */
+    getAppearance(): Promise<AppearanceInfo>;
+    /** Subscribes to system appearance/accent changes. Returns an unsubscribe function. */
+    onAppearanceChange(handler: (info: AppearanceInfo) => void): () => void;
+};
+export interface AudioPlayOptions {
+    path?: string;
+    url?: string;
+    volume?: number;
+    spectrum?: boolean;
+}
+export type AudioState = "playing" | "paused" | "ended" | "stopped" | "error";
+export interface AudioStateEvent {
+    handle: string;
+    state: AudioState;
+    position: number;
+    duration: number | null;
+    error?: string;
+}
+export interface AudioSpectrumEvent {
+    handle: string;
+    bins: number[];
+}
+/** Audio playback. `core:audio` is default-granted (ND_ACL_GRANTS manifests extend the default set — they cannot revoke it). */
+export declare const audio: {
+    /** Starts playback from exactly one of `path` (local file) or `url` (remote). Resolves to a handle used by the other methods below. */
+    play(options: AudioPlayOptions): Promise<string>;
+    /** Pauses playback for `handle`. */
+    pause(handle: string): Promise<void>;
+    /** Resumes playback for `handle`. */
+    resume(handle: string): Promise<void>;
+    /** Stops playback and releases `handle` — it is no longer valid afterward. */
+    stop(handle: string): Promise<void>;
+    /** Seeks `handle` to `positionMs` milliseconds. */
+    seek(handle: string, positionMs: number): Promise<void>;
+    /** Sets playback volume (0..1) for `handle`. */
+    setVolume(handle: string, volume: number): Promise<void>;
+    /** Subscribes to playback state transitions (not position ticks). Returns an unsubscribe function. */
+    onState(handler: (e: AudioStateEvent) => void): () => void;
+    /** Subscribes to spectrum frames (32 bins, 0..1, ~15 Hz) — only emitted for handles played with `spectrum: true`. Returns an unsubscribe function. */
+    onSpectrum(handler: (e: AudioSpectrumEvent) => void): () => void;
+};
+export {};

package/dist/packages/react/src/toast.d.ts

@@ -0,0 +1,19 @@
+import type { NdNodeRef } from "./generated/intrinsics.ts";
+export type ToastPriority = "normal" | "high";
+export interface ShowToastOptions {
+    title: string;
+    buttonLabel?: string;
+    timeoutSeconds?: number;
+    priority?: ToastPriority;
+}
+export interface ToastResult {
+    buttonClicked: boolean;
+}
+export declare function showToast(node: NdNodeRef<"toastoverlay">, options: ShowToastOptions): Promise<ToastResult>;
+export declare function dismissToast(node: NdNodeRef<"toastoverlay">, id?: string): void;
+export declare function onToastButtonClicked(e: {
+    data: unknown;
+}): void;
+export declare function onToastDismissed(e: {
+    data: unknown;
+}): void;

package/dist/packages/react/src/webview.d.ts

@@ -0,0 +1,5 @@
+import type { NdNodeRef } from "./generated/intrinsics.ts";
+export declare function executeJavaScript(node: NdNodeRef<"webview">, code: string): Promise<string>;
+export declare function onJavaScriptResult(e: {
+    data: unknown;
+}): void;

package/dist/runtime/ndp-binary.d.ts

@@ -0,0 +1,42 @@
+type Op = {
+    op: "create";
+    id: number;
+    widget: string;
+    props: Record<string, unknown>;
+} | {
+    op: "append";
+    parent: number;
+    child: number;
+} | {
+    op: "insertBefore";
+    parent: number;
+    child: number;
+    before: number | null;
+} | {
+    op: "remove";
+    id: number;
+} | {
+    op: "setText";
+    id: number;
+    text: string;
+} | {
+    op: "update";
+    id: number;
+    props: Record<string, unknown>;
+} | {
+    op: "hide";
+    id: number;
+} | {
+    op: "unhide";
+    id: number;
+};
+type Batch = {
+    commitId: number;
+    generation: number;
+    ops: readonly Op[];
+};
+export declare class BinaryUnsupportedValue extends Error {
+    constructor(key: string, value: unknown);
+}
+export declare function encodeCommitBatchBinary(batch: Batch): Uint8Array;
+export {};

package/dist/runtime/ndp.d.ts

@@ -0,0 +1,38 @@
+import type { Runtime, Op, CommitBatch, EventMsg } from "../packages/react/src/generated/protocol";
+export declare class Ndp {
+    private socket;
+    private inbox;
+    private eventCb;
+    private helloAckResolve;
+    private outbox;
+    private outboxOffset;
+    private encoding;
+    private backendName;
+    private hostWidgetsSet;
+    private hostCommandsSet;
+    private pending;
+    private nextRequestId;
+    private systemEventCb;
+    private constructor();
+    /** The host's active widget backend, valid after `handshake()` resolves. */
+    get backend(): string;
+    /** Intrinsics the host build knows, or null on a pre-manifest host. Valid after `handshake()`. */
+    get hostWidgets(): Set<string> | null;
+    /** "<intrinsic>.<command>" entries the host dispatches, or null on a pre-manifest host. Valid after `handshake()`. */
+    get hostCommands(): Set<string> | null;
+    static connect(): Promise<Ndp>;
+    private pump;
+    private onData;
+    private dispatch;
+    private send;
+    handshake(runtime: Runtime): Promise<void>;
+    sendCommit(batch: Omit<CommitBatch, "type">): void;
+    private sendBinaryFrame;
+    sendWidgetCommand(nodeId: number, command: string, arg?: unknown): void;
+    onEvent(cb: (e: EventMsg) => void): void;
+    request(method: string, params: unknown): Promise<unknown>;
+    onSystemEvent(cb: (channel: string, data: unknown) => void): void;
+    ping(): void;
+    sendRuntimeError(message: string, stack: string, fatal: boolean): void;
+}
+export type { Op, CommitBatch, EventMsg, Runtime };

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nativedesktop/react",
+  "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/react"
+  },
+  "publishConfig": {
+  "access": "public"
+},
+"files": ["dist"],
+"main": "./dist/index.js",
+"types": "./dist/packages/react/src/index.d.ts",
+"exports": {
+  ".": {
+    "types": "./dist/packages/react/src/index.d.ts",
+    "default": "./dist/index.js"
+  },
+  "./jsx-runtime": {
+    "types": "./dist/packages/react/src/jsx-runtime.d.ts",
+    "default": "./dist/jsx-runtime.js"
+  },
+  "./jsx-dev-runtime": {
+    "types": "./dist/packages/react/src/jsx-dev-runtime.d.ts",
+    "default": "./dist/jsx-dev-runtime.js"
+  },
+  "./rpc": {
+    "types": "./dist/packages/react/src/generated/rpc.d.ts",
+    "default": "./dist/generated/rpc.js"
+  }
+},
+"scripts": {
+  "build": "rm -rf dist && tsc -p tsconfig.build.json && bun build ./src/index.ts ./src/jsx-runtime.ts ./src/jsx-dev-runtime.ts ./src/generated/rpc.ts --outdir dist --target node --format esm --external react --external react-reconciler --external react-refresh",
+  "prepack": "bun run build",
+  "prepare": "bun run build"
+},
+"peerDependencies": {
+  "react": "^19.2.7"
+},
+"dependencies": {
+  "react-reconciler": "0.33.0",
+  "react-refresh": "0.17.0"
+},
+"devDependencies": {
+  "@types/react": "19.2.17",
+  "@types/react-reconciler": "0.33.0",
+  "@types/react-refresh": "0.14.7",
+  "react": "19.2.7",
+  "typescript": "7.0.2"
+}
+}