@brftech/filex-app-ui 0.48.1

package/src/index.ts

@@ -0,0 +1,384 @@
+/**
+ * @brftech/filex-app-ui — the SDK an app's own interface bundles.
+ *
+ * ```js
+ * import { connect } from '@brftech/filex-app-ui';
+ *
+ * const fx = await connect();          // the handshake with filex
+ * const file = await fx.open();        // the file the app was opened with
+ * editor.setValue(await file.text());
+ * editor.onChange(() => fx.dirty(true));
+ * fx.onSave(async () => editor.getValue()); // filex's Save, a draft's "Save to disk", Ctrl+S
+ * ```
+ *
+ * No dependency, a few KB. The interface runs in a sandboxed frame with no
+ * network and no storage of its own: every call below goes to filex over the
+ * MessagePort the handshake set up, and filex decides it (docs/APP-PLUGINS.md
+ * → "An app's own interface"). The protocol itself is `./protocol`.
+ */
+import {
+  BRIDGE_VERSION,
+  HELLO,
+  LIMITS,
+  isPortMessage,
+  type BridgeError,
+  type ConfirmParams,
+  type ErrorCode,
+  type FileInfo,
+  type HostEvent,
+  type HostRequestMessage,
+  type Method,
+  type ReadResult,
+  type SaveAsResult,
+  type SaveResult,
+  type Session,
+  type Theme,
+  type ToastParams,
+  type DownloadResult,
+} from './protocol';
+
+export * from './protocol';
+
+/** A call filex refused, with the reason as a code. */
+export class FilexError extends Error {
+  readonly code: ErrorCode;
+  constructor(err: BridgeError) {
+    super(err.message || err.code);
+    this.name = 'FilexError';
+    this.code = err.code;
+  }
+}
+
+/** Content the app hands to a save. */
+export type SaveData = string | Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array>;
+
+/** One opened file, read the way the app needs it. */
+export interface OpenedFile extends FileInfo {
+  text(): Promise<string>;
+  bytes(): Promise<ArrayBuffer>;
+  stream(): Promise<ReadableStream<Uint8Array>>;
+  /** Save new content over this file (a new version, or the draft it is). */
+  save(data: SaveData, mime?: string): Promise<SaveResult>;
+}
+
+export interface ConnectOptions {
+  /** How long to wait for filex (default 10 s). */
+  timeoutMs?: number;
+  /**
+   * Put filex's colours (`--fe-*`), `lang`, `dir` and `data-theme` on
+   * `<html>`, and keep them current (default true).
+   */
+  applyTheme?: boolean;
+  /** Ctrl/Cmd+S inside the interface runs the save handler (default true). */
+  saveShortcut?: boolean;
+}
+
+export interface FilexApp {
+  readonly session: Session;
+  /** The file at `index` (default the first) the interface was opened with. */
+  open(index?: number): Promise<OpenedFile>;
+  /** Save new content over an opened file. */
+  save(data: SaveData, opts?: { index?: number; mime?: string }): Promise<SaveResult>;
+  /** Save a NEW file; filex asks the person where (its own folder picker). */
+  saveAs(name: string, data: SaveData, mime?: string): Promise<SaveAsResult>;
+  /** Unsaved changes, or not: filex asks before the person leaves them. */
+  dirty(on: boolean): void;
+  title(text: string): void;
+  toast(text: string, tone?: ToastParams['tone']): void;
+  confirm(opts: ConfirmParams | string): Promise<boolean>;
+  /** Ask filex to close the interface (it asks first when there are changes). */
+  close(): void;
+  /** Put text on the clipboard (filex does it, the same way in every browser). */
+  copy(text: string): Promise<void>;
+  /**
+   * Hand the person a file for their own disk (the app needs `ui.download`
+   * in its manifest). Call it from a click or a key press: without one,
+   * filex asks the person first. `cancelled` when they say no.
+   */
+  download(name: string, data: SaveData, mime?: string): Promise<DownloadResult>;
+  /** Call the app's own module (`ui_call` export) with the opened files. */
+  call<T = unknown>(method: string, params?: unknown): Promise<T>;
+  /** Queue one of the app's actions on the opened files; answers the op. */
+  submit(action: string, params?: Record<string, unknown>): Promise<{ op: unknown }>;
+  /** This person's small store for this app (JSON values, 8 KiB each). */
+  state: {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+  };
+  /** Listen to filex. Returns the unsubscribe. */
+  on(event: HostEvent, handler: (data: unknown) => void): () => void;
+  /**
+   * What to save when filex asks (its Save button, a draft's "Save to disk",
+   * Ctrl+S): return the document and the SDK saves it over the opened file;
+   * return nothing if the handler saved by itself.
+   */
+  onSave(handler: () => SaveData | void | Promise<SaveData | void>): () => void;
+  /** Raw call, for a method this SDK has no helper for. */
+  request<T = unknown>(method: Method, params?: unknown, transfer?: Transferable[]): Promise<T>;
+}
+
+let connecting: Promise<FilexApp> | null = null;
+
+/**
+ * The handshake. Resolves once filex answered with its port and the session;
+ * rejects outside filex or when filex did not answer in time. Calling it again
+ * answers the same connection.
+ */
+export function connect(opts: ConnectOptions = {}): Promise<FilexApp> {
+  if (!connecting) connecting = open(opts);
+  return connecting;
+}
+
+function open(opts: ConnectOptions): Promise<FilexApp> {
+  return new Promise<FilexApp>((resolve, reject) => {
+    if (typeof window === 'undefined' || window.parent === window) {
+      reject(new FilexError({ code: 'unavailable', message: 'not running inside filex' }));
+      return;
+    }
+    const parent = window.parent;
+    // Where filex runs, when the browser says so (Chrome, Safari). A frame
+    // drawn with referrerpolicy="no-referrer" has no document.referrer, and
+    // Firefox has no ancestorOrigins: then `source === parent` is the check,
+    // which is the one that matters (only the parent window IS the parent).
+    const expected = ancestorOrigin();
+    const timer = setTimeout(() => {
+      window.removeEventListener('message', onMessage);
+      reject(new FilexError({ code: 'unavailable', message: 'filex did not answer' }));
+    }, opts.timeoutMs ?? LIMITS.connectTimeoutMs);
+
+    function onMessage(ev: MessageEvent) {
+      if (ev.source !== parent || !isPortMessage(ev.data) || !ev.ports[0]) return;
+      if (expected && ev.origin !== expected) return;
+      window.removeEventListener('message', onMessage);
+      clearTimeout(timer);
+      const port = ev.ports[0];
+      const app = bridge(port, opts);
+      app
+        .request<Session>('session.get')
+        .then((session) => {
+          (app as { session: Session }).session = session;
+          if (opts.applyTheme !== false) {
+            applyLook(session.theme, session.locale, session.dir);
+            app.on('theme', (t) => applyLook(t as Theme));
+            app.on('locale', (l) => {
+              const v = l as { locale?: string; dir?: 'ltr' | 'rtl' };
+              applyLook(undefined, v.locale, v.dir);
+            });
+          }
+          resolve(app);
+        })
+        .catch(reject);
+    }
+    window.addEventListener('message', onMessage);
+    parent.postMessage({ type: HELLO, v: BRIDGE_VERSION }, '*');
+  });
+}
+
+function ancestorOrigin(): string {
+  try {
+    const list = (window.location as Location & { ancestorOrigins?: DOMStringList }).ancestorOrigins;
+    if (list && list.length > 0 && list[0] !== 'null') return list[0];
+  } catch {
+    /* no such API */
+  }
+  return '';
+}
+
+function bridge(port: MessagePort, opts: ConnectOptions): FilexApp {
+  let seq = 0;
+  const pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: unknown) => void }>();
+  const listeners = new Map<HostEvent, Set<(data: unknown) => void>>();
+  let saveHandler: (() => SaveData | void | Promise<SaveData | void>) | null = null;
+
+  port.onmessage = (ev: MessageEvent) => {
+    const m = ev.data as Record<string, unknown> | null;
+    if (!m || typeof m !== 'object') return;
+    if (typeof m.id === 'number') {
+      const p = pending.get(m.id);
+      if (!p) return;
+      pending.delete(m.id);
+      if (m.error) p.reject(new FilexError(m.error as BridgeError));
+      else p.resolve(m.result);
+      return;
+    }
+    if (typeof m.hid === 'number') {
+      void answerHost(m as unknown as HostRequestMessage);
+      return;
+    }
+    if (typeof m.event === 'string') {
+      for (const h of listeners.get(m.event as HostEvent) ?? []) {
+        try {
+          h(m.data);
+        } catch (e) {
+          console.error('[filex-app-ui] listener failed', e);
+        }
+      }
+    }
+  };
+
+  async function answerHost(m: HostRequestMessage) {
+    if (m.request === 'save') {
+      if (!saveHandler) {
+        port.postMessage({ hid: m.hid, error: { code: 'unavailable', message: 'this app has no save handler' } });
+        return;
+      }
+      try {
+        const res = await runSave();
+        port.postMessage({ hid: m.hid, result: res ?? { saved: true } });
+      } catch (e) {
+        const err = e instanceof FilexError ? { code: e.code, message: e.message } : { code: 'failed', message: String((e as Error)?.message ?? e) };
+        port.postMessage({ hid: m.hid, error: err });
+      }
+      return;
+    }
+    port.postMessage({ hid: m.hid, error: { code: 'unknown_method' } });
+  }
+
+  async function runSave(): Promise<SaveResult | null> {
+    if (!saveHandler) return null;
+    const data = await saveHandler();
+    if (data === undefined || data === null) return null;
+    return app.save(data as SaveData);
+  }
+
+  function request<T>(method: Method, params?: unknown, transfer: Transferable[] = []): Promise<T> {
+    const id = ++seq;
+    return new Promise<T>((resolve, reject) => {
+      pending.set(id, { resolve: resolve as (v: unknown) => void, reject });
+      try {
+        port.postMessage({ id, method, params }, transfer);
+      } catch (e) {
+        pending.delete(id);
+        reject(e);
+      }
+    });
+  }
+
+  function notify(method: Method, params?: unknown) {
+    request(method, params).catch((e) => console.warn('[filex-app-ui]', method, e));
+  }
+
+  async function payload(data: SaveData): Promise<{ data: ReadableStream<Uint8Array> | ArrayBuffer | string; transfer: Transferable[] }> {
+    if (typeof data === 'string') return { data, transfer: [] };
+    if (data instanceof ArrayBuffer) return { data, transfer: [data] };
+    if (ArrayBuffer.isView(data)) {
+      const copy = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+      return { data: copy, transfer: [copy] };
+    }
+    if (typeof Blob !== 'undefined' && data instanceof Blob) {
+      const buf = await data.arrayBuffer();
+      return { data: buf, transfer: [buf] };
+    }
+    if (typeof ReadableStream !== 'undefined' && data instanceof ReadableStream) {
+      return { data, transfer: [data as unknown as Transferable] };
+    }
+    throw new FilexError({ code: 'invalid', message: 'save takes a string, a Blob, bytes or a ReadableStream' });
+  }
+
+  const app: FilexApp = {
+    session: undefined as unknown as Session,
+    async open(index = 0) {
+      const info = app.session?.files?.[index];
+      if (!info) throw new FilexError({ code: 'not_found', message: `no file at ${index}` });
+      const read = <K extends keyof ReadResult>(as: 'stream' | 'bytes' | 'text', key: K) =>
+        request<ReadResult>('file.read', { index, as }).then((r) => r[key] as NonNullable<ReadResult[K]>);
+      return {
+        ...info,
+        text: () => read('text', 'text'),
+        bytes: () => read('bytes', 'bytes'),
+        stream: () => read('stream', 'stream'),
+        save: (data: SaveData, mime?: string) => app.save(data, { index, mime }),
+      };
+    },
+    async save(data, o = {}) {
+      const p = await payload(data);
+      return request<SaveResult>('file.save', { index: o.index ?? 0, data: p.data, mime: o.mime }, p.transfer);
+    },
+    async saveAs(name, data, mime) {
+      const p = await payload(data);
+      return request<SaveAsResult>('file.saveAs', { name, data: p.data, mime }, p.transfer);
+    },
+    async download(name, data, mime) {
+      const p = await payload(data);
+      return request<DownloadResult>('ui.download', { name, data: p.data, mime }, p.transfer);
+    },
+    dirty(on) {
+      notify('ui.dirty', { dirty: !!on });
+    },
+    title(text) {
+      notify('ui.title', { text: String(text).slice(0, LIMITS.maxLineChars) });
+    },
+    toast(text, tone) {
+      notify('ui.toast', { text: String(text).slice(0, LIMITS.maxLineChars), tone });
+    },
+    confirm(o) {
+      const params = typeof o === 'string' ? { text: o } : o;
+      return request<boolean>('ui.confirm', params);
+    },
+    close() {
+      notify('ui.close');
+    },
+    copy(text) {
+      return request<void>('clipboard.write', { text: String(text) });
+    },
+    call<T>(method: string, params?: unknown) {
+      return request<T>('engine.call', { method, params });
+    },
+    submit(action, params) {
+      return request<{ op: unknown }>('job.submit', { action, params });
+    },
+    state: {
+      get<T>(key: string) {
+        return request<T | undefined>('state.get', { key });
+      },
+      set(key: string, value: unknown) {
+        return request<void>('state.set', { key, value });
+      },
+    },
+    on(event, handler) {
+      let set = listeners.get(event);
+      if (!set) listeners.set(event, (set = new Set()));
+      set.add(handler);
+      return () => set!.delete(handler);
+    },
+    onSave(handler) {
+      saveHandler = handler;
+      return () => {
+        if (saveHandler === handler) saveHandler = null;
+      };
+    },
+    request,
+  };
+
+  if (opts.saveShortcut !== false && typeof document !== 'undefined') {
+    // ⚠ The keystroke is handled HERE and never forwarded: a frame that could
+    // send key events to filex could press filex's own shortcuts. Ctrl+S runs
+    // the app's own save handler, which saves through the bridge like any call.
+    document.addEventListener(
+      'keydown',
+      (e) => {
+        if ((e.ctrlKey || e.metaKey) && !e.altKey && !e.shiftKey && (e.key === 's' || e.key === 'S') && saveHandler) {
+          e.preventDefault();
+          runSave().catch((err) => app.toast(String((err as Error)?.message ?? err), 'error'));
+        }
+      },
+      true,
+    );
+  }
+  return app;
+}
+
+/** Paint filex's look onto the interface's own document. */
+function applyLook(theme?: Theme, locale?: string, dir?: 'ltr' | 'rtl') {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  if (theme) {
+    root.dataset.theme = theme.mode;
+    root.style.colorScheme = theme.mode;
+    for (const [k, v] of Object.entries(theme.tokens ?? {})) {
+      if (/^--fe-[a-z0-9-]+$/.test(k) && typeof v === 'string') root.style.setProperty(k, v);
+    }
+  }
+  if (locale) root.lang = locale;
+  if (dir) root.dir = dir;
+}

package/src/protocol.ts

@@ -0,0 +1,320 @@
+/**
+ * The bridge between filex and an app's own interface — the ONE definition.
+ *
+ * An app's interface (the `ui` block of its filex-app.json) runs in a frame
+ * filex draws with `sandbox="allow-scripts"`: an opaque origin, no cookies, no
+ * storage, no network (the server's CSP says `connect-src 'none'`). Everything
+ * it may do goes through this bridge, and the host decides every call.
+ *
+ * Both halves import this file — the SDK the app bundles (`src/index.ts`) and
+ * filex's own frame (`packages/core/src/components/plugin/AppFrame.vue`) — so a
+ * method or an event added here is added on both sides at once.
+ *
+ * The wire, in order (docs/APP-PLUGINS-API.md → "The interface bridge"):
+ *
+ *  1. The app posts `{type: 'filex:hello', v: 1}` to its parent window.
+ *  2. The host takes it ONLY when `event.source` is the frame it drew. The
+ *     origin says nothing here: a sandboxed frame's origin is always "null",
+ *     so any other sandboxed frame on the page would look the same (measured,
+ *     2026-09-27, Chrome, Firefox and WebKit).
+ *  3. The host answers with a MessagePort: `{type: 'filex:port', v: 1}` and
+ *     the port transferred. Once per load of the frame; a second hello is
+ *     ignored.
+ *  4. The app takes the port ONLY when `event.source` is its parent window.
+ *  5. From then on, only the port: requests `{id, method, params}`, answers
+ *     `{id, result}` or `{id, error}`, events `{event, data}`, and the host's
+ *     own requests `{hid, request, params}` answered `{hid, result|error}`.
+ */
+
+/** The bridge generation both sides speak. */
+export const BRIDGE_VERSION = 1;
+
+/** The app's first message, to `window.parent`. */
+export const HELLO = 'filex:hello';
+/** The host's answer, carrying the port. */
+export const PORT = 'filex:port';
+
+/** What the app may ask the host. Anything else is `unknown_method`. */
+export type Method =
+  | 'session.get'
+  | 'file.read'
+  | 'file.save'
+  | 'file.saveAs'
+  | 'ui.dirty'
+  | 'ui.title'
+  | 'ui.toast'
+  | 'ui.confirm'
+  | 'ui.close'
+  | 'clipboard.write'
+  | 'ui.download'
+  | 'engine.call'
+  | 'job.submit'
+  | 'state.get'
+  | 'state.set';
+
+export const METHODS: readonly Method[] = [
+  'session.get',
+  'file.read',
+  'file.save',
+  'file.saveAs',
+  'ui.dirty',
+  'ui.title',
+  'ui.toast',
+  'ui.confirm',
+  'ui.close',
+  'clipboard.write',
+  'ui.download',
+  'engine.call',
+  'job.submit',
+  'state.get',
+  'state.set',
+];
+
+/** What the host tells the app, unasked. */
+export type HostEvent =
+  /** The interface's colours changed (light/dark, palette). `data: Theme`. */
+  | 'theme'
+  /** The reader's language changed. `data: {locale, dir}`. */
+  | 'locale'
+  /** The open file changed underneath (another tab, another person). */
+  | 'file.changed'
+  /** The person closed the frame's surroundings; last chance to say so. */
+  | 'close.request'
+  /** An administrator installed a new version of this app: reload to use it. */
+  | 'app.updated';
+
+/** What the host may ask the app (and wait for). */
+export type HostRequest =
+  /** Save now (the host's Save button, a draft's "Save to disk"): the app
+   *  hands its document to `file.save` and answers when it is written. */
+  'save';
+
+/** Why a call was refused. */
+export type ErrorCode =
+  /** The app was not granted what the call needs (files:write for a save…). */
+  | 'not_granted'
+  /** No such file (an index past the opened files), no such key. */
+  | 'not_found'
+  /** The file cannot be written: a read-only storage, a view-only opening. */
+  | 'read_only'
+  /** The call's parameters are wrong. */
+  | 'invalid'
+  /** Over a limit (LIMITS). */
+  | 'too_large'
+  /** The server could not be reached or refused; `message` says what. */
+  | 'failed'
+  /** The person said no (a confirm, a save-as picker closed). */
+  | 'cancelled'
+  /** The host does not offer this here (no engine, no save handler). */
+  | 'unavailable'
+  | 'unknown_method';
+
+export interface BridgeError {
+  code: ErrorCode;
+  message?: string;
+}
+
+/* ── messages ──────────────────────────────────────────────────────────── */
+
+export interface HelloMessage {
+  type: typeof HELLO;
+  v: number;
+}
+
+export interface PortMessage {
+  type: typeof PORT;
+  v: number;
+}
+
+export interface RequestMessage {
+  id: number;
+  method: Method;
+  params?: unknown;
+}
+
+export interface ResponseMessage {
+  id: number;
+  result?: unknown;
+  error?: BridgeError;
+}
+
+export interface EventMessage {
+  event: HostEvent;
+  data?: unknown;
+}
+
+export interface HostRequestMessage {
+  hid: number;
+  request: HostRequest;
+  params?: unknown;
+}
+
+export interface HostResponseMessage {
+  hid: number;
+  result?: unknown;
+  error?: BridgeError;
+}
+
+/* ── shapes ────────────────────────────────────────────────────────────── */
+
+/** The interface's look: `mode` and filex's own `--fe-*` custom properties. */
+export interface Theme {
+  mode: 'light' | 'dark';
+  /** `--fe-bg`, `--fe-text`, `--fe-accent`… — the SDK sets them on `<html>`. */
+  tokens: Record<string, string>;
+}
+
+/** One file the interface was opened with. Never a storage path. */
+export interface FileInfo {
+  index: number;
+  name: string;
+  /** Lower-case, no dot. */
+  ext: string;
+  size: number;
+  mime: string;
+  /** It cannot be saved over: read-only storage, view-only opening, or the
+   *  app holds no `files:write`. */
+  readOnly: boolean;
+}
+
+/** What `session.get` answers — what the app knows about where it runs. */
+export interface Session {
+  v: number;
+  app: { name: string; version: string };
+  view: { id: string; placement: 'modal' | 'page' | 'inspector' | 'home' | 'viewer' };
+  /** The reader's language tag (`tr`, `pt-br`) and its direction. */
+  locale: string;
+  dir: 'ltr' | 'rtl';
+  theme: Theme;
+  /** The person's display name; never their e-mail, never a token. */
+  user: { name: string };
+  files: FileInfo[];
+  /** The permissions this app was granted — so it can hide what it may not do. */
+  grants: string[];
+  /** The administrator's non-secret settings for this app (grant `settings`). */
+  settings?: Record<string, string>;
+}
+
+/** `file.read` params. */
+export interface ReadParams {
+  index?: number;
+  /** `stream` (a transferred ReadableStream<Uint8Array>), `bytes` (an
+   *  ArrayBuffer), or `text` (UTF-8, at most LIMITS.maxTextBytes). */
+  as?: 'stream' | 'bytes' | 'text';
+}
+
+export interface ReadResult {
+  name: string;
+  size: number;
+  mime: string;
+  stream?: ReadableStream<Uint8Array>;
+  bytes?: ArrayBuffer;
+  text?: string;
+}
+
+/** `file.save` params: the new content of the opened file. */
+export interface SaveParams {
+  index?: number;
+  /** A transferred ReadableStream<Uint8Array>, an ArrayBuffer or a string. */
+  data: ReadableStream<Uint8Array> | ArrayBuffer | string;
+  mime?: string;
+}
+
+export interface SaveResult {
+  saved: true;
+  size: number;
+}
+
+/** `file.saveAs`: a NEW file, somewhere the person picks in filex's own dialog. */
+/**
+ * `ui.download`: a file for the person's own disk. filex does it (a sandboxed
+ * frame cannot download), with the app's `ui:download` grant, on a gesture in
+ * the frame or the person's yes, never over LIMITS.maxDownloadBytes.
+ */
+export interface DownloadParams {
+  /** The file name offered — a name, not a path. */
+  name: string;
+  /** A transferred ReadableStream<Uint8Array>, an ArrayBuffer or a string. */
+  data: ReadableStream<Uint8Array> | ArrayBuffer | string;
+  mime?: string;
+}
+
+export interface DownloadResult {
+  saved: true;
+  size: number;
+}
+
+export interface SaveAsParams {
+  name: string;
+  data: ReadableStream<Uint8Array> | ArrayBuffer | string;
+  mime?: string;
+}
+
+export interface SaveAsResult {
+  saved: true;
+  name: string;
+  size: number;
+}
+
+export interface ToastParams {
+  text: string;
+  tone?: 'info' | 'success' | 'warning' | 'error';
+}
+
+export interface ConfirmParams {
+  title?: string;
+  text: string;
+  confirm?: string;
+  cancel?: string;
+  danger?: boolean;
+}
+
+/** `engine.call`: the app's own module, `ui_call` export. */
+export interface EngineCallParams {
+  method: string;
+  params?: unknown;
+}
+
+/** `job.submit`: queue one of the app's actions on the opened files. */
+export interface JobSubmitParams {
+  action: string;
+  params?: Record<string, unknown>;
+}
+
+/* ── limits ────────────────────────────────────────────────────────────── */
+
+export const LIMITS = {
+  /** `file.read({as: 'text'})` refuses a file larger than this; read a stream. */
+  maxTextBytes: 32 << 20,
+  /** One `state.set` value, as JSON. */
+  maxStateBytes: 8 << 10,
+  /** A `ui.toast` / `ui.title` text, in characters. */
+  maxLineChars: 300,
+  /** How long the SDK waits for the host's port. */
+  connectTimeoutMs: 10_000,
+  /** The largest file `ui.download` hands the person (streamed or not). */
+  maxDownloadBytes: 256 << 20,
+} as const;
+
+/* ── guards ────────────────────────────────────────────────────────────── */
+
+export function isHello(d: unknown): d is HelloMessage {
+  return !!d && typeof d === 'object' && (d as HelloMessage).type === HELLO && typeof (d as HelloMessage).v === 'number';
+}
+
+export function isPortMessage(d: unknown): d is PortMessage {
+  return !!d && typeof d === 'object' && (d as PortMessage).type === PORT;
+}
+
+export function isRequest(d: unknown): d is RequestMessage {
+  return (
+    !!d &&
+    typeof d === 'object' &&
+    typeof (d as RequestMessage).id === 'number' &&
+    typeof (d as RequestMessage).method === 'string'
+  );
+}
+
+export function isKnownMethod(m: string): m is Method {
+  return (METHODS as readonly string[]).includes(m);
+}