ugly-app 0.1.619 → 0.1.621

package/src/native/contract.ts

@@ -1,4 +1,6 @@
-// Live Activity state shapes (mirror ugly-fit FitLiveActivity.ts).
+// Single source of truth for the UglyNative extension surface.
+
+// ── Shared state shapes ──────────────────────────────────────────────────────
 export interface WorkoutLAState {
   workoutName?: string;
   exerciseName: string;
@@ -18,27 +20,114 @@ export interface CardioLAState {
   elapsedSeconds: number;
   isPaused: boolean;
 }
+export interface HostDirent {
+  name: string;
+  isDirectory: boolean;
+  isFile: boolean;
+}
+export interface HostStat {
+  size: number;
+  isDirectory: boolean;
+  isFile: boolean;
+  mtimeMs: number;
+}
+export interface UpdateStatus {
+  state: 'idle' | 'checking' | 'up-to-date' | 'available' | 'downloading' | 'downloaded' | 'error';
+  version?: string;
+  progressPercent?: number;
+  error?: string;
+}
+export type GrantState = 'granted' | 'denied' | 'scoped' | 'full' | 'prompt';
+export interface SpawnOpts {
+  cwd?: string;
+  env?: Record<string, string>;
+  replaceEnv?: boolean;
+  detached?: boolean;
+  treeKill?: boolean;
+}
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
 
-// Per-channel: payload (web->native) + result (native->web reply).
-// `web` declares the no-shell fallback: 'noop' resolves to the result default,
-// 'throw' rejects with NativeUnavailableError.
+// ── Request/response channels (via invoke) ───────────────────────────────────
 export interface NativeContract {
   channels: {
-    'gps.start': { payload: { activityType: 'run' | 'hike' | 'bike' }; result: void; web: 'noop' };
-    'gps.stop': { payload: void; result: void; web: 'noop' };
-    'alarm.schedule': { payload: { id: string; title?: string; body?: string; delaySeconds: number }; result: void; web: 'noop' };
-    'alarm.cancel': { payload: { id?: string }; result: void; web: 'noop' };
-    'alarm.playAudio': { payload: { id: string; base64: string; mimeType?: string }; result: void; web: 'noop' };
-    'liveActivity.startWorkout': { payload: WorkoutLAState; result: void; web: 'noop' };
-    'liveActivity.updateWorkout': { payload: Partial<WorkoutLAState>; result: void; web: 'noop' };
-    'liveActivity.endWorkout': { payload: void; result: void; web: 'noop' };
-    'liveActivity.startCardio': { payload: CardioLAState; result: void; web: 'noop' };
-    'liveActivity.updateCardio': { payload: Partial<CardioLAState>; result: void; web: 'noop' };
-    'liveActivity.endCardio': { payload: void; result: void; web: 'noop' };
+    // capture
+    'capture.screenshot': { payload: void; result: string };
+    // gps
+    'gps.start': { payload: { activityType: 'run' | 'hike' | 'bike' }; result: void };
+    'gps.stop': { payload: void; result: void };
+    // liveActivity
+    'liveActivity.startWorkout': { payload: WorkoutLAState; result: void };
+    'liveActivity.updateWorkout': { payload: Partial<WorkoutLAState>; result: void };
+    'liveActivity.endWorkout': { payload: void; result: void };
+    'liveActivity.startCardio': { payload: CardioLAState; result: void };
+    'liveActivity.updateCardio': { payload: Partial<CardioLAState>; result: void };
+    'liveActivity.endCardio': { payload: void; result: void };
+    // alarm
+    'alarm.schedule': { payload: { id: string; delaySeconds: number; title?: string; body?: string }; result: void };
+    'alarm.cancel': { payload: { id?: string }; result: void };
+    'alarm.playAudio': { payload: { id: string; base64: string; mimeType?: string }; result: void };
+    // tts
+    'tts.start': { payload: { text: string; voice?: string }; result: void };
+    'tts.pause': { payload: void; result: void };
+    'tts.resume': { payload: void; result: void };
+    'tts.stop': { payload: void; result: void };
+    // push
+    'push.register': { payload: void; result: { token: string } };
+    // clipboard
+    'clipboard.write': { payload: { text: string }; result: void };
+    'clipboard.read': { payload: void; result: { text: string } };
+    // system
+    'system.openExternal': { payload: { url: string }; result: void };
+    'system.share': { payload: { title?: string; text?: string; url?: string }; result: void };
+    // badge
+    'badge.set': { payload: { count: number }; result: void };
+    // ui
+    'ui.getSafeArea': { payload: void; result: SafeAreaInsets };
+    // fs (text ops; byte ops are facade)
+    'fs.readFile': { payload: { path: string }; result: { content: string } };
+    'fs.writeFile': { payload: { path: string; content: string }; result: void };
+    'fs.mkdir': { payload: { path: string; recursive?: boolean }; result: void };
+    'fs.rm': { payload: { path: string; recursive?: boolean; force?: boolean }; result: void };
+    'fs.rename': { payload: { from: string; to: string }; result: void };
+    'fs.readdir': { payload: { path: string }; result: { entries: HostDirent[] } };
+    'fs.stat': { payload: { path: string }; result: HostStat };
+    'fs.exists': { payload: { path: string }; result: { exists: boolean } };
+    'fs.realpath': { payload: { path: string }; result: { path: string } };
+    // secrets
+    'secrets.get': { payload: { key: string }; result: { value: string | null } };
+    'secrets.set': { payload: { key: string; value: string }; result: void };
+    'secrets.delete': { payload: { key: string }; result: void };
+    'secrets.list': { payload: void; result: { keys: string[] } };
+    // serve
+    'serve.start': { payload: { dir?: string }; result: { port: number; url: string } };
+    'serve.stop': { payload: { port: number }; result: void };
+    // workers
+    'workers.register': { payload: { path: string; boot?: boolean }; result: { id: string } };
+    'workers.unregister': { payload: { id: string }; result: void };
+    'workers.list': { payload: void; result: { ids: string[] } };
   };
   events: {
-    'gps.position': { lat: number; lng: number; accuracy: number; timestamp: number; altitude?: number; speed?: number; course?: number };
+    'gps.position': {
+      lat: number;
+      lng: number;
+      accuracy: number;
+      timestamp: number;
+      altitude?: number;
+      speed?: number;
+      course?: number;
+    };
     'alarm.fired': { id: string };
+    'keyboard.height': { height: number };
+    'safeArea.insets': SafeAreaInsets;
+    'tts.state': { state: 'idle' | 'loading' | 'playing' | 'paused' | 'finished' };
+    'push.token': { token: string };
+    'push.notificationClick': { action: string; data: Record<string, string> };
+    'studio.update.status': UpdateStatus;
   };
 }
 
@@ -46,21 +135,30 @@ export type Channel = keyof NativeContract['channels'];
 export type NativeEvent = keyof NativeContract['events'];
 export type PayloadOf<C extends Channel> = NativeContract['channels'][C]['payload'];
 export type ResultOf<C extends Channel> = NativeContract['channels'][C]['result'];
-export type WebFallbackOf<C extends Channel> = NativeContract['channels'][C]['web'];
 export type DataOf<E extends NativeEvent> = NativeContract['events'][E];
 
-// Runtime mirror of each channel's `web` field (TS types are erased, so the
-// fallback behaviour also needs a runtime table). Keep keys in sync with channels.
-export const CHANNEL_WEB_FALLBACK: Record<Channel, 'noop' | 'throw'> = {
-  'gps.start': 'noop',
-  'gps.stop': 'noop',
-  'alarm.schedule': 'noop',
-  'alarm.cancel': 'noop',
-  'alarm.playAudio': 'noop',
-  'liveActivity.startWorkout': 'noop',
-  'liveActivity.updateWorkout': 'noop',
-  'liveActivity.endWorkout': 'noop',
-  'liveActivity.startCardio': 'noop',
-  'liveActivity.updateCardio': 'noop',
-  'liveActivity.endCardio': 'noop',
-};
+// Top-level namespaces (permission units). Includes streaming-facade namespaces
+// (process, net, studio) that are NOT in `channels` but ARE permission/wrapper units.
+export type Namespace =
+  | 'capture'
+  | 'gps'
+  | 'liveActivity'
+  | 'alarm'
+  | 'tts'
+  | 'push'
+  | 'clipboard'
+  | 'system'
+  | 'badge'
+  | 'ui'
+  | 'fs'
+  | 'secrets'
+  | 'serve'
+  | 'workers'
+  | 'net'
+  | 'process'
+  | 'permissions'
+  | 'studio';
+
+export function namespaceOf(channel: Channel): Namespace {
+  return channel.split('.')[0] as Namespace;
+}

package/src/native/facades/facades.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { createProcessFacade } from './process';
+import { createNetFacade } from './net';
+import { createStudioFacade } from './studio';
+import { NativeUnavailableError } from '../protocol';
+
+describe('process facade', () => {
+  it('throws NativeUnavailableError off-desktop', () => {
+    const proc = createProcessFacade(() => undefined, 'ios', async () => {});
+    expect(() => proc.spawn('ls', [])).toThrow(NativeUnavailableError);
+  });
+  it('delegates to the desktop bridge on desktop', () => {
+    const handle = {
+      onStdout() {}, onStderr() {}, onExit() {}, onError() {}, write() {}, closeStdin() {}, kill() {},
+    };
+    const bridge = { spawn: () => handle };
+    const proc = createProcessFacade(() => bridge, 'desktop', async () => {});
+    expect(proc.spawn('ls', ['-a'])).toBe(handle);
+  });
+});
+
+describe('net facade', () => {
+  it('throws on web', () => {
+    const net = createNetFacade(() => undefined, 'web', async () => {});
+    expect(() => net.connect('h', 1)).toThrow(NativeUnavailableError);
+  });
+});
+
+describe('studio facade', () => {
+  it('app.platform returns the platform; revealInFolder throws off-desktop', async () => {
+    const studio = createStudioFacade(() => undefined, 'web');
+    expect(studio.app.platform()).toBe('web');
+    await expect(studio.revealInFolder('/x')).rejects.toBeInstanceOf(NativeUnavailableError);
+  });
+});

package/src/native/facades/net.ts

@@ -0,0 +1,50 @@
+import { NativeUnavailableError } from '../protocol.js';
+import type { Platform } from '../contract-meta.js';
+
+export interface UglySocket {
+  onConnect(cb: () => void): void;
+  onData(cb: (chunk: Uint8Array) => void): void;
+  onClose(cb: () => void): void;
+  onError(cb: (err: string) => void): void;
+  write(data: Uint8Array | string): void;
+  end(): void;
+  close(): void;
+}
+export interface UglyServer {
+  port: number;
+  onConnection(cb: (s: UglySocket) => void): void;
+  close(): void;
+}
+
+interface NetBridge {
+  connect(host: string, port: number): UglySocket;
+  listen(port?: number): Promise<UglyServer>;
+}
+
+export interface NetFacade {
+  connect(host: string, port: number): UglySocket;
+  listen(port?: number): Promise<UglyServer>;
+}
+
+export function createNetFacade(
+  getBridge: () => NetBridge | undefined,
+  platform: Platform,
+  ensure: () => Promise<void>,
+): NetFacade {
+  const guard = (): NetBridge => {
+    if (platform === 'web') throw new NativeUnavailableError('net.connect');
+    const b = getBridge();
+    if (!b) throw new NativeUnavailableError('net.connect');
+    return b;
+  };
+  return {
+    connect(host, port) {
+      void ensure();
+      return guard().connect(host, port);
+    },
+    listen(port) {
+      void ensure();
+      return guard().listen(port);
+    },
+  };
+}

package/src/native/facades/process.ts

@@ -0,0 +1,37 @@
+import { NativeUnavailableError } from '../protocol.js';
+import type { Platform } from '../contract-meta.js';
+import type { SpawnOpts } from '../contract.js';
+
+export interface UglyProcess {
+  onStdout(cb: (chunk: string) => void): void;
+  onStderr(cb: (chunk: string) => void): void;
+  onExit(cb: (code: number | null) => void): void;
+  onError(cb: (err: string) => void): void;
+  write(data: string): void;
+  closeStdin(): void;
+  kill(signal?: string): void;
+}
+
+interface ProcessBridge {
+  spawn(cmd: string, args: string[], opts?: SpawnOpts): UglyProcess;
+}
+
+export interface ProcessFacade {
+  spawn(cmd: string, args: string[], opts?: SpawnOpts): UglyProcess;
+}
+
+export function createProcessFacade(
+  getBridge: () => ProcessBridge | undefined,
+  platform: Platform,
+  ensure: () => Promise<void>,
+): ProcessFacade {
+  return {
+    spawn(cmd, args, opts) {
+      if (platform !== 'desktop') throw new NativeUnavailableError('process.spawn');
+      void ensure(); // fire the permission check; the desktop daemon also enforces
+      const bridge = getBridge();
+      if (!bridge) throw new NativeUnavailableError('process.spawn');
+      return bridge.spawn(cmd, args, opts);
+    },
+  };
+}

package/src/native/facades/studio.ts

@@ -0,0 +1,73 @@
+import { NativeUnavailableError } from '../protocol.js';
+import type { NativePlatform } from '../protocol.js';
+import type { Platform } from '../contract-meta.js';
+import type { UpdateStatus } from '../contract.js';
+
+export interface StudioFacade {
+  window: {
+    minimize(): Promise<void>;
+    maximizeToggle(): Promise<boolean>;
+    close(): Promise<void>;
+    isMaximized(): Promise<boolean>;
+  };
+  fullscreen: { toggle(): Promise<boolean>; is(): Promise<boolean> };
+  zoom: { get(): Promise<number>; set(level: number): Promise<void> };
+  update: {
+    check(): Promise<UpdateStatus>;
+    download(): Promise<UpdateStatus>;
+    install(): Promise<void>;
+    getStatus(): Promise<UpdateStatus>;
+  };
+  dialog: { openDirectory(): Promise<string | null> };
+  revealInFolder(path: string): Promise<void>;
+  app: { version(): Promise<string>; platform(): NativePlatform };
+  openProjectInNewWindow(path: string): Promise<void>;
+}
+
+type StudioBridge = Partial<{
+  window: StudioFacade['window'];
+  fullscreen: StudioFacade['fullscreen'];
+  zoom: StudioFacade['zoom'];
+  update: StudioFacade['update'];
+  dialog: StudioFacade['dialog'];
+  revealInFolder: (p: string) => Promise<void>;
+  getAppVersion: () => Promise<string>;
+  openProjectInNewWindow: (p: string) => Promise<void>;
+}>;
+
+export function createStudioFacade(getBridge: () => StudioBridge | undefined, platform: Platform): StudioFacade {
+  const b = () => getBridge();
+  const noop = async (): Promise<void> => {};
+  const unavailable = (ch: string): never => {
+    throw new NativeUnavailableError(ch);
+  };
+  return {
+    window: {
+      minimize: async () => (b()?.window ? b()!.window!.minimize() : noop()),
+      maximizeToggle: async () => (b()?.window ? b()!.window!.maximizeToggle() : false),
+      close: async () => (b()?.window ? b()!.window!.close() : noop()),
+      isMaximized: async () => (b()?.window ? b()!.window!.isMaximized() : false),
+    },
+    fullscreen: {
+      toggle: async () => (b()?.fullscreen ? b()!.fullscreen!.toggle() : false),
+      is: async () => (b()?.fullscreen ? b()!.fullscreen!.is() : false),
+    },
+    zoom: {
+      get: async () => (b()?.zoom ? b()!.zoom!.get() : 0),
+      set: async (l) => (b()?.zoom ? b()!.zoom!.set(l) : noop()),
+    },
+    update: {
+      check: async () => (b()?.update ? b()!.update!.check() : unavailable('studio.update.check')),
+      download: async () => (b()?.update ? b()!.update!.download() : unavailable('studio.update.download')),
+      install: async () => (b()?.update ? b()!.update!.install() : unavailable('studio.update.install')),
+      getStatus: async () => (b()?.update ? b()!.update!.getStatus() : unavailable('studio.update.getStatus')),
+    },
+    dialog: { openDirectory: async () => (b()?.dialog ? b()!.dialog!.openDirectory() : null) },
+    revealInFolder: async (p) => (b()?.revealInFolder ? b()!.revealInFolder!(p) : unavailable('studio.revealInFolder')),
+    app: {
+      version: async () => (b()?.getAppVersion ? b()!.getAppVersion!() : ''),
+      platform: () => platform as NativePlatform,
+    },
+    openProjectInNewWindow: async (p) => (b()?.openProjectInNewWindow ? b()!.openProjectInNewWindow!(p) : noop()),
+  };
+}

package/src/native/index.ts

@@ -1,7 +1,28 @@
 export type {
-  NativeContract, Channel, NativeEvent, PayloadOf, ResultOf, DataOf, WorkoutLAState, CardioLAState,
+  NativeContract,
+  Channel,
+  NativeEvent,
+  PayloadOf,
+  ResultOf,
+  DataOf,
+  Namespace,
+  WorkoutLAState,
+  CardioLAState,
+  HostDirent,
+  HostStat,
+  UpdateStatus,
+  GrantState,
+  SpawnOpts,
+  SafeAreaInsets,
 } from './contract.js';
+export { namespaceOf } from './contract.js';
+export type { Platform, Fallback } from './contract-meta.js';
+export { CHANNEL_FALLBACK, NAMESPACES, fallbackFor } from './contract-meta.js';
 export type { NativePlatform, UglyNative } from './protocol.js';
-export { NativeUnavailableError } from './protocol.js';
-export { native, nativePlatform, isNativeAvailable } from './wrapper.js';
+export { NativeUnavailableError, PermissionDeniedError } from './protocol.js';
 export { installUglyNative } from './install.js';
+export { native, permissions, nativePlatform, isNativeAvailable } from './wrapper.js';
+export type { PermissionsFacade } from './permissions.js';
+export type { UglyProcess } from './facades/process.js';
+export type { UglySocket, UglyServer } from './facades/net.js';
+export type { StudioFacade } from './facades/studio.js';

package/src/native/install.test.ts

@@ -1,3 +1,4 @@
+// @vitest-environment jsdom
 import { describe, it, expect, vi } from 'vitest';
 import { buildUglyNative } from './install';
 
@@ -56,6 +57,13 @@ describe('buildUglyNative', () => {
     await expect(p).resolves.toBeNull();
   });
 
+  it('web platform routes clipboard.read through the web-adapter', async () => {
+    (navigator as unknown as { clipboard: unknown }).clipboard = { readText: async () => 'zz' };
+    const n = buildUglyNative(fakeWin({}));
+    expect(n.platform).toBe('web');
+    expect(await n.invoke('clipboard.read', undefined)).toEqual({ text: 'zz' });
+  });
+
   it('delivers events to subscribers', () => {
     const win = fakeWin({});
     const n = buildUglyNative(win);

package/src/native/install.ts

@@ -1,7 +1,6 @@
 import type { Channel, NativeEvent, PayloadOf, ResultOf, DataOf } from './contract.js';
-import { CHANNEL_WEB_FALLBACK } from './contract.js';
 import type { UglyNative, UglyNativeWindow } from './protocol.js';
-import { NativeUnavailableError } from './protocol.js';
+import { webInvoke } from './web-adapter.js';
 
 type WinLike = UglyNativeWindow & {
   addEventListener(type: string, cb: (e: unknown) => void): void;
@@ -10,6 +9,16 @@ type WinLike = UglyNativeWindow & {
 };
 
 export function buildUglyNative(win: WinLike): UglyNative {
+  // Native→web event bus: dispatch a uniform CustomEvent the subscriber reads.
+  const emit = <E extends NativeEvent>(event: E, data: DataOf<E>): void => {
+    const detail = { event, data };
+    const ev =
+      typeof CustomEvent === 'function'
+        ? new CustomEvent('uglyNative', { detail })
+        : ({ type: 'uglyNative', detail } as unknown as Event);
+    win.dispatchEvent(ev);
+  };
+
   // ── invoke transport (priority: desktop -> ios -> android -> web) ──
   let platform: UglyNative['platform'];
   let rawInvoke: (channel: string, payload: unknown) => Promise<unknown>;
@@ -44,12 +53,7 @@ export function buildUglyNative(win: WinLike): UglyNative {
       });
   } else {
     platform = 'web';
-    rawInvoke = (channel) => {
-      if (CHANNEL_WEB_FALLBACK[channel as Channel] === 'throw') {
-        return Promise.reject(new NativeUnavailableError(channel));
-      }
-      return Promise.resolve(undefined);
-    };
+    rawInvoke = (channel, payload) => webInvoke(channel as Channel, payload, emit);
   }
 
   // ── events: single 'uglyNative' CustomEvent carrying {event, data} ──

package/src/native/permissions.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createPermissions } from './permissions';
+import { PermissionDeniedError } from './protocol';
+
+// A fake transport that models grants accumulating via permissions.request.
+function fakeInvoke() {
+  const granted: Record<string, string> = {};
+  return vi.fn(async (channel: string, payload: unknown) => {
+    if (channel === 'permissions.request') {
+      const grants = (payload as { grants: Record<string, string | boolean> }).grants;
+      for (const [k, v] of Object.entries(grants)) granted[k] = v === true ? 'granted' : String(v);
+      return { granted: { ...granted } };
+    }
+    if (channel === 'permissions.query') return { granted: { ...granted } };
+    if (channel === 'permissions.revoke') {
+      delete granted[(payload as { namespace: string }).namespace];
+      return undefined;
+    }
+    return undefined;
+  });
+}
+
+describe('permissions facade', () => {
+  it('ensure throws for ungranted daemon namespace, passes after grant', async () => {
+    const invoke = fakeInvoke();
+    const perms = createPermissions(invoke, 'desktop');
+    await expect(perms.ensure('fs')).rejects.toBeInstanceOf(PermissionDeniedError);
+    await perms.request({ fs: 'scoped' });
+    await expect(perms.ensure('fs')).resolves.toBeUndefined();
+  });
+  it('ensure is a no-op for app namespaces (gps)', async () => {
+    const invoke = fakeInvoke();
+    const perms = createPermissions(invoke, 'ios');
+    await expect(perms.ensure('gps')).resolves.toBeUndefined();
+    expect(invoke).not.toHaveBeenCalled();
+  });
+  it('daemon namespace on web always throws', async () => {
+    const invoke = fakeInvoke();
+    const perms = createPermissions(invoke, 'web');
+    await expect(perms.ensure('secrets')).rejects.toBeInstanceOf(PermissionDeniedError);
+  });
+});

package/src/native/permissions.ts

@@ -0,0 +1,53 @@
+import type { Namespace, GrantState } from './contract.js';
+import type { Platform } from './contract-meta.js';
+import { PermissionDeniedError } from './protocol.js';
+
+// Namespaces gated by explicit grants (daemon capabilities). OS-backed and app
+// namespaces are not pre-gated here (the OS prompts at call time).
+const GATED: ReadonlySet<Namespace> = new Set<Namespace>([
+  'fs',
+  'secrets',
+  'serve',
+  'workers',
+  'net',
+  'process',
+]);
+
+type Invoke = (channel: string, payload: unknown) => Promise<unknown>;
+
+export interface PermissionsFacade {
+  request(grants: Partial<Record<Namespace, GrantState | boolean>>): Promise<Record<string, GrantState>>;
+  query(): Promise<Record<string, GrantState>>;
+  revoke(namespace: Namespace): Promise<void>;
+  ensure(namespace: Namespace): Promise<void>;
+}
+
+export function createPermissions(invoke: Invoke, platform: Platform): PermissionsFacade {
+  const cache = new Map<Namespace, GrantState>();
+  const facade: PermissionsFacade = {
+    async request(grants) {
+      const res = (await invoke('permissions.request', { grants })) as { granted: Record<string, GrantState> };
+      for (const [k, v] of Object.entries(res.granted)) cache.set(k as Namespace, v);
+      return res.granted;
+    },
+    async query() {
+      const res = (await invoke('permissions.query', undefined)) as { granted: Record<string, GrantState> };
+      for (const [k, v] of Object.entries(res.granted)) cache.set(k as Namespace, v);
+      return res.granted;
+    },
+    async revoke(namespace) {
+      await invoke('permissions.revoke', { namespace });
+      cache.delete(namespace);
+    },
+    async ensure(namespace) {
+      if (!GATED.has(namespace)) return;
+      if (platform === 'web') throw new PermissionDeniedError(namespace);
+      const cached = cache.get(namespace);
+      if (cached && cached !== 'denied' && cached !== 'prompt') return;
+      const granted = await facade.query();
+      const state = granted[namespace];
+      if (!state || state === 'denied' || state === 'prompt') throw new PermissionDeniedError(namespace);
+    },
+  };
+  return facade;
+}

package/src/native/protocol.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { PermissionDeniedError, NativeUnavailableError } from './protocol';
+
+describe('protocol errors', () => {
+  it('PermissionDeniedError carries the namespace', () => {
+    const e = new PermissionDeniedError('fs');
+    expect(e).toBeInstanceOf(Error);
+    expect(e.namespace).toBe('fs');
+    expect(e.message).toContain('fs');
+  });
+  it('NativeUnavailableError carries the channel', () => {
+    const e = new NativeUnavailableError('process.spawn');
+    expect(e.message).toContain('process.spawn');
+  });
+});

package/src/native/protocol.ts

@@ -1,4 +1,4 @@
-import type { Channel, NativeEvent, PayloadOf, ResultOf, DataOf } from './contract.js';
+import type { Channel, NativeEvent, PayloadOf, ResultOf, DataOf, Namespace } from './contract.js';
 
 export type NativePlatform = 'ios' | 'android' | 'desktop' | 'web';
 
@@ -9,6 +9,15 @@ export class NativeUnavailableError extends Error {
   }
 }
 
+export class PermissionDeniedError extends Error {
+  readonly namespace: Namespace;
+  constructor(namespace: Namespace) {
+    super(`uglyNative.${namespace}.* requires the "${namespace}" permission (not granted)`);
+    this.name = 'PermissionDeniedError';
+    this.namespace = namespace;
+  }
+}
+
 export interface UglyNative {
   readonly platform: NativePlatform;
   invoke<C extends Channel>(channel: C, payload: PayloadOf<C>): Promise<ResultOf<C>>;

package/src/native/web-adapter.test.ts

@@ -0,0 +1,27 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { webInvoke } from './web-adapter';
+import { NativeUnavailableError } from './protocol';
+
+describe('web-adapter', () => {
+  beforeEach(() => {
+    (navigator as unknown as { clipboard: unknown }).clipboard = {
+      writeText: vi.fn().mockResolvedValue(undefined),
+      readText: vi.fn().mockResolvedValue('hi'),
+    };
+  });
+  it('clipboard.write delegates to navigator.clipboard.writeText', async () => {
+    await webInvoke('clipboard.write', { text: 'yo' }, () => {});
+    expect((navigator.clipboard as { writeText: ReturnType<typeof vi.fn> }).writeText).toHaveBeenCalledWith('yo');
+  });
+  it('clipboard.read returns navigator.clipboard.readText', async () => {
+    const r = await webInvoke('clipboard.read', undefined, () => {});
+    expect(r).toEqual({ text: 'hi' });
+  });
+  it('fs.readFile throws NativeUnavailableError on web', async () => {
+    await expect(webInvoke('fs.readFile', { path: '/x' }, () => {})).rejects.toBeInstanceOf(NativeUnavailableError);
+  });
+  it('liveActivity.endWorkout is a silent noop-ish resolve (no throw)', async () => {
+    await expect(webInvoke('liveActivity.endWorkout', undefined, () => {})).resolves.toBeUndefined();
+  });
+});