@nativescript/cloudflare-desktop 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @nativescript/cloudflare-desktop
 
-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.
+Runs an ns-edge project as a macOS desktop app on the [NativeScript Node-API runtime](https://github.com/NativeScript/runtimes/tree/main/packages/macos-node-api), hot-reloaded from the edge, with its window streamed to the project's browser IDE.
+
+```sh
+npx @nativescript/cloudflare-desktop 'https://<host>/p/<project id>#<device key>'
+```
+
+The device link is in the IDE's **Pair device** dialog. Create the project from the `macos` template (`POST /api/projects?template=macos`). Projects from the `electron` template run in the Electron host instead: see [apps/desktop-electron](../../apps/desktop-electron/README.md).
+
+The host asks before joining: the project's code runs in this process with your user account's access to files, network and apps, and anyone with the write key can watch and click its window.
+
+| Option | |
+| --- | --- |
+| `--yes` | Join without asking |
+| `--allow-eval` | Let the agent's `runOnDevice` run code here (off by default) |
+| `--metadata <path>` | Runtime metadata (.nsmd) to use instead of the copy bundled in the package. The npm runtime's built-in metadata has no `SCStream`, which streaming needs |
+| `--runtime <path>` | A `NativeScript.framework` binary to load instead of the npm one |
+
+`NS_METADATA` and `NS_RUNTIME` set the same defaults.
+
+## Entry contract
+
+A desktop app owns windows rather than one root view. `app/main.ts` default-exports a function that opens the app and returns the function that closes it; the host calls that before running the next version. If it returns nothing, the host closes the windows it opened.
+
+AppKit holds control targets and delegates weakly. Keep them referenced from JavaScript for as long as their views live, for example from the returned close function, or they're collected and the controls stop responding.
+
+## How it works
+
+- **Code.** The host joins the project's socket as `platform: 'macos'`, walks each new entry's module graph over HTTP and serves it to Node through `module.registerHooks`. Module URLs are versioned, so only changed modules are fetched. Node can't unload old versions; they stay in memory until the host restarts.
+- **Event loop.** Cocoa events are pumped from Node's timers, so sockets and `fetch` keep working.
+- **Memory.** Each frame's native objects are released as soon as it's sent (`interop.releaseNativeObject`, NativeScript/runtimes#103); runtimes without it get a garbage collection every few frames instead.
+- **Stream.** While a viewer watches, ScreenCaptureKit captures the project's window (only that window, through the current-process listing, macOS 14.4+) at up to 30 fps and at the window's point size (at most 800 px wide); frames go out as JPEG over `/p/<id>/stream/<stream>`, a relay separate from the project's hub, in chunks of at most 16 KB under a budget of about 4.8 Mbps with adaptive quality. Cloudflare cuts a Durable Object's WebSocket when messages are large or one Mac streams two windows at once, so the IDE only watches a window while its pane is on screen.
+- **Input.** Pointer, wheel and key events from the viewer are posted to the app's own event queue, so they reach only this app, never move the real cursor and need no Accessibility permission. A press is held until its release arrives, because a control's tracking loop blocks the JS thread in between: drags land on release, and press-and-hold isn't possible yet.
+
+## Publishing
+
+`npm pack` runs `scripts/metadata.mjs` first, which copies runtime metadata generated from a macOS SDK (`NS_METADATA`, default `../ns-electron/metadata`) into `metadata/`, so the published host streams without the user generating any.
+
+## Requirements
+
+Apple Silicon, macOS 14.4 or later, Node 22.15 or later.

package/dist/app.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runs Cocoa's event loop from Node's, so Node keeps its timers and sockets
+ * and AppKit still gets every event, including ones the host posts itself.
+ */
+export declare function startApp(name: string): void;

package/dist/app.js

@@ -0,0 +1,44 @@
+const PUMP_MS = 4;
+/**
+ * Runs Cocoa's event loop from Node's, so Node keeps its timers and sockets
+ * and AppKit still gets every event, including ones the host posts itself.
+ */
+export function startApp(name) {
+    const app = NSApplication.sharedApplication;
+    app.setActivationPolicy(NSApplicationActivationPolicy.Regular);
+    app.mainMenu = mainMenu(name);
+    app.finishLaunching();
+    const pump = () => {
+        for (let i = 0; i < 64; i++) {
+            const event = app.nextEventMatchingMaskUntilDateInModeDequeue(NSEventMask.Any, null, 'kCFRunLoopDefaultMode', true);
+            if (!event)
+                break;
+            app.sendEvent(event);
+        }
+        setTimeout(pump, PUMP_MS);
+    };
+    pump();
+}
+/** Quit and the standard Edit commands; text fields only get ⌘C/⌘V/⌘A through menu key equivalents. */
+function mainMenu(name) {
+    const bar = NSMenu.new();
+    const appMenu = NSMenu.alloc().initWithTitle(name);
+    appMenu.addItemWithTitleActionKeyEquivalent(`Quit ${name}`, 'terminate:', 'q');
+    const edit = NSMenu.alloc().initWithTitle('Edit');
+    for (const [title, action, key] of [
+        ['Undo', 'undo:', 'z'],
+        ['Redo', 'redo:', 'Z'],
+        ['Cut', 'cut:', 'x'],
+        ['Copy', 'copy:', 'c'],
+        ['Paste', 'paste:', 'v'],
+        ['Select All', 'selectAll:', 'a'],
+    ]) {
+        edit.addItemWithTitleActionKeyEquivalent(title, action, key);
+    }
+    for (const menu of [appMenu, edit]) {
+        const item = NSMenuItem.new();
+        item.submenu = menu;
+        bar.addItem(item);
+    }
+    return bar;
+}

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { startApp } from './app.js';
+import { DesktopClient } from './client.js';
+import { loadRuntime } from './runtime.js';
+const USAGE = `Usage: ns-edge-desktop <device link> [options]
+
+Runs an ns-edge project on this Mac and streams its window to the project's IDE.
+The device link is the project's https://<host>/p/<id>#<device key> link.
+
+Options:
+  --yes            Join without asking
+  --allow-eval     Let the project's agent run arbitrary code here (runOnDevice)
+  --metadata <p>   Runtime metadata (.nsmd) generated from this Mac's SDK
+  --runtime <p>    A NativeScript.framework binary to load instead of the npm one
+`;
+const out = (line) => process.stderr.write(`${line}\n`);
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            yes: { type: 'boolean', default: false },
+            'allow-eval': { type: 'boolean', default: false },
+            metadata: { type: 'string', default: process.env.NS_METADATA },
+            runtime: { type: 'string', default: process.env.NS_RUNTIME },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    const link = positionals[0];
+    if (values.help || !link)
+        return out(USAGE);
+    const { url } = DesktopClient.parse(link);
+    out(`Project: ${url}`);
+    out('Its code will run in this process with your user account\'s access to files, network and apps,');
+    out(`and anyone with the project's write key can watch and click its window${values['allow-eval'] ? ' and run code here' : ''}.`);
+    if (!values.yes) {
+        if (!process.stdin.isTTY)
+            throw new Error('Not a terminal: pass --yes to join without asking.');
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await rl.question('Join? [y/N] ');
+        rl.close();
+        if (!/^y(es)?$/i.test(answer.trim()))
+            return out('Not joined.');
+    }
+    await loadRuntime({ runtime: values.runtime, metadata: values.metadata });
+    startApp('ns-edge Desktop');
+    const client = new DesktopClient({
+        link,
+        allowEval: values['allow-eval'],
+        onStatus: (status, detail) => out(`[ns-edge] ${status}${detail ? ` ${detail}` : ''}`),
+        onRendered: ({ version, ms, fetched }) => out(`[ns-edge] v${version} rendered in ${ms} ms (${fetched} module${fetched === 1 ? '' : 's'} fetched)`),
+        onError: (message) => out(`[ns-edge] ${message}`),
+        onStream: (streaming, viewers) => out(`[ns-edge] ${streaming ? `streaming the window to ${viewers} viewer${viewers === 1 ? '' : 's'}` : 'stopped streaming'}`),
+    });
+    client.connect();
+    for (const signal of ['SIGINT', 'SIGTERM'])
+        process.on(signal, () => (client.close(), process.exit(0)));
+}
+main().catch((e) => {
+    out(String(e instanceof Error ? e.message : e));
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+import type { DeviceInfo } from '@nativescript/cloudflare-protocol';
+export type DesktopStatus = 'connecting' | 'connected' | 'offline';
+export interface DesktopClientOptions {
+    /** `http(s)://host/p/<id>#<device key>` */
+    link: string;
+    /** Lets the agent's `runOnDevice` run code here. Off unless the developer opts in. */
+    allowEval?: boolean;
+    /** Packages remote modules may import by bare specifier. */
+    linked?: Record<string, object>;
+    host?: DeviceInfo['host'];
+    onStatus?(status: DesktopStatus, detail?: string): void;
+    onRendered?(info: {
+        version: number;
+        ms: number;
+        fetched: number;
+    }): void;
+    onError?(message: string): void;
+    onStream?(streaming: boolean, viewers: number): void;
+    /** Paths changed by an update, whether or not the entry re-runs (e.g. `web/` files an Electron host reloads). */
+    onChanges?(paths: string[]): void;
+}
+/**
+ * Joins one edge project as a macOS device: runs its entry, applies hot
+ * updates, forwards console output and errors, answers RPCs, and streams the
+ * project's window to viewers through the project's stream relay.
+ */
+export declare class DesktopClient {
+    private options;
+    readonly projectUrl: string;
+    private deviceKey;
+    private stream;
+    private streamer;
+    private ws?;
+    private backoff;
+    private timer?;
+    private queue;
+    private renderedEntry;
+    private dispose?;
+    static parse(link: string): {
+        url: string;
+        key: string;
+    };
+    constructor(options: DesktopClientOptions);
+    connect(): void;
+    close(): void;
+    private open;
+    private deviceInfo;
+    private provides;
+    private send;
+    /** Desktop projects have no stylesheets; boot and update differ only in what they replace. */
+    private handle;
+    /**
+     * Imports the entry's versioned URL, closes what the previous version
+     * opened, then runs the new one. Only modules whose version changed are
+     * fetched. Node can't unload superseded modules, so they stay in memory
+     * until the host restarts.
+     */
+    private render;
+    private disposeCurrent;
+    private answer;
+    private reportError;
+    private captureConsole;
+    /** Project code throwing from a native callback or a timer is reported; the host keeps running. */
+    private captureErrors;
+}

package/dist/client.js

@@ -0,0 +1,223 @@
+import { randomBytes } from 'node:crypto';
+import { installLoader, prefetch } from './loader.js';
+import { handleRpc } from './rpc.js';
+import { runtimeVersion } from './runtime.js';
+import { formatArgs } from './serialize.js';
+import { WindowStreamer } from './stream.js';
+const PROJECT_LINK = /^(https?:\/\/[^/#]+\/p\/[0-9a-f]{32})\/?#([0-9a-f]{32})$/;
+/** Plain HTTP is only for development servers on this machine or the LAN. */
+const LOCAL_HOST = /^http:\/\/(localhost|127\.0\.0\.1|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|[\w-]+\.local)(:\d+)?\//;
+const MAX_BACKOFF_MS = 8000;
+const RPC_TIMEOUT_MS = 15_000;
+/**
+ * Joins one edge project as a macOS device: runs its entry, applies hot
+ * updates, forwards console output and errors, answers RPCs, and streams the
+ * project's window to viewers through the project's stream relay.
+ */
+export class DesktopClient {
+    options;
+    projectUrl;
+    deviceKey;
+    stream = randomBytes(16).toString('hex');
+    streamer;
+    ws;
+    backoff = 500;
+    timer;
+    queue = Promise.resolve();
+    renderedEntry = '';
+    dispose;
+    static parse(link) {
+        const m = PROJECT_LINK.exec(link.trim());
+        if (!m)
+            throw new Error(`Not a device link: ${link}\nExpected https://<host>/p/<project id>#<device key>`);
+        if (m[1].startsWith('http:') && !LOCAL_HOST.test(m[1] + '/'))
+            throw new Error(`Refusing plain HTTP to a non-local host: ${m[1]}`);
+        return { url: m[1], key: m[2] };
+    }
+    constructor(options) {
+        this.options = options;
+        const { url, key } = DesktopClient.parse(options.link);
+        this.projectUrl = url;
+        this.deviceKey = key;
+        this.streamer = new WindowStreamer(`${url.replace(/^http/, 'ws')}/stream/${this.stream}?role=host&key=${key}`, options.onStream);
+        installLoader();
+        const linked = options.linked ?? {};
+        Object.assign(globalThis, {
+            __nsEdge: { require: (name) => linked[name] },
+            __APPLE__: true,
+            __MACOS__: true,
+            __IOS__: false,
+            __ANDROID__: false,
+            __VISIONOS__: false,
+            __DEV__: true,
+        });
+        this.captureConsole();
+        this.captureErrors();
+    }
+    connect() {
+        this.open();
+        this.streamer.open();
+    }
+    close() {
+        clearTimeout(this.timer);
+        const ws = this.ws;
+        this.ws = undefined;
+        ws?.close();
+        this.streamer.close();
+    }
+    open() {
+        this.options.onStatus?.('connecting', this.projectUrl);
+        const ws = new WebSocket(`${this.projectUrl.replace(/^http/, 'ws')}/ws?role=device&key=${this.deviceKey}`);
+        this.ws = ws;
+        ws.onopen = () => {
+            this.backoff = 500;
+            this.send({ type: 'hello', device: this.deviceInfo(), provides: this.provides() });
+            this.options.onStatus?.('connected');
+        };
+        ws.onmessage = (e) => {
+            if (this.ws !== ws)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(String(e.data));
+            }
+            catch {
+                return;
+            }
+            // RPCs run beside the render queue so a hung eval can't stall hot reload.
+            if (msg.type === 'rpc')
+                return void this.answer(msg);
+            if (msg.type === 'boot')
+                this.queue = Promise.resolve();
+            this.queue = this.queue.then(() => this.handle(msg)).catch((err) => this.reportError(err));
+        };
+        ws.onclose = (e) => {
+            if (this.ws !== ws)
+                return;
+            if (e.code === 4404)
+                return this.options.onError?.('This project no longer exists.');
+            if (e.code === 4401)
+                return this.options.onError?.('This device link is not valid for the project.');
+            this.options.onStatus?.('offline');
+            this.timer = setTimeout(() => this.open(), this.backoff);
+            this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+        };
+    }
+    deviceInfo() {
+        const v = NSProcessInfo.processInfo.operatingSystemVersion;
+        return {
+            platform: 'macos',
+            model: String(NSProcessInfo.processInfo.hostName ?? 'Mac').replace(/\.local$/, ''),
+            osVersion: `${v.majorVersion}.${v.minorVersion}.${v.patchVersion}`,
+            runtimeVersion: runtimeVersion(),
+            coreVersion: '',
+            moduleLoader: true,
+            host: this.options.host ?? 'node',
+            stream: this.stream,
+        };
+    }
+    provides() {
+        return Object.fromEntries(Object.entries(this.options.linked ?? {}).map(([name, mod]) => [name, Object.keys(mod)]));
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN)
+            this.ws.send(JSON.stringify(msg));
+    }
+    /** Desktop projects have no stylesheets; boot and update differ only in what they replace. */
+    async handle(msg) {
+        if (msg.entry !== this.renderedEntry)
+            await this.render(msg.entry, msg.version);
+        if (msg.type === 'update')
+            this.options.onChanges?.(msg.changes.map((c) => c.path));
+    }
+    /**
+     * Imports the entry's versioned URL, closes what the previous version
+     * opened, then runs the new one. Only modules whose version changed are
+     * fetched. Node can't unload superseded modules, so they stay in memory
+     * until the host restarts.
+     */
+    async render(entry, version) {
+        const started = performance.now();
+        try {
+            const fetched = await prefetch(entry);
+            const mod = await import(entry);
+            if (typeof mod.default !== 'function')
+                throw new Error('app/main.ts must default-export a function that opens the app and returns a function that closes it');
+            this.disposeCurrent();
+            const before = new Set(windowNumbers());
+            const result = await mod.default();
+            // An entry that returns nothing still gets its windows closed on the next update.
+            this.dispose = typeof result === 'function' ? result : () => closeWindowsOpenedSince(before);
+            this.renderedEntry = entry;
+            const ms = Math.round(performance.now() - started);
+            this.send({ type: 'rendered', version, ms });
+            this.options.onRendered?.({ version, ms, fetched });
+            this.streamer.retarget();
+        }
+        catch (e) {
+            this.reportError(e);
+        }
+    }
+    disposeCurrent() {
+        const dispose = this.dispose;
+        this.dispose = undefined;
+        try {
+            dispose?.();
+        }
+        catch (e) {
+            this.reportError(e);
+        }
+    }
+    async answer(msg) {
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`no result within ${RPC_TIMEOUT_MS / 1000}s`)), RPC_TIMEOUT_MS);
+        });
+        try {
+            this.send({ type: 'rpc:result', id: msg.id, ok: true, value: await Promise.race([handleRpc(msg, this.options.allowEval === true), timeout]) });
+        }
+        catch (e) {
+            this.send({ type: 'rpc:result', id: msg.id, ok: false, error: describe(e) });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    reportError(e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        this.send({ type: 'error', message: err.message, stack: err.stack, ts: Date.now() });
+        this.options.onError?.(describe(err));
+    }
+    captureConsole() {
+        for (const level of ['log', 'info', 'warn', 'error']) {
+            const original = console[level].bind(console);
+            console[level] = (...args) => {
+                original(...args);
+                this.send({ type: 'log', level, args: formatArgs(args), ts: Date.now() });
+            };
+        }
+    }
+    /** Project code throwing from a native callback or a timer is reported; the host keeps running. */
+    captureErrors() {
+        process.on('uncaughtException', (e) => this.reportError(e));
+        process.on('unhandledRejection', (e) => this.reportError(e));
+    }
+}
+function windowNumbers() {
+    const windows = NSApp.windows;
+    const out = [];
+    for (let i = 0; i < windows.count; i++)
+        out.push(windows.objectAtIndex(i).windowNumber);
+    return out;
+}
+function closeWindowsOpenedSince(before) {
+    const windows = NSApp.windows;
+    for (let i = windows.count - 1; i >= 0; i--) {
+        const w = windows.objectAtIndex(i);
+        if (!before.has(w.windowNumber))
+            w.close();
+    }
+}
+function describe(e) {
+    return e instanceof Error ? `${e.message}${e.stack ? `\n${e.stack.split('\n').slice(1, 6).join('\n')}` : ''}` : String(e);
+}

package/dist/electron.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Helpers for projects running in an Electron host. A project imports them
+ * from '@nativescript/cloudflare-desktop'; the host links them in.
+ */
+/** The live NSView behind a BrowserWindow, for adding native views above its page. */
+export declare function nativeView(win: {
+    getNativeWindowHandle(): Buffer;
+}): any;
+/** Where a project's `web/` file is served, for `BrowserWindow.loadURL`. */
+export declare function webUrlFor(projectUrl: string): (path?: string) => string;

package/dist/electron.js

@@ -0,0 +1,18 @@
+/**
+ * Helpers for projects running in an Electron host. A project imports them
+ * from '@nativescript/cloudflare-desktop'; the host links them in.
+ */
+/** The live NSView behind a BrowserWindow, for adding native views above its page. */
+export function nativeView(win) {
+    // Electron hands out the NSView* as a Buffer holding the raw pointer.
+    const handle = win.getNativeWindowHandle();
+    const slot = interop.alloc(8);
+    new interop.Reference(interop.types.pointer, slot).value = new interop.Pointer(handle.readBigUInt64LE(0));
+    const view = new interop.Reference(interop.types.id, slot).value;
+    interop.free(slot);
+    return view;
+}
+/** Where a project's `web/` file is served, for `BrowserWindow.loadURL`. */
+export function webUrlFor(projectUrl) {
+    return (path = 'index.html') => `${projectUrl}/web/${path.replace(/^\/+/, '')}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { DesktopClient, type DesktopClientOptions, type DesktopStatus } from './client.js';
+export { loadRuntime, type RuntimeOptions } from './runtime.js';
+export { startApp } from './app.js';
+export { InputInjector } from './input.js';
+export { WindowStreamer, projectWindow } from './stream.js';
+export { nativeView, webUrlFor } from './electron.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { DesktopClient } from './client.js';
+export { loadRuntime } from './runtime.js';
+export { startApp } from './app.js';
+export { InputInjector } from './input.js';
+export { WindowStreamer, projectWindow } from './stream.js';
+export { nativeView, webUrlFor } from './electron.js';

package/dist/input.d.ts

@@ -0,0 +1,31 @@
+import { type StreamInput } from '@nativescript/cloudflare-protocol';
+/**
+ * Turns viewer input into AppKit events for one window. Events go through
+ * the app's own queue (`postEvent`), the only path that drives controls'
+ * tracking loops; a direct `sendEvent` or `mouseDown` never presses an
+ * NSButton. Nothing reaches other apps, the real cursor never moves, and no
+ * Accessibility permission is involved.
+ *
+ * A press is held back until its release arrives, then the whole gesture is
+ * posted at once: a control's tracking loop runs synchronously on this
+ * thread from the press until the release, so a release still waiting in a
+ * socket message would never be read. Drags therefore show up when the
+ * pointer is released, and press-and-hold isn't possible.
+ */
+export declare class InputInjector {
+    private pressed;
+    private eventNumber;
+    private lastDown;
+    private gesture;
+    private gestureTimer?;
+    private lastPointer?;
+    inject(input: StreamInput, window: any): void;
+    private pointer;
+    private flush;
+    /** Ends a gesture whose release never came (the viewer left mid-drag). */
+    private release;
+    /** Double and triple clicks: AppKit reads the count from each event rather than inferring it. */
+    private clickCount;
+    private wheel;
+    private key;
+}