@bun-native/protocol 0.0.0-stage → 0.33.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bunly contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bun-native/protocol
 
-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.
+The private native protocol shared by Bun Native packages and hosts.
+
+Part of [Bun Native](https://github.com/0xPlayerOne/bun-native), an experimental developer preview. Version 0.33.0 was built from [fa8bef754122](https://github.com/0xPlayerOne/bun-native/tree/fa8bef754122621d4235eb06e30bb1085b4f7b1e) and published from GitHub Actions with npm provenance. Use the Bun revision pinned in that commit's toolchain.json. Start with the [getting-started guide](https://github.com/0xPlayerOne/bun-native/blob/fa8bef754122621d4235eb06e30bb1085b4f7b1e/docs/getting-started.md); `bun-native host install` fetches the matching release host. The license notice is in LICENSE.

package/bun-native-source.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "commit": "fa8bef754122621d4235eb06e30bb1085b4f7b1e",
+  "tree": "f805e2eb19a4e10fc29d1dc827cf5bc617b5773b",
+  "files": {
+    "package.json": {
+      "bytes": 2164,
+      "sha256": "db50b6f81f25c113a46f8c9b038bc548a92effaeb4ad9562e5e95044baa7b66f"
+    },
+    "packages/protocol/package.json": {
+      "bytes": 129,
+      "sha256": "668f52c10a6db801c2d0c68c59998c489b50c0bb79cb7f60298dfbb83923b0ba"
+    },
+    "packages/protocol/src/app-menu.ts": {
+      "bytes": 6435,
+      "sha256": "52ec565f7423671a13e3bc43d49129496ed9869f22b4fa1b7e3eba79191137b8"
+    },
+    "packages/protocol/src/dialogs.ts": {
+      "bytes": 4896,
+      "sha256": "c2ea74d7175c75710146c788b261e5566301da5952359b8e50bc69a323cdef00"
+    },
+    "packages/protocol/src/drops.ts": {
+      "bytes": 1968,
+      "sha256": "478b9952e406853b22e32e8b5c227fdc5936363665d984c628d18581de112191"
+    },
+    "packages/protocol/src/elements.ts": {
+      "bytes": 16161,
+      "sha256": "3529a4f7fefa9d56880a5f32be83b7daea9ad492784478ddc413d2deb85f5283"
+    },
+    "packages/protocol/src/files.ts": {
+      "bytes": 10163,
+      "sha256": "d4d890f22b6abdc713e544a4e3f7b0ed53df4a1d5f44044febea8d8cf9ca96a5"
+    },
+    "packages/protocol/src/framing.ts": {
+      "bytes": 3259,
+      "sha256": "47d2473785f245d8f85bd1447fba3f7ed47d5ddac170f590df5c83623064158a"
+    },
+    "packages/protocol/src/index.ts": {
+      "bytes": 3388,
+      "sha256": "7c7fd785b5037bc74ce0594f0ec5c49fca7ef9ae0b4dbab8fbf83d8427f6ead8"
+    },
+    "packages/protocol/src/message-dialogs.ts": {
+      "bytes": 3997,
+      "sha256": "551dc23a2fde7771c28e485212d670f37db199da6f2f006344b0dc6b9064ef2b"
+    },
+    "packages/protocol/src/messages.ts": {
+      "bytes": 43791,
+      "sha256": "cef29b0d2fa4b84d73df5c9b8abbf321dafc6a66d688ad00838f0c8aa50a1d03"
+    },
+    "packages/protocol/src/processes.ts": {
+      "bytes": 9709,
+      "sha256": "80f109623ec5f17bc21fb20c4e3093829124839c6c9e5b2457120bff0a45c778"
+    },
+    "packages/protocol/src/services.ts": {
+      "bytes": 7587,
+      "sha256": "eb128b1ef12d2650acc53b71c2c802f35d3fb983d1f584aa1d81251adfccd37b"
+    },
+    "packages/protocol/src/values.ts": {
+      "bytes": 2078,
+      "sha256": "75d8f7ee9772c1aa2929a9dc4c416f42569795db089d17321398c3cdf482731b"
+    },
+    "LICENSE": {
+      "bytes": 1075,
+      "sha256": "86673fb485f12fa9aaa3941dfccc9f69a7f8322f8141d0d5c73db4323de10ac5"
+    }
+  },
+  "toolchain": {
+    "bytes": 3012,
+    "sha256": "00c3f707aae8abe9ca75cd2e162f5e1c7c34362a03675da39afead60d856066a"
+  },
+  "dependencyLock": {
+    "bytes": 28357,
+    "sha256": "65e3dbd01be4a1889367690faf1a9c3f08fb31d22dbd273d9bb9f39dd6baa6fb"
+  }
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@bun-native/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.33.0",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "bun-native-source.json"
+  ],
+  "engines": {
+    "bun": "1.4.4-canary.1"
+  },
+  "exports": "./src/index.ts",
+  "description": "The private native protocol shared by Bun Native packages and hosts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xPlayerOne/bun-native.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://github.com/0xPlayerOne/bun-native#readme",
+  "bugs": "https://github.com/0xPlayerOne/bun-native/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/app-menu.ts

@@ -0,0 +1,209 @@
+import { ProtocolError } from './framing.ts'
+import { keys, object, string } from './values.ts'
+
+/** Top-level menus in one menu bar. */
+export const MAX_APP_MENUS = 16
+/** Items, separators and submenus in one menu bar, at every depth. */
+export const MAX_APP_MENU_ENTRIES = 128
+/** A top-level menu is depth 1; submenus nest at most two levels below it. */
+export const MAX_APP_MENU_DEPTH = 3
+export const MAX_APP_MENU_LABEL_BYTES = 64
+export const MAX_APP_MENU_ITEM_ID_BYTES = 64
+
+export const APP_MENU_NAMED_KEYS = Object.freeze([
+  'enter',
+  'escape',
+  'tab',
+  'space',
+  'backspace',
+  'delete',
+  'up',
+  'down',
+  'left',
+  'right',
+  'home',
+  'end',
+  'pageup',
+  'pagedown',
+] as const)
+export const APP_MENU_PUNCTUATION_KEYS = Object.freeze([
+  ',',
+  '.',
+  '/',
+  ';',
+  "'",
+  '[',
+  ']',
+  '-',
+  '=',
+  '`',
+  '\\',
+] as const)
+
+/** The closed key set of a menu shortcut. */
+export const APP_MENU_KEYS = Object.freeze([
+  ...'abcdefghijklmnopqrstuvwxyz0123456789',
+  ...Array.from({ length: 12 }, (_, index) => `f${index + 1}`),
+  ...APP_MENU_PUNCTUATION_KEYS,
+  ...APP_MENU_NAMED_KEYS,
+]) as readonly string[]
+
+export interface MenuShortcutModifiers {
+  control: boolean
+  alt: boolean
+  shift: boolean
+  /** Command on macOS. */
+  platform: boolean
+}
+
+export interface MenuShortcut {
+  key: string
+  modifiers: MenuShortcutModifiers
+}
+
+export type AppMenuEntry =
+  | {
+      kind: 'item'
+      id: string
+      label: string
+      shortcut?: MenuShortcut
+      enabled: boolean
+      checked: boolean
+    }
+  | { kind: 'separator' }
+  | { kind: 'submenu'; label: string; enabled: boolean; items: AppMenuEntry[] }
+
+export interface AppMenu {
+  title: string
+  items: AppMenuEntry[]
+}
+
+const ITEM_ID = /^[A-Za-z0-9._:-]{1,64}$/
+
+/** `[A-Za-z0-9._:-]`, 1-64 bytes: an application identifier, never a native name. */
+export function parseAppMenuItemId(value: unknown): string {
+  if (typeof value !== 'string' || !ITEM_ID.test(value))
+    throw new ProtocolError(
+      "Menu item id must be 1-64 bytes of letters, digits, '.', '_', ':' or '-'"
+    )
+  return value
+}
+
+function label(value: unknown, field: string): string {
+  const text = string(value, field, MAX_APP_MENU_LABEL_BYTES)
+  if (!text || /\p{Cc}/u.test(text))
+    throw new ProtocolError(field + ' must be nonempty and contain no control characters')
+  return text
+}
+
+function flag(data: Record<string, unknown>, key: string): boolean {
+  const value = data[key]
+  if (typeof value !== 'boolean') throw new ProtocolError('Menu ' + key + ' must be a boolean')
+  return value
+}
+
+const isFunctionKey = (key: string) => /^f([1-9]|1[0-2])$/.test(key)
+
+function parseMenuShortcut(value: unknown): MenuShortcut {
+  const data = object(value)
+  keys(data, ['key', 'modifiers'])
+  const key = data['key']
+  if (typeof key !== 'string' || !APP_MENU_KEYS.includes(key))
+    throw new ProtocolError('Menu shortcut key is not in the closed key set')
+  const raw = object(data['modifiers'])
+  keys(raw, ['control', 'alt', 'shift', 'platform'])
+  const modifiers = {
+    control: flag(raw, 'control'),
+    alt: flag(raw, 'alt'),
+    shift: flag(raw, 'shift'),
+    platform: flag(raw, 'platform'),
+  }
+  if (!isFunctionKey(key) && !modifiers.control && !modifiers.alt && !modifiers.platform)
+    throw new ProtocolError('Menu shortcut requires control, alt or platform unless it is f1-f12')
+  return { key, modifiers }
+}
+
+const shortcutKey = ({ key, modifiers: m }: MenuShortcut) =>
+  `${+m.control}${+m.alt}${+m.shift}${+m.platform}${key}`
+
+interface Census {
+  entries: number
+  ids: Set<string>
+  shortcuts: Set<string>
+}
+
+function entries(value: unknown, depth: number, census: Census): AppMenuEntry[] {
+  if (!Array.isArray(value) || !value.length)
+    throw new ProtocolError('A menu or submenu needs at least one entry')
+  return value.map((raw): AppMenuEntry => {
+    if (++census.entries > MAX_APP_MENU_ENTRIES)
+      throw new ProtocolError('A menu bar holds at most 128 entries')
+    const data = object(raw)
+    switch (data['kind']) {
+      case 'item': {
+        keys(data, ['kind', 'id', 'label', 'shortcut', 'enabled', 'checked'])
+        const id = parseAppMenuItemId(data['id'])
+        if (census.ids.has(id))
+          throw new ProtocolError('Menu item ids must be unique in a menu bar')
+        census.ids.add(id)
+        const entry: AppMenuEntry = {
+          kind: 'item',
+          id,
+          label: label(data['label'], 'menu label'),
+          enabled: flag(data, 'enabled'),
+          checked: flag(data, 'checked'),
+        }
+        if ('shortcut' in data) {
+          const shortcut = parseMenuShortcut(data['shortcut'])
+          const identity = shortcutKey(shortcut)
+          if (census.shortcuts.has(identity))
+            throw new ProtocolError('Menu shortcuts must be unique in a menu bar')
+          census.shortcuts.add(identity)
+          entry.shortcut = shortcut
+        }
+        return entry
+      }
+      case 'separator':
+        keys(data, ['kind'])
+        return { kind: 'separator' }
+      case 'submenu': {
+        keys(data, ['kind', 'label', 'enabled', 'items'])
+        const text = label(data['label'], 'menu label')
+        const enabled = flag(data, 'enabled')
+        if (depth >= MAX_APP_MENU_DEPTH)
+          throw new ProtocolError('Submenus nest at most two levels below a top-level menu')
+        return {
+          kind: 'submenu',
+          label: text,
+          enabled,
+          items: entries(data['items'], depth + 1, census),
+        }
+      }
+      default:
+        throw new ProtocolError('Unknown menu entry kind')
+    }
+  })
+}
+
+/**
+ * A context menu: the entries of one menu-bar menu, with the same bounds,
+ * unique ids and shortcuts, and submenus nested at most two levels deep.
+ */
+export function parseContextMenuItems(value: unknown): AppMenuEntry[] {
+  return entries(value, 1, { entries: 0, ids: new Set(), shortcuts: new Set() })
+}
+
+/** An empty bar is valid: it removes the application's menus. */
+export function parseAppMenus(value: unknown): AppMenu[] {
+  if (!Array.isArray(value) || value.length > MAX_APP_MENUS)
+    throw new ProtocolError('A menu bar holds at most 16 menus')
+  const census: Census = { entries: 0, ids: new Set(), shortcuts: new Set() }
+  return value.map((raw) => {
+    const data = object(raw)
+    keys(data, ['title', 'items'])
+    return {
+      title: label(data['title'], 'menu title'),
+      items: entries(data['items'], 1, census),
+    }
+  })
+}

package/src/dialogs.ts

@@ -0,0 +1,131 @@
+import { ProtocolError } from './framing.ts'
+import { keys, object, string } from './values.ts'
+
+/** Live file dialogs per session. Each window owns at most one at a time. */
+export const MAX_FILE_DIALOGS = 16
+export const MAX_DIALOG_TITLE_BYTES = 256
+export const MAX_DIALOG_LABEL_BYTES = 64
+export const MAX_DIALOG_PATH_BYTES = 4_096
+export const MAX_DIALOG_NAME_BYTES = 255
+export const MAX_DIALOG_FILTERS = 16
+export const MAX_DIALOG_FILTER_PATTERNS = 16
+export const MAX_DIALOG_FILTER_NAME_BYTES = 128
+export const MAX_DIALOG_PATTERN_BYTES = 64
+/** Selected paths in one result. The whole result must also fit one frame. */
+export const MAX_DIALOG_PATHS = 256
+
+export const FILE_DIALOG_MODES = Object.freeze([
+  'open_file',
+  'open_files',
+  'open_directory',
+  'save_file',
+] as const)
+export type FileDialogMode = (typeof FILE_DIALOG_MODES)[number]
+
+export interface FileFilter {
+  name: string
+  patterns: readonly string[]
+}
+
+export interface FileDialogOptions {
+  mode: FileDialogMode
+  title: string
+  accept_label?: string
+  folder?: string
+  name?: string
+  filters?: readonly FileFilter[]
+}
+
+/** Paths are data: a selection carries no filesystem authority. */
+export type FileDialogResult =
+  | { kind: 'selected'; paths: readonly string[] }
+  | { kind: 'cancelled' }
+  | { kind: 'failed'; code: 'native_failure' | 'payload_too_large' }
+
+function line(value: unknown, field: string, limit: number): string {
+  const text = string(value, field, limit)
+  if (!text || /\p{Cc}/u.test(text))
+    throw new ProtocolError(field + ' must be nonempty and contain no control characters')
+  return text
+}
+
+/** A nonempty absolute POSIX path without NUL, at most 4096 UTF-8 bytes. */
+function parseDialogPath(value: unknown, field = 'dialog path'): string {
+  const path = string(value, field, MAX_DIALOG_PATH_BYTES)
+  if (!path.startsWith('/')) throw new ProtocolError(field + ' must be absolute')
+  return path
+}
+
+function filter(value: unknown): FileFilter {
+  const data = object(value)
+  keys(data, ['name', 'patterns'])
+  const patterns = data['patterns']
+  if (
+    !Array.isArray(patterns) ||
+    patterns.length < 1 ||
+    patterns.length > MAX_DIALOG_FILTER_PATTERNS
+  )
+    throw new ProtocolError('A file filter needs between 1 and 16 patterns')
+  return {
+    name: line(data['name'], 'file filter name', MAX_DIALOG_FILTER_NAME_BYTES),
+    patterns: patterns.map((pattern) =>
+      line(pattern, 'file filter pattern', MAX_DIALOG_PATTERN_BYTES)
+    ),
+  }
+}
+
+export function parseFileDialogOptions(value: unknown): FileDialogOptions {
+  const data = object(value)
+  keys(data, ['mode', 'title', 'accept_label', 'folder', 'name', 'filters'])
+  const mode = FILE_DIALOG_MODES.find((candidate) => candidate === data['mode'])
+  if (!mode) throw new ProtocolError('Unknown file dialog mode')
+  const options: FileDialogOptions = {
+    mode,
+    title: line(data['title'], 'dialog title', MAX_DIALOG_TITLE_BYTES),
+  }
+  if ('accept_label' in data)
+    options.accept_label = line(data['accept_label'], 'dialog accept label', MAX_DIALOG_LABEL_BYTES)
+  if ('folder' in data) options.folder = parseDialogPath(data['folder'], 'dialog folder')
+  if ('name' in data) {
+    if (mode !== 'save_file') throw new ProtocolError('Only a save dialog accepts a suggested name')
+    const name = line(data['name'], 'suggested name', MAX_DIALOG_NAME_BYTES)
+    if (name.includes('/') || name === '.' || name === '..')
+      throw new ProtocolError('Suggested name must be one path component')
+    options.name = name
+  }
+  if ('filters' in data) {
+    const filters = data['filters']
+    if (!Array.isArray(filters) || filters.length > MAX_DIALOG_FILTERS)
+      throw new ProtocolError('A file dialog accepts at most 16 filters')
+    if (filters.length && mode === 'open_directory')
+      throw new ProtocolError('A folder dialog does not accept file filters')
+    if (filters.length) options.filters = filters.map(filter)
+  }
+  return options
+}
+
+export function parseFileDialogResult(value: unknown): FileDialogResult {
+  const data = object(value)
+  switch (data['kind']) {
+    case 'selected': {
+      keys(data, ['kind', 'paths'])
+      const paths = data['paths']
+      if (!Array.isArray(paths) || paths.length < 1 || paths.length > MAX_DIALOG_PATHS)
+        throw new ProtocolError('A dialog selection holds between 1 and 256 paths')
+      return { kind: 'selected', paths: paths.map((path) => parseDialogPath(path)) }
+    }
+    case 'cancelled':
+      keys(data, ['kind'])
+      return { kind: 'cancelled' }
+    case 'failed': {
+      keys(data, ['kind', 'code'])
+      const code = (['native_failure', 'payload_too_large'] as const).find(
+        (candidate) => candidate === data['code']
+      )
+      if (!code) throw new ProtocolError('Unknown file dialog failure')
+      return { kind: 'failed', code }
+    }
+    default:
+      throw new ProtocolError('Unknown file dialog result')
+  }
+}

package/src/drops.ts

@@ -0,0 +1,47 @@
+import { ProtocolError } from './framing.ts'
+import { integer, keys, object, string } from './values.ts'
+
+/** Live drop targets across a session. */
+export const MAX_DROP_TARGETS = 32
+/** Items one drop may deliver. A larger drop is rejected, never truncated. */
+export const MAX_DROP_ITEMS = 64
+/** UTF-8 bytes of one untrusted display name. */
+export const MAX_DROP_NAME_BYTES = 255
+
+export const DRAG_STATES = Object.freeze(['entered', 'left'] as const)
+export type DragState = (typeof DRAG_STATES)[number]
+export const DROP_REJECTIONS = Object.freeze(['empty', 'limit_exceeded'] as const)
+export type DropRejection = (typeof DROP_REJECTIONS)[number]
+
+/** Untrusted display metadata for one dropped item. It is not a path. */
+export interface DroppedItem {
+  name: string
+}
+
+function choice<T extends string>(value: unknown, values: readonly T[], field: string): T {
+  const found = values.find((candidate) => candidate === value)
+  if (!found) throw new ProtocolError(field + ' must be one of ' + values.join(', '))
+  return found
+}
+
+export const parseDragState = (value: unknown): DragState =>
+  choice(value, DRAG_STATES, 'Drag state')
+export const parseDropRejection = (value: unknown): DropRejection =>
+  choice(value, DROP_REJECTIONS, 'Drop rejection')
+
+export function parseDropItemIndex(value: unknown): number {
+  return integer(value, 'Dropped item index', 0, MAX_DROP_ITEMS - 1)
+}
+
+export function parseDroppedItems(value: unknown): DroppedItem[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > MAX_DROP_ITEMS)
+    throw new ProtocolError('A drop must deliver between 1 and ' + MAX_DROP_ITEMS + ' items')
+  return value.map((entry) => {
+    const data = object(entry)
+    keys(data, ['name'])
+    const name = string(data['name'], 'Dropped item name', MAX_DROP_NAME_BYTES)
+    if (!name || /\p{Cc}/u.test(name))
+      throw new ProtocolError('Dropped item name must be nonempty without control characters')
+    return { name }
+  })
+}