@bun-native/protocol 0.0.0-stage → 0.33.1

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.1 was built from [c56fdd675365](https://github.com/0xPlayerOne/bun-native/tree/c56fdd6753653a10144a4167c1d3dfb3c38a0647) 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/c56fdd6753653a10144a4167c1d3dfb3c38a0647/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": "c56fdd6753653a10144a4167c1d3dfb3c38a0647",
+  "tree": "c6e81b3f9d041e11dd0413b5fdd7a50910383854",
+  "files": {
+    "package.json": {
+      "bytes": 2115,
+      "sha256": "caf866d56f3cd7530d5735ecbf62512e9e22526bc44c75a4b48a18c26352c0b8"
+    },
+    "packages/protocol/package.json": {
+      "bytes": 129,
+      "sha256": "668f52c10a6db801c2d0c68c59998c489b50c0bb79cb7f60298dfbb83923b0ba"
+    },
+    "packages/protocol/src/app-menu.ts": {
+      "bytes": 6687,
+      "sha256": "a0346cff0bfe26a1b2d1eaf1470521d5602d59dd54f831b3353be56499a5efc3"
+    },
+    "packages/protocol/src/dialogs.ts": {
+      "bytes": 5261,
+      "sha256": "c26aab88e0e6ca9838b8c7dd471165e03f967694576a257dec88cff8343e4175"
+    },
+    "packages/protocol/src/drops.ts": {
+      "bytes": 2029,
+      "sha256": "03894f9b2b40f7645e74824de630bebc4d7d7145eafade79739248126826a42b"
+    },
+    "packages/protocol/src/elements.ts": {
+      "bytes": 17017,
+      "sha256": "b831c4906806cd8b46aab29983481c85617b84b4bcc6cde515c3c2d8f5f4dfb1"
+    },
+    "packages/protocol/src/files.ts": {
+      "bytes": 10818,
+      "sha256": "4fda4c2ebcc489f330b52ff042fe3b005b7b09718799f4b684d06c7728b86730"
+    },
+    "packages/protocol/src/framing.ts": {
+      "bytes": 4321,
+      "sha256": "63148dfde50d4e98dafd8e1923db43d290565453a28113cf356ed3e33c4a5d70"
+    },
+    "packages/protocol/src/index.ts": {
+      "bytes": 2940,
+      "sha256": "3aa7a5bb90bbcb4c58fa999a6179fcca860b53913984efb857505d90438e79ae"
+    },
+    "packages/protocol/src/message-dialogs.ts": {
+      "bytes": 4229,
+      "sha256": "3fe42b3c42ff255761a867c87d0ea69f0404ee9dd64ba57cda9f9573588db210"
+    },
+    "packages/protocol/src/messages.ts": {
+      "bytes": 48950,
+      "sha256": "17d92d1b5f08fb04f1dc9e6269291ffc7ff39f3c6ace3c9a6b7b216c6a63c2d3"
+    },
+    "packages/protocol/src/processes.ts": {
+      "bytes": 10019,
+      "sha256": "b64ee81b209a4e6ccf0965409c355a1bc3bfa8d813668aec385b50050be4f2b6"
+    },
+    "packages/protocol/src/services.ts": {
+      "bytes": 7933,
+      "sha256": "4906b13929e96382fe55c8f94316e5b6629c74a6482ce25c55c621bc449a45e9"
+    },
+    "packages/protocol/src/values.ts": {
+      "bytes": 2365,
+      "sha256": "cca3d96f72dde820f154b6e492ea1a94ee33d8af8da44aca6fd1039912de63c1"
+    },
+    "LICENSE": {
+      "bytes": 1075,
+      "sha256": "86673fb485f12fa9aaa3941dfccc9f69a7f8322f8141d0d5c73db4323de10ac5"
+    }
+  },
+  "toolchain": {
+    "bytes": 3234,
+    "sha256": "9f4d9362cb4cc38c0f4e705295789a0cbfec46ffdd007e0541b9441a7c3003a7"
+  },
+  "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.1",
+  "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,217 @@
+import { ProtocolError } from './framing.ts'
+import { fields, keys, object, string } from './values.ts'
+
+/** Top-level menus in one menu bar. */
+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
+const MAX_APP_MENU_LABEL_BYTES = 64
+
+const APP_MENU_NAMED_KEYS = Object.freeze([
+  'enter',
+  'escape',
+  'tab',
+  'space',
+  'backspace',
+  'delete',
+  'up',
+  'down',
+  'left',
+  'right',
+  'home',
+  'end',
+  'pageup',
+  'pagedown',
+] as const)
+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)
+
+const MENU_SHORTCUT_KEYS = fields('key', 'modifiers')
+const MENU_MODIFIER_KEYS = fields('control', 'alt', 'shift', 'platform')
+
+function parseMenuShortcut(value: unknown): MenuShortcut {
+  const data = object(value)
+  keys(data, MENU_SHORTCUT_KEYS)
+  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, MENU_MODIFIER_KEYS)
+  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>
+}
+
+const ENTRIES_ITEM_KEYS = fields('kind', 'id', 'label', 'shortcut', 'enabled', 'checked')
+const ENTRIES_SEPARATOR_KEYS = fields('kind')
+const ENTRIES_SUBMENU_KEYS = fields('kind', 'label', 'enabled', 'items')
+
+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, ENTRIES_ITEM_KEYS)
+        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, ENTRIES_SEPARATOR_KEYS)
+        return { kind: 'separator' }
+      case 'submenu': {
+        keys(data, ENTRIES_SUBMENU_KEYS)
+        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() })
+}
+
+const APP_MENUS_KEYS = fields('title', 'items')
+
+/** 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, APP_MENUS_KEYS)
+    return {
+      title: label(data['title'], 'menu title'),
+      items: entries(data['items'], 1, census),
+    }
+  })
+}

package/src/dialogs.ts

@@ -0,0 +1,146 @@
+import { ProtocolError } from './framing.ts'
+import { fields, 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
+}
+
+const FILTER_KEYS = fields('name', 'patterns')
+
+function filter(value: unknown): FileFilter {
+  const data = object(value)
+  keys(data, FILTER_KEYS)
+  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)
+    ),
+  }
+}
+
+const FILE_DIALOG_OPTIONS_KEYS = fields(
+  'mode',
+  'title',
+  'accept_label',
+  'folder',
+  'name',
+  'filters'
+)
+
+export function parseFileDialogOptions(value: unknown): FileDialogOptions {
+  const data = object(value)
+  keys(data, FILE_DIALOG_OPTIONS_KEYS)
+  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
+}
+
+const FILE_DIALOG_RESULT_SELECTED_KEYS = fields('kind', 'paths')
+const FILE_DIALOG_RESULT_CANCELLED_KEYS = fields('kind')
+const FILE_DIALOG_RESULT_FAILED_KEYS = fields('kind', 'code')
+
+export function parseFileDialogResult(value: unknown): FileDialogResult {
+  const data = object(value)
+  switch (data['kind']) {
+    case 'selected': {
+      keys(data, FILE_DIALOG_RESULT_SELECTED_KEYS)
+      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, FILE_DIALOG_RESULT_CANCELLED_KEYS)
+      return { kind: 'cancelled' }
+    case 'failed': {
+      keys(data, FILE_DIALOG_RESULT_FAILED_KEYS)
+      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,49 @@
+import { ProtocolError } from './framing.ts'
+import { fields, 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)
+}
+
+const DROPPED_ITEMS_KEYS = fields('name')
+
+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, DROPPED_ITEMS_KEYS)
+    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 }
+  })
+}