@wyndlass/app-sdk 0.0.0 → 1.1.0

package/package.json

@@ -1,8 +1,87 @@
 {
   "name": "@wyndlass/app-sdk",
-  "version": "0.0.0",
-  "description": "A placeholder for Wyndlass's app SDK. Its first release is 1.0.0.",
+  "version": "1.1.0",
+  "description": "Build apps for Wyndlass's screens: web components on the app contract (Player API 2), with the runtime Wyndlass's own apps use.",
+  "keywords": [
+    "wyndlass",
+    "digital-signage",
+    "signage",
+    "web-components"
+  ],
   "license": "MIT",
   "author": "Northwynd Labs LLC",
-  "files": ["README.md", "LICENSE"]
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NorthwyndLabs/wyndlass.git",
+    "directory": "app-sdk"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "wyndlass-app": "./cli/main.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./qr": {
+      "types": "./dist/qr.d.ts",
+      "import": "./dist/qr.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./app-definition.schema.json": "./protocol/app-definition.schema.json",
+    "./common.schema.json": "./protocol/common.schema.json"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "templates",
+    "skill",
+    "protocol",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "acorn": "8.19.0",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "esbuild": "^0.28.2",
+    "qrcode-generator": "2.0.4"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "22",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "playwright-core": "1.63.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsx": "^4.23.15",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "copy-protocol": "node scripts/copy-protocol.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p preview/tsconfig.json",
+    "build": "node scripts/copy-protocol.mjs --check && tsc -p tsconfig.build.json && node scripts/build-preview.mjs",
+    "test": "pnpm build && node --import tsx --test --test-force-exit test/*.test.ts",
+    "check": "node scripts/copy-protocol.mjs --check && pnpm typecheck"
+  }
+}

package/protocol/app-definition.schema.json

@@ -0,0 +1,435 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.wyndlass.ai/protocol/v0/app-definition.schema.json",
+  "title": "App definition",
+  "description": "The YAML definition of a web component app (scoping doc 7.8). Drives the designer's property panel, the catalog and the MCP tools.",
+  "type": "object",
+  "required": [
+    "id",
+    "version",
+    "name",
+    "element"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9-]*)+$",
+      "description": "Reverse-domain id, e.g. com.wyndlass.weather. com.wyndlass. is Wyndlass's own: an app an organization imports may not use it (WP-0100)."
+    },
+    "version": {
+      "$ref": "common.schema.json#/$defs/semver"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 500
+    },
+    "element": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*-[a-z0-9-]+$",
+      "description": "The element's name. From Player API 2 (WP-0100) the host defines the module's default export under this name, a hyphen and a suffix of its own, so it is the readable part of the tag. Wyndlass's apps also define it themselves, for players older than that."
+    },
+    "params": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-zA-Z0-9]*$"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/param"
+      }
+    },
+    "properties": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "resizable": {
+          "type": "boolean"
+        },
+        "minDuration": {
+          "type": "string",
+          "pattern": "^[0-9]+(ms|s|m)$"
+        },
+        "offline": {
+          "type": "boolean"
+        },
+        "transparent": {
+          "type": "boolean"
+        },
+        "aspectRatio": {
+          "type": "string",
+          "pattern": "^[0-9]+:[0-9]+$"
+        }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "network": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 253
+          }
+        },
+        "sensors": {
+          "description": "Sensors the app reads on the screen. `impressions`: the live, anonymous feed of the people at the screen, where its site measures them (WP-0105): context.impressions.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 64
+          }
+        },
+        "audio": {
+          "type": "boolean"
+        },
+        "peers": {
+          "type": "boolean"
+        },
+        "player": {
+          "enum": [
+            "read",
+            "control"
+          ],
+          "description": "What the app may do with the player's controller (ADR 0050): read its properties and events (read, the default), or also command playback, audio and display (control). The CMS shows it when the app is added."
+        }
+      }
+    },
+    "bindings": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 256
+      }
+    },
+    "slots": {
+      "type": "object",
+      "description": "Named binding slots (ADR 0053, decision 8; DES-AP-01): each a field the app shows, mapped to a table column in a layout's binding. A layout's binding.fields names these.",
+      "propertyNames": {
+        "pattern": "^[a-z][a-zA-Z0-9]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "label",
+          "type"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "label": {
+            "type": "string",
+            "maxLength": 80
+          },
+          "type": {
+            "enum": [
+              "text",
+              "number",
+              "currency",
+              "date",
+              "datetime",
+              "image",
+              "url",
+              "boolean"
+            ],
+            "description": "What the column must hold."
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "help": {
+            "type": "string",
+            "maxLength": 300
+          }
+        }
+      }
+    },
+    "animation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The presets the app's enter and exit hooks take (ADR 0053, decision 8; DES-AH-01 to 07). An app without them is animated as one box.",
+      "properties": {
+        "enter": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,31}$"
+          },
+          "uniqueItems": true,
+          "description": "Presets its enter hook plays (fade, slide, typewriter...)."
+        },
+        "exit": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{0,31}$"
+          },
+          "uniqueItems": true,
+          "description": "Presets its exit hook plays."
+        },
+        "stagger": {
+          "type": "boolean",
+          "description": "Its items can enter one after another (DES-AN-06)."
+        },
+        "pages": {
+          "type": "boolean",
+          "description": "It pages through its items, playing exit and enter at each page (DES-DB-13): its page count comes from the snapshot the layout started with."
+        }
+      }
+    },
+    "data": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "The data service's sources it reads (ADR 0069): weather, news.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{0,31}$"
+      }
+    },
+    "events": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "emits": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 128
+          }
+        },
+        "consumes": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 128
+          }
+        }
+      }
+    },
+    "mobile": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": {
+          "enum": [
+            "render",
+            "snapshot",
+            "hidden"
+          ]
+        }
+      }
+    },
+    "locales": {
+      "type": "array",
+      "items": {
+        "$ref": "common.schema.json#/$defs/locale"
+      }
+    }
+  },
+  "$defs": {
+    "param": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "enum": [
+            "string",
+            "text",
+            "number",
+            "boolean",
+            "enum",
+            "color",
+            "font",
+            "media",
+            "location",
+            "datetime",
+            "duration",
+            "url",
+            "datatable",
+            "column",
+            "secret",
+            "json"
+          ],
+          "description": "A param's kind. A font param's value is a typography object (layout.schema.json#/$defs/typography): a family with its weight, style, decoration, letter case and spacing, line height, shadow and scale."
+        },
+        "label": {
+          "type": "string",
+          "maxLength": 80
+        },
+        "default": {},
+        "values": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/paramValue"
+          },
+          "description": "On an enum, its choices. On any other type, suggestions the designer offers, while any valid value is still allowed (WP-0098). Each is a plain value, or labeled: shown by its label, under its group."
+        },
+        "group": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "min": {
+          "type": "number"
+        },
+        "max": {
+          "type": "number"
+        },
+        "step": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "help": {
+          "type": "string",
+          "maxLength": 300
+        },
+        "advanced": {
+          "type": "boolean"
+        },
+        "when": {
+          "type": "object",
+          "minProperties": 1,
+          "maxProperties": 8,
+          "propertyNames": {
+            "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/paramTest"
+          },
+          "description": "When the param applies (WP-0068 part f, after gadget.yaml's depends): each key names another param of this app, and its test must hold. A param that does not apply is not shown in the designer and is not required; its value is kept."
+        }
+      },
+      "if": {
+        "properties": {
+          "type": {
+            "const": "enum"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "values"
+        ]
+      }
+    },
+    "paramValue": {
+      "description": "A value as a param's values list it (WP-0098): a string, number or boolean, or labeled ({ value, label, group }) for the designer to show by its label, under its group.",
+      "if": {
+        "type": "object"
+      },
+      "then": {
+        "type": "object",
+        "required": [
+          "value",
+          "label"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "value": {
+            "anyOf": [
+              { "type": "string" },
+              { "type": "number" },
+              { "type": "boolean" }
+            ]
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          "group": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          }
+        }
+      },
+      "else": {
+        "anyOf": [
+          { "type": "string" },
+          { "type": "number" },
+          { "type": "boolean" }
+        ]
+      }
+    },
+    "paramTest": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "description": "A test of another param's value (WP-0068 part f): every one given must hold. Values compare as text.",
+      "properties": {
+        "anyOf": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          },
+          "description": "Its value is one of these."
+        },
+        "allOf": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          },
+          "description": "Its value, a list, holds every one of these."
+        },
+        "noneOf": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 50,
+          "items": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          },
+          "description": "Its value is none of these."
+        },
+        "set": {
+          "type": "boolean",
+          "description": "true: it has a value; false: it has none (absent, empty text, or an empty list)."
+        }
+      }
+    }
+  }
+}