@opentray/spec 0.0.0 → 0.1.0

package/README.md

@@ -9,3 +9,11 @@ Shared TypeScript protocol and contract package for OpenTray.
 - Keep protocol types reusable by the `opentray` package and official extensions.
 
 This package must stay platform-neutral and must not import native implementation packages.
+
+## Example
+
+Run a protocol parser example that shows successful server-frame parsing and malformed-frame rejection:
+
+```bash
+pnpm --filter @opentray/spec example:parse
+```

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+//#region src/index.d.ts
+type LeaseId = string;
+type SurfaceId = string;
+type TrayId = string;
+type MenuItemId = number;
+interface SurfaceOptions {
+  appId: string;
+  title?: string;
+  icon?: Icon;
+  default?: boolean;
+}
+interface SurfaceRef {
+  surfaceId: SurfaceId;
+  appId: string;
+}
+interface TrayOptions {
+  trayId?: TrayId;
+  appId?: string;
+  title?: string;
+  tooltip?: Tooltip;
+  icon: Icon;
+  menu?: Menu;
+}
+interface Tooltip {
+  title: string;
+  description: string;
+}
+interface Menu {
+  items: MenuItem[];
+}
+type MenuItem = {
+  type: "item";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  shortcut?: string;
+} | {
+  type: "check";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+} | {
+  type: "radio";
+  id: MenuItemId;
+  title: string;
+  enabled?: boolean;
+  checked?: boolean;
+  group: number;
+} | {
+  type: "separator";
+} | {
+  type: "submenu";
+  title: string;
+  enabled?: boolean;
+  items: MenuItem[];
+};
+type Icon = {
+  type: "rgba";
+  data: Uint8Array | number[];
+  width: number;
+  height: number;
+} | {
+  type: "encoded";
+  data: Uint8Array | number[];
+} | {
+  type: "file";
+  path: string;
+};
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+type MouseButton = "left" | "right" | "middle";
+type TrayEvent = {
+  type: "ready";
+  surfaceId: SurfaceId;
+} | {
+  type: "menuClick";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  itemId: MenuItemId;
+} | {
+  type: "trayClick";
+  surfaceId: SurfaceId;
+  button: MouseButton;
+  x: number;
+  y: number;
+} | {
+  type: "trayDoubleClick";
+  surfaceId: SurfaceId;
+  button: MouseButton;
+  x: number;
+  y: number;
+};
+interface ExtensionScope {
+  surfaceId: SurfaceId;
+  trayId?: TrayId;
+  ext: string;
+}
+interface ExtensionEnvelope<TData = unknown> {
+  scope: ExtensionScope;
+  data: TData;
+}
+type ClientFrame = {
+  type: "init";
+  version: number;
+} | ({
+  type: "create-surface";
+} & SurfaceOptions) | {
+  type: "resolve-default-surface";
+} | {
+  type: "create-tray";
+  surface: SurfaceRef;
+  tray: TrayOptions;
+} | {
+  type: "destroy-tray";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+} | {
+  type: "set-tray-menu";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  menu: Menu;
+} | {
+  type: "set-tray-icon";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  icon: Icon;
+} | {
+  type: "set-tray-tooltip";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  tooltip: Tooltip;
+} | {
+  type: "load-ext";
+  surfaceId: SurfaceId;
+  name: string;
+  path: string;
+} | {
+  type: "ext-command";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  ext: string;
+  data: unknown;
+} | {
+  type: "unload-ext";
+  surfaceId: SurfaceId;
+  name: string;
+} | {
+  type: "exit";
+};
+type ServerFrame = {
+  type: "ready";
+  version: number;
+} | {
+  type: "surface-created";
+  surface: SurfaceRef;
+} | {
+  type: "default-surface";
+  surface: SurfaceRef;
+} | {
+  type: "tray-created";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+} | {
+  type: "event";
+  event: TrayEvent;
+} | {
+  type: "ext-event";
+  surfaceId: SurfaceId;
+  trayId: TrayId;
+  ext: string;
+  data: unknown;
+} | {
+  type: "error";
+  message: string;
+};
+interface ParseResult<T> {
+  ok: boolean;
+  frame?: T;
+  error?: string;
+}
+declare const parseServerFrame: (line: string) => ParseResult<ServerFrame>;
+declare const isServerFrame: (value: unknown) => value is ServerFrame;
+//#endregion
+export { ClientFrame, ExtensionEnvelope, ExtensionScope, Icon, LeaseId, Menu, MenuItem, MenuItemId, MouseButton, ParseResult, Rect, ServerFrame, SurfaceId, SurfaceOptions, SurfaceRef, Tooltip, TrayEvent, TrayId, TrayOptions, isServerFrame, parseServerFrame };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1,25 @@
+//#region src/index.ts
+const parseServerFrame = (line) => {
+	try {
+		const value = JSON.parse(line);
+		if (!isServerFrame(value)) return {
+			ok: false,
+			error: "invalid server frame"
+		};
+		return {
+			ok: true,
+			frame: value
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Error ? error.message : "unknown parse error"
+		};
+	}
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isServerFrame = (value) => isRecord(value) && typeof value.type === "string";
+//#endregion
+export { isServerFrame, parseServerFrame };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["export type LeaseId = string;\nexport type SurfaceId = string;\nexport type TrayId = string;\nexport type MenuItemId = number;\n\nexport interface SurfaceOptions {\n  appId: string;\n  title?: string;\n  icon?: Icon;\n  default?: boolean;\n}\n\nexport interface SurfaceRef {\n  surfaceId: SurfaceId;\n  appId: string;\n}\n\nexport interface TrayOptions {\n  trayId?: TrayId;\n  appId?: string;\n  title?: string;\n  tooltip?: Tooltip;\n  icon: Icon;\n  menu?: Menu;\n}\n\nexport interface Tooltip {\n  title: string;\n  description: string;\n}\n\nexport interface Menu {\n  items: MenuItem[];\n}\n\nexport type MenuItem =\n  | {\n      type: \"item\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      shortcut?: string;\n    }\n  | {\n      type: \"check\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      checked?: boolean;\n    }\n  | {\n      type: \"radio\";\n      id: MenuItemId;\n      title: string;\n      enabled?: boolean;\n      checked?: boolean;\n      group: number;\n    }\n  | {\n      type: \"separator\";\n    }\n  | {\n      type: \"submenu\";\n      title: string;\n      enabled?: boolean;\n      items: MenuItem[];\n    };\n\nexport type Icon =\n  | { type: \"rgba\"; data: Uint8Array | number[]; width: number; height: number }\n  | { type: \"encoded\"; data: Uint8Array | number[] }\n  | { type: \"file\"; path: string };\n\nexport interface Rect {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport type MouseButton = \"left\" | \"right\" | \"middle\";\n\nexport type TrayEvent =\n  | { type: \"ready\"; surfaceId: SurfaceId }\n  | { type: \"menuClick\"; surfaceId: SurfaceId; trayId: TrayId; itemId: MenuItemId }\n  | { type: \"trayClick\"; surfaceId: SurfaceId; button: MouseButton; x: number; y: number }\n  | { type: \"trayDoubleClick\"; surfaceId: SurfaceId; button: MouseButton; x: number; y: number };\n\nexport interface ExtensionScope {\n  surfaceId: SurfaceId;\n  trayId?: TrayId;\n  ext: string;\n}\n\nexport interface ExtensionEnvelope<TData = unknown> {\n  scope: ExtensionScope;\n  data: TData;\n}\n\nexport type ClientFrame =\n  | { type: \"init\"; version: number }\n  | ({ type: \"create-surface\" } & SurfaceOptions)\n  | { type: \"resolve-default-surface\" }\n  | { type: \"create-tray\"; surface: SurfaceRef; tray: TrayOptions }\n  | { type: \"destroy-tray\"; surfaceId: SurfaceId; trayId: TrayId }\n  | { type: \"set-tray-menu\"; surfaceId: SurfaceId; trayId: TrayId; menu: Menu }\n  | { type: \"set-tray-icon\"; surfaceId: SurfaceId; trayId: TrayId; icon: Icon }\n  | { type: \"set-tray-tooltip\"; surfaceId: SurfaceId; trayId: TrayId; tooltip: Tooltip }\n  | { type: \"load-ext\"; surfaceId: SurfaceId; name: string; path: string }\n  | { type: \"ext-command\"; surfaceId: SurfaceId; trayId: TrayId; ext: string; data: unknown }\n  | { type: \"unload-ext\"; surfaceId: SurfaceId; name: string }\n  | { type: \"exit\" };\n\nexport type ServerFrame =\n  | { type: \"ready\"; version: number }\n  | { type: \"surface-created\"; surface: SurfaceRef }\n  | { type: \"default-surface\"; surface: SurfaceRef }\n  | { type: \"tray-created\"; surfaceId: SurfaceId; trayId: TrayId }\n  | { type: \"event\"; event: TrayEvent }\n  | { type: \"ext-event\"; surfaceId: SurfaceId; trayId: TrayId; ext: string; data: unknown }\n  | { type: \"error\"; message: string };\n\nexport interface ParseResult<T> {\n  ok: boolean;\n  frame?: T;\n  error?: string;\n}\n\nexport const parseServerFrame = (line: string): ParseResult<ServerFrame> => {\n  try {\n    const value: unknown = JSON.parse(line);\n    if (!isServerFrame(value)) {\n      return { ok: false, error: \"invalid server frame\" };\n    }\n    return { ok: true, frame: value };\n  } catch (error) {\n    return {\n      ok: false,\n      error: error instanceof Error ? error.message : \"unknown parse error\",\n    };\n  }\n};\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nexport const isServerFrame = (value: unknown): value is ServerFrame =>\n  isRecord(value) && typeof value.type === \"string\";\n"],"mappings":";AAgIA,MAAa,oBAAoB,SAA2C;CAC1E,IAAI;EACF,MAAM,QAAiB,KAAK,MAAM,IAAI;EACtC,IAAI,CAAC,cAAc,KAAK,GACtB,OAAO;GAAE,IAAI;GAAO,OAAO;EAAuB;EAEpD,OAAO;GAAE,IAAI;GAAM,OAAO;EAAM;CAClC,SAAS,OAAO;EACd,OAAO;GACL,IAAI;GACJ,OAAO,iBAAiB,QAAQ,MAAM,UAAU;EAClD;CACF;AACF;AAEA,MAAM,YAAY,UAChB,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAErE,MAAa,iBAAiB,UAC5B,SAAS,KAAK,KAAK,OAAO,MAAM,SAAS"}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@opentray/spec",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Shared TypeScript protocol and contract types for OpenTray.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jixoai/opentray"
+  },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
     "./package.json": "./package.json"
   },
@@ -15,5 +19,16 @@
     "dist",
     "README.md"
   ],
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "tsdown": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts",
+    "example:parse": "bun run examples/parse-frame.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }