@jay-framework/editor-protocol 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,3 +1,20 @@
+interface ContractTag {
+    tag: string;
+    type: string | string[];
+    dataType?: string;
+    elementType?: string;
+    required?: boolean;
+    repeated?: boolean;
+    tags?: ContractTag[];
+    link?: string;
+    trackBy?: string;
+    async?: boolean;
+    phase?: string;
+}
+interface Contract {
+    name: string;
+    tags: ContractTag[];
+}
 interface BaseMessage<TResponse extends BaseResponse = BaseResponse> {
     type: string;
 }
@@ -34,6 +51,17 @@ interface HasImageMessage extends BaseMessage<HasImageResponse> {
 interface GetProjectInfoMessage extends BaseMessage<GetProjectInfoResponse> {
     type: 'getProjectInfo';
 }
+interface ExportMessage<TVendorDoc> extends BaseMessage<ExportResponse> {
+    type: 'export';
+    vendorId: string;
+    pageUrl: string;
+    vendorDoc: TVendorDoc;
+}
+interface ImportMessage<TVendorDoc> extends BaseMessage<ImportResponse<TVendorDoc>> {
+    type: 'import';
+    vendorId: string;
+    pageUrl: string;
+}
 interface PublishResponse extends BaseResponse {
     type: 'publish';
     status: {
@@ -59,7 +87,7 @@ interface ProjectPage {
     name: string;
     url: string;
     filePath: string;
-    contractSchema?: ContractSchema;
+    contract?: Contract;
     usedComponents: {
         appName: string;
         componentName: string;
@@ -71,55 +99,9 @@ interface ProjectComponent {
     filePath: string;
     contractPath?: string;
 }
-interface StaticContractDef {
-    name: string;
-    contract: string;
-    component: string;
-    description?: string;
-}
-interface DynamicContractDef {
-    prefix: string;
-    component: string;
-    generator: string;
-}
-interface PluginManifest {
-    name: string;
-    module?: string;
-    contracts?: StaticContractDef[];
-    dynamic_contracts?: DynamicContractDef;
-}
 interface Plugin {
-    manifest: PluginManifest;
-    location: {
-        type: 'local' | 'npm';
-        path?: string;
-        module?: string;
-    };
-}
-interface InstalledApp {
     name: string;
-    module: string;
-    pages: {
-        name: string;
-        headless_components: {
-            name: string;
-            key: string;
-            contract: string;
-            slugs?: string[];
-        }[];
-    }[];
-    components: {
-        name: string;
-        headless_components: {
-            name: string;
-            key: string;
-            contract: string;
-        }[];
-    }[];
-    config_map?: {
-        display_name: string;
-        key: string;
-    }[];
+    contracts: Contract[];
 }
 interface ProjectInfo {
     name: string;
@@ -127,64 +109,49 @@ interface ProjectInfo {
     pages: ProjectPage[];
     components: ProjectComponent[];
     plugins: Plugin[];
-    installedApps: InstalledApp[];
-    installedAppContracts: {
-        [appName: string]: InstalledAppContracts;
-    };
 }
 interface GetProjectInfoResponse extends BaseResponse {
     type: 'getProjectInfo';
     info: ProjectInfo;
 }
-interface ContractTag {
-    tag: string;
-    type: string | string[];
-    dataType?: string;
-    elementType?: string;
-    required?: boolean;
-    repeated?: boolean;
-    tags?: ContractTag[];
-    link?: string;
+interface ExportResponse extends BaseResponse {
+    type: 'export';
+    vendorSourcePath?: string;
+    jayHtmlPath?: string;
+    contractPath?: string;
+    warnings?: string[];
 }
-interface ContractSchema {
-    name: string;
-    tags: ContractTag[];
+interface ImportResponse<TVendorDoc> extends BaseResponse {
+    type: 'import';
+    vendorDoc?: TVendorDoc;
 }
-interface InstalledAppContracts {
-    appName: string;
-    module: string;
-    pages: Array<{
-        pageName: string;
-        contractSchema: ContractSchema;
-    }>;
-    components: Array<{
-        componentName: string;
-        contractSchema: ContractSchema;
-    }>;
-}
-type EditorProtocolMessageTypes = PublishMessage | SaveImageMessage | HasImageMessage | GetProjectInfoMessage;
-type EditorProtocolResponseTypes = PublishResponse | SaveImageResponse | HasImageResponse | GetProjectInfoResponse;
-interface ProtocolMessage {
+type EditorProtocolMessageTypes<TVendorDoc> = PublishMessage | SaveImageMessage | HasImageMessage | GetProjectInfoMessage | ExportMessage<TVendorDoc> | ImportMessage<TVendorDoc>;
+type EditorProtocolResponseTypes<TVendorDoc> = PublishResponse | SaveImageResponse | HasImageResponse | GetProjectInfoResponse | ExportResponse | ImportResponse<TVendorDoc>;
+interface ProtocolMessage<TVendorDoc> {
     id: string;
     timestamp: number;
-    payload: EditorProtocolMessageTypes;
+    payload: EditorProtocolMessageTypes<TVendorDoc>;
 }
-interface ProtocolResponse {
+interface ProtocolResponse<TVendorDoc> {
     id: string;
     timestamp: number;
-    payload: EditorProtocolResponseTypes;
+    payload: EditorProtocolResponseTypes<TVendorDoc>;
 }
 interface EditorProtocol {
     publish(params: PublishMessage): Promise<PublishResponse>;
     saveImage(params: SaveImageMessage): Promise<SaveImageResponse>;
     hasImage(params: HasImageMessage): Promise<HasImageResponse>;
     getProjectInfo(params: GetProjectInfoMessage): Promise<GetProjectInfoResponse>;
+    export<TVendorDoc>(params: ExportMessage<TVendorDoc>): Promise<ExportResponse>;
+    import<TVendorDoc>(params: ImportMessage<TVendorDoc>): Promise<ImportResponse<TVendorDoc>>;
 }
 interface DevServerProtocol {
     onPublish(callback: EditorProtocol['publish']): void;
     onSaveImage(callback: EditorProtocol['saveImage']): void;
     onHasImage(callback: EditorProtocol['hasImage']): void;
     onGetProjectInfo(callback: EditorProtocol['getProjectInfo']): void;
+    onExport(callback: EditorProtocol['export']): void;
+    onImport(callback: EditorProtocol['import']): void;
 }
 
 interface EditorConfig {
@@ -206,11 +173,150 @@ declare function createPublishMessage(pages?: PublishMessage['pages'], component
 declare function createSaveImageMessage(imageId: string, imageData: string): SaveImageMessage;
 declare function createHasImageMessage(imageId: string): HasImageMessage;
 declare function createGetProjectInfoMessage(): GetProjectInfoMessage;
+declare function createExportMessage<TVendorDoc>(vendorId: string, pageUrl: string, vendorDoc: TVendorDoc): ExportMessage<TVendorDoc>;
+declare function createImportMessage<TVendorDoc>(vendorId: string, pageUrl: string): ImportMessage<TVendorDoc>;
 declare function createPublishResponse(status: PublishResponse['status']): PublishResponse;
 declare function createSaveImageResponse(success: boolean, imageUrl?: string, error?: string): SaveImageResponse;
 declare function createHasImageResponse(exists: boolean, imageUrl?: string): HasImageResponse;
 declare function createGetProjectInfoResponse(info: ProjectInfo, success?: boolean, error?: string): GetProjectInfoResponse;
-declare function createProtocolMessage(payload: EditorProtocolMessageTypes): ProtocolMessage;
-declare function createProtocolResponse(id: string, payload: EditorProtocolResponseTypes): ProtocolResponse;
+declare function createExportResponse(success: boolean, vendorSourcePath?: string, jayHtmlPath?: string, contractPath?: string, warnings?: string[], error?: string): ExportResponse;
+declare function createImportResponse<TVendorDoc>(success: boolean, vendorDoc?: TVendorDoc, error?: string): ImportResponse<TVendorDoc>;
+declare function createProtocolMessage<TVendorDoc>(payload: EditorProtocolMessageTypes<TVendorDoc>): ProtocolMessage<TVendorDoc>;
+declare function createProtocolResponse<TVendorDoc>(id: string, payload: EditorProtocolResponseTypes<TVendorDoc>): ProtocolResponse<TVendorDoc>;
+
+/**
+ * Figma Vendor Document Type
+ *
+ * A JSON-compatible representation of Figma nodes that can be safely
+ * transmitted over the protocol.
+ *
+ * @example
+ * ```typescript
+ * import { FigmaVendorDocument } from '@jay-framework/editor-protocol';
+ *
+ * const sectionNode = figma.currentPage.selection[0];
+ * const vendorDoc: FigmaVendorDocument = serializeNode(sectionNode);
+ *
+ * await editorProtocol.export({
+ *   vendorId: 'figma',
+ *   pageUrl: '/home',
+ *   vendorDoc
+ * });
+ * ```
+ */
+type FigmaVendorDocument = {
+    id: string;
+    name: string;
+    type: string;
+    visible?: boolean;
+    locked?: boolean;
+    parentId?: string;
+    children?: FigmaVendorDocument[];
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    pluginData?: {
+        [key: string]: string;
+    };
+    componentPropertyDefinitions?: {
+        [propertyName: string]: {
+            type: 'VARIANT' | 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP';
+            variantOptions?: string[];
+            defaultValue?: string | boolean;
+        };
+    };
+    componentSetId?: string;
+    componentSetName?: string;
+    mainComponentId?: string;
+    mainComponentName?: string;
+    componentProperties?: any;
+    variantProperties?: {
+        [propertyName: string]: string;
+    };
+    variants?: FigmaVendorDocument[];
+    characters?: string;
+    fontName?: {
+        family: string;
+        style: string;
+    } | 'MIXED';
+    fontSize?: number | 'MIXED';
+    fontWeight?: number | 'MIXED';
+    textAlignHorizontal?: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED';
+    textAlignVertical?: 'TOP' | 'CENTER' | 'BOTTOM';
+    letterSpacing?: {
+        value: number;
+        unit: 'PIXELS' | 'PERCENT';
+    };
+    lineHeight?: {
+        value: number;
+        unit: 'PIXELS' | 'PERCENT' | 'AUTO';
+    } | {
+        unit: 'AUTO';
+    };
+    textDecoration?: 'NONE' | 'UNDERLINE' | 'STRIKETHROUGH';
+    textCase?: 'ORIGINAL' | 'UPPER' | 'LOWER' | 'TITLE';
+    textTruncation?: 'DISABLED' | 'ENDING';
+    maxLines?: number;
+    maxWidth?: number;
+    textAutoResize?: 'NONE' | 'WIDTH_AND_HEIGHT' | 'HEIGHT' | 'TRUNCATE';
+    hasMissingFont?: boolean;
+    hyperlinks?: Array<{
+        start: number;
+        end: number;
+        url: string;
+    }>;
+    fills?: any[];
+    strokes?: any[];
+    effects?: any[];
+    cornerRadius?: number | 'MIXED';
+    topLeftRadius?: number;
+    topRightRadius?: number;
+    bottomLeftRadius?: number;
+    bottomRightRadius?: number;
+    strokeWeight?: number;
+    strokeTopWeight?: number;
+    strokeBottomWeight?: number;
+    strokeLeftWeight?: number;
+    strokeRightWeight?: number;
+    dashPattern?: number[];
+    layoutMode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+    primaryAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN';
+    counterAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX';
+    itemSpacing?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    paddingTop?: number;
+    paddingBottom?: number;
+    layoutPositioning?: 'AUTO' | 'ABSOLUTE';
+    layoutSizingHorizontal?: 'FIXED' | 'HUG' | 'FILL';
+    layoutSizingVertical?: 'FIXED' | 'HUG' | 'FILL';
+    layoutGrow?: number;
+    layoutAlign?: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH';
+    layoutWrap?: 'NO_WRAP' | 'WRAP';
+    clipsContent?: boolean;
+    overflowDirection?: 'NONE' | 'HORIZONTAL' | 'VERTICAL' | 'BOTH';
+    scrollBehavior?: 'SCROLLS' | 'FIXED';
+    parentLayoutMode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL';
+    parentType?: string;
+    parentOverflowDirection?: 'NONE' | 'HORIZONTAL' | 'VERTICAL' | 'BOTH';
+    parentNumberOfFixedChildren?: number;
+    parentChildIndex?: number;
+    opacity?: number;
+    rotation?: number;
+    vectorPaths?: Array<{
+        windingRule: 'NONZERO' | 'EVENODD';
+        data: string;
+    }>;
+    fillGeometry?: Array<{
+        windingRule: 'NONZERO' | 'EVENODD';
+        data: string;
+    }>;
+    strokeGeometry?: Array<{
+        windingRule: 'NONZERO' | 'EVENODD';
+        data: string;
+    }>;
+    [key: string]: any;
+};
 
-export { type BaseMessage, type BaseResponse, type ConnectionState, type ContractSchema, type ContractTag, type DevServerProtocol, type DynamicContractDef, type EditorConfig, type EditorProtocol, type EditorProtocolMessageTypes, type EditorProtocolResponseTypes, type GetProjectInfoMessage, type GetProjectInfoResponse, type HasImageMessage, type HasImageResponse, type InstalledApp, type InstalledAppContracts, type Plugin, type PluginManifest, type PortDiscoveryResponse, type ProjectComponent, type ProjectInfo, type ProjectPage, type ProtocolMessage, type ProtocolResponse, type PublishComponent, type PublishMessage, type PublishPage, type PublishResponse, type PublishStatus, type SaveImageMessage, type SaveImageResponse, type StaticContractDef, createGetProjectInfoMessage, createGetProjectInfoResponse, createHasImageMessage, createHasImageResponse, createProtocolMessage, createProtocolResponse, createPublishMessage, createPublishResponse, createSaveImageMessage, createSaveImageResponse };
+export { type BaseMessage, type BaseResponse, type ConnectionState, type Contract, type ContractTag, type DevServerProtocol, type EditorConfig, type EditorProtocol, type EditorProtocolMessageTypes, type EditorProtocolResponseTypes, type ExportMessage, type ExportResponse, type FigmaVendorDocument, type GetProjectInfoMessage, type GetProjectInfoResponse, type HasImageMessage, type HasImageResponse, type ImportMessage, type ImportResponse, type Plugin, type PortDiscoveryResponse, type ProjectComponent, type ProjectInfo, type ProjectPage, type ProtocolMessage, type ProtocolResponse, type PublishComponent, type PublishMessage, type PublishPage, type PublishResponse, type PublishStatus, type SaveImageMessage, type SaveImageResponse, createExportMessage, createExportResponse, createGetProjectInfoMessage, createGetProjectInfoResponse, createHasImageMessage, createHasImageResponse, createImportMessage, createImportResponse, createProtocolMessage, createProtocolResponse, createPublishMessage, createPublishResponse, createSaveImageMessage, createSaveImageResponse };

package/dist/index.js

@@ -23,6 +23,21 @@ function createGetProjectInfoMessage() {
     type: "getProjectInfo"
   };
 }
+function createExportMessage(vendorId, pageUrl, vendorDoc) {
+  return {
+    type: "export",
+    vendorId,
+    pageUrl,
+    vendorDoc
+  };
+}
+function createImportMessage(vendorId, pageUrl) {
+  return {
+    type: "import",
+    vendorId,
+    pageUrl
+  };
+}
 function createPublishResponse(status) {
   return {
     type: "publish",
@@ -54,6 +69,25 @@ function createGetProjectInfoResponse(info, success = true, error) {
     error
   };
 }
+function createExportResponse(success, vendorSourcePath, jayHtmlPath, contractPath, warnings, error) {
+  return {
+    type: "export",
+    success,
+    vendorSourcePath,
+    jayHtmlPath,
+    contractPath,
+    warnings,
+    error
+  };
+}
+function createImportResponse(success, vendorDoc, error) {
+  return {
+    type: "import",
+    success,
+    vendorDoc,
+    error
+  };
+}
 let messageIdCounter = 0;
 function generateMessageId() {
   const timestamp = Date.now();
@@ -75,10 +109,14 @@ function createProtocolResponse(id, payload) {
   };
 }
 export {
+  createExportMessage,
+  createExportResponse,
   createGetProjectInfoMessage,
   createGetProjectInfoResponse,
   createHasImageMessage,
   createHasImageResponse,
+  createImportMessage,
+  createImportResponse,
   createProtocolMessage,
   createProtocolResponse,
   createPublishMessage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/editor-protocol",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "license": "Apache-2.0",
   "main": "dist/index.js",
@@ -23,9 +23,12 @@
     "test": ":",
     "test:watch": ":"
   },
+  "dependencies": {
+    "@jay-framework/compiler-shared": "^0.13.0"
+  },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.11.0",
-    "@jay-framework/jay-cli": "^0.11.0",
+    "@jay-framework/dev-environment": "^0.13.0",
+    "@jay-framework/jay-cli": "^0.13.0",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",

package/readme.md

@@ -25,12 +25,16 @@ import {
   createPublishMessage,
   createSaveImageMessage,
   createHasImageMessage,
+  createExportMessage,
+  createImportMessage,
   createProtocolMessage,
 } from '@jay-framework/editor-protocol';
 
 // Use in editor applications
 const editor: EditorProtocol = {
   publish: async (params) => ({
+    type: 'publish',
+    success: true,
     status: [
       {
         success: true,
@@ -39,8 +43,40 @@ const editor: EditorProtocol = {
       },
     ],
   }),
-  saveImage: async (params) => ({ success: true, imageUrl: '/assets/image.png' }),
-  hasImage: async (params) => ({ exists: true, imageUrl: '/assets/image.png' }),
+  saveImage: async (params) => ({
+    type: 'saveImage',
+    success: true,
+    imageUrl: '/assets/image.png',
+  }),
+  hasImage: async (params) => ({
+    type: 'hasImage',
+    success: true,
+    exists: true,
+    imageUrl: '/assets/image.png',
+  }),
+  getProjectInfo: async (params) => ({
+    type: 'getProjectInfo',
+    success: true,
+    info: {
+      name: 'My Project',
+      localPath: '/path/to/project',
+      pages: [],
+      components: [],
+      plugins: [],
+    },
+  }),
+  export: async (params) => ({
+    type: 'export',
+    success: true,
+    vendorSourcePath: '/pages/home/page.figma.json',
+  }),
+  import: async (params) => ({
+    type: 'import',
+    success: true,
+    vendorDoc: {
+      /* vendor document */
+    },
+  }),
 };
 
 // Use in dev servers
@@ -48,6 +84,9 @@ const server: DevServerProtocol = {
   onPublish: (callback) => {},
   onSaveImage: (callback) => {},
   onHasImage: (callback) => {},
+  onGetProjectInfo: (callback) => {},
+  onExport: (callback) => {},
+  onImport: (callback) => {},
 };
 
 // Create messages using constructors
@@ -91,6 +130,9 @@ const protocolMessage = createProtocolMessage(publishMessage);
 - `createPublishMessage(pages?, components?)` - Creates a publish message with optional pages and components
 - `createSaveImageMessage(imageId, imageData)` - Creates a save image message
 - `createHasImageMessage(imageId)` - Creates a has image message
+- `createGetProjectInfoMessage()` - Creates a get project info message
+- `createExportMessage<TVendorDoc>(vendorId, pageUrl, vendorDoc)` - Creates an export message with vendor document
+- `createImportMessage<TVendorDoc>(vendorId, pageUrl)` - Creates an import message to retrieve vendor document
 - `createProtocolMessage(payload)` - Creates a protocol message wrapper with auto-generated timestamp-based ID
 
 ### Response Constructors
@@ -98,6 +140,9 @@ const protocolMessage = createProtocolMessage(publishMessage);
 - `createPublishResponse(status)` - Creates a publish response
 - `createSaveImageResponse(success, imageUrl?, error?)` - Creates a save image response
 - `createHasImageResponse(exists, imageUrl?)` - Creates a has image response
+- `createGetProjectInfoResponse(info, success?, error?)` - Creates a get project info response
+- `createExportResponse(success, vendorSourcePath?, jayHtmlPath?, contractPath?, warnings?, error?)` - Creates an export response
+- `createImportResponse<TVendorDoc>(success, vendorDoc?, error?)` - Creates an import response with vendor document
 - `createProtocolResponse(id, payload)` - Creates a protocol response wrapper with timestamp
 
 ## Protocol Operations
@@ -121,6 +166,81 @@ Saves base64 image data to the dev server's public assets.
 
 Checks if an image with the given ID already exists on the server.
 
+### Get Project Info
+
+Retrieves comprehensive project information including pages, components, and installed plugins with their contracts.
+
+### Export
+
+Exports a vendor-specific document (e.g., Figma, Wix) to the dev server at a specific page route. The document is saved as `page.<vendorId>.json` alongside the page's jay-html file.
+
+**Use case**: When a designer exports a Figma design to Jay, the original Figma document can be saved so it can be re-imported later.
+
+**Example:**
+
+```typescript
+import { createExportMessage } from '@jay-framework/editor-protocol';
+
+interface FigmaDocument {
+  nodeId: string;
+  name: string;
+  layers: any[];
+}
+
+const figmaDoc: FigmaDocument = {
+  nodeId: 'abc123',
+  name: 'Homepage',
+  layers: [
+    /* ... */
+  ],
+};
+
+const exportMessage = createExportMessage<FigmaDocument>(
+  'figma', // vendorId
+  '/home', // pageUrl
+  figmaDoc, // vendor document
+);
+
+const response = await editorClient.export(exportMessage);
+// File saved at: src/pages/home/page.figma.json
+```
+
+### Import
+
+Imports a previously exported vendor document from the dev server for a specific page route.
+
+**Use case**: When reopening a page in Figma, retrieve the original Figma document to maintain design history and node references.
+
+**Example:**
+
+```typescript
+import { createImportMessage } from '@jay-framework/editor-protocol';
+
+interface FigmaDocument {
+  nodeId: string;
+  name: string;
+  layers: any[];
+}
+
+const importMessage = createImportMessage<FigmaDocument>(
+  'figma', // vendorId
+  '/home', // pageUrl
+);
+
+const response = await editorClient.import(importMessage);
+if (response.success && response.vendorDoc) {
+  const figmaDoc = response.vendorDoc;
+  // Restore Figma design from saved document
+  console.log('Restored Figma node:', figmaDoc.nodeId);
+}
+```
+
+**File naming convention**: Vendor documents are saved as `page.<vendorId>.json` in the same directory as the page's jay-html file. For example:
+
+- `/src/pages/home/page.jay-html`
+- `/src/pages/home/page.figma.json`
+- `/src/pages/home/page.wix.json`
+
 ## Contract Publishing
 
 Contract files enable headless component support by defining the component's data interface and refs structure. When publishing components or pages, you can optionally include contract content: