@web-applets/sdk 0.1.1 → 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

@@ -1,15 +1,14 @@
 export interface AppletManifest {
     name?: string;
     short_name?: string;
-    icons: AppletIcons;
+    icons: ManifestIcon[];
     description?: string;
-    icon?: string;
     display?: string;
     start_url?: string;
     unsafe?: boolean;
     actions?: AppletAction[];
 }
-export interface AppletIcons {
+export interface ManifestIcon {
     src: string;
     purpose?: string;
     sizes?: string;
@@ -19,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/core/shared.js

@@ -13,7 +13,10 @@ export async function loadManifest(pageUrl) {
         const manifestUrl = parseUrl(href, pageUrl);
         const manifestRequest = await fetch(manifestUrl);
         manifest = await manifestRequest.json();
-        // TODO: Add verification this is a valid manifest
+        manifest.icons = manifest.icons.map((icon) => {
+            icon.src = parseUrl(icon.src, pageUrl);
+            return icon;
+        });
     }
     catch (e) {
         return;

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

@@ -1,8 +1,24 @@
 // Adds http/https to URLs, and prepends with window location if relative
 export function parseUrl(url, base) {
-    if (url)
-        url = URL.parse(url, base ?? window.location.href).href;
-    return trimTrailingSlash(url);
+    if (!url)
+        return '';
+    try {
+        // If the base URL is provided, ensure it has a trailing slash for proper path resolution
+        if (base) {
+            // Don't add trailing slash if the base already ends with a file extension
+            if (!base.match(/\.[a-zA-Z0-9]+$/)) {
+                base = base.endsWith('/') ? base : base + '/';
+            }
+        }
+        // Use URL constructor to properly resolve relative paths
+        const resolvedUrl = new URL(url, base ?? window.location.href);
+        return trimTrailingSlash(resolvedUrl.href);
+    }
+    catch (e) {
+        // Return original URL if parsing fails
+        console.warn('Failed to parse URL:', e);
+        return url;
+    }
 }
 function trimTrailingSlash(url) {
     if (url.endsWith('/')) {
@@ -10,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.1",
+  "version": "0.1.3",
   "description": "The Web Applets SDK, for creating & hosting Web Applets.",
   "author": "Rupert Manfredi <rupert@unternet.co>",
   "license": "MIT",

package/dist/core/host.d.ts

@@ -1,31 +0,0 @@
-import { AppletAction, AppletMessage, ActionParams, AppletManifest, AppletDataEvent, AppletResizeEvent, AppletActionsEvent, AppletMessageRelay } from './shared';
-interface LoadOpts {
-    unsafe?: boolean;
-}
-declare function load(url: string, container?: HTMLIFrameElement, opts?: LoadOpts): Promise<Applet>;
-interface AppletOptions {
-    manifest: AppletManifest;
-    container: HTMLIFrameElement;
-}
-declare class Applet<T = any> extends EventTarget {
-    #private;
-    messageRelay: AppletMessageRelay;
-    url: string;
-    actions: AppletAction[];
-    container: HTMLIFrameElement;
-    type: string;
-    constructor(options: AppletOptions);
-    initializeListeners(): void;
-    get data(): T;
-    set data(data: T);
-    get manifest(): AppletManifest;
-    onresize(event: AppletResizeEvent): void;
-    onactions(event: AppletActionsEvent): void;
-    ondata(event: AppletDataEvent): void;
-    disconnect(): void;
-    dispatchAction(actionId: string, params: ActionParams): Promise<AppletMessage>;
-}
-export declare const applets: {
-    load: typeof load;
-};
-export { Applet };

package/dist/core/host.js

@@ -1,134 +0,0 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _Applet_manifest, _Applet_data;
-import { AppletMessage, AppletDataMessage, AppletInitMessage, AppletDataEvent, AppletResizeEvent, AppletActionsEvent, AppletMessageRelay, } from './shared';
-import { parseUrl } from '../lib/utils';
-// Container for initializing applets without an explicit container
-const hiddenContainer = document.createElement('iframe');
-hiddenContainer.style.display = 'none';
-document.body.appendChild(hiddenContainer);
-const defaultOpts = {
-    unsafe: false,
-};
-// Load an applet object from a URL
-async function load(url, container, opts) {
-    const _opts = Object.assign(defaultOpts, opts ?? {});
-    if (!container)
-        container = hiddenContainer;
-    url = parseUrl(url);
-    const manifest = await loadManifest(`${url}`);
-    // If unsafe enabled, allow same origin sandbox
-    // This is required for e.g. YouTube embeds
-    if (_opts.unsafe && manifest.unsafe) {
-        container.setAttribute('sandbox', 'allow-scripts allow-forms allow-same-origin');
-    }
-    else {
-        container.setAttribute('sandbox', 'allow-scripts allow-forms');
-    }
-    // Load the applet
-    const applet = new Applet({
-        manifest,
-        container,
-    });
-    return new Promise((resolve) => {
-        applet.messageRelay.on('ready', () => {
-            resolve(applet);
-        });
-    });
-}
-class Applet extends EventTarget {
-    constructor(options) {
-        super();
-        this.actions = [];
-        _Applet_manifest.set(this, void 0);
-        this.type = 'host';
-        _Applet_data.set(this, void 0);
-        this.container = options.container;
-        this.container.src = options.manifest.start_url;
-        this.messageRelay = new AppletMessageRelay(this.container.contentWindow);
-        __classPrivateFieldSet(this, _Applet_manifest, options.manifest, "f");
-        this.initializeListeners();
-        this.messageRelay.on('ready', () => {
-            this.messageRelay.send(new AppletInitMessage({ manifest: options.manifest }));
-        });
-    }
-    initializeListeners() {
-        this.messageRelay.on('data', (message) => {
-            __classPrivateFieldSet(this, _Applet_data, message.data, "f");
-            const dataEvent = new AppletDataEvent({ data: message.data });
-            if (typeof this.ondata === 'function')
-                this.ondata(dataEvent);
-            this.dispatchEvent(dataEvent);
-        });
-        this.messageRelay.on('resize', (message) => {
-            const resizeEvent = new AppletResizeEvent({
-                dimensions: message.dimensions,
-            });
-            if (typeof this.onresize === 'function')
-                this.onresize(resizeEvent);
-            this.dispatchEvent(resizeEvent);
-        });
-        this.messageRelay.on('actions', (message) => {
-            this.actions = message.actions;
-            const actionsEvent = new AppletActionsEvent({ actions: message.actions });
-            if (typeof this.onactions === 'function')
-                this.onactions(actionsEvent);
-            this.dispatchEvent(actionsEvent);
-        });
-    }
-    get data() {
-        return __classPrivateFieldGet(this, _Applet_data, "f");
-    }
-    set data(data) {
-        __classPrivateFieldSet(this, _Applet_data, data, "f");
-        this.messageRelay.send(new AppletDataMessage({ data }));
-    }
-    get manifest() {
-        return __classPrivateFieldGet(this, _Applet_manifest, "f");
-    }
-    onresize(event) { }
-    onactions(event) { }
-    ondata(event) { }
-    disconnect() {
-        this.container.src = 'about:blank';
-    }
-    async dispatchAction(actionId, params) {
-        const actionMessage = new AppletMessage('action', {
-            actionId,
-            params,
-        });
-        return await this.messageRelay.send(actionMessage);
-    }
-}
-_Applet_manifest = new WeakMap(), _Applet_data = new WeakMap();
-// Loads a manifest and parses the JSON
-async function loadManifest(baseUrl) {
-    baseUrl = parseUrl(baseUrl);
-    let manifest;
-    try {
-        const request = await fetch(`${baseUrl}/manifest.json`);
-        manifest = await request.json();
-        // TODO: Add verification this is a valid manifest
-    }
-    catch (e) {
-        console.error(e.message);
-    }
-    manifest.start_url = manifest.start_url
-        ? parseUrl(manifest.start_url, baseUrl)
-        : baseUrl;
-    return manifest;
-}
-// Exports
-export const applets = {
-    load,
-};
-export { Applet };

package/dist/lib/utils.d.ts

@@ -1,17 +0,0 @@
-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/lib/utils.js

@@ -1,37 +0,0 @@
-// Adds http/https to URLs, and prepends with window location if relative
-export function parseUrl(url, base) {
-    if (['http', 'https'].includes(url.split('://')[0])) {
-        return url;
-    }
-    let path = trimSlashes(url);
-    url = `${base || window.location.origin}/${path}`;
-    return url;
-}
-function trimSlashes(str) {
-    return str.replace(/^\/+|\/+$/g, '');
-}
-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,
-        },
-    };
-}
-// export async function loadAppletManifest(url: string): Promise<AppletManifest> {
-//   url = parseUrl(url);
-//   const request = await fetch(`${url}/manifest.json`);
-//   const appletManifest = await request.json();
-//   if (appletManifest.type !== 'applet') {
-//     throw new Error("URL doesn't point to a valid applet manifest.");
-//   }
-//   appletManifest.entrypoint = parseUrl(appletManifest.entrypoint, url);
-//   return appletManifest;
-// }