@web-applets/sdk 0.1.2 → 0.1.3

package/README.md

@@ -1,29 +1,44 @@
 # Web Applets
 
-> An open spec & SDK for creating apps that agents can use.
+> An open spec & SDK for creating web apps that agents can use.
 
-💌 [Mailing List](https://groups.google.com/a/unternet.co/g/community)
+👾 [Community Discord](https://discord.gg/2aUvMe8HrC) | 💌 [Mailing List](https://groups.google.com/a/unternet.co/g/community)
 
-## What is it?
+[![Mozilla builders logo](docs/assets/builders.png)](https://builders.mozilla.org/)
+
+Web Applets is a [Mozilla Builders](https://builders.mozilla.org/) project.
 
-**Web Applets is an open specification for building software that both humans and AI can understand and use together.** Instead of forcing AI to operate traditional point-and-click apps built for humans, Web Applets creates a new kind of software designed for human-AI collaboration.
+## What is it?
 
-Think of them a bit like Claude artifacts, but they _do stuff_ & _work anywhere_!
+**Web Applets is an open specification for building software that both humans and AI can understand and use together.** Instead of forcing AI to operate traditional point-and-click apps built for humans, Web Applets creates a new kind of web software designed for human-AI collaboration.
 
 ![Demo of a web applets chatbot](./docs/assets/applets-chat-demo.gif)
 
-Think of any web software you use today - maps, documents, shopping, calendars - and imagine if instead of visiting these as separate websites, you could pull them into your own environment where both you and AI could use them together seamlessly. Web applets can do that!
+## Why?
+
+[Unternet](https://unternet.co) is building a new, intelligent user agent that can do things for you across the web. As part of that effort, we needed a way to actuate an embedded web app. You can do this with a computer use model, but for many use cases it's not suitable to point and click around in a virtual browser. Why make a computer talk to another computer via a clumsy web interface when they can just talk directly?
+
+Web Applets lets you define a simple, computer-readable API for a web app running in a browser, webview, or iframe. You can send it actions as JSON objects, which an LLM can easily create (see [OpenAI's structured JSON endpoint](https://openai.com/index/introducing-structured-outputs-in-the-api/)), and they can update their UI instantly in-place. Plus, you can expose the internal state of the applets to the model so you can do cool stuff like chat to a map.
+
+We wanted anyone to be able to build these actions into their own third-party applets and distribute them. So, we extended the web & made it available to everyone!
+
+## Getting started
+
+Create a new web app using our CLI:
+
+```bash
+npx @web-applets/create
+```
+
+Inside the generated folder, you'll find a basic web app setup:
 
-- **Built on Web Standards:** Create applets using familiar web technologies (HTML, CSS, JavaScript, React, Vue, etc.)
-- **AI-Native Protocol:** Applets expose their state and actions in a way AI can understand and use
-- **Rich Interfaces:** Full support for complex graphical UIs, not just text
-- **Local-First:** Runs in your environment, keeping your data under your control
-- **Composable:** Applets can work together, sharing context and state
-- **Open Standard:** Designed for interoperability across clients, not platform lock-in
+- `public/manifest.json`: A web app manifest, where you can define initial actions, add icons, etc.
+- `index.html`: Much like a website, this holds the main page for your applet
+- `src/main.ts`: Declares functions that respond to each action, and a render function that updates the view based on state
 
-## Example
+> Want to use React? Svelte? Vue? – No problem, just install the dependencies and create an app the way you normally would in a website. So long as you're receiving the action events, it will all just work.
 
-Let's say we have a simple website that says hello. It might look something like this:
+Now let's build out a basic web applet that will say hello when we send it an action:
 
 `index.html`:
 
@@ -37,7 +52,29 @@ Let's say we have a simple website that says hello. It might look something like
 </html>
 ```
 
-Let's add some Web Applets functionality, so this can respond to a `set_name` message:
+Let's add some Web Applets functionality, so this can respond to a `set_name` action:
+
+`public/manifest.json`:
+
+```json
+{
+  // ...
+  "actions": [
+    {
+      "id": "set_name",
+      "description": "Sets the name of the user.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  ]
+}
+```
 
 `main.js`:
 
@@ -47,60 +84,30 @@ import { applets } from '@web-applets/sdk';
 const context = applets.getContext();
 
 // Define a 'set_name' action, and make it update the shared data object with the new name
-context.defineAction('set_name', {
-  params: {
-    name: {
-      type: string,
-      description: 'The name of the person to be greeted.',
-    },
-  },
-  handler: ({ name }) => applet.data = { name };
+context.addActionHandler('set_name', ({ name }) => {
+  context.data = { name };
 });
 
 // Whenever the data is updated, update the view
 context.ondata = () => {
-  document.getElementById('name').innerText = applet.data.name;
+  const nameElement = document.getElementById('name');
+  if (nameElement) {
+    nameElement.innerText = context.data.name;
+  }
 };
 ```
 
-Done! If you load this up in the inspector and introduce yourself, it will respond by greeting you.
-
-To use this applet, we need to load it in our host web app using the SDK. Assuming the applet lives in our public directory, here's what that might look like:
-
-```js
-const applet = await applets.load('/helloworld.applet');
-applet.onstateupdated = (state) => console.log(state);
-applet.dispatchAction('set_name', { name: 'Web Applets' });
-// { name: 'Web Applets' }
-```
-
-For a live example you can download and play with now, check out the [applets chat demo](https://github.com/unternet-co/applets-chat).
-
-## Getting started
-
-Create a new web app with the applets SDK installed. You can do this quickly using our CLI:
-
-```bash
-npx @web-applets/create
-```
-
-Inside the generated folder, you'll find a basic web app setup:
-
-- `public/manifest.json`: A web app manifest, useful when publishing your applet, adding icons, etc.
-- `index.html`: Much like a website, this holds the main page for your applet
-- `src/main.ts`: Declares functions that respond to each action, and a render function that updates the view based on state
-
-> Want to use React? Svelte? Vue? – No problem, just install the dependencies and create an app the way you normally would in a website. So long as you're receiving the action events, it will all just work.
-
-Now if you run `npx @web-applets/inspector`, you should be able to test out your new applet directly. This applet will now work in any environment where the SDK is installed.
+To test out this applet, first start the dev server with `npm run dev`, and take note of the dev server URL. Then, fire up the Web Applets inspector by running `npx @web-applets/inspector`, and enter the dev URL into the URL bar up the top.
 
 ![A screenshot showing the 'playground' editing UI, with a web applets showing 'Hello, Web Applets'](docs/assets/web-applets-inspector.png)
 
+You can build this applet, by running `npm run build`, and host it on any static site host. This applet will now work in any environment where the SDK is installed.
+
 ## Integrating Web Applets into your client
 
-Using Web Applets is just as easy as creating them!
+In order to run, web applets need to be embedded in an environment that supports the Web Applets protocol. This might look like a browser (email me if you're interested!), or an electron app with `<webview>` tags, or sometthing as simple as a web-based AI chat client using iframes.
 
-Install & import the applets client in your app:
+First, install & import the applets SDK in your client app:
 
 ```bash
 npm install @web-applets/sdk
@@ -110,12 +117,12 @@ npm install @web-applets/sdk
 import { applets } from '@web-applets/sdk';
 ```
 
-Now you can import your applets from wherever they're being served from (note – you can also host them anywhere on the web):
+Now you can import your applets from wherever they're being served from (note – you can also host them locally, or anywhere on the web):
 
 ```js
-const applet = await applets.load('/helloworld.applet'); // replace with an https URL if hosted remotely
+const applet = await applets.load('https://applets.unternet.co/maps');
 applet.ondata = (e) => console.log(e.data);
-applet.dispatchAction('set_name', { name: 'Web Applets' });
+applet.dispatchAction('set_name', { name: 'Web Applets' }); // console.log: { name: "Ada Lovelace" }
 ```
 
 The above applet is actually running headless, but we can get it to display by attaching it to a container. For the loading step, instead run:
@@ -129,8 +136,7 @@ const applet = await applets.load(`/helloworld.applet`, container);
 To load pre-existing saved data into an applet, simply set the data property:
 
 ```js
-applet.data = { name: 'Ada Lovelace' };
-// console.log: { name: "Ada Lovelace" }
+applet.data = { name: 'Ada Lovelace' }; // console.log: { name: "Ada Lovelace" }
 ```
 
 ## Feedback & Community

package/dist/core/context.d.ts

@@ -1,4 +1,4 @@
-import { ActionParams, AppletDataEvent, AppletLoadEvent, AppletReadyEvent, JSONSchemaProperties, AppletManifest, AppletAction, AppletMessageRelay } from './shared';
+import { ActionParams, AppletDataEvent, AppletLoadEvent, AppletReadyEvent, JSONSchema, AppletManifest, AppletAction, AppletMessageRelay } from './shared';
 export type ActionHandler<T extends ActionParams> = (params: T) => void | Promise<void>;
 export type ActionHandlerDict = {
     [key: string]: ActionHandler<any>;
@@ -25,7 +25,7 @@ export declare class AppletContext extends EventTarget {
     ondata(event: AppletDataEvent): void;
 }
 interface ActionDefinition<T> extends Omit<AppletAction, 'id'> {
-    params?: JSONSchemaProperties;
+    parameters?: JSONSchema;
     handler?: ActionHandler<T>;
 }
 export declare function getContext(): AppletContext;

package/dist/core/shared.d.ts

@@ -18,13 +18,17 @@ export interface AppletAction {
     id: string;
     name?: string;
     description?: string;
-    params?: JSONSchemaProperties;
+    parameters?: JSONSchema;
 }
-export type JSONSchemaProperties = Record<string, {
-    type: string;
+export interface JSONSchema {
+    type: 'object' | 'string' | 'number' | 'integer' | 'array' | 'boolean' | 'null';
     description?: string;
-    properties?: JSONSchemaProperties;
-}>;
+    properties?: {
+        [key: string]: JSONSchema;
+    };
+    required?: string[];
+    additionalProperties?: boolean;
+}
 export type ActionParams = Record<string, any>;
 export declare function loadManifest(pageUrl: string): Promise<AppletManifest>;
 interface SendMessageOptions {

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export interface JSONSchema {
+    type: 'object' | 'string' | 'number' | 'integer' | 'array' | 'boolean' | 'null';
+    description?: string;
+    properties?: {
+        [key: string]: JSONSchema;
+    };
+    required?: string[];
+    additionalProperties?: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -1,17 +1 @@
-import { AppletAction } from './core/shared';
 export declare function parseUrl(url: string, base?: string): string;
-export declare function createOpenAISchemaForAction(action: AppletAction): {
-    strict: boolean;
-    name: string;
-    schema: {
-        type: string;
-        required: string[];
-        properties: {
-            id: {
-                type: string;
-            };
-            params: import("./core/shared").JSONSchemaProperties;
-        };
-        additionalProperties: boolean;
-    };
-};

package/dist/utils.js

@@ -26,19 +26,3 @@ function trimTrailingSlash(url) {
     }
     return url;
 }
-// Creates an OpenAI-compatible schema declaration for an action
-export function createOpenAISchemaForAction(action) {
-    return {
-        strict: true,
-        name: 'action_schema',
-        schema: {
-            type: 'object',
-            required: Object.keys(action),
-            properties: {
-                id: { type: 'string' },
-                params: action.params,
-            },
-            additionalProperties: false,
-        },
-    };
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-applets/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The Web Applets SDK, for creating & hosting Web Applets.",
   "author": "Rupert Manfredi <rupert@unternet.co>",
   "license": "MIT",